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

package/skills/meritdata-platform-data-boundary/references/validate-rules.md

@@ -0,0 +1,341 @@
+# CI 校验命令（data-boundary）
+
+> **本文件与 [anti-patterns.md](anti-patterns.md) 一一对应**。每条铁律给出可在 CI 中直接执行的检测命令。**任一 🔴 阻断命令失败即拒绝合并**。
+>
+> **与 code-spec 的差异**：本文件聚焦"二开库 vs 平台库"的边界，code-spec 聚焦"编码层反模式"。两者铁律有部分重叠（如循环不调 Feign、catch 不吞异常），但**侧重不同**——本文件强调"跨库/跨服务"，code-spec 强调"循环/异常处理"。
+
+## 使用方式
+
+```bash
+bash tools/skill-vetter/run.sh data-boundary
+```
+
+---
+
+## 1. 不映射 `PF_` 前缀平台表（🔴 阻断）
+
+### 1.1 检测二开库 @TableName / @Table 映射 PF_ 表
+
+```bash
+SRC="${SRC:-src/main/java}"
+RES="${RES:-src/main/resources}"
+
+check "1.1 二开库映射 PF_ 表" \
+  "! grep -rEn '@TableName\\s*\\(\\s*\"PF_|:\\s*\"PF_|:\\s*cloud\\.PF_' $SRC --include='*.java' | \
+       grep -v '// ALLOW-platform-table'" \
+  block
+```
+
+### 1.2 检测二开库 CREATE TABLE PF_
+
+```bash
+check "1.2 二开库建 PF_ 表" \
+  "! grep -rEn 'CREATE TABLE\\s+PF_' $RES 2>/dev/null" \
+  block
+```
+
+### 1.3 检测跨库 JOIN 平台表
+
+```bash
+check "1.3 跨库 JOIN 平台表" \
+  "! grep -rEn 'JOIN\\s+[a-zA-Z_]*\\.PF_|:\\s*PF_' $RES 2>/dev/null | grep -i 'join'" \
+  block
+```
+
+更严格的检测（含 MyBatis 全限定名）：
+
+```bash
+check "1.3b 跨 schema JOIN" \
+  "! grep -rEn 'JOIN\\s+cloud\\.' $RES 2>/dev/null" \
+  block
+```
+
+### 1.4 检测 Controller 直连 cloud 库
+
+```bash
+check "1.4 Controller 注入 cloud DataSource" \
+  "! grep -rEn '@Qualifier\\s*\\(\\s*\"(cloud|platform)' $SRC --include='*.java'" \
+  block
+
+check "1.4b Controller 接受 SQL 参数" \
+  "! grep -rEn '@RequestBody\\s+String\\s+[a-z][a-zA-Z]*\\s*;' $SRC --include='*.java' | grep -i 'sql\|query'" \
+  block
+```
+
+---
+
+## 2. 不分页循环逐条 Feign（🔴 阻断）
+
+### 2.1 检测 N+1：for 循环内调 getById
+
+```bash
+check "2.1 for 循环内调 getById" \
+  "! grep -rEn '(for|while)\\s*\\(' $SRC --include='*.java' -A 3 | \
+       grep -E '\\.(getById|getOne|findOne)\\(' | \
+       grep -E 'Client\\.|Feign'" \
+  block
+```
+
+### 2.2 检测分页循环 Feign
+
+```bash
+check "2.2 分页循环 Feign" \
+  "! grep -rEn 'for\\s*\\(\\s*int\\s+page\\s*=' $SRC --include='*.java' -A 5 | \
+       grep -E '\\.(getById|getOne)\\(' | \
+       grep -E 'Client\\.'" \
+  block
+```
+
+### 2.3 兜底检测：Feign 客户端使用模式
+
+```bash
+# 列出所有 Client.getById 调用，应远少于 listByIds
+WARN_PATTERN=$(grep -rEn '\\.getById\\(' $SRC --include='*.java' | wc -l)
+LIST_PATTERN=$(grep -rEn '\\.listByIds\\(' $SRC --include='*.java' | wc -l)
+echo "📊 getById 调用: $WARN_PATTERN 次，listByIds 调用: $LIST_PATTERN 次"
+if [ "$WARN_PATTERN" -gt "$((LIST_PATTERN * 3))" ]; then
+  echo "⚠️ getById 过多，建议批量改造"
+fi
+```
+
+---
+
+## 3. 不复制平台 Entity/Repository（🔴 阻断）
+
+### 3.1 检测二开代码 import 平台 Entity
+
+```bash
+check "3.1 二开 import 平台 Entity" \
+  "! grep -rEn 'import\\s+com\\.meritdata\\.cloud\\.platform\\.entity\\.' $SRC --include='*.java' | \
+       grep -v '// ALLOW-platform-entity'" \
+  block
+```
+
+**例外**：同 JVM 项目（依赖 `cloud-system-manage-module`）可豁免。判定方法见 [same-jvm.md](same-jvm.md)。
+
+### 3.2 检测二开 @Autowired 平台 Repository
+
+```bash
+check "3.2 @Autowired 平台 Repository" \
+  "! grep -rEn '@Autowired\\s+(private\\s+)?[A-Z][a-zA-Z]*Repository\\s' $SRC --include='*.java' | \
+       grep -v '// ALLOW-platform-repo'" \
+  block
+```
+
+更严格的检测（按包名）：
+
+```bash
+check "3.2b @Autowired 平台包下的 Bean" \
+  "! grep -rEn 'private\\s+[A-Z][a-zA-Z]*\\s+[a-z][a-zA-Z]*\\s*;\\s*$' $SRC --include='*.java' | \
+       grep -B 1 | grep -E '@Autowired.*com\\.meritdata\\.cloud\\.platform'" \
+  block
+```
+
+### 3.3 检测复制平台 Entity 类
+
+```bash
+# 检测二开 entity 包下类名与平台 entity 重名
+check "3.3 实体类重名平台实体" \
+  "! comm -12 <(grep -rhE 'class\\s+[A-Z][a-zA-Z]*\\s' src/main/java/com/example/seconddev/entity/ 2>/dev/null | \
+            grep -oE 'class\\s+[A-Z][a-zA-Z]*' | sort -u | sed 's/class //') \
+          <(grep -rhE 'class\\s+[A-Z][a-zA-Z]*\\s' $SRC 2>/dev/null | \
+            grep 'com.meritdata.cloud.platform.entity' | \
+            grep -oE 'class\\s+[A-Z][a-zA-Z]*' | sort -u | sed 's/class //')" \
+  warn
+```
+
+---
+
+## 4. 不掩盖平台故障（🔴 阻断）
+
+### 4.1 检测 catch + return emptyList 吞异常
+
+```bash
+check "4.1 catch + return emptyList" \
+  "! grep -rEn 'catch\\s*\\(\\s*(Exception|Throwable)\\s+[a-zA-Z]+\\s*\\)\\s*\\{[^}]*return\\s+Collections\\.emptyList' $SRC --include='*.java'" \
+  block
+```
+
+更宽松版本（含 catch + return null）：
+
+```bash
+check "4.1b catch + return null 吞异常" \
+  "! grep -rEn 'catch\\s*\\([^)]+\\)\\s*\\{[^}]*return\\s+null\\s*;\\s*\\}' $SRC --include='*.java'" \
+  warn
+```
+
+### 4.2 检测 catch 后无日志
+
+```bash
+check "4.2 catch 块无日志" \
+  "! grep -rEnA 5 'catch\\s*\\([^)]+\\)\\s*\\{' $SRC --include='*.java' | \
+       grep -E '^\\s*\\}\\s*$' | \
+       # 找出每个 catch 块，检查是否包含 log
+       grep -v 'log\\.' | head" \
+  warn
+```
+
+**精确版本**（逐 catch 检查）：
+
+```bash
+python3 << 'EOF'
+import re, os, sys
+issues = []
+for root, _, files in os.walk('src/main/java'):
+    for f in files:
+        if not f.endswith('.java'):
+            continue
+        path = os.path.join(root, f)
+        content = open(path, encoding='utf-8').read()
+        # 匹配 catch 块
+        for m in re.finditer(r'catch\s*\([^)]+\)\s*\{([^}]*)\}', content):
+            body = m.group(1)
+            # 如果 body 为空或只有注释，标记
+            stripped = re.sub(r'//.*$|/\*.*?\*/', '', body, flags=re.DOTALL).strip()
+            if not stripped:
+                line_no = content[:m.start()].count('\n') + 1
+                issues.append(f'{path}:{line_no}: 空 catch 块')
+
+if issues:
+    print('❌ 空 catch 块检测：')
+    for i in issues: print('  ' + i)
+    sys.exit(1)
+else:
+    print('✅ pass')
+EOF
+```
+
+### 4.3 允许的兜底模式（仅供参考，不阻断）
+
+```java
+// ✅ 允许：catch + log.warn + 不阻塞主业务（消息通知类）
+try {
+    messageClient.send(...);
+} catch (FeignException e) {
+    log.warn("消息发送失败", e);
+    // 不阻塞主业务，但记录日志供监控
+}
+```
+
+---
+
+## 5. 综合脚本（data-boundary）
+
+```bash
+#!/bin/bash
+# tools/skill-vetter/run.sh data-boundary
+set -e
+
+SRC="${SRC:-src/main/java}"
+RES="${RES:-src/main/resources}"
+EXIT=0
+
+check() {
+  local label="$1"
+  local pattern="$2"
+  local level="${3:-warn}"
+  echo "▶ [$level] $label"
+  if eval "$pattern" >/dev/null 2>&1; then
+    echo "  ✅ pass"
+  else
+    echo "  ❌ FAIL"
+    [ "$level" = "block" ] && EXIT=1
+  fi
+}
+
+echo "===== data-boundary ====="
+
+# 铁律 1：不映射 PF_
+check "1.1 二开库映射 PF_ 表" \
+  "! grep -rEn '@TableName\\s*\\(\\s*\"PF_|:\\s*\"PF_' $SRC --include='*.java' | grep -v 'ALLOW-platform-table'" \
+  block
+check "1.2 二开库建 PF_ 表" \
+  "! grep -rEn 'CREATE TABLE\\s+PF_' $RES 2>/dev/null" \
+  block
+check "1.3 跨 schema JOIN" \
+  "! grep -rEn 'JOIN\\s+cloud\\.' $RES 2>/dev/null" \
+  block
+check "1.4 Controller 注入 cloud DataSource" \
+  "! grep -rEn '@Qualifier\\s*\\(\\s*\"(cloud|platform)' $SRC --include='*.java'" \
+  block
+
+# 铁律 2：不分页循环 Feign
+check "2.1 for 循环内调 getById" \
+  "! grep -rEn '(for|while)\\s*\\(' $SRC --include='*.java' -A 3 | grep -E '\\.(getById|getOne|findOne)\\(' | grep -E 'Client\\.'" \
+  block
+check "2.2 分页循环 Feign" \
+  "! grep -rEn 'for\\s*\\(\\s*int\\s+page\\s*=' $SRC --include='*.java' -A 5 | grep -E '\\.(getById|getOne)\\('" \
+  block
+
+# 铁律 3：不复制平台 Entity
+check "3.1 二开 import 平台 Entity" \
+  "! grep -rEn 'import\\s+com\\.meritdata\\.cloud\\.platform\\.entity\\.' $SRC --include='*.java' | grep -v 'ALLOW-platform-entity'" \
+  block
+check "3.2 @Autowired 平台 Repository" \
+  "! grep -rEn '@Autowired\\s+(private\\s+)?[A-Z][a-zA-Z]*Repository\\s' $SRC --include='*.java' | grep -v 'ALLOW-platform-repo'" \
+  block
+
+# 铁律 4：不掩盖异常
+check "4.1 catch + return emptyList" \
+  "! grep -rEn 'catch\\s*\\(\\s*(Exception|Throwable)\\s+[a-zA-Z]+\\s*\\)\\s*\\{[^}]*return\\s+Collections\\.emptyList' $SRC --include='*.java'" \
+  block
+
+exit $EXIT
+```
+
+---
+
+## 6. 同 JVM 例外判定
+
+详见 [same-jvm.md](same-jvm.md)。**关键判定**：
+
+```bash
+# 检测项目是否同 JVM
+check "同 JVM 判定" \
+  "grep -q 'cloud-system-manage-module' pom.xml 2>/dev/null || \
+   grep -q 'cloud-system-manage-module' build.gradle 2>/dev/null" \
+  info
+```
+
+如果输出"未引入 cloud-system-manage-module"，则 §3.1 / §3.2 检测**必须通过**；如有违反 → 🔴 阻断。
+
+---
+
+## 7. CI 接入示例（GitHub Actions）
+
+```yaml
+name: skill-vetter
+on: [pull_request]
+
+jobs:
+  data-boundary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 检测 PF_ 映射
+        run: |
+          ! grep -rEn '@TableName\s*\(\s*"PF_' src/main/java/ || (echo "❌ 阻断"; exit 1)
+
+      - name: 检测分页循环 Feign
+        run: |
+          ! grep -rEn 'for\s*\(\s*int\s+page\s*=' src/main/java/ -A 5 | grep -E '\.(getById|getOne)\(' || (echo "❌ 阻断"; exit 1)
+
+      - name: 检测 catch 吞异常
+        run: |
+          ! grep -rEn 'catch\s*\([^)]+\)\s*\{[^}]*return\s+Collections\.emptyList' src/main/java/ || (echo "❌ 阻断"; exit 1)
+
+      - name: 报告豁免
+        run: |
+          echo "📋 豁免清单："
+          grep -rEn 'ALLOW-' src/main/java/ || echo "  (无)"
+```
+
+---
+
+## 8. 关联阅读
+
+- [anti-patterns.md](anti-patterns.md) — 反模式案例 + 正模式代码
+- [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) — 铁律摘要

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

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-data-classification
+description: |
+  数据密级管理。行级权限 / 列级权限 / 字段脱敏；密级标签（公开/内部/秘密/机密）；基于密级的访问控制；与 DAM 配合。
+  触发场景：业务数据需要按密级过滤；敏感字段需要脱敏展示；不同角色看到不同字段。
+  何时不用：纯按钮权限 → 用 permission；菜单权限 → 用 menu-config。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: high
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 数据密级（data-classification）
+
+## 触发
+- 业务表字段需要按密级脱敏（手机号/身份证/银行卡）
+- 行级权限（按组织/部门过滤）
+- 列级权限（不同角色看到不同字段）
+- 数据导出需要按密级审计
+
+## 不触发
+- 按钮权限 → 用 `meritdata-platform-permission`
+- 菜单权限 → 用 `meritdata-platform-menu-config`
+- 平台资源权限点 → 用 `meritdata-platform-org-user-api` 的 IDamService
+
+## 前置约束
+- 密级策略由平台统一管理，二开不能绕过
+- 敏感字段脱敏**必须**走平台（不自己写脱敏逻辑）
+- 详见 [rules/security-rules.md §三](../../rules/security-rules.md) 敏感信息保护
+
+## 路由
+- 密级标签 + 行/列权限 → [references/guide.md](references/guide.md)
+- 字段脱敏 + 注解方式 → [references/masking.md](references/masking.md)
+- Hibernate 字段密级过滤（@EnableDataSecretFilter）→ [references/hibernate-filter.md](references/hibernate-filter.md)
+- 与 DAM 权限集成 → [references/integration-with-dam.md](references/integration-with-dam.md)

