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

package/skills/meritdata-platform-data-access-review/references/guide.md

@@ -1,228 +0,0 @@
-# 数据访问审查清单（data-access-review）
-
-> 4 条铁律逐条审查清单。违反即阻断 PR。
-
----
-
-## 1. 4 条铁律速查
-
-| # | 铁律 | 检测方法 | 严重度 |
-|---|------|---------|--------|
-| §1.1 | 不映射 PF_ 前缀平台表 | grep `@TableName("PF_` | 🔴 阻断 |
-| §1.2 | 不分页循环逐条 Feign | 代码审查 + AST | 🔴 阻断 |
-| §1.3 | 不复制平台 Entity | grep `import 平台 Entity` | 🔴 阻断 |
-| §1.4 | 不掩盖平台故障 | grep `catch.*emptyList` | 🔴 阻断 |
-
-详见 [rules/meritdata-platform-data-boundary.md](../../rules/meritdata-platform-data-boundary.md)。
-
----
-
-## 2. §1.1 检查清单 — 不映射 PF_ 表
-
-### 2.1 grep 检测
-
-```bash
-grep -rE '@TableName\("PF_' src/main/java/ \
-  && echo "❌ 发现 PF_ 映射" && exit 1 \
-  || echo "✅ 通过"
-```
-
-### 2.2 跨库 JOIN
-
-```bash
-grep -rE 'JOIN\s+PF_' src/main/resources/mapper/ \
-  && echo "❌ 跨库 JOIN" && exit 1 \
-  || echo "✅ 通过"
-```
-
-### 2.3 人工审查清单
-
-- [ ] 没有 `@TableName("PF_xxx")`
-- [ ] 没有跨库 JOIN（`JOIN PF_xxx`）
-- [ ] 没有 `@Column` 映射到 PF_ 字段
-- [ ] Mapper XML 没有跨库 SQL
-- [ ] **唯一例外**：同 JVM 平台模块（已声明依赖 cloud-system-manage-module）
-
-### 2.4 正确模式
-
-```java
-// ✅ 正确：业务库 t_xxx
-@TableName("t_purchase_order")
-public class PurchaseOrder { ... }
-
-// ✅ 正确：跨平台表通过 Feign
-@FeignClient(name = "cloud-system-manage")
-public interface IUserClient {
-    @GetMapping("/users/{id}")
-    UserDTO getById(@PathVariable String id);
-}
-```
-
----
-
-## 3. §1.2 检查清单 — 不分页循环 Feign
-
-### 3.1 AST 检测（伪代码）
-
-```python
-# 检测模式
-for (Page page : pages) {
-    for (Data data : page.getData()) {
-        Feign.method(data.getId());  # N+1
-    }
-}
-```
-
-### 3.2 人工审查清单
-
-- [ ] 没有 `for (Data d : list) { feignClient.method(d.getId()); }`
-- [ ] 批量操作走 `listByIds` / `batchGet`
-- [ ] 内存 join 替换循环 Feign
-- [ ] 复杂聚合查询在服务端完成
-
-### 3.3 正确模式
-
-```java
-// ❌ 反例
-for (Order order : orderList) {
-    UserDTO user = userClient.getById(order.getUserId());
-    order.setUserName(user.getRealName());
-}
-
-// ✅ 正确：批量装配
-List<String> userIds = orderList.stream()
-    .map(Order::getUserId).distinct()
-    .collect(Collectors.toList());
-Map<String, UserDTO> userMap = userClient.listByIds(userIds).stream()
-    .collect(Collectors.toMap(UserDTO::getUserId, Function.identity()));
-
-orderList.forEach(o ->
-    o.setUserName(userMap.get(o.getUserId()).getRealName())
-);
-```
-
----
-
-## 4. §1.3 检查清单 — 不复制平台 Entity
-
-### 4.1 grep 检测
-
-```bash
-grep -r 'import com.meritdata.cloud.platform.entity' src/main/java/com/example/ \
-  && echo "❌ 二开项目不应 import 平台 Entity" && exit 1 \
-  || echo "✅ 通过"
-```
-
-### 4.2 人工审查清单
-
-- [ ] 没有 `import com.meritdata.cloud.platform.entity.*`
-- [ ] 没有 `import com.meritdata.cloud.*.entity.*`（同 JVM 例外）
-- [ ] 通过 DTO 转换 / Feign 接收
-- [ ] 没有 `@Entity public class UserEntity extends 平台 User {}`
-
-### 4.3 正确模式
-
-```java
-// ✅ 正确：DTO 转换
-@Data
-public class UserDTO {
-    private String userId;
-    private String realName;
-    // ... 不暴露平台 Entity
-}
-
-// Feign 接收 DTO
-@FeignClient(name = "cloud-system-manage")
-public interface IUserClient {
-    @GetMapping("/api/v1/users/{id}")
-    UserDTO getById(@PathVariable String id);
-}
-```
-
----
-
-## 5. §1.4 检查清单 — 不掩盖平台故障
-
-### 5.1 grep 检测
-
-```bash
-grep -rn 'catch.*Exception.*emptyList\|catch.*Exception.*Collections.empty' src/main/java/ \
-  | grep -v 'test/' \
-  && echo "⚠️ 疑似空集合掩盖异常" \
-  || echo "✅ 通过"
-```
-
-### 5.2 人工审查清单
-
-- [ ] 没有 `catch (Exception e) { return Collections.emptyList(); }`
-- [ ] Feign 失败显式抛 `ServiceException`
-- [ ] 不吞掉异常（`catch (e) {}`）
-- [ ] Fallback 必须有日志 + 监控 + 业务降级
-
-### 5.3 正确模式
-
-```java
-// ❌ 反例
-try {
-    return userClient.listByIds(ids);
-} catch (Exception e) {
-    return Collections.emptyList();  // 掩盖故障
-}
-
-// ✅ 正确
-try {
-    return userClient.listByIds(ids);
-} catch (FeignException.ServiceUnavailable e) {
-    log.error("平台用户服务不可用", e);
-    alertService.send("USER_SERVICE_UNAVAILABLE");
-    throw new ServiceException("USER_SERVICE_UNAVAILABLE");
-}
-```
-
----
-
-## 6. 审查流程
-
-### 6.1 PR Review
-
-1. 跑 CI 扫描脚本（[ci-scan.md](ci-scan.md)）
-2. 人工审查 4 铁律
-3. 标注严重度（🔴/🟠/🟢）
-4. 🔴 阻断合并
-5. 🟠 必须修复
-6. 🟢 建议优化
-
-### 6.2 评审模板
-
-```markdown
-## 数据访问审查
-
-### §1.1 PF_ 平台表
-- [ ] 无 PF_ 映射
-- [ ] 无跨库 JOIN
-- [ ] 同 JVM 例外已声明
-**结论**：✅ 通过 / ❌ 阻断
-
-### §1.2 分页循环 Feign
-- [ ] 无循环 Feign
-- [ ] 批量装配
-- [ ] 内存 join
-**结论**：✅ 通过 / ❌ 阻断
-
-### §1.3 平台 Entity
-- [ ] 无平台 Entity import
-- [ ] DTO 转换
-**结论**：✅ 通过 / ❌ 阻断
-
-### §1.4 空集合掩盖
-- [ ] 无空集合掩盖
-- [ ] 显式抛异常
-**结论**：✅ 通过 / ❌ 阻断
-```
-
-## 7. 关联阅读
-
-- [ci-scan.md](ci-scan.md) — CI 扫描脚本
-- [anti-patterns.md](anti-patterns.md) — 反模式库
-- [rules/meritdata-platform-data-boundary.md](../../rules/meritdata-platform-data-boundary.md)
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-boundary/SKILL.md

