@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.11

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

@@ -1,251 +0,0 @@
-# 批量装配模式（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

@@ -1,120 +0,0 @@
-# 平台 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

@@ -1,211 +0,0 @@
-# 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)