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

package/skills/meritdata-platform-domain-model/references/validate-rules.md

@@ -1,305 +0,0 @@
-# CI 校验命令（domain-model）
-
-> **本文件与 [anti-patterns.md](anti-patterns.md) 一一对应**。每条铁律给出可在 CI 中直接执行的检测命令。**任一 🔴 阻断命令失败即拒绝合并**。
->
-> **与 code-spec / data-boundary 的差异**：本文件聚焦"建模层决策"（表设计、字段命名、聚合关系），其他两个聚焦"代码层 / 跨库层"。
-
-## 使用方式
-
-```bash
-bash tools/skill-vetter/run.sh domain-model
-```
-
----
-
-## 1. 二开业务表/字段必须小写蛇形（🔴 阻断）
-
-### 1.1 检测大写 / 驼峰表名
-
-```bash
-RES="${RES:-src/main/resources}"
-SRC="${SRC:-src/main/java}"
-
-check "1.1 CREATE TABLE 大写/驼峰" \
-  "! grep -rEn 'CREATE TABLE\\s+[A-Z]' $RES 2>/dev/null" \
-  block
-```
-
-### 1.2 检测沿用 PF_ 前缀
-
-```bash
-check "1.2 CREATE TABLE PF_" \
-  "! grep -rEn 'CREATE TABLE\\s+PF_' $RES 2>/dev/null" \
-  block
-```
-
-### 1.3 检测大写/驼峰字段
-
-```bash
-# 检测实体类中无 @Column 注解的驼峰 String/Long/Integer 字段
-check "1.3 字段缺 @Column 映射" \
-  "! grep -rEn 'private\\s+(String|Long|Integer)\\s+[a-z]+[A-Z]' $SRC --include='*.java' | \
-       grep -v '@Column'" \
-  warn
-```
-
-### 1.4 检测索引/唯一约束命名不规范
-
-```bash
-check "1.4 索引名未用 idx_/uk_ 前缀" \
-  "! grep -rEn 'CREATE\\s+(UNIQUE\\s+)?INDEX\\s+[A-Z]' $RES 2>/dev/null" \
-  block
-```
-
-### 1.5 检测小写实体类
-
-```bash
-check "1.5 实体类小写命名" \
-  "! grep -rEn '^public class [a-z]' $SRC --include='*.java' | grep -v 'package'" \
-  block
-```
-
----
-
-## 2. 不得把人员/组织名称作为关联键（🔴 阻断）
-
-### 2.1 检测 WHERE/JOIN 用名称关联
-
-```bash
-check "2.1 WHERE 用名称关联" \
-  "! grep -rEn 'WHERE.*_name\\s*=' $RES 2>/dev/null | grep -E '\\.(applicant_name|dept_name|user_name)\\s*='" \
-  block
-```
-
-更精确检测（MyBatis Mapper）：
-
-```bash
-check "2.1b MyBatis ON 用名称关联" \
-  "! grep -rEn 'ON.*\\.(name|deptName|orgName|userName)' $RES 2>/dev/null" \
-  block
-```
-
-### 2.2 检测实体类缺 user_id 字段但有 applicant_name
-
-```bash
-check "2.2 实体有 applicant_name 缺 user_id" \
-  "! python3 -c '
-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)
-        c = open(path, encoding=\"utf-8\").read()
-        if \"applicantName\" in c and \"applicantUserId\" not in c:
-            for m in re.finditer(r\"@Entity\\s*(class|public class)\\s+\\w+\\s*\\{([^}]*)\", c):
-                if \"applicantName\" in m.group(2):
-                    issues.append(f\"{path}: applicantName 无 applicantUserId\")
-if issues:
-    print(\"\\n\".join(issues)); sys.exit(1)
-'" \
-  warn
-```
-
-### 2.3 检测实体用工号做关联
-
-```bash
-check "2.3 工号做关联（应改 user_id）" \
-  "! grep -rEn 'private\\s+String\\s+(applicantCode|userCode|empCode)\\s*;' $SRC --include='*.java' | \
-       grep -B 2 | grep '@Column'" \
-  warn
-```
-
----
-
-## 3. 跨服务禁止数据库外键（🔴 阻断）
-
-### 3.1 检测跨服务外键
-
-```bash
-check "3.1 跨服务 FOREIGN KEY" \
-  "! grep -rEn 'FOREIGN KEY.*REFERENCES.*\\.(t_|service_)' $RES 2>/dev/null | grep -v 'local_schema'" \
-  block
-```
-
-### 3.2 检测跨服务事务
-
-```bash
-# 检测 @Transactional 方法内调 Feign
-check "3.2 @Transactional 内调 Feign" \
-  "! python3 -c '
-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)
-        c = open(path, encoding=\"utf-8\").read()
-        # 找 @Transactional 方法
-        for m in re.finditer(r\"@Transactional[^\\n]*\\n\\s*(public|private|protected)[^\\n]*\\n[^\\{]*\\{([^}]*)\", c, re.DOTALL):
-            body = m.group(2)
-            # 检查 body 是否含 Feign 调用
-            if re.search(r\"\\.(getById|listByIds|create|update|delete)\\(\", body):
-                if \"Client\" in body or \"Feign\" in body:
-                    line_no = c[:m.start()].count(\"\\n\") + 1
-                    issues.append(f\"{path}:{line_no}: @Transactional 内调 Feign\")
-if issues:
-    print(\"\\n\".join(issues)); sys.exit(1)
-'" \
-  block
-```
-
-### 3.3 检测附件二进制存主表
-
-```bash
-check "3.3 主表含 byte[]" \
-  "! grep -rEn 'private\\s+byte\\[\\]\\s+[a-z]' $SRC --include='*.java' | grep -B 1 '@Entity'" \
-  warn
-```
-
----
-
-## 4. 唯一性校验穿透软删除（🔴 阻断 — 与 code-spec 共享）
-
-> **本铁律完整 CI 命令**见 [code-spec validate-rules.md §1](../meritdata-platform-code-spec/references/validate-rules.md#1-软删除实体铁律阻断)。
->
-> 本文件补充建模层专属命令。
-
-### 4.1 检测唯一约束不含 deleted
-
-```bash
-check "4.1 UNIQUE KEY 不含 deleted" \
-  "! grep -rEn 'UNIQUE\\s+KEY\\s+\\w+\\s*\\(\\s*\\w+_no\\s*\\)' $RES 2>/dev/null | grep -v 'deleted'" \
-  warn
-```
-
-### 4.2 检测实体含 @SQLDelete 但缺 @Where
-
-```bash
-check "4.2 实体含 @SQLDelete 但缺 @Where" \
-  "! grep -rln '@SQLDelete' $SRC --include='*.java' | xargs grep -L '@Where(clause' 2>/dev/null" \
-  block
-```
-
-### 4.3 检测业务查询 / 全量查询未成对出现
-
-```bash
-check "4.3 业务查询无配对的全量查询" \
-  "! python3 -c '
-import re, os, sys
-issues = []
-for root, _, files in os.walk(\"src/main/java\"):
-    for f in files:
-        if not f.endswith(\".java\") or \"Repository\" not in f: continue
-        path = os.path.join(root, f)
-        c = open(path, encoding=\"utf-8\").read()
-        # 找 findByXxx 方法
-        for m in re.finditer(r\"findBy([A-Z]\\w+)\", c):
-            name = m.group(1)
-            # 检查是否有 findXxxIncludingDeleted
-            if \"IncludingDeleted\" not in c:
-                issues.append(f\"{path}: findBy{name} 无 IncludingDeleted 配对\")
-                break  # 每文件只报一次
-if issues:
-    print(\"\\n\".join(issues)); sys.exit(1)
-'" \
-  warn
-```
-
----
-
-## 5. 平台语义字段规范（⚠️ 警告）
-
-### 5.1 检测业务状态与流程实例 ID 混用
-
-```bash
-check "5.1 status 字段无 processInstanceId 配对" \
-  "! grep -rln '@Column.*\\\"status\\\"' $SRC --include='*.java' | \
-       xargs grep -L 'processInstanceId' 2>/dev/null" \
-  warn
-```
-
-### 5.2 检测附件二进制存主表
-
-（与 §3.3 重复）
-
-### 5.3 检测字典字段用中文
-
-```bash
-check "5.3 字典字段值为中文" \
-  "! grep -rEn '@Column.*status.*=\\s*\"[\\u4e00-\\u9fa5]' $SRC --include='*.java' 2>/dev/null" \
-  warn
-```
-
----
-
-## 6. 完整脚本（domain-model）
-
-```bash
-#!/bin/bash
-# tools/skill-vetter/run.sh domain-model
-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 "===== domain-model ====="
-
-# 铁律 1：表/字段小写蛇形
-check "1.1 CREATE TABLE 大写" "! grep -rEn 'CREATE TABLE\\s+[A-Z]' $RES 2>/dev/null" block
-check "1.2 CREATE TABLE PF_" "! grep -rEn 'CREATE TABLE\\s+PF_' $RES 2>/dev/null" block
-check "1.4 索引名未用 idx_/uk_" "! grep -rEn 'CREATE\\s+(UNIQUE\\s+)?INDEX\\s+[A-Z]' $RES 2>/dev/null" block
-check "1.5 实体类小写命名" "! grep -rEn '^public class [a-z]' $SRC --include='*.java' | grep -v package" block
-
-# 铁律 2：不用名称做关联
-check "2.1 WHERE 用名称关联" "! grep -rEn 'WHERE.*_name\\s*=' $RES 2>/dev/null | grep 'applicant_name\\|dept_name\\|user_name'" block
-check "2.1b ON 用名称关联" "! grep -rEn 'ON.*\\.(name|deptName|orgName)' $RES 2>/dev/null" block
-
-# 铁律 3：跨服务禁外键
-check "3.1 跨服务 FOREIGN KEY" "! grep -rEn 'FOREIGN KEY.*REFERENCES.*\\.(t_|service_)' $RES 2>/dev/null | grep -v local_schema" block
-
-# 铁律 4：软删除穿透
-check "4.2 实体含 @SQLDelete 但缺 @Where" "! grep -rln '@SQLDelete' $SRC --include='*.java' | xargs grep -L '@Where(clause' 2>/dev/null" block
-
-exit $EXIT
-```
-
----
-
-## 7. 集成：与 code-spec / data-boundary 共跑
-
-```bash
-#!/bin/bash
-# tools/skill-vetter/run.sh all
-set -e
-
-for skill in code-spec data-boundary domain-model; do
-  bash tools/skill-vetter/run.sh "$skill" || exit 1
-done
-
-echo "✅ 所有方法论 skill 校验通过"
-```
-
----
-
-## 8. 关联阅读
-
-- [anti-patterns.md](anti-patterns.md) — 反模式案例 + 正模式代码
-- [SKILL.md](../SKILL.md) — skill 顶层入口
-- [code-spec validate-rules](../meritdata-platform-code-spec/references/validate-rules.md) — 编码层校验
-- [data-boundary validate-rules](../meritdata-platform-data-boundary/references/validate-rules.md) — 数据访问边界校验
-- [rules/code-dev-rules.md §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model) — 铁律摘要

package/skills/meritdata-platform-file/SKILL.md

@@ -1,100 +0,0 @@
----
-name: meritdata-platform-file
-description: |
-  平台业务附件契约集成（MeritData Cloud 6.13.2）。覆盖 6 个动作：上传 / 回显 / 下载 / 删除 / 复制 / 密级；2 个 Service：IUploadService（按 joinId 管理附件集合）+ IEnclosureService（通用 enclosure）；2 个 ID 模型：joinId（业务聚合关联）+ fileId（PfUpload.id）。
-  触发场景：业务表单要上传附件；要按业务聚合管理附件集合；要 joinId/fileId 生命周期设计；要清理孤儿文件；要排查路径穿越 / 越权下载 / 文件残留。
-  何时不用：流程附件 → bpm；Excel 导入导出 → impexp；消息附件 → message-center；前端上传组件 → frontend。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-08"
-  last_modified: "2026-09-08"
-  risk: high
-  layer: L3
-  sub-layer: L3-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 平台业务附件（platform-file）
-
-> **来源**：石油 + 研发 `merit-cloud-file` 22-modules（v2.5.0 P1-B 新建）
-> **平台版本**：MeritData Cloud 6.13.2（不要推断未公开语义）
-> **核心定位**：业务附件契约集成，**不是通用文件上传**（不涉及 OSS/MinIO 等通用存储）
-
----
-
-## 触发
-
-- 业务表单/业务聚合需要上传附件（采购单附件 / 合同附件 / 报告附件）
-- 按 `joinId` 管理附件集合（一个业务对象 + N 个附件）
-- 单附件操作（按 `fileId` = `PfUpload.id`）
-- 6 个动作：**上传 / 回显 / 下载 / 删除 / 复制 / 密级**
-- 安全需求：路径穿越防护、越权下载防护、孤儿文件清理
-
-## 不触发
-
-- 流程专属附件 → 用 `meritdata-platform-bpm`
-- 消息附件 → 用 `meritdata-platform-message-center`
-- Excel 导入导出附件 → 用 `meritdata-platform-impexp`
-- 前端上传组件 → 用 `meritdata-platform-frontend`
-- 通用文件存储（OSS/MinIO/CDN）→ ❌ 本 skill 不涉及（用 platform-config 的 Nacos 配置）
-- 跨服务传文件（不经过平台附件）→ 用 `meritdata-platform-data-access/inbound/`
-
----
-
-## 前置约束
-
-- **必须使用平台契约**：IUploadService / IEnclosureService（不绕过 AbstractFileOperation）
-- **必须设计 joinId/fileId 生命周期**：避免孤儿文件（详见 lifecycle.md）
-- **必须做密级 + 租户 + 下载授权**：详见 security.md
-- **不暴露物理路径**：前端只接收 `fileId` 或 URL token
-- **同 JVM 注入**：系统管理同进程才注入本地 Service；独立业务微服务走 HTTP 网关契约
-- **平台版本证据**：6.13.2，不要按旧版本/方法名推断未公开语义
-
----
-
-## 路由
-
-### Step 1：识别附件类型
-
-| 附件类型 | 用什么 Service | 参考 |
-|---------|--------------|------|
-| 普通业务附件 | `IUploadService`（按 joinId） | references/api-contracts.md |
-| 通用 enclosure | `IEnclosureService`（参数语义已证明时） | references/api-contracts.md |
-| 流程附件 | 转 `meritdata-platform-bpm` | — |
-| 消息附件 | 转 `meritdata-platform-message-center` | — |
-| Excel 导入导出 | 转 `meritdata-platform-impexp` | — |
-
-### Step 2：识别部署边界
-
-| 部署形态 | 接入方式 |
-|---------|---------|
-| 系统管理同进程 | 直接注入 `IUploadService`（同 JVM Service） |
-| 独立业务微服务 | 调 HTTP 网关契约（Feign Client） |
-
-### Step 3：完整方案设计
-
-| 维度 | 参考 |
-|------|------|
-| joinId / fileId 生命周期 | [references/lifecycle.md](references/lifecycle.md) |
-| 真实类 / 方法 / 实体字段 | [references/api-contracts.md](references/api-contracts.md) |
-| 密级 / 租户 / 下载授权 / 路径安全 | [references/security.md](references/security.md) |
-| 正反例对照 | [references/examples.md](references/examples.md) |
-| 验收清单（MS-01 ~ MS-08）| [references/acceptance.md](references/acceptance.md) |
-
----
-
-## 关键提醒
-
-- **不要绕过 AbstractFileOperation**（平台内部存储抽象）→ 业务代码不得直接拼接 path
-- **不要把 IEnclosureService 当通用上传**（独立契约，参数语义不同）
-- **不要漏 joinId 设计** → 否则附件无法关联业务对象（孤儿文件）
-- **不要硬编码物理路径** → URL token + 临时下载授权
-- **Excel 导入导出附件** → 走 impexp，本 skill 只管业务附件
-
----
-
-**最后更新**：2026-09-08（v2.5.0 P1-B 新建）
-**来源**：石油 + 研发 `merit-cloud-file` 22-modules（module.md + 5 references）