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

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

@@ -1,44 +1,186 @@
 ---
 name: meritdata-platform-playbook
-description: |
-  MeritData 二开标准件 L1 唯一入口。识别用户的"动作意图"→ 路由到对应 L2 skill（code-spec / data-boundary / domain-model / bpm / entities / services / integration / frontend / job / impexp / sso）。
-  触发场景：用户说"我要做XX"但不确定从哪个 skill 开始；新二开项目冷启动；跨 skill 的复合需求（如"加一个审批流"= domain-model + bpm + code-spec）。
-  何时不用：用户明确说了 skill 名（如 /code-spec）→ 直接调对应 skill；纯查铁律 → 直接读 rules/。
+description: 公司级 Skill 套件的唯一编排入口。用于跨 skill 需求、平台能力查询、方案设计、新建工程，以及在现有 Git/SVN 项目新增或扩展模块、字段、接口、页面、流程等功能；按 references/public-entry-map.json 自动路由并执行强制门禁。
 metadata:
   version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
   risk: low
-  layer: L1
-allowed-tools: Read, Grep, Glob, AskUserQuestion
+  allowed-tools: Read, Grep, Glob, Bash
 ---
 
-# MeritData 二开 playbook（L1 入口）
+## ⭐ MUST DO
 
-## 触发
-- 用户描述"我要做XX"但没说 skill 名
-- 新二开项目冷启动，从需求到上线的完整路径
-- 跨多个 skill 的复合需求（如"加采购审批流"= domain-model + bpm + code-spec）
-- 用户明确说"我不知道从哪开始"
+**作为公司级 Skill 套件的唯一编排入口，按 references/public-entry-map.json 路由到最窄 skill，不暴露模块选择给用户。**
 
-## 不触发
-- 用户明确说了 skill 名（如 `/code-spec`）→ 直接调对应 skill
-- 纯查铁律 / 命名规范 → 直接读 `../../rules/`
-- 纯前端样式调整 → `meritdata-platform-frontend`
-- 平台模块（与平台同 JVM）的代码 → `meritdata-platform-entities` / `services`
+## 触发条件 / 不适用
 
-## 路由
+**适用**：
+- 用户说 `meritdata-platform-playbook <需求>`
+- 跨 skill 综合需求（如"新建一个采购模块"）
+- 存量项目接入（任何 `.git/` 或 `.svn/` 管理的 Maven 项目）
+- 项目模式识别、版本治理、强制门禁触发
 
-按用户意图二选一：
+**不适用**：
+- 单一 skill 的领域问题 → 直接触发对应 skill
+- 用户已明确知道用哪个 skill（如 `meritdata-platform-bpm 发起审批`）
 
-### 路径 A：单动作（用户表达明确）
-→ 查 [references/intent-routing.md](references/intent-routing.md) 的"意图关键词表"，直接路由到唯一 L2 skill。
+## 主题路由
 
-### 路径 B：复合需求（多 skill 组合）
-→ 查 [references/flows.md](references/flows.md) 的典型流程（如"加审批流"/"加定时任务"/"加导入"），按顺序调多个 L2 skill。
+| 任务 | 优先读取 |
+| --- | --- |
+| 识别项目模式（new / existing / existing-legacy） | [`references/legacy-detect.md`](references/legacy-detect.md) |
+| 跨 skill 路由表（22 个 skill） | [`references/public-entry-map.json`](references/public-entry-map.json) |
+| Git 集成（只读） | [`references/git-integration.md`](references/git-integration.md) |
+| SVN 集成（只读） | [`references/svn-integration.md`](references/svn-integration.md) |
+| 代码规范 | [`references/code-spec.md`](references/code-spec.md) |
+| Skill 套件治理 | [`references/governance.md`](references/governance.md) |
 
-## 前置约束
-- 所有目标 skill 的铁律都在 `../../rules/code-dev-rules.md §八`，必须先读
-- 路由前**先问 1 个澄清问题**确认意图（避免误路由），见 [references/intent-routing.md §问询模板](references/intent-routing.md#问询模板)
+### 公司级研发参考资料（dev-docs 整合）
+
+> 原 `meritdata-dev-docs-file-finder`（兜底查找 skill）的功能已由 playbook 路由表承担。
+
+| 用户场景 | 对应攻略 |
+|---------|---------|
+| 启动流程实例 | [`../meritdata-platform-bpm/references/api/攻略-01-流程API-章节03_启动流程实例接口.md`](../meritdata-platform-bpm/references/api/攻略-01-流程API-章节03_启动流程实例接口.md) |
+| 监听器开发 | [`../meritdata-platform-bpm/references/listener/攻略-03-监听表达式-00_总览.md`](../meritdata-platform-bpm/references/listener/攻略-03-监听表达式-00_总览.md) |
+| 系统认证（SSO/CAS）| [`../meritdata-platform-sso/references/auth/攻略-06-系统认证-00_总览.md`](../meritdata-platform-sso/references/auth/攻略-06-系统认证-00_总览.md) |
+| 组织人员同步 | [`../meritdata-platform-integration/references/org-sync/攻略-09-组织人员同步-00_总览.md`](../meritdata-platform-integration/references/org-sync/攻略-09-组织人员同步-00_总览.md) |
+| 定时调度 | [`../meritdata-platform-job/references/scheduler-ref/攻略-10-定时调度-00_总览.md`](../meritdata-platform-job/references/scheduler-ref/攻略-10-定时调度-00_总览.md) |
+| 配置项管理 | [`../meritdata-platform-config-item/references/nacos-config/攻略-11-配置项-00_总览.md`](../meritdata-platform-config-item/references/nacos-config/攻略-11-配置项-00_总览.md) |
+| 消息中心 | [`../meritdata-platform-messaging/references/msg-center/攻略-12-消息中心-00_总览.md`](../meritdata-platform-messaging/references/msg-center/攻略-12-消息中心-00_总览.md) |
+
+> 完整研发参考资料：见 `references/`（含 references/public-entry-map.json / references/legacy-detect.md / references/governance.md 等）
+
+## 工作方式（Step 1/2/3/4/5）
+
+### Step 1：识别项目模式
+
+```yaml
+project_mode:
+  new:           # 全新工程，无 src/ 目录
+    action: 触发 cloud-dev 生成 scaffold
+  existing:      # 已有 pom.xml + src/，核心路径
+    action: 不生成 scaffold，最小修改
+  existing-legacy: # 5.x 旧版 / 缺平台指纹 / 非标准结构
+    action: 强制 2nd-dev-check 体检后增量
+```
+
+读取 `legacy-detect.md` 完成 5 步自动识别。
+
+### Step 2：识别动作
+
+| 动作 | 路由 |
+|------|------|
+| 能力查询 | 加载 `cloud-dev` |
+| 方案设计 | 加载 `cloud-dev` + 跨 skill |
+| 新建工程 | 加载 `cloud-dev/references/modules/gen.md` |
+| 存量增量 | 加载 `cloud-dev/references/modules/gen.md`（不生成 scaffold） |
+| 集成查询 | 加载 `integration` |
+| 项目验证 | 加载 `2nd-dev-check` |
+
+### Step 3：加载最窄 skill
+
+- 一个请求只有一个主入口
+- 复合需求由主入口加载补充模块
+- 不暴露模块选择给用户
+
+### Step 4：执行强制门禁（5 条）
+
+| # | 门禁 | 触发场景 |
+|---|------|---------|
+| 1 | 不猜测平台接口、依赖坐标、跨版本签名 | 任何代码生成前 |
+| 2 | 不连接 cloud 平台库、不跨库 JOIN、不复制 Entity | 二开库写库前 |
+| 3 | Git/SVN 状态只读、不自动 commit | 任何 patch 输出前 |
+| 4 | 本地维护不自动打包 | 维护阶段 |
+| 5 | 不暴露模块选择给用户 | 路由阶段 |
+
+### Step 5：输出
+
+```
+- 能力路径
+- 新增/修改文件清单
+- SQL migration（如有）
+- 验证结果
+- 剩余 GAP 项
+- 人工联调项
+```
+
+## 代码示例
+
+### 用户输入
+
+```text
+meritdata-platform-playbook 在项目 X 加一个请假模块
+```
+
+### playbook 输出
+
+```yaml
+project_mode: existing
+vcs: git-managed
+platform_version: 6.13.2
+build_tool: Maven
+
+action_routing:
+  main: cloud-dev
+  supplement:
+    - bpm       # 流程审批
+    - frontend  # 页面
+    - impexp    # 附件上传
+
+gates_triggered:
+  - data-boundary  # 二开库不连平台库
+  - global-3       # Git 只读
+
+files_to_modify:
+  - src/main/java/com/example/leave/LeaveController.java
+  - src/main/java/com/example/leave/LeaveService.java
+  - src/main/resources/mapper/leave.xml
+  - src/main/resources/db/migration/2026-09-01-create-leave.sql
+
+sql_migrations:
+  - 2026-09-01-create-leave-table.sql
+
+verification:
+  - 编译通过
+  - 单元测试 100% pass
+  - data-boundary 校验通过
+
+gap:
+  - 流程定义 JSON 需用户上传
+
+manual_steps:
+  - 用户手动 git commit
+```
+
+## 📚 详细文档
+
+- [`references/public-entry-map.json`](references/public-entry-map.json) — 22 个 skill 的路由表
+- [`references/legacy-detect.md`](references/legacy-detect.md) — 5 步项目模式识别
+- [`references/git-integration.md`](references/git-integration.md) — Git 只读契约
+- [`references/svn-integration.md`](references/svn-integration.md) — SVN 只读契约
+- [`references/code-spec.md`](references/code-spec.md) — 代码规范引用
+- [`references/governance.md`](references/governance.md) — 套件治理规则
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 让用户自己选 skill | 违反"不暴露模块选择"门禁 | playbook 自动路由 |
+| 在 playbook 中实现 BPM 逻辑 | 职责错位 | 触发 `meritdata-platform-bpm` |
+| 自动调用 `git commit` | 违反全局门禁 3 | 输出 patch，用户手动提交 |
+| 连接 cloud 平台库 | 违反全局门禁 2 | 通过 Feign/API 批量装配 |
+| 用空集合掩盖平台故障 | 违反 data-boundary 门禁 4 | 显式上抛异常 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - BPM 审批流 → `meritdata-platform-bpm`
+  - 缓存/Nacos/加密 → `meritdata-platform-core`
+  - 调度任务 → `meritdata-platform-job`
+  - 前端开发 → `meritdata-platform-frontend`
+  - 导入导出 → `meritdata-platform-impexp`
+- **强制要求**：本 skill 是唯一会做"多 skill 编排"的入口，其他 skill 单职责

package/skills/meritdata-platform-playbook/agents/openai.yaml

@@ -0,0 +1,29 @@
+display_name: "MeritData 平台 Playbook"
+short_description: "公司级 Skill 套件的唯一编排入口，跨 skill 路由与强制门禁"
+default_prompt: |
+  meritdata-platform-playbook 是公司级 Skill 套件（meritdata-platform-suite）的唯一编排入口。
+
+  适用场景：
+  - 跨 skill 综合需求（"新建一个采购模块"）
+  - 存量项目接入（Git/SVN 管理的 Maven 项目）
+  - 项目模式识别（new / existing / existing-legacy）
+  - 平台能力综合查询
+
+  使用方式：
+  ```
+  meritdata-platform-playbook <需求描述>
+  ```
+
+  工作方式：
+  1. 识别项目模式（5 步自动识别）
+  2. 识别动作（能力查询/方案设计/新建/存量/集成/验证）
+  3. 按 references/public-entry-map.json 加载最窄 skill
+  4. 执行 5 条全局强制门禁
+  5. 输出能力路径、文件清单、SQL migration、验证结果、GAP 项
+
+  强制约束：
+  - 不暴露模块选择给用户
+  - 不猜测平台接口、依赖坐标、跨版本签名
+  - 不连接 cloud 平台库、不跨库 JOIN、不复制 Entity
+  - Git/SVN 状态只读，不自动 commit
+  - 本地维护不自动打包

package/skills/meritdata-platform-playbook/examples/existing-increment/README.md

@@ -0,0 +1,83 @@
+# Playbook 示例：存量项目增量开发
+
+## 场景
+
+在已有的采购服务中新增一个"供应商管理"模块。
+
+## 用户输入
+
+```text
+$meritdata-platform-playbook 在项目 purchase-service 加一个供应商管理模块
+```
+
+## playbook 输出（节选）
+
+```yaml
+project_mode: existing
+vcs: git-managed
+build_tool: Maven
+platform_version: 6.13.2
+working_dir: ./purchase-service
+
+analysis:
+  detected_components:
+    - meritdata-cloud-starter: 6.13.2
+    - cloud-system-bpm-module-core: 6.13.2
+    - mybatis-plus-boot-starter: 3.4.3
+    - element-ui: 2.15.14
+    - cloud-module-base: 1.2.0
+
+modules_loaded:
+  - gen: 符号级最小修改
+  - feign-api: 不涉及
+  - code-spec: 沿用现有规范
+
+files_to_create:
+  - src/main/java/com/example/purchase/supplier/SupplierController.java
+  - src/main/java/com/example/purchase/supplier/SupplierService.java
+  - src/main/java/com/example/purchase/supplier/SupplierRepository.java
+  - src/main/java/com/example/purchase/supplier/SupplierEntity.java
+  - src/main/java/com/example/purchase/supplier/SupplierParam.java
+  - src/main/resources/mapper/SupplierMapper.xml
+  - src/main/resources/db/migration/V2__create_supplier.sql
+  - src/main/webapp/pages/supplier/main.js
+  - src/main/webapp/pages/supplier/router.js
+
+files_to_modify:
+  - src/main/java/com/example/purchase/PurchaseApplication.java（无）
+  - src/main/resources/application.yml（无）
+
+gates_passed:
+  - data-boundary: 新表以 T_SUPPLIER 前缀（业务表）
+  - code-spec: 沿用现有 Controller/Service/Repository 命名
+  - 编译通过: 基于真实源码修改
+
+verification:
+  - mvn clean compile 通过
+  - 单元测试覆盖率 ≥ 80%
+
+gap_items: []
+manual_steps:
+  - 用户手动 git add + git commit
+```
+
+## 关键决策
+
+1. **不生成 scaffold**：保留现有项目结构
+2. **新表使用 T_ 前缀**：业务表命名规范
+3. **不修改 PurchaseApplication.java**：保持启动类稳定
+4. **仅新增文件 + 必要 import**：符号级最小修改
+
+## 与新建工程的区别
+
+| 维度 | 新建工程 | 存量增量 |
+|------|---------|---------|
+| scaffold 生成 | ✅ | ❌ |
+| 真实源码读取 | N/A | ✅ 必读 |
+| 命名规范沿用 | 默认 | 项目已有 |
+| 数据库表 | 全新 | 增量 migration |
+| 启动类修改 | 创建 | 不修改 |
+
+## 错误处理
+
+如果 playbook 检测到项目存在冲突（如端口占用、依赖冲突），会在 `gap_items` 中列出，用户需先解决再继续。

package/skills/meritdata-platform-playbook/examples/new-project/README.md

@@ -0,0 +1,73 @@
+# Playbook 示例：新建一个采购服务
+
+## 场景
+
+从零开始新建一个 Spring Cloud 微服务，用于采购订单管理。
+
+## 用户输入
+
+```text
+$meritdata-platform-playbook 新建一个采购服务，包括订单的增删改查、审批流程、Excel 导出
+```
+
+## playbook 输出（节选）
+
+```yaml
+project_mode: new
+vcs: git-managed（待初始化）
+build_tool: Maven
+
+recommended_action:
+  - 触发 cloud-dev/references/modules/gen.md
+  - 触发 bpm（采购审批）
+  - 触发 impexp（Excel 导出）
+
+generated_files:
+  - pom.xml
+  - src/main/java/com/example/purchase/PurchaseApplication.java
+  - src/main/java/com/example/purchase/controller/PurchaseOrderController.java
+  - src/main/java/com/example/purchase/service/PurchaseOrderService.java
+  - src/main/java/com/example/purchase/repository/PurchaseOrderRepository.java
+  - src/main/java/com/example/purchase/entity/PurchaseOrder.java
+  - src/main/java/com/example/purchase/param/PurchaseOrderParam.java
+  - src/main/resources/application.yml
+  - src/main/resources/mapper/PurchaseOrderMapper.xml
+  - src/main/resources/db/migration/V1__create_purchase_order.sql
+  - src/main/webapp/index.html
+  - src/main/webapp/pages/purchase-order/main.js
+  - src/main/webapp/pages/purchase-order/router.js
+  - README.md
+```
+
+## 关键决策
+
+1. **项目模式**：`new`（无 src/ 目录，触发 scaffold）
+2. **包名**：`com.example.purchase`
+3. **数据库表前缀**：`T_PURCHASE_*`（业务表，非 PF_）
+4. **依赖**：
+   - meritdata-cloud-starter
+   - cloud-system-bpm-module-core（采购审批）
+   - mybatis-plus-boot-starter
+   - easyexcel（Excel 导出）
+5. **前端**：Vue CLI 多页面 + Element UI + cloud-module-base
+
+## 后续步骤
+
+```bash
+# 1. 初始化 Git
+git init
+git add .
+git commit -m "feat(purchase): init project"
+
+# 2. 启动开发
+mvn spring-boot:run
+
+# 3. 访问
+open http://localhost:8080/purchase-order
+```
+
+## 注意事项
+
+- 本示例**仅展示** playbook 输出格式，不包含真实可编译代码
+- 真实开发请通过 `$meritdata-platform-playbook` 触发自动生成
+- 详见 `meritdata-platform-clouddev` skill 的 `references/modules/gen.md`（同公司其他 skill）

package/skills/meritdata-platform-playbook/references/code-spec.md

@@ -0,0 +1,67 @@
+---
+name: merit-code-spec
+description: merit 公司 Java 代码规范自查/检查（命名/OOP/集合/并发/异常/注释/SQL/日志/Swagger + ResultBody/GridView + 表名大写下划线+业务前缀 T_xxx 等平台规范）
+---
+
+# Merit 公司代码规范检查
+
+> ⚠️ **本规范已修订（2026-09-10）**：
+> - 表名规范以 `.claude/rules/sql-naming-rules.md` 为权威（大写 + 下划线 + 业务前缀，如 `T_CONTRACT`），**不再使用"小写蛇形"**
+> - 门禁脚本 `spec_scan.py` 已删除，统一使用 `meritdata-platform-2nd-dev-check` 执行体检
+> - 4 个 MISS 下级文件已整合到 `.claude/rules/*.md`，**不再单独维护**
+
+对生成或修改的 Java、SQL 和接口代码执行强制规范门禁。项目专属规范优先；不冲突的通用规则同时生效。
+
+## 路由
+
+| 维度 | 权威规则文件 |
+|------|------------|
+| Java 命名、OOP、集合、并发、异常、注释、SQL 与技术日志 | [.claude/rules/coding-standards-rules.md](../../../rules/coding-standards-rules.md) |
+| 安全、注入、认证、敏感信息 | [.claude/rules/security-rules.md](../../../rules/security-rules.md) |
+| 性能、数据库、缓存、并发 | [.claude/rules/performance-rules.md](../../../rules/performance-rules.md) |
+| SQL 命名（表/字段/索引/约束）| [.claude/rules/sql-naming-rules.md](../../../rules/sql-naming-rules.md) |
+| SQL 脚本规范 | [.claude/rules/sql-script-rules.md](../../../rules/sql-script-rules.md) |
+| 命名约定（类/方法/常量/包）| [.claude/rules/naming-conventions-rules.md](../../../rules/naming-conventions-rules.md) |
+| REST API 规范 | [.claude/rules/api-design-rules.md](../../../rules/api-design-rules.md) |
+| 代码开发指南（流程/异常/资源）| [.claude/rules/code-dev-rules.md](../../../rules/code-dev-rules.md) |
+| 平台二开数据边界铁律 | [.claude/rules/data-boundary-rules.md](../../../rules/data-boundary-rules.md) |
+| Nacos 配置规范 | [.claude/rules/nacos-rules.md](../../../rules/nacos-rules.md) |
+| Git 工作流 | [.claude/rules/git-workflow-rules.md](../../../rules/git-workflow-rules.md) |
+| 文档规范 | `~/.claude/rules/documentation-rules.md`（**用户级**，非项目级）|
+
+> **不再单独维护** `java-core-rules.md` / `meritdata-platform-rules.md` / `checklist.md` / `spec_scan.py`，全部规则已统一收纳到项目级 rules 目录。
+
+## 检查流程
+
+1. 识别项目平台版本、Java/Spring 版本、数据库和项目已有约定。
+2. **加载门禁**：触发 `meritdata-platform-2nd-dev-check` skill（替代原 `spec_scan.py`），做 7 类 60+ 项体检。
+3. **数据边界**：触发 `.claude/rules/data-boundary-rules.md` 的 4 条铁律校验。
+4. 只检查与本次改动相关的维度，但覆盖所有受影响文件。
+5. 报告精确到文件和行，给出规则、风险和最小修复。
+6. 修复强制项后重新扫描、编译和测试；不能确认的依赖/API 标记 GAP。
+
+## 输出
+
+```text
+Merit 代码规范自查报告
+  ❌ [强制] <文件>:<行> <问题>（修复建议）
+  ⚠️ [建议] <文件>:<行> <问题>
+强制违反 N 项，建议 N 项
+```
+
+只有强制违反为 0、2nd-dev-check 体检 0 FAIL、数据边界 4 铁律全通过，才可声明规范门禁通过。
+
+## SQL 命名（最重要，速查）
+
+| 对象 | 规则 | 示例 |
+|------|------|------|
+| 表名 | 大写 + 下划线 + 业务前缀（`T_xxx`）| `T_USER`、`T_CONTRACT` |
+| 字段名 | 大写 + 下划线 | `USER_NAME`、`CREATE_TIME` |
+| 索引 | `IDX_` / `UNI_` / `PK_` 前缀 | `IDX_USER_NAME` |
+| 约束 | `PK_` / `UK_` / `FK_` / `CK_` 前缀 | `PK_USER` |
+
+> ❌ **不要使用"小写蛇形"**（如 `t_user` / `user_name`）—— 与平台 6.13.2 jar 实体映射不兼容，会导致 MyBatis 实体类字段映射失败。
+
+---
+
+**修订说明**：2026-09-10 同步 `.claude/rules/*.md` 12 个项目级规则文件；删除 4 个 MISS 下级文件（`java-core-rules.md` / `checklist.md` / `meritdata-platform-rules.md` / `spec_scan.py`）；修正表名规范与 `sql-naming-rules.md` 一致。