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

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

@@ -0,0 +1,519 @@
+# 反模式 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

@@ -0,0 +1,32 @@
+# 平台表清单与对应 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

@@ -0,0 +1,52 @@
+# 同 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 例外硬规则