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

package/skills/meritdata-platform-data-boundary/references/anti-patterns.md

@@ -1,519 +0,0 @@
-# 反模式 vs 正模式（data-boundary）
-
-> **本文件与 rules/code-dev-rules.md §八.1 一一对应**。每条铁律给出：❌ 反模式 → ✅ 正模式 → 根因 → 真实案例。
->
-> **使用方法**：写二开数据访问代码时按目录逐项检查；PR review 时逐项打钩；CI 扫描时按 [validate-rules.md](validate-rules.md) 自动检测。
-
----
-
-## 1. 不映射 `PF_` 前缀平台表（铁律 1）
-
-**铁律来源**：[rules §八.1](../../../../rules/code-dev-rules.md#81-数据访问边界data-boundary)
-
-### 1.1 @TableName 映射平台表
-
-#### ❌ 反模式
-
-```java
-// 二开业务库试图直接映射 cloud 平台表
-@Entity
-@Table(name = "PF_USER")
-public class UserPo {
-    @Id
-    private Long id;
-    private String userName;
-}
-
-// 同理：@TableName("PF_USER_INFO") / @TableName("PF_ORGANIZATION") 等
-```
-
-#### ✅ 正模式
-
-```java
-// 二开业务库只建业务表；人员只存稳定 user_id
-@Entity
-@Table(name = "t_order")
-public class Order {
-    @Id
-    private Long id;
-    private Long applicantUserId;  // 只存 ID，姓名通过 Feign 装配
-    @Transient
-    private String applicantUserName;  // 装配结果，运行时计算
-}
-
-// 装配：一次 Feign 批量查
-Map<Long, String> userNameMap = userClient.listByIds(userIds).stream()
-    .collect(Collectors.toMap(UserDTO::getId, UserDTO::getName));
-```
-
-### 1.2 跨库 JOIN 平台表
-
-#### ❌ 反模式
-
-```xml
-<!-- MyBatis Mapper.xml -->
-<select id="listOrdersWithUser" resultType="OrderVO">
-    SELECT o.*, u.user_name
-    FROM t_order o
-    JOIN cloud.PF_USER u ON o.applicant_user_id = u.id  <!-- 💥 跨库 JOIN -->
-</select>
-```
-
-#### ✅ 正模式
-
-```xml
-<!-- 二开业务库内只查业务表 -->
-<select id="listOrders" resultType="OrderVO">
-    SELECT o.* FROM t_order o
-    WHERE o.deleted = false
-    ORDER BY o.create_time DESC
-    LIMIT #{offset}, #{limit}
-</select>
-```
-
-```java
-// 应用层装配
-List<OrderVO> orders = orderMapper.listOrders(query);
-Set<Long> userIds = orders.stream().map(OrderVO::getApplicantUserId).collect(toSet());
-Map<Long, UserDTO> userMap = userClient.listByIds(new ArrayList<>(userIds)).stream()
-    .collect(Collectors.toMap(UserDTO::getId, u -> u));
-orders.forEach(o -> {
-    UserDTO u = userMap.get(o.getApplicantUserId());
-    if (u != null) o.setApplicantUserName(u.getName());
-});
-```
-
-### 1.3 Controller 直连 cloud 库
-
-#### ❌ 反模式
-
-```java
-@RestController
-public class OrderController {
-    @Autowired
-    @Qualifier("cloudDataSource")  // 平台数据源
-    private DataSource cloudDs;
-
-    @PostMapping("/query")
-    public List<UserVO> query(@RequestBody String sql) {
-        // 💥 接受任意 SQL 直连平台库
-        Connection conn = cloudDs.getConnection();
-        // ...
-    }
-}
-```
-
-#### ✅ 正模式
-
-```java
-@RestController
-public class OrderController {
-    private final OrderRepo orderRepo;
-    private final UserClient userClient;  // 平台 Feign 客户端
-
-    @PostMapping("/list")
-    public GridView<OrderVO> list(GridQuery query) {
-        // 业务库查 + Feign 装配，不接受任意 SQL
-        List<OrderVO> orders = orderRepo.findPage(query);
-        Map<Long, UserDTO> userMap = userClient.listByIds(extractUserIds(orders)).stream()
-            .collect(toMap(UserDTO::getId, u -> u));
-        return new GridView<>(assemble(orders, userMap));
-    }
-}
-```
-
-### 根因
-
-PF_ 是平台专属表前缀，平台对表结构有自主演进权。二开业务库：
-- 直接映射 → 平台升级时 schema 变化导致二开库崩溃
-- 跨库 JOIN → 数据库耦合，平台升级必须等二开配合
-- 直连 cloud 库 → 绕过服务边界，平台故障转嫁到二开
-
-### 真实踩坑案例
-
-- **2025-11**：某项目 `@TableName("PF_USER")` 映射平台表，平台 6.13 → 6.14 升级时新增字段，二开库启动失败，回滚 2 天
-- **2026-03**：某二开通过 `JOIN cloud.PF_ORG` 查组织，平台分库后 JOIN 性能从 50ms 退化到 8s
-
----
-
-## 2. 不分页循环逐条 Feign（铁律 2）
-
-**铁律来源**：[rules §八.1](../../../../rules/code-dev-rules.md#81-数据访问边界data-boundary)
-
-### 2.1 N+1 查询（for + getById）
-
-#### ❌ 反模式
-
-```java
-public List<OrderVO> listOrders() {
-    List<Order> orders = orderRepo.findAll();
-    List<OrderVO> result = new ArrayList<>();
-    for (Order order : orders) {  // 💥 N 次 Feign
-        UserDTO user = userClient.getById(order.getApplicantUserId());
-        OrderVO vo = toVO(order);
-        vo.setApplicantUserName(user != null ? user.getName() : "");
-        result.add(vo);
-    }
-    return result;
-}
-```
-
-#### ✅ 正模式（批量 Feign + 内存 join）
-
-```java
-public List<OrderVO> listOrders() {
-    List<Order> orders = orderRepo.findAll();
-
-    // 1. 收集去重的 user_id
-    Set<Long> userIds = orders.stream()
-        .map(Order::getApplicantUserId)
-        .filter(Objects::nonNull)
-        .collect(Collectors.toSet());
-
-    // 2. 一次 Feign 批量查
-    Map<Long, UserDTO> userMap = userIds.isEmpty()
-        ? Collections.emptyMap()
-        : userClient.listByIds(new ArrayList<>(userIds)).stream()
-            .collect(Collectors.toMap(UserDTO::getId, u -> u, (a, b) -> a));
-
-    // 3. 内存 join
-    return orders.stream().map(order -> {
-        OrderVO vo = toVO(order);
-        UserDTO user = userMap.get(order.getApplicantUserId());
-        vo.setApplicantUserName(user != null ? user.getName() : "");
-        return vo;
-    }).collect(Collectors.toList());
-}
-```
-
-### 2.2 分页循环逐条 Feign
-
-#### ❌ 反模式
-
-```java
-public List<OrderVO> listAllOrdersPaged() {
-    List<OrderVO> all = new ArrayList<>();
-    int page = 1;
-    while (true) {
-        Page<Order> p = orderRepo.findPage(page, PAGE_SIZE);
-        if (p.isEmpty()) break;
-        for (Order order : p.getContent()) {  // 💥 每页 N 次 Feign
-            UserDTO user = userClient.getById(order.getApplicantUserId());
-            all.add(toVO(order, user));
-        }
-        page++;
-    }
-    return all;
-}
-```
-
-#### ✅ 正模式（先分页业务数据，再合并 Feign）
-
-```java
-public List<OrderVO> listAllOrdersPaged() {
-    // 1. 一次性分页查完所有业务数据
-    List<Order> allOrders = new ArrayList<>();
-    int page = 1;
-    while (true) {
-        Page<Order> p = orderRepo.findPage(page, PAGE_SIZE);
-        if (p.isEmpty()) break;
-        allOrders.addAll(p.getContent());
-        page++;
-    }
-
-    // 2. 合并去重的 user_id
-    Set<Long> userIds = allOrders.stream()
-        .map(Order::getApplicantUserId).collect(Collectors.toSet());
-
-    // 3. 一次 Feign 批量查
-    Map<Long, UserDTO> userMap = userClient.listByIds(new ArrayList<>(userIds)).stream()
-        .collect(Collectors.toMap(UserDTO::getId, u -> u));
-
-    // 4. 内存装配
-    return allOrders.stream().map(o -> {
-        UserDTO u = userMap.get(o.getApplicantUserId());
-        return toVO(o, u);
-    }).collect(Collectors.toList());
-}
-```
-
-### 2.3 异常处理（Feign 调用）
-
-#### ❌ 反模式
-
-```java
-try {
-    user = userClient.getById(order.getApplicantUserId());
-} catch (Exception e) {
-    user = null;  // 💥 平台故障被吞，上游无法感知
-}
-```
-
-#### ✅ 正模式
-
-```java
-// 批量调用时，捕获并明确失败
-Map<Long, UserDTO> userMap = new HashMap<>();
-try {
-    userMap = userClient.listByIds(new ArrayList<>(userIds)).stream()
-        .collect(Collectors.toMap(UserDTO::getId, u -> u));
-} catch (FeignException e) {
-    log.error("批量查询用户失败, ids={}, status={}", userIds, e.status());
-    throw new ServiceException("USER_FETCH_FAIL", "用户服务调用失败", e);
-    // ↑ 不掩盖故障，让上游感知并降级
-}
-```
-
-### 根因
-
-- N+1 查询：响应时间 = N × RTT（一次 Feign 50ms，100 条数据就是 5s）
-- 数据库连接耗尽：每次循环持有连接，长事务
-- 平台压力转嫁：高峰时段二开项目的循环 Feign 把平台打挂
-
-### 真实踩坑案例
-
-- **2025-08**：某二开订单列表加载 200 条数据，循环 Feign 耗时 12 秒，平台 User 服务 CPU 飙到 95%
-- **2026-01**：某报表功能循环 5000 次查部门，触发平台限流，10 分钟故障
-
----
-
-## 3. 不复制平台 Entity/Repository（铁律 3）
-
-**铁律来源**：[rules §八.1](../../../../rules/code-dev-rules.md#81-数据访问边界data-boundary)
-
-### 3.1 二开项目直接 import 平台 Entity
-
-#### ❌ 反模式
-
-```java
-// 二开服务 A
-import com.meritdata.cloud.platform.entity.User;
-import com.meritdata.cloud.platform.entity.UserRepository;
-
-@Service
-public class OrderService {
-    @Autowired
-    private UserRepository userRepo;  // 💥 跨 JVM 部署后注入失败
-
-    public void createOrder(OrderDTO dto) {
-        User user = userRepo.findById(dto.getUserId()).orElseThrow();
-        // ...
-    }
-}
-```
-
-#### ✅ 正模式
-
-```java
-// 二开服务 A（独立部署）
-import com.meritdata.cloud.dto.UserDTO;  // 平台对外 DTO
-import com.meritdata.cloud.client.UserClient;  // 平台 Feign Client
-
-@Service
-public class OrderService {
-    private final UserClient userClient;
-
-    public void createOrder(OrderDTO dto) {
-        UserDTO user = userClient.getById(dto.getUserId())
-            .orElseThrow(() -> new ServiceException("USER_NOT_FOUND"));
-        // ...
-    }
-}
-```
-
-### 3.2 复制平台 Entity 到二开库
-
-#### ❌ 反模式
-
-```java
-// 二开项目 src/main/java 下复制了一份
-package com.example.seconddev.entity;
-// ⚠️ 与 com.meritdata.cloud.platform.entity.User 字段 99% 相同
-public class User {
-    private Long id;
-    private String userName;
-    private String password;  // 💥 字段不同步、绕过安全审计
-    // ...
-}
-```
-
-#### ✅ 正模式
-
-- 接收 DTO 而非 Entity
-- 业务字段放二开实体，平台字段引用 DTO
-- 用 MapStruct / 手工转换
-
-```java
-// 二开业务表
-@Entity
-@Table(name = "t_order")
-public class Order {
-    private Long id;
-    private Long applicantUserId;  // 平台 user_id 快照
-}
-
-// 装配时用 DTO
-@Service
-public class OrderAssembler {
-    public OrderVO toVO(Order order) {
-        OrderVO vo = new OrderVO();
-        vo.setOrderId(order.getId());
-        vo.setApplicantUserId(order.getApplicantUserId());
-        // 姓名通过 Feign 装配后单独设
-        return vo;
-    }
-}
-```
-
-### 3.3 同 JVM 例外（不要一刀切）
-
-**场景**：二开代码与平台模块部署在同一个 JVM 进程 + 显式引入 `cloud-system-manage-module`。
-
-```java
-// ✅ 同 JVM 时，可以直接用平台本地 Bean（如 IDamService）
-// 判定方法：见 [same-jvm.md](same-jvm.md)
-@Service
-public class OrderService {
-    @Autowired
-    private IDamService damService;  // 平台本地服务，同 JVM 可用
-
-    public void createOrder(OrderDTO dto) {
-        DamUser user = damService.getCurrentUser();  // OK
-        // ...
-    }
-}
-```
-
-**注意**：即使是同 JVM，**仍禁止**：
-- ❌ 直连平台数据库
-- ❌ 复制平台 Entity 到二开库
-- ❌ 跨库 JOIN
-
-### 根因
-
-- **跨 JVM 部署后注入失败**：独立部署场景下 @Autowired 平台 Bean 无法注入，启动直接报错
-- **绕过安全审计**：平台 Entity 含密码、密级等敏感字段，复制后审计失效
-- **同步成本**：平台升级字段变化，二开复制版必须同步，违反"业务自治"原则
-
-### 真实踩坑案例
-
-- **2025-12**：某二开项目从"与平台同 JVM"重构为"独立部署"，因 `@Autowired UserRepository` 启动失败，回滚 1 天
-- **2026-04**：某二开复制了 `PF_USER` 实体到二开库，平台密码策略升级后该实体字段未同步，安全审计告警
-
----
-
-## 4. 不掩盖平台故障（铁律 4）
-
-**铁律来源**：[rules §八.1](../../../../rules/code-dev-rules.md#81-数据访问边界data-boundary)
-
-### 4.1 catch + return emptyList 吞异常
-
-#### ❌ 反模式
-
-```java
-public List<UserVO> listUsers() {
-    try {
-        return userClient.listAll();
-    } catch (Exception e) {  // 💥 任何异常都吞
-        return Collections.emptyList();
-    }
-}
-```
-
-#### ✅ 正模式
-
-```java
-public List<UserVO> listUsers() {
-    try {
-        List<UserDTO> dtos = userClient.listAll();
-        return dtos.stream().map(this::toVO).collect(Collectors.toList());
-    } catch (FeignException.ServiceUnavailable e) {
-        log.error("User 服务不可用", e);
-        throw new ServiceException("USER_UNAVAILABLE", "用户服务暂时不可用", e);
-    } catch (FeignException e) {
-        log.error("User 服务调用失败, status={}", e.status(), e);
-        throw new ServiceException("USER_FETCH_FAIL", "用户查询失败", e);
-    }
-}
-```
-
-### 4.2 默认值掩盖真实失败
-
-#### ❌ 反模式
-
-```java
-public String getUserName(Long userId) {
-    try {
-        return userClient.getById(userId).getName();
-    } catch (Exception e) {
-        return "未知用户";  // 💥 用户看到错误数据，运维看不到告警
-    }
-}
-```
-
-#### ✅ 正模式
-
-```java
-public String getUserName(Long userId) {
-    try {
-        UserDTO user = userClient.getById(userId);
-        return user != null ? user.getName() : "用户不存在";
-    } catch (FeignException e) {
-        log.error("查询用户失败, userId={}", userId, e);
-        throw new ServiceException("USER_FETCH_FAIL", "用户查询失败", e);
-    }
-}
-```
-
-### 4.3 业务层兜底必须可观测
-
-#### ✅ 允许场景（但要可观测）
-
-```java
-// 场景：消息通知失败不应阻塞主业务
-public void notifyAfterOrder(Order order) {
-    try {
-        messageClient.send(order.getApplicantUserId(), "订单创建成功");
-    } catch (FeignException e) {
-        log.warn("消息发送失败, orderId={}, reason={}", order.getId(), e.getMessage());
-        // ✅ 不阻塞主业务，但记录日志供运维监控
-        // ✅ 不返回 emptyList，调用方知道通知失败（可选重试）
-    }
-}
-```
-
-### 根因
-
-- 平台故障被吞 → 上游业务正常运行，运维看不到告警，平台恢复时间延长
-- 错误数据伪装成功 → 用户/管理员基于错误数据做决策
-- 缺乏重试依据 → 调用方无法决定是否重试
-
-### 真实踩坑案例
-
-- **2026-02**：某二开项目 `catch + return emptyList`，平台 User 服务宕机 3 小时，前端无任何提示，运维仅通过用户反馈才发现
-- **2026-05**：某二开把 Feign 失败默认成"未知用户"，管理员误以为权限系统出问题
-
----
-
-## 5. 速查表
-
-| 铁律 | 反模式关键特征 | 正模式关键特征 |
-|------|--------------|--------------|
-| 不映射 PF_ | `@TableName("PF_*")`、`@Table(name="cloud.PF_*")` | 二开库建 `t_*` 表 + Feign 装配 |
-| 不跨库 JOIN | `JOIN cloud.PF_*` | 业务库内 JOIN + Feign 装配 |
-| 不分页 Feign | `for + userClient.getById` | `userClient.listByIds` 批量 |
-| 不复制 Entity | `import 平台 Entity`、`@Autowired UserRepository` | `import UserDTO`、`UserClient` Feign |
-| 同 JVM 例外 | 一刀切禁止 | 显式 `cloud-system-manage-module` 依赖可注入本地 Bean |
-| 不掩盖异常 | `catch + return emptyList` | `throw new ServiceException` |
-| 默认值兜底 | `return "未知用户"` | 上抛 + 调用方决策 |
-
----
-
-## 6. 关联阅读
-
-- [validate-rules.md](validate-rules.md) — CI 自动化校验命令
-- [same-jvm.md](same-jvm.md) — 同 JVM 例外判定方法
-- [cloud-tables.md](cloud-tables.md) — 平台表清单与对应 Feign
-- [rules/code-dev-rules.md §八.1](../../../../rules/code-dev-rules.md#81-数据访问边界data-boundary) — 铁律摘要
-- [code-spec anti-patterns](../meritdata-platform-code-spec/references/anti-patterns.md) — 编码层反模式
-- [domain-model anti-patterns](../meritdata-platform-domain-model/references/anti-patterns.md) — 业务建模反模式

package/skills/meritdata-platform-data-boundary/references/cloud-tables.md

@@ -1,32 +0,0 @@
-# 平台表清单与对应 Feign（cloud-tables）
-
-> **v2.6.1 补建**：v2.5.0 拆分时遗漏创建。
-> **重要**：二开业务库**禁止** `@TableName("PF_xxx")` 或跨库 JOIN `PF_*` 表（违反铁律 1.1）。所有平台数据访问必须走 Feign Client 或同 JVM Service。
-
-## 一、平台表前缀清单（PF_*）
-
-| 表名 | 中文 | 对应 Feign / Service |
-|------|------|---------------------|
-| `PF_USER` | 用户 | `IUserService`（同 JVM） / `UserClient.listByIds` |
-| `PF_ORG` | 组织 | `IOrgService` / `OrgClient` |
-| `PF_DEPT` | 部门 | `IOrgService.getDeptTree` |
-| `PF_ROLE` | 角色 | `IRoleService` / `RoleClient` |
-| `PF_RESOURCE` | 资源 | `IResourceService` / `PermissionClient` |
-| `PF_DICT` / `PF_DICT_ITEM` | 字典 | `ILookupService` / `LookupClient` |
-| `PF_LOOKUP` | Lookup | `ILookupService` |
-| `PF_LOGIN_LOG` / `PF_OPERATION_LOG` | 日志 | `IOperationLogService` |
-| `PF_ATTACHMENT` | 附件 | `IAttachmentService` |
-| `PF_MESSAGE` | 消息 | `IMessageCenterService` |
-
-## 二、平台表 → Feign 映射原则
-
-```
-业务表（PF_）→ ❌ 禁止 @TableName 直连
-业务表（PF_）→ ✅ 走 IUserService / UserClient
-```
-
-## 三、参考
-
-- [anti-patterns.md](anti-patterns.md) — §1 不映射 PF_ 前缀平台表
-- [validate-rules.md](validate-rules.md) — §3.1 检测 PF_ 前缀引用
-- [rules/meritdata-platform-data-boundary.md §3.1](../../../../rules/meritdata-platform-data-boundary.md) — CI 校验命令

package/skills/meritdata-platform-data-boundary/references/same-jvm.md

@@ -1,52 +0,0 @@
-# 同 JVM 例外判定（same-jvm）
-
-> **v2.6.1 补建**：v2.5.0 拆分时遗漏创建。配套主文档：[anti-patterns.md](anti-patterns.md) §6。
-
-## 一、什么算"同 JVM"
-
-| 判定项 | 同 JVM ✅ | 跨 JVM ❌ |
-|--------|----------|----------|
-| 部署形式 | 二开模块与平台模块**同进程**启动 | 二开模块独立部署 / 微服务 |
-| 依赖 | 显式引入 `cloud-system-manage-module` | 通过 Feign Client 调用 |
-| 数据源 | 共享平台数据源 | 独立数据源（即使表结构相同）|
-
-## 二、判定方法
-
-```bash
-# 1. 看 pom.xml 是否引入 platform-system-module
-grep -E 'cloud-system-manage-module' pom.xml
-
-# 2. 看 application.yml 是否共享数据源
-grep -E 'spring.datasource' application.yml
-
-# 3. 看启动类是否扫描平台包
-grep -E '@ComponentScan.*com.meritdata.cloud' 启动类.java
-```
-
-3 个条件**全部满足** → 同 JVM；任一不满足 → 跨 JVM。
-
-## 三、同 JVM 允许 vs 禁止
-
-| 行为 | 同 JVM | 跨 JVM |
-|------|--------|--------|
-| 直接注入 `IUserService` / `IDamService` 等平台 Service | ✅ | ❌ |
-| Feign Client 调平台 | ✅（推荐）| ✅ |
-| `@Autowired` 平台 Repository | ❌（违反铁律 1.1）| ❌ |
-| 直连平台数据库 | ❌（违反铁律 1.1）| ❌ |
-| 跨库 JOIN 平台表 | ❌（违反铁律 1.1）| ❌ |
-| 复制平台 Entity | ❌（违反铁律 1.3）| ❌ |
-
-## 四、灰度场景（部分同 JVM）
-
-部分模块同 JVM + 部分模块独立时：
-
-- **统一走 Feign**：阻力最小，fallback 走本地
-- **同 JVM 也写 Feign**：防止后续拆分时大改
-
-详见：`meritdata-platform-data-access` SKILL §关键提醒。
-
-## 五、参考
-
-- [anti-patterns.md](anti-patterns.md) — 反模式案例 + §6 同 JVM 例外
-- [validate-rules.md](validate-rules.md) — §3.1 跨库 JOIN 检测 + §6 同 JVM 检测
-- [rules/meritdata-platform-data-boundary.md §6.1](../../../../rules/meritdata-platform-data-boundary.md) — 同 JVM 例外硬规则