package/skills/meritdata-platform-data-classification/references/guide.md

@@ -0,0 +1,179 @@
+# 数据密级管理指南（data-classification）
+
+> 行级权限 / 列级权限 / 字段脱敏。密级标签由平台统一管理。
+
+---
+
+## 1. 密级标签
+
+平台支持的密级：
+
+| 密级 | code | 含义 |
+|------|------|------|
+| 公开 | `PUBLIC` | 所有人都可见 |
+| 内部 | `INTERNAL` | 内部员工可见 |
+| 秘密 | `CONFIDENTIAL` | 指定人员/角色可见 |
+| 机密 | `SECRET` | 严格授权可见 |
+
+## 2. 行级权限
+
+### 2.1 场景
+
+员工只能看本部门的订单；部门经理可看本部门全部订单；总经理可看全部。
+
+### 2.2 配置（平台 DAM）
+
+在平台 DAM 配置：
+- 资源：`order:view`
+- 范围规则：`org_id IN (当前用户 org_id 及其子组织)`
+
+### 2.3 业务代码（自动注入）
+
+```java
+@GetMapping("/orders")
+public List<OrderVO> list() {
+    // 平台自动注入过滤条件，业务代码无感知
+    return orderService.list();
+}
+```
+
+平台通过 MyBatis Interceptor 或 JPA Filter 自动追加 SQL 过滤条件。
+
+### 2.4 ❌ 反例：业务代码自己过滤
+
+```java
+// ❌ 错：业务代码自己实现行级过滤
+@GetMapping("/orders")
+public List<OrderVO> list() {
+    UserDTO user = SecurityUtils.getCurrentUser();
+    String orgId = user.getOrgId();
+    return orderRepository.findByOrgId(orgId);  // 自己写过滤逻辑
+}
+```
+
+✅ 应该用平台 DAM，二开不重复实现。
+
+## 3. 列级权限
+
+### 3.1 场景
+
+普通员工看不到订单的"成本"字段；财务可看。
+
+### 3.2 配置（平台 DAM）
+
+- 资源：`order.cost:view`
+- 授权：财务角色
+
+### 3.3 业务代码（注解）
+
+```java
+@Data
+public class OrderVO {
+    private String orderNo;
+    private BigDecimal amount;     // 所有人可见
+    @SensitiveField("order.cost:view")
+    private BigDecimal cost;       // 仅财务可见
+}
+```
+
+### 3.4 输出处理
+
+```java
+public OrderVO toVO(Order order) {
+    OrderVO vo = new OrderVO();
+    vo.setOrderNo(order.getOrderNo());
+    vo.setAmount(order.getAmount());
+    // cost 字段由平台 SensitiveFieldHandler 自动处理（无权限 → null）
+    vo.setCost(order.getCost());
+    return vo;
+}
+```
+
+## 4. 字段脱敏
+
+详见 [masking.md](masking.md)。
+
+### 4.1 注解方式
+
+```java
+@Data
+public class UserVO {
+    private String name;
+
+    @Sensitive(type = SensitiveType.MOBILE)
+    private String phone;       // 输出 "138****1234"
+
+    @Sensitive(type = SensitiveType.ID_CARD)
+    private String idCard;      // 输出 "110101********1234"
+
+    @Sensitive(type = SensitiveType.BANK_CARD)
+    private String bankCard;    // 输出 "6225 **** **** 1234"
+}
+```
+
+### 4.2 支持的脱敏类型
+
+| SensitiveType | 示例输入 | 示例输出 |
+|---------------|---------|---------|
+| MOBILE | 13812345678 | 138****5678 |
+| ID_CARD | 110101199001011234 | 110101********1234 |
+| BANK_CARD | 6225123456781234 | 6225 **** **** 1234 |
+| EMAIL | zhangsan@example.com | z****@example.com |
+| NAME | 张三丰 | 张*丰 |
+
+## 5. 与 DAM 集成
+
+详见 [integration-with-dam.md](integration-with-dam.md)。
+
+## 6. 数据导出审计
+
+```java
+@PostMapping("/orders/export")
+@DamAudit(module = "ORDER", action = "EXPORT", sensitive = true)
+public void export(HttpServletResponse response) {
+    // 平台自动记录：
+    // - 导出人、时间、数据量
+    // - 敏感字段访问情况
+    // - 授权链路
+}
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ 业务代码自己脱敏
+
+```java
+// ❌ 错：业务代码自己写脱敏
+public String maskPhone(String phone) {
+    return phone.substring(0, 3) + "****" + phone.substring(7);
+}
+```
+
+✅ 用平台 `@Sensitive` 注解（统一规则）。
+
+### 7.2 ❌ 前端自己做权限控制
+
+```javascript
+// ❌ 错：前端隐藏字段
+if (user.hasRole('finance')) {
+    showField('cost');
+}
+```
+
+✅ 后端不返回该字段（前端无字段可显示）。
+
+### 7.3 ❌ 导出全量数据不审计
+
+```java
+// ❌ 错：导出无审计
+@GetMapping("/export-all")
+public void exportAll() { ... }
+```
+
+✅ 加 `@DamAudit(sensitive = true)` 记录审计。
+
+## 8. 关联阅读
+
+- [masking.md](masking.md) — 字段脱敏
+- [integration-with-dam.md](integration-with-dam.md) — DAM 集成
+- [SKILL.md](../SKILL.md)