@@ -1,41 +0,0 @@
----
-name: meritdata-platform-data-boundary
-description: |
-  数据访问边界方法论。约束 MeritData Cloud 平台库与二开业务库的数据隔离：禁止二开业务库 @TableName("PF_*") / 跨库 JOIN / 复制平台 Entity / 分页循环 Feign / catch 吞异常。
-  触发场景：二开库数据访问代码生成、PR 提交前、CI 扫描时。
-  何时不用：平台模块（与平台同 JVM）代码修改；前端代码；纯文档生成。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: high
-  layer: L2
-  sub-layer: L2-M
-  stack: methodology
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 数据访问边界方法论（data-boundary）
-
-## 触发
-- 二开库准备 `@TableName(...)` / `CREATE TABLE` / Repository 设计
-- 准备写 `for + userClient.getById` 类循环 Feign 代码
-- PR 评审涉及跨服务数据访问
-- CI 扫描需拦截平台 Entity import / 空集合掩盖异常
-
-## 不触发
-- 平台模块（与平台同 JVM）的代码 → 用 `meritdata-platform-entities` / `services`
-- 前端代码 → 不涉及数据库访问
-- 纯文档生成 / 测试代码（test/ 目录豁免）
-
-## 前置约束
-- 4 条铁律见 [rules/code-dev-rules.md §8.1](../../rules/code-dev-rules.md#81-数据访问边界data-boundary)
-- 同 JVM 例外：显式引入 `cloud-system-manage-module` 时可注入平台本地 Bean（仍禁跨库 JOIN / 复制 Entity）
-
-## 路由
-- 反模式案例 + 正模式代码 → [references/anti-patterns.md](references/anti-patterns.md)
-- 平台表清单与对应 Feign → [references/cloud-tables.md](references/cloud-tables.md)
-- 同 JVM 判定方法 → [references/same-jvm.md](references/same-jvm.md)
-- CI 检测命令 → [references/validate-rules.md](references/validate-rules.md)