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

package/README.md

@@ -0,0 +1,366 @@
+# MeritData Platform Suite（整合包）
+
+> **版本**：v2.6.4 · **发布日期**：2026-09-09
+> **来源**：三方 skill 集合整合（工业互联codex + 石油skills + 研发skills）
+> **目标读者**：MeritData Cloud 二开项目团队 / 平台架构组 / 研发效能组
+
+---
+
+## 一、套件定位
+
+本套件是 **MeritData Cloud 二开标准件 v2.6**，将原本分散在 3 个团队（44 个 skill）的知识合并为完整的 4 层架构：
+
+- **18 条铁律**（rules）— 自动加载，开门见山
+- **35 个 skill**（P0 × 3 + P1 × 1 + P2 × 7 + P3 × 21 + P4 × 3）— L1 入口 + L2 方法论/能力/前端 + L3 单点 API + L4 工具
+- **3 个 tools/**（P4）— L0 治理（skill-vetter v2.6.1 增强版 / skill-stocktake / skill-authoring-workflow）
+
+### 1.1 边界声明（重要）
+
+| ✅ 套件**包含** | ❌ 套件**不包含** |
+|---------------|------------------|
+| MeritData 平台 18 条铁律 | 通用 Java / Spring Boot / TDD skill |
+| MeritData 二开 35 个 skill | 通用 Frontend 设计 skill |
+| MeritData 平台治理工具（vetter/stocktake/authoring-workflow） | 通用架构 / Code Review skill |
+| 三方平台特性（缓存/Nacos/字典/...）| 通用后端模式 skill |
+
+**原则**：
+- **套件自包含**：所有 MeritData 二开所需的 skill + rule + 治理工具都齐全，复制到任意项目根即可用
+- **不混入通用工具**：通用开发 skill（`java-architect` / `java-springboot` / `frontend-design` 等）走全局 `~/.claude/skills/`，与套件**职责分离**
+- **治理工具双份说明**：套件 `tools/` 的 3 个工具与全局 `~/.claude/skills/` 下同名 skill 是同一份内容（套件版用于对外分发，全局版用于个人本地）；新增 PR 改其中一份即可
+
+### 1.2 与全局 `~/.claude/` 的关系
+
+| 位置 | 内容 | 用途 |
+|------|------|------|
+| `meritdata-platform-suite/rules/` | 18 条铁律 | **唯一权威**，复制即用 |
+| `meritdata-platform-suite/skills/` | 35 个 platform skill | **唯一权威**，复制即用 |
+| `meritdata-platform-suite/tools/` | 3 个治理脚本 | 套件治理 / 对外分发 |
+| `~/.claude/rules/`（全局） | 14 个通用 + meritdata-* 兜底 | 个人本地兜底（不再单独维护，已下放至套件） |
+| `~/.claude/skills/`（全局） | 181 个通用 skill | 通用开发工具（与套件无重叠） |
+
+适用场景：
+
+| 阶段 | 用什么 |
+|------|--------|
+| 写代码前不知道从哪开始 | `meritdata-platform-playbook` ✅ |
+| 写完二开代码提交前自查 | `meritdata-platform-code-spec` ✅ |
+| 二开库数据访问 / 跨服务 JOIN / Feign | `meritdata-platform-data-boundary` ✅ |
+| 新业务模块数据库设计 / 聚合根 | `meritdata-platform-domain-model` ✅ |
+| 接入平台单点 API（缓存/Nacos/字典/会话/...）| L3 skill（19 个）✅ |
+| 提交前 4 铁律审查 / 4 维度 code review | `meritdata-platform-data-access-review` / `meritdata-platform-code-review` ✅ |
+| 写测试用例 | `meritdata-platform-test-case` ✅ |
+| 日常开发 | `rules/` 13 个 rule（自动加载） |
+
+---
+
+## 二、目录结构
+
+```
+meritdata-platform-suite/
+├── README.md                          ← 本文件
+├── CHANGELOG.md                       ← 变更记录
+├── docs/                              ← 技术文档（v2.2 起）
+│   └── 二开12阶段开发流程文档框架提取_20260907.md
+├── rules/                             ← 18 条铁律（CLAUDE.md 自动注入）
+│   ├── README.md
+│   ├── meritdata-platform-data-boundary.md     ← L0 数据边界 4 铁律（PF_/Feign/Entity/异常）
+│   ├── meritdata-platform-domain-model-rules.md ← L0 业务建模 5 硬规则（小写蛇形/ID 关联/无外键/软删除）
+│   ├── api-design-rules.md            ← REST API 设计
+│   ├── code-dev-rules.md              ← 通用代码 + §八 方法论铁律（核心）
+│   ├── coding-standards-rules.md      ← 编码细节（资源/集合/异常/并发）
+│   ├── frontend-coding-rules.md       ← 前端编码
+│   ├── frontend-component-rules.md    ← 前端组件
+│   ├── git-workflow-rules.md          ← Git 分支/提交/合并
+│   ├── nacos-rules.md                 ← Nacos 配置
+│   ├── naming-conventions-rules.md    ← 类/方法/包/配置命名
+│   ├── performance-rules.md           ← DB/缓存/并发/内存
+│   ├── security-rules.md              ← 注入/认证/敏感信息
+│   ├── sql-naming-rules.md            ← SQL 命名
+│   └── sql-script-rules.md            ← SQL 脚本
+│
+└── skills/                            ← 35 个 skill（4 层架构）
+    ├── README.md
+    │
+    ├── meritdata-platform-playbook/   ← L1 入口
+    │   ├── SKILL.md
+    │   └── references/
+    │       ├── intent-routing.md      ← 意图路由（含 19 个 L3 skill 清单）
+    │       └── flows.md               ← 8 个典型流程
+    │
+    ├── L2-M 方法论（methodology）：
+    │   ├── meritdata-platform-code-spec/      ← 编码规范
+    │   ├── meritdata-platform-data-boundary/  ← 数据边界
+    │   ├── meritdata-platform-domain-model/   ← 业务建模
+    │   ├── meritdata-platform-data-access-review/ ← 数据访问审查（4 铁律）
+    │   ├── meritdata-platform-code-review/    ← 代码审查（4 维度）
+    │   └── meritdata-platform-test-case/      ← 测试用例（TDD）
+    │
+    ├── L2-C 平台能力（java）：
+    │   ├── meritdata-platform-bpm/
+    │   ├── meritdata-platform-data-access/
+    │   ├── meritdata-platform-job/
+    │   ├── meritdata-platform-impexp/
+    │   ├── meritdata-platform-sso/
+    │   ├── meritdata-platform-backend-deploy/  ← 后端部署（Deploy 工具）
+    │   └── meritdata-platform-cloud-dev/      ← 二开执行入口（22 modules 路由）
+    │
+    ├── L2-F 前端（frontend）：
+    │   └── meritdata-platform-frontend/
+    │
+    └── L3 单点 API（19 个）：
+        ├── meritdata-platform-cache/             ← L3-C 多级缓存
+        ├── meritdata-platform-nacos-config/       ← L3-C Nacos 配置
+        ├── meritdata-platform-sm-crypto/          ← L3-C 国密
+        ├── meritdata-platform-data-classification/ ← L3-C 数据密级
+        ├── meritdata-platform-session/            ← L3-C 会话
+        ├── meritdata-platform-operation-log/      ← L3-C 操作日志
+        ├── meritdata-platform-message-center/     ← L3-C 消息中心
+        ├── meritdata-platform-lookup-api/         ← L3-C 字典 API
+        ├── meritdata-platform-org-user-api/       ← L3-C 组织人员 API
+        ├── meritdata-platform-menu-config/        ← L3-C 菜单配置
+        ├── meritdata-platform-menu-resource/      ← L3-C 菜单资源
+        ├── meritdata-platform-permission/         ← L3-C 资源授权
+        ├── meritdata-platform-platform-config/    ← L3-C 平台基础配置
+        ├── meritdata-platform-ui-components/      ← L3-F 前端组件库
+        └── meritdata-platform-frontend-deploy/    ← L3-F 前端部署
+```
+
+### L4 工具 skill（3 个）
+
+```
+skills/（续）：
+├── meritdata-bootstrap-2nd-dev/         ← L4-T 二开项目脚手架
+├── meritdata-nacos-importer/            ← L4-T Nacos 配置导入
+└── meritdata-platform-2nd-dev-check/    ← L4-T 二开合规扫描
+```
+
+### tools/（L0 治理，3 个）
+
+```
+tools/
+├── skill-vetter/
+│   ├── run.sh                           ← skill 结构校验
+│   └── README.md
+├── skill-stocktake/
+│   ├── run.sh                           ← skill 清单盘点
+│   └── README.md
+└── skill-authoring-workflow/
+    ├── README.md                        ← skill 编写规范
+    └── templates/                       ← SKILL.md + references 模板
+```
+
+---
+
+## 三、4 层架构
+
+```
+L0 治理层（rules 自动加载 + tools/ 治理脚本）
+    ↓ 铁律约束
+L1 入口层（playbook 路由器）
+    ↓ 意图分流
+L2 领域层（方法论 + 平台能力 + 前端）
+    ↓ 路由到单点
+L3 单点 API 层（19 个具体平台特性）
+    ↓ 配合
+L4 工具层（3 个 CI / 脚手架 / 导入工具）
+```
+
+| 层 | 角色 | 数量 | 加载方式 |
+|----|------|------|---------|
+| **L0 治理** | rules 铁律（18 条）| 18 | CLAUDE.md 自动 |
+| **L1 入口** | playbook | 1 | Skill 工具 |
+| **L2-M 方法论** | code-spec / data-boundary / domain-model / data-access-review / code-review / test-case | 6 | Skill 工具 |
+| **L2-C 平台能力** | bpm / data-access / job / impexp / sso / cloud-dev | 6 | Skill 工具 |
+| **L2-F 前端** | frontend | 1 | Skill 工具 |
+| **L3-C 单点 API** | cache / nacos-config / sm-crypto / ... | 14 | Skill 工具 |
+| **L3-F 前端单点** | ui-components / frontend-deploy | 2 | Skill 工具 |
+| **L4 工具** | bootstrap-2nd-dev / nacos-importer / 2nd-dev-check | 3 | Skill 工具 |
+| **L0 治理 scripts** | skill-vetter / skill-stocktake / skill-authoring-workflow | 3 (tools/) | bash 脚本 |
+
+---
+
+## 四、双轨制原则（rules ↔ skill）
+
+| 角色 | 内容 | 文件 | 加载方式 |
+|------|------|------|---------|
+| **rules** | 铁律摘要（一句话一段，引用章节号）| `rules/*.md` | CLAUDE.md 自动注入（每次会话） |
+| **skill SKILL.md** | 纯路由器：触发 + 不触发 + 前置约束 + 路由 | `skills/<name>/SKILL.md` | Skill 工具按需触发 |
+| **skill references/** | 详细文档：完整代码 + 真实案例 + bash 脚本 | `skills/<name>/references/*.md` | skill 触发后按需加载 |
+
+### 关键约束
+
+- SKILL.md **不重复** rules 铁律正文——只引用 `rules/code-dev-rules.md §八.1`
+- references/ **承载** rules 容纳不下的内容：完整对比代码、真实事故案例、可执行 bash
+- **铁律变更**：先改 `rules/`，再同步 `skills/<name>/references/`（保持一致）
+- **结构变更**：先改 `skills/<name>/SKILL.md`，不直接动 references
+
+---
+
+## 五、SKILL.md 写法规范
+
+详见 `skills/README.md §四`。简化要点：
+
+- ✅ **必须含**：frontmatter + 触发（3-5 条）+ 不触发（2-4 条）+ 前置约束（引用 rules）+ 路由
+- ❌ **禁止写**：铁律正文 / 完整代码 / CI 命令 / 适用范围（与 rules 重复）
+- 📏 **行数控制**：15-40 行（不含 frontmatter）
+
+样本：
+
+| skill | 行数 |
+|-------|------|
+| `meritdata-platform-code-spec` | 33 |
+| `meritdata-platform-data-boundary` | 38 |
+| `meritdata-platform-domain-model` | 38 |
+| `meritdata-platform-data-access-review` | 38 |
+| `meritdata-platform-code-review` | 38 |
+| `meritdata-platform-test-case` | 38 |
+| `meritdata-platform-cache` | 38 |
+
+---
+
+## 六、方法论 ↔ rules 章节映射
+
+3 个核心方法论 skill 与 `rules/code-dev-rules.md §八` 铁律一一对应：
+
+```
+rules/code-dev-rules.md §8.1 数据访问边界（data-boundary）
+  ├─ 4 条铁律：不映射 PF_/不分页循环 Feign/不复制平台 Entity/不掩盖异常
+  └─ skill: meritdata-platform-data-boundary
+       └─ references/anti-patterns.md §1-§4
+       └─ references/validate-rules.md §1-§4（CI 命令 + GitHub Actions）
+
+rules/code-dev-rules.md §8.2 业务建模（domain-model）
+  ├─ 4 条铁律：表/字段小写蛇形/不用名称做关联/跨服务禁外键/软删除穿透
+  └─ skill: meritdata-platform-domain-model
+       └─ references/anti-patterns.md §1-§5
+       └─ references/validate-rules.md §1-§5（CI 命令）
+
+rules/code-dev-rules.md §8.3 code-spec 补充铁律
+  ├─ 6 大类：软删除/循环/异常/敏感信息/架构/平台特定
+  └─ skill: meritdata-platform-code-spec
+       └─ references/anti-patterns.md §1-§6
+       └─ references/validate-rules.md §1-§6（bash + GitHub Actions）
+```
+
+P3 新增 3 个方法论 skill（data-access-review / code-review / test-case）是 L2-M 扩展，针对 PR review 和 TDD 流程提供专门流程。
+
+**任何铁律调整必须先改 `rules/code-dev-rules.md`，再同步对应 skill 的 references**。
+
+---
+
+## 七、与三方源目录的关系
+
+```
+工业互联codex/  石油skills/  研发skills/    ← 三方源，44 个 skill
+                              ↓ 阶段 2 合稿
+                     skills/meritdata-platform-*/  ← 29 个 skill
+                              ↓ 路由
+                     rules/code-dev-rules.md §八  ← 铁律摘要
+```
+
+**三方源处理**：
+
+- ✅ **完成**：44 → 29（已抽取并精简）
+- 📦 **下一步**：三方源加 `LEGACY.md` 标记只读
+
+---
+
+## 八、阶段计划
+
+| 优先级 | 数量 | 状态 | 周期 | 内容 |
+|--------|------|------|------|------|
+| **P0** ✅ | 3 | 完成 | - | L2-M 方法论（code-spec / data-boundary / domain-model）|
+| **P1** ✅ | 1 | 完成 | - | L1 入口 `meritdata-platform-playbook` |
+| **P2** ✅ | 6 | 完成 | - | L2-C 平台能力 Java（bpm / data-access / job / impexp / sso / backend-deploy）+ L2-F 前端 |
+| **P3** ✅ | 19 | 完成 | 2 周 | L3 单点 API（缓存/Nacos/国密/密级/会话/日志/消息/字典/组织/资源/菜单/UI/部署/数据访问审查/code review/测试）|
+| **P4** ✅ | 3 + 3 tools/ | 完成 | 1 周 | L4 工具（bootstrap/nacos-importer/check）+ L0 治理 tools（skill-vetter/stocktake/authoring-workflow）|
+| **P5 v2.6.x** ✅ | 35 + 5 reference | 完成 | - | v2.2.0 缺口收尾（masterdata-sync/file/http-client/webapi）+ skill-vetter 增强（4 项校验 + 2 类输出）|
+| **合计** | **35** + 3 tools | 35/35 | 2-3 周 | 整合完成 |
+
+---
+
+## 九、整合方法（怎么用本套件）
+
+### 9.1 团队接入
+
+```bash
+# 1. 复制本套件到项目根目录
+cp -r meritdata-platform-suite/<rules|skills> ./
+
+# 2. 在项目 CLAUDE.md 引用 rules
+echo '请遵守 ./rules/code-dev-rules.md 等 18 条铁律' >> CLAUDE.md
+
+# 3. skill 按需加载（无需声明，Skill 工具自动发现）
+```
+
+### 9.2 日常使用
+
+| 场景 | 操作 |
+|------|------|
+| 写代码前查铁律 | 直接读 `rules/code-dev-rules.md`（自动加载）|
+| 写完代码自查 | 调用 `meritdata-platform-code-spec` skill |
+| 设计新业务模块 | 调用 `meritdata-platform-domain-model` skill |
+| 跨服务数据访问 | 调用 `meritdata-platform-data-boundary` skill |
+| 接入缓存/Nacos/字典/... | 调用 L3 对应 skill（cache / nacos-config / lookup-api / ...）|
+| PR 提交前审查 | 调用 `meritdata-platform-data-access-review` + `meritdata-platform-code-review` |
+| 写测试 | 调用 `meritdata-platform-test-case` skill |
+| 不确定从哪开始 | 等 `meritdata-platform-playbook` 路由 |
+
+### 9.3 CI 集成
+
+每个方法论 skill 的 `references/validate-rules.md` 都有可执行 bash 命令：
+
+```bash
+# 单 skill 校验
+bash tools/skill-vetter/run.sh code-spec
+
+# 全量校验
+bash tools/skill-vetter/run.sh all
+
+# GitHub Actions 集成
+# 参考各 skill validate-rules.md 末尾的 yml 片段
+```
+
+---
+
+## 十、版本与变更
+
+详见 [CHANGELOG.md](CHANGELOG.md)。
+
+- **v1.0.0**（2026-09-07）：初始版本。3 个方法论 skill + 12 条铁律 rules。
+- **v1.1.0**（2026-09-07）：新增 L1 入口 playbook（含意图路由表 + 8 个典型流程）。
+- **v1.2.0**（2026-09-07）：新增 8 个 L2 领域 skill（bpm/data-access/job/impexp/sso + frontend + 3 个数据访问 skill）。
+- **v1.3.0**（2026-09-07）：合并 entities+services+integration → data-access；L2 加 sub-layer + stack 标注。
+- **v2.0.0**（2026-09-07）：**完整 4 层架构落地**。新增 19 个 L3 单点 API skill（13 个 L3-C java + 2 个 L3-F frontend + 3 个 L2-M 扩展方法论 skill）+ L3-C backend-deploy。rules 数量无变化（仍 12 条）。
+- **v2.1.0**（2026-09-07）：**L4 + L0 治理完工**。新增 3 个 L4 工具 skill（bootstrap-2nd-dev / nacos-importer / 2nd-dev-check）+ `tools/` 目录的 3 个 L0 治理脚本（skill-vetter / skill-stocktake / skill-authoring-workflow）。4 层架构完整闭环。
+- **v2.2.0**（2026-09-07）：**补齐执行入口 `meritdata-platform-cloud-dev`**。v2.0.0 遗漏的执行引擎补齐（22 modules 路由 + 7 类动作契约 + 13 个路由场景）。承认 v2.0.0 错误：playbook 是路由器、cloud-dev 是执行引擎，两者职责不同。skill 总数从 32 升到 33。
+- **v2.6.0**（2026-09-08）：**v2.2.0 缺口收尾 4/4**。http-client 合并入 `frontend/references/http-client/`（5 篇）+ webapi 合并入 `data-access/references/outbound/webapi.md`；35 skill / 0 真正缺失 / 0 剩余缺口 / 44 原始 skill 100% 已映射。
+- **v2.6.1**（2026-09-08）：**运维优化 / skill-vetter 增强**。4 项新校验（死链扫描 / 敏感信息扫描 / TODO 残留 / 重复 name）+ 2 类新输出（summary 表格 / JSON 报告）+ 5 个遗漏 reference 补建（status-mapping / same-jvm / cloud-tables / relationship-patterns / review-checklist）。35 skill / 0 失败。
+- **v2.6.2**（2026-09-09）：**冗余清理 + 内容恢复**。恢复 `coding-standards-rules.md`（198 字节 stub → 2659 字节真实内容）；删除项目根冗余 `skills/`（3 个）与 `rules/`（14 个）；rules/README.md 同步。35 skill / 18 rule / 0 stub。
+- **v2.6.3**（2026-09-09）：**套件自包含升级**。下放 6 个全局独有 rules 到套件（`meritdata-platform-data-boundary` / `meritdata-platform-domain-model-rules` / `documentation-rules` / `requirement-dev-rules` / `system-test-rules` / `test-case-dev-rules`），套件从 12 rule → **18 rule**，**复制即用、不再依赖全局**。`code-dev-rules.md §8.1/§8.2` 引用路径同步更新。**明确边界**：套件仅含 MeritData 平台相关 skill/rule，不含通用开发工具。
+- **v2.6.4**（2026-09-09）：**清理根级 3 个空壳目录**（`meritdata-bootstrap-2nd-dev` / `meritdata-nacos-importer` / `meritdata-platform-2nd-dev-check`），权威版本均在 `skills/` 下；套件根级从 9 项 → **6 项**，**0 空目录 / 0 重复**。
+
+---
+
+## 十一、维护原则
+
+| 类别 | 原则 |
+|------|------|
+| **铁律** | 严格通过（不可绕过），CI 阻断 |
+| **skill 路由** | 灵活（按用户意图触发），不阻断 |
+| **references** | 可增长（案例、CI 命令可累积），不破坏既有结构 |
+| **命名** | L2 用稳定名词（如 `code-spec`），L0/L4 用动词（如 `bootstrap`）|
+| **冲突** | rules 优先于 skill（专项规则优先）|
+| **亚层标注** | L2 skill 必须声明 sub-layer（L2-M / L2-C / L2-F）+ stack（methodology / java / frontend）|
+| **🔴 边界红线** | **套件仅含 MeritData 平台相关 skill/rule，不包含通用 Java / Spring Boot / Frontend 等开发工具**。通用工具由下游团队从全局 `~/.claude/skills/` 或 `everything-claude-code` 插件获取，平台不重复分发、不背版本同步债。详见 §1.1 边界声明 |
+
+---
+
+## 十二、反馈与贡献
+
+- **铁律修订**：提 PR 到 `rules/code-dev-rules.md`，需架构组 review
+- **skill 新增**：参考 `skills/README.md §四` 写法规范，提 PR 到 `skills/`
+- **CI 命令补充**：直接 PR 到 `skills/<name>/references/validate-rules.md`
+- **案例补充**：直接 PR 到 `skills/<name>/references/anti-patterns.md`
+
+联系：架构组 / 研发效能组（详见组织内通讯录）