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

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

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

@@ -1,42 +0,0 @@
----
-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

@@ -1,179 +0,0 @@
-# 数据密级管理指南（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)