@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-data-access/references/outbound/batch-assembly.md

@@ -0,0 +1,251 @@
+# 批量装配模式（batch-assembly）
+
+> **核心模式**：一次 Feign `listByIds(去重 ID 集合)` + 内存 join。**禁止**分页循环逐条 Feign。
+
+---
+
+## 1. 标准模式
+
+### 1.1 场景
+
+订单列表展示，每条订单要显示申请人姓名 + 部门名称。
+
+### 1.2 ❌ 反例：循环 Feign（N+1）
+
+```java
+// ❌ 错：100 条订单 = 200 次 Feign
+public List<OrderVO> toVOListBad(List<Order> orders) {
+    List<OrderVO> vos = new ArrayList<>();
+    for (Order order : orders) {
+        UserDTO user = userClient.getById(order.getApplicantUserId());  // N 次
+        OrgDTO org = orgClient.getById(user.getOrgId());                // N 次
+        OrderVO vo = OrderConverter.toVO(order);
+        vo.setApplicantName(user.getName());
+        vo.setApplicantOrgName(org.getName());
+        vos.add(vo);
+    }
+    return vos;
+}
+```
+
+**性能**：100 条订单 = 200 次 Feign 调用 = ~2-10s 延迟
+
+### 1.3 ✅ 正确：批量装配
+
+```java
+// ✅ 正确：100 条订单 = 2 次 Feign
+public List<OrderVO> toVOListGood(List<Order> orders) {
+    if (orders.isEmpty()) return Collections.emptyList();
+
+    // 1. 提取用户 ID（去重）
+    List<String> userIds = orders.stream()
+        .map(Order::getApplicantUserId)
+        .filter(Objects::nonNull)
+        .distinct()
+        .collect(Collectors.toList());
+
+    // 2. 一次 Feign 拉所有用户
+    List<UserDTO> users = userClient.listByIds(userIds).getData();
+    Map<String, UserDTO> userMap = users.stream()
+        .collect(Collectors.toMap(UserDTO::getId, Function.identity()));
+
+    // 3. 提取组织 ID（去重）
+    List<String> orgIds = users.stream()
+        .map(UserDTO::getOrgId)
+        .filter(Objects::nonNull)
+        .distinct()
+        .collect(Collectors.toList());
+
+    // 4. 一次 Feign 拉所有组织
+    List<OrgDTO> orgs = orgClient.listByIds(orgIds).getData();
+    Map<String, OrgDTO> orgMap = orgs.stream()
+        .collect(Collectors.toMap(OrgDTO::getId, Function.identity()));
+
+    // 5. 内存 join
+    return orders.stream().map(order -> {
+        OrderVO vo = OrderConverter.toVO(order);
+        UserDTO user = userMap.get(order.getApplicantUserId());
+        if (user != null) {
+            vo.setApplicantName(user.getName());
+            OrgDTO org = orgMap.get(user.getOrgId());
+            if (org != null) {
+                vo.setApplicantOrgName(org.getName());
+            }
+        }
+        return vo;
+    }).collect(Collectors.toList());
+}
+```
+
+**性能**：100 条订单 = 2 次 Feign 调用 = ~50-200ms 延迟
+
+---
+
+## 2. 分页场景的特殊处理
+
+### 2.1 场景
+
+订单表 10 万条，分页查询（page=1, size=20）。
+
+### 2.2 ❌ 反例：分页循环
+
+```java
+// ❌ 错：5 页 = 5×20 = 100 次 Feign
+public List<OrderVO> listAllBad() {
+    List<OrderVO> all = new ArrayList<>();
+    int totalPages = (int) Math.ceil(totalCount / 20.0);
+    for (int page = 1; page <= totalPages; page++) {
+        List<Order> orders = orderRepository.findPage(page, 20);
+        for (Order order : orders) {
+            UserDTO user = userClient.getById(order.getApplicantUserId());  // N+1
+            // ...
+        }
+    }
+    return all;
+}
+```
+
+### 2.3 ✅ 正确：每页内批量装配
+
+```java
+// ✅ 正确：5 页 = 5 次（每页 1 次批量 Feign）
+public List<OrderVO> listAllGood() {
+    List<OrderVO> all = new ArrayList<>();
+    int totalPages = (int) Math.ceil(totalCount / 20.0);
+    for (int page = 1; page <= totalPages; page++) {
+        List<Order> orders = orderRepository.findPage(page, 20);
+        List<OrderVO> pageVOs = toVOListGood(orders);  // 内部批量装配
+        all.addAll(pageVOs);
+    }
+    return all;
+}
+```
+
+### 2.4 更优：单次大查询 + 内存分页
+
+```java
+// ✅ 更优：一次查所有需要的 ID，一次 Feign 装配
+public PageResult<OrderVO> pageWithJoin(OrderQuery query) {
+    // 1. 分页查订单（只查 ID）
+    Page<Long> idPage = orderRepository.findIds(query, pageable);
+
+    // 2. 按 ID 查完整订单
+    List<Order> orders = orderRepository.findAllById(idPage.getContent());
+
+    // 3. 批量装配（一次 Feign 拉所有用户）
+    List<OrderVO> vos = toVOListGood(orders);
+
+    // 4. 组装分页结果
+    PageResult<OrderVO> result = new PageResult<>();
+    result.setTotal(idPage.getTotalElements());
+    result.setRecords(vos);
+    return result;
+}
+```
+
+---
+
+## 3. 多层级装配
+
+### 3.1 场景
+
+订单 → 用户 → 组织 → 上级组织 → 组织负责人
+
+### 3.2 实现
+
+```java
+public List<OrderVO> toVOListMultiLevel(List<Order> orders) {
+    // 1. 装配用户
+    Map<String, UserDTO> userMap = batchLoadUsers(orders);
+
+    // 2. 装配组织（一级）
+    Map<String, OrgDTO> orgMap = batchLoadOrgs(userMap.values());
+
+    // 3. 装配上级组织
+    Map<String, OrgDTO> parentOrgMap = batchLoadOrgs(
+        orgMap.values().stream()
+            .map(OrgDTO::getParentId)
+            .filter(Objects::nonNull)
+            .distinct()
+            .collect(Collectors.toList())
+    );
+
+    // 4. 装配组织负责人
+    Map<String, UserDTO> leaderMap = batchLoadUsers(
+        orgMap.values().stream()
+            .map(OrgDTO::getLeaderId)
+            .filter(Objects::nonNull)
+            .distinct()
+            .collect(Collectors.toList())
+    );
+
+    // 5. 内存 join（一次性装配所有层级）
+    return orders.stream().map(order -> {
+        OrderVO vo = OrderConverter.toVO(order);
+        UserDTO user = userMap.get(order.getApplicantUserId());
+        if (user != null) {
+            vo.setApplicantName(user.getName());
+            OrgDTO org = orgMap.get(user.getOrgId());
+            if (org != null) {
+                vo.setApplicantOrgName(org.getName());
+                OrgDTO parentOrg = parentOrgMap.get(org.getParentId());
+                if (parentOrg != null) {
+                    vo.setApplicantParentOrgName(parentOrg.getName());
+                }
+                UserDTO leader = leaderMap.get(org.getLeaderId());
+                if (leader != null) {
+                    vo.setApplicantOrgLeaderName(leader.getName());
+                }
+            }
+        }
+        return vo;
+    }).collect(Collectors.toList());
+}
+```
+
+---
+
+## 4. 通用工具类
+
+```java
+public class BatchAssembleHelper {
+
+    /**
+     * 通用批量装配：一次 Feign + 内存 join
+     */
+    public static <K, V, R> List<R> assemble(
+            List<K> sourceIds,
+            Function<List<K>, List<V>> batchLoader,    // Feign listByIds
+            Function<V, K> keyExtractor,              // getId
+            Function<K, R> assembler                  // 装配逻辑
+    ) {
+        if (sourceIds == null || sourceIds.isEmpty()) {
+            return Collections.emptyList();
+        }
+        List<V> entities = batchLoader.apply(sourceIds);
+        Map<K, V> entityMap = entities.stream()
+            .collect(Collectors.toMap(keyExtractor, Function.identity(), (a, b) -> a));
+        return sourceIds.stream()
+            .map(id -> assembler.apply(id))
+            .collect(Collectors.toList());
+    }
+}
+```
+
+---
+
+## 5. 性能对比
+
+| 场景 | 订单数 | 反例（循环 Feign）| 正例（批量）| 提升 |
+|------|--------|------------------|-------------|------|
+| 单页列表 | 20 | 40 次 = ~1s | 2 次 = ~50ms | 20× |
+| 多页循环 | 1000 | 2000 次 = ~50s | 100 次 = ~5s | 10× |
+| 大列表导出 | 10000 | 20000 次 = ~10min | 2 次 = ~2s | 300× |
+
+---
+
+## 6. 关联阅读
+
+- [feign-guide.md](feign-guide.md) — Feign 写法
+- [third-party.md](third-party.md) — 第三方接口
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-access/references/outbound/dto-catalog.md

@@ -0,0 +1,120 @@
+# 平台 DTO 清单（entities）
+
+> **铁律**：禁止 import 平台 Entity 到二开库代码。一律使用平台公共 DTO + Feign 装配。
+
+---
+
+## 1. 核心 DTO 清单
+
+### 1.1 人员 / 用户
+
+| DTO | 关键字段 | 用途 |
+|-----|---------|------|
+| `UserDTO` | `id`, `name`, `code`, `phone`, `email`, `orgId` | 用户基本信息 |
+| `UserDetailDTO` | `id`, `name`, `code`, `orgId`, `deptId`, `position`, `status` | 用户完整信息（含组织）|
+| `UserSimpleDTO` | `id`, `name` | 简化版（弹框选项）|
+
+### 1.2 组织 / 部门
+
+| DTO | 关键字段 | 用途 |
+|-----|---------|------|
+| `OrgDTO` | `id`, `name`, `code`, `parentId`, `type` | 组织基本信息 |
+| `OrgTreeDTO` | `id`, `name`, `children` | 组织树 |
+| `DeptDTO` | `id`, `name`, `parentId`, `leaderId` | 部门信息 |
+
+### 1.3 角色 / 权限
+
+| DTO | 关键字段 | 用途 |
+|-----|---------|------|
+| `RoleDTO` | `id`, `code`, `name`, `type` | 角色 |
+| `PermissionDTO` | `id`, `code`, `name`, `resourceType` | 权限点 |
+| `AssignDTO` | `userId`, `roleCodes`, `orgId` | 用户角色分配 |
+
+### 1.4 字典
+
+| DTO | 关键字段 | 用途 |
+|-----|---------|------|
+| `LookupDTO` | `type`, `code`, `name`, `parentCode` | 字典项 |
+| `LookupTypeDTO` | `type`, `name` | 字典类型 |
+
+### 1.5 附件 / 文件
+
+| DTO | 关键字段 | 用途 |
+|-----|---------|------|
+| `AttachmentDTO` | `id`, `name`, `url`, `size`, `bizId` | 附件元数据 |
+| `UploadTokenDTO` | `token`, `url` | 上传凭证 |
+
+---
+
+## 2. 字段命名约定
+
+```java
+public class UserDTO {
+    private String id;              // 用户 ID（稳定）
+    private String name;            // 用户姓名（冗余展示用）
+    private String code;            // 工号
+    private String phone;           // 手机号
+    private String email;           // 邮箱
+    private String orgId;           // 所属组织 ID
+    private String deptId;          // 所属部门 ID
+    private Integer status;         // 1=在职 0=离职
+    private LocalDateTime createTime;
+    private LocalDateTime updateTime;
+}
+```
+
+**关键约定**：
+- ID 类字段（`id` / `orgId` / `deptId`）是**稳定关联键**
+- 名称类字段（`name`）是**展示快照**，不用作关联
+
+---
+
+## 3. 典型使用场景
+
+### 3.1 列表展示人员姓名（批量装配）
+
+```java
+// ✅ 正确：一次 Feign 拉所有
+List<String> userIds = orderList.stream()
+    .map(Order::getApplicantUserId)
+    .distinct()
+    .collect(Collectors.toList());
+
+Map<String, UserDTO> userMap = userClient.listByIds(userIds).stream()
+    .collect(Collectors.toMap(UserDTO::getId, Function.identity()));
+
+// 内存 join
+orderList.forEach(o -> {
+    UserDTO user = userMap.get(o.getApplicantUserId());
+    o.setApplicantName(user != null ? user.getName() : "");
+});
+```
+
+### 3.2 ❌ 反例：循环 Feign
+
+```java
+// ❌ 错：N+1 问题
+for (Order order : orderList) {
+    UserDTO user = userClient.getById(order.getApplicantUserId());
+    order.setApplicantName(user.getName());
+}
+```
+
+---
+
+## 4. DTO 转换工具类
+
+详见 [dto-converter.md](dto-converter.md)。
+
+---
+
+## 5. Q 类查询
+
+详见 [querydsl-guide.md](querydsl-guide.md)。
+
+---
+
+## 6. 关联阅读
+
+- [SKILL.md](../SKILL.md)
+- [rules/code-dev-rules.md §八.1](../../rules/code-dev-rules.md#81-数据访问边界data-boundary)

package/skills/meritdata-platform-data-access/references/outbound/dto-converter.md

@@ -0,0 +1,211 @@
+# DTO 转换工具（dto-converter）
+
+> DTO 与业务 VO 的转换工具类，避免每个 Service 写一遍 getter/setter。
+
+---
+
+## 1. MapStruct（推荐）
+
+### 1.1 引入依赖
+
+```xml
+<dependency>
+    <groupId>org.mapstruct</groupId>
+    <artifactId>mapstruct</artifactId>
+    <version>1.5.5.Final</version>
+</dependency>
+<dependency>
+    <groupId>org.mapstruct</groupId>
+    <artifactId>mapstruct-processor</artifactId>
+    <scope>provided</scope>
+</dependency>
+```
+
+### 1.2 定义 Mapper
+
+```java
+@Mapper
+public interface OrderMapper {
+
+    OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);
+
+    @Mapping(source = "applicantUserId", target = "applicantUserIdSnapshot")
+    OrderVO toVO(Order order, @Context UserDTO user);
+
+    // 嵌套字段映射
+    @Mapping(target = "applicantName", expression = "java(user != null ? user.getName() : \"\")")
+    @Mapping(target = "applicantOrgName", expression = "java(org != null ? org.getName() : \"\")")
+    OrderDetailVO toDetailVO(Order order, @Context UserDTO user, @Context OrgDTO org);
+}
+```
+
+### 1.3 使用
+
+```java
+UserDTO user = userClient.getById(order.getApplicantUserId());
+OrgDTO org = orgClient.getById(user.getOrgId());
+
+OrderDetailVO vo = OrderMapper.INSTANCE.toDetailVO(order, user, org);
+```
+
+---
+
+## 2. Spring Bean 注入方式（适合有状态 Mapper）
+
+### 2.1 定义
+
+```java
+@Mapper(componentModel = "spring")
+public interface OrderMapper {
+    OrderVO toVO(Order order);
+}
+```
+
+### 2.2 注入使用
+
+```java
+@Service
+public class OrderService {
+
+    @Autowired
+    private OrderMapper orderMapper;
+
+    public OrderVO getById(Long id) {
+        Order order = orderRepository.findById(id).orElseThrow();
+        return orderMapper.toVO(order);
+    }
+}
+```
+
+---
+
+## 3. 手写 Converter（轻量场景）
+
+### 3.1 工具类
+
+```java
+public class OrderConverter {
+
+    public static OrderVO toVO(Order order) {
+        if (order == null) return null;
+        OrderVO vo = new OrderVO();
+        vo.setId(order.getId());
+        vo.setOrderNo(order.getOrderNo());
+        vo.setStatus(order.getStatus());
+        vo.setCreateTime(order.getCreateTime());
+        return vo;
+    }
+
+    public static List<OrderVO> toVOList(List<Order> orders) {
+        if (orders == null) return Collections.emptyList();
+        return orders.stream().map(OrderConverter::toVO).collect(Collectors.toList());
+    }
+}
+```
+
+### 3.2 使用
+
+```java
+List<OrderVO> vos = OrderConverter.toVOList(orderList);
+```
+
+---
+
+## 4. 字段拷贝（不推荐，复杂场景难维护）
+
+```java
+// ❌ 不推荐
+BeanUtils.copyProperties(order, vo);
+
+// 缺点：
+// 1. 不同名字段不拷贝（如 applicantUserId → applicantUserIdSnapshot）
+// 2. 类型不一致时不拷贝
+// 3. 没有编译期检查
+```
+
+---
+
+## 5. 嵌套 DTO 装配模式
+
+### 5.1 场景
+
+业务表存 `applicant_user_id`，展示要 `applicant_name` + `applicant_org_name`。
+
+### 5.2 标准模式：批量装配 + 内存 join
+
+```java
+public List<OrderVO> listWithApplicant(List<Order> orders) {
+    if (orders.isEmpty()) return Collections.emptyList();
+
+    // 1. 提取用户 ID
+    List<String> userIds = orders.stream()
+        .map(Order::getApplicantUserId)
+        .distinct()
+        .collect(Collectors.toList());
+
+    // 2. 批量拉用户（一次 Feign）
+    Map<String, UserDTO> userMap = userClient.listByIds(userIds).stream()
+        .collect(Collectors.toMap(UserDTO::getId, Function.identity()));
+
+    // 3. 提取组织 ID
+    List<String> orgIds = userMap.values().stream()
+        .map(UserDTO::getOrgId)
+        .filter(Objects::nonNull)
+        .distinct()
+        .collect(Collectors.toList());
+
+    // 4. 批量拉组织
+    Map<String, OrgDTO> orgMap = orgClient.listByIds(orgIds).stream()
+        .collect(Collectors.toMap(OrgDTO::getId, Function.identity()));
+
+    // 5. 内存装配
+    return orders.stream().map(order -> {
+        OrderVO vo = OrderConverter.toVO(order);
+        UserDTO user = userMap.get(order.getApplicantUserId());
+        if (user != null) {
+            vo.setApplicantName(user.getName());
+            OrgDTO org = orgMap.get(user.getOrgId());
+            if (org != null) {
+                vo.setApplicantOrgName(org.getName());
+            }
+        }
+        return vo;
+    }).collect(Collectors.toList());
+}
+```
+
+---
+
+## 6. ❌ 反模式
+
+### 6.1 在循环里转换
+
+```java
+// ❌ 错
+for (Order order : orders) {
+    UserDTO user = userClient.getById(order.getApplicantUserId());  // N 次 Feign
+    OrderVO vo = OrderConverter.toVO(order);
+    vo.setApplicantName(user.getName());
+    voList.add(vo);
+}
+```
+
+### 6.2 复制平台 DTO 字段到业务 VO
+
+```java
+// ❌ 错：业务 VO 直接继承 UserDTO
+public class OrderVO extends UserDTO { ... }
+
+// 应该用组合：
+public class OrderVO {
+    private UserDTO applicant;  // 嵌套
+}
+```
+
+---
+
+## 7. 关联阅读
+
+- [dto-catalog.md](dto-catalog.md) — 平台 DTO 清单
+- [querydsl-guide.md](querydsl-guide.md) — Q 类查询
+- [SKILL.md](../SKILL.md)