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

package/rules/coding-standards-rules.md

@@ -1,99 +0,0 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-合并入套件：2026-09-08
-修复说明：v2.6.x 抽取时丢失全部正文（仅留 198 字节 TODO stub），从全局 `~/.claude/rules/coding-standards-rules.md` 恢复 92 行真实内容。
--->
-
-# 编码规范
-
-**触发条件**：编写Java代码、开发功能模块时
-
----
-
-## 一、资源管理
-
-**必须执行**：
-- 使用 `try-with-resources` 自动关闭资源
-- 关闭顺序与开启顺序相反
-- 文件读取前检查是文件而非文件夹
-
-**禁止执行**：
-- 禁止在 `finally` 块中抛出异常
-- 禁止关闭连接后继续使用
-
-**正确示例**：
-```java
-try (InputStream in = new FileInputStream(file);
-     BufferedReader reader = new BufferedReader(new InputStreamReader(in))) {
-    // 使用 reader
-} // 自动关闭
-```
-
----
-
-## 二、集合处理
-
-**必须执行**：
-- 创建集合时指定初始容量：`new ArrayList<>(16)`、`new HashMap<>(16)`
-- 方法返回集合时，**返回空集合而非 null**：`return Collections.emptyList()`
-- 判断集合为空使用 `isEmpty()` 而非 `size() == 0`
-- 使用 `CollectionUtils.isEmpty()` 判断 null 或空
-
----
-
-## 三、字符串处理
-
-**必须执行**：
-- `equals` 比较时，**常量写在前面**：`"constant".equals(str)`
-- 避免不必要的字符串拼接，优先使用 StringBuilder
-- 拼接路径时使用 `/` 或 `Paths.get()`，避免硬编码分隔符
-
----
-
-## 四、异常处理
-
-**必须执行**：
-- 异常信息**脱敏后再记录日志**（移除 password、keytab、principal 等）
-- 使用自定义异常类 + 错误码，不直接暴露 JDK 异常
-- 接口调用要进行超时处理
-
-**禁止执行**：
-- 禁止空的 catch 块
-- 禁止吞掉异常不处理
-
----
-
-## 五、并发处理
-
-**必须执行**：
-- 线程池使用 `Executors` 工厂方法创建后，务必指定队列大小
-- 使用 `RateLimiter` 限流时设置合理的 QPS
-- 缓存 key **必须包含用户标识**实现用户隔离：`userId:appId`
-
----
-
-## 六、对象创建
-
-**禁止执行**：
-- 禁止在循环内创建大对象引用
-- 禁止在循环内调用外部资源（数据库、Redis、HTTP）
-
----
-
-## 七、日志规范
-
-**必须执行**：
-- 使用 SLF4J 日志门面
-- 日志级别：`ERROR`（业务异常）、`WARN`（降级处理）、`INFO`（关键流程）、`DEBUG`（调试）
-
-**禁止执行**：
-- **禁止记录敏感信息**：password、keytab、principal、token
-
----
-
-## 重要提醒
-
-- 资源必须及时关闭，否则会导致连接泄漏
-- 用户输入永远不可信，必须校验
-- 敏感信息最小化原则：只收集必要的信息

package/rules/data-boundary-rules.md

@@ -0,0 +1,32 @@
+---
+name: data-boundary-rules
+description: 美林平台数据边界硬约束 —— 二开业务库严禁连接 cloud 平台库、跨库 JOIN、复制平台 Entity；跨 JVM 数据访问必须走 Feign/API 批量装配，不得在分页循环中逐条 Feign。
+metadata:
+  type: rules
+  source: company
+  risk: high
+---
+
+# Cloud 数据边界（4 条铁律）
+
+## 强制原则
+
+1. **不连接 cloud 平台库** —— 二开业务库严禁直连 cloud 微服务平台表（`PF_` 前缀）
+2. **不跨库 JOIN** —— 业务表与平台表禁止跨库 JOIN，改用应用层内存 join
+3. **不复制平台 Entity/Repository** —— 人员/组织/角色/字典只保存稳定 ID/code，不复制平台 Java 实体
+4. **不掩盖故障** —— 平台不可用时显式上抛异常，不得用空集合/false 伪装成功
+
+## 实施要求
+
+- 跨 JVM 数据访问必须走 Feign/API 批量装配，**不得在分页循环中逐条 Feign**（N+1 问题）
+- 人员/组织/角色/字典等基础数据，**同 JVM 平台模块**用本地 Bean（详见 `meritdata-platform-entities`）
+- **跨 JVM 业务服务**用 Feign（详见 `meritdata-platform-integration`）
+- 写平台数据只调用明确开放的写契约，不臆造 Client
+- 涉及数据访问前**请阅读本 rules**学习完整约束
+
+## 校验方式
+
+- 静态扫描：`grep -r 'PF_[A-Z]' src/main/java/` 查找 PF_ 表映射
+- 静态扫描：`grep -rE 'JOIN\s+PF_' src/main/resources/mapper/` 查找跨库 JOIN
+- 静态扫描：`grep -r 'import com.meritdata.cloud.platform.entity' src/main/java/` 查找平台 Entity 引用
+- 提交前用 `meritdata-platform-2nd-dev-check` 体检

package/rules/frontend-coding-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # 前端编程规范
 
 **触发条件**：编写Vue/Element UI前端代码、开发前端功能模块时

package/rules/frontend-component-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # 前端组件和交互规范
 
 **触发条件**：设计前端组件、定义用户交互行为、开发Element UI组件时

package/rules/git-workflow-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # Git 工作流
 
 **触发条件**：使用 Git 进行版本控制时

package/rules/nacos-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # Nacos 配置中心规范（项目级）
 
 **触发条件**：在 cloud_back 项目中使用 Nacos 进行配置管理时

package/rules/naming-conventions-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # 命名规范
 
 ---

package/rules/performance-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # 性能规范
 
 **触发条件**：涉及数据库查询、缓存使用、并发处理、大数据量处理时

package/rules/security-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # 安全编码规范
 
 **触发条件**：涉及用户认证、数据传输、权限控制、敏感信息处理时

package/rules/sql-naming-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # SQL 命名规范
 
 **触发条件**：编写 SQL 语句、数据库表设计、字段命名、索引命名、数据库对象命名时

package/rules/sql-script-rules.md

@@ -1,9 +1,3 @@
-<!--
-来源：研发skills/rules v1.0（2026-08 收录）
-抽取到 pfsuite/rules：2026-09-04
-后续治理：合并三方意见后再升级
--->
-
 # SQL脚本提交规范
 
 **触发条件**：编写SQL脚本、数据库迁移、DML/DDL操作时

package/skills/meritdata-platform-2nd-dev-check/README.md

@@ -0,0 +1,196 @@
+# meritdata-platform-2nd-dev-check Skill
+
+> **美林微服务应用开发平台 6.x 样例工程二开就绪度检查工具**
+> 自动从**项目内配置的 Nacos 导出目录**加载真实配置（默认 `<项目根>/nacos_config_export/DEFAULT_GROUP/`，可自定义），零硬编码，适配任何美林 6.x 二开项目。
+
+## 🎯 用途
+
+新开发者接手美林 6.x 样例工程时，用此 skill 一键检查：
+
+- ✅ 基础设施是否可达（MySQL / Redis / Nacos / 4 个平台服务）
+- ✅ 后端工程结构（pom.xml / Java 包 / 配置）
+- ✅ 前端工程结构（package.json / 页面 / 构建）
+- ✅ 平台依赖（9 工具类 + 5 组件 100% 验证）
+- ✅ 数据库表（cloud 库 139 张表）
+- ✅ 代码规范（包路径 / 命名 / 审计字段）
+
+避免在配置不全或路径错误的情况下启动后端浪费几小时。
+
+## 🚀 快速开始
+
+### 第 1 步：设置环境变量（最少 7 项）
+
+```bash
+export APP_NAME=your-app-name                # 你的 Spring Boot 应用名
+export APP_PORT=18080                          # 你的服务端口
+export MAVEN_SETTINGS="<你的 settings.xml 绝对路径>"
+export MERIT_HOME="<美林平台环境根，含 key/ 证书>"
+export PLATFORM_VERSION=6.13.2                 # 或其他 6.x 版本
+export FRONTEND_PAGES=page1,page2,page3      # 前端业务页面（逗号分隔）
+export NACOS_HOST=localhost
+export NACOS_PORT=8850
+```
+
+### 第 2 步：跑检查
+
+```bash
+# 一键全套
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/run-all.sh
+
+# 单项
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/check-platform.sh
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/check-backend.sh
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/check-frontend.sh
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/check-database.sh
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/check-conventions.sh
+```
+
+### 第 3 步：阅读报告
+
+- 通过 60+ 项：✅ 工程可立即进入业务开发
+- 有 FAIL 项：参考 `references/fix-guide.md` 修复
+
+## 🔧 自动配置加载机制
+
+skill 启动时**自动从项目内配置的 Nacos 导出目录（默认 `<项目根>/nacos_config_export/DEFAULT_GROUP/`，可自定义）读取真实配置**，无需手填。
+
+| 来源文件 | 自动解析的字段 |
+|----------|---------------|
+| `common-datasource.properties` | `spring.datasource.url` → MYSQL_HOST/PORT/USER/PASSWORD/DATABASE<br>`driver-class-name` |
+| `common-cache.properties` | `meritdata.cloud.cache.serve-hosts` → REDIS_HOST/PORT<br>`meritdata.cloud.cache.serve-password` |
+| `common.properties` | `meritdata.cloud.platform-version`<br>`meritdata.cloud.nacos-addr` |
+| `common-cloud-system-manage.properties` | `spring.cloud.nacos.discovery.server-addr` |
+| `common-${APP_NAME}.properties` | `server.port` |
+
+### 配置优先级
+
+```
+1. 用户 export 的环境变量（最高优先级）
+   ↓
+2. Nacos 导出目录（默认 `<项目根>/nacos_config_export/DEFAULT_GROUP/`，可自定义）解析
+   ↓
+3. 报错"环境变量未设置"
+```
+
+### 数据源类型自适应
+
+根据 `spring.datasource.driver-class-name` 自动识别：
+- `com.mysql.cj.jdbc.Driver` → MySQL
+- `oracle.jdbc.OracleDriver` → Oracle
+- `org.postgresql.Driver` → PostgreSQL
+
+## 📂 目录结构
+
+```
+.claude/skills/meritdata-platform-2nd-dev-check/
+├── SKILL.md                       # skill 入口（含 YAML frontmatter）
+├── README.md                      # 本文件
+├── references/
+│   ├── checklist.md               # 60+ 项检查清单（含占位符）
+│   └── fix-guide.md                # 修复指南（5 个包路径偏差 + 6 个方法名修正）
+├── scripts/
+│   ├── run-all.sh                  # 一键全套检查
+│   ├── load-config.sh              # 自动从 Nacos 导出目录（默认 `<项目根>/nacos_config_export/`，可自定义）加载配置
+│   ├── check-platform.sh           # 1️⃣ 基础设施（MySQL/Redis/Nacos/平台服务）
+│   ├── check-backend.sh            # 2️⃣ 后端工程（pom.xml/Java/编译）
+│   ├── check-frontend.sh           # 3️⃣ 前端工程（npm/页面/构建）
+│   ├── check-database.sh           # 4️⃣ 数据库（cloud 库表）
+│   └── check-conventions.sh        # 5️⃣ 代码规范（包路径/命名/审计字段）
+└── 历史报告输出（默认 `<项目根>/examples/`，可自定义）
+    ├── last-check-report.log       # 历史报告
+    └── last-check-report.json      # 历史报告（JSON）
+```
+
+## 📋 7 大类检查项
+
+### 1️⃣ 基础设施（Prerequisites）
+- [ ] MySQL 可达（含 130+ 张表）
+- [ ] Redis 可达（含 CACHE_SESSION_LIST_KEY）
+- [ ] Nacos 可达（含 6 份 common-* + 工程专属配置）
+- [ ] 平台服务 4 个健康（gateway :8081 / manage :8085 / bpm-engine :8089 / job :8086）
+
+### 2️⃣ 后端工程（Back-end）
+- [ ] pom.xml artifactId = `${APP_NAME}`
+- [ ] 3 个必备依赖（cloud-starter-core / cloud-module-base / cloud-system-bpm-module-core）
+- [ ] bootstrap.properties 5 项关键配置
+- [ ] CLOUD_HOME/key/ 3 个证书文件
+- [ ] mvn compile 通过
+
+### 3️⃣ 前端工程（Front-end）
+- [ ] package.json 双私有依赖 6.13.2
+- [ ] .npmrc registry 配置
+- [ ] vue.config.js pages 配置每个 `$FRONTEND_PAGES` 页面
+- [ ] node_modules 验证（cloud-module-base / cloud-module-bpm 实际安装）
+- [ ] npm run build 通过
+
+### 4️⃣ 平台依赖（Platform JARs）
+- [ ] 9 个后端工具类 100% 存在
+- [ ] 5 个后端组件 100% 存在
+- [ ] 2 个缺失组件已用替代方案
+
+### 5️⃣ 平台服务（Platform Services）
+- [ ] Nacos 6 份 common 配置
+- [ ] common-${APP_NAME}.properties 工程专属
+- [ ] 4 个平台服务 healthy
+
+### 6️⃣ 数据库（Database）
+- [ ] cloud 库 130+ 张表
+- [ ] pf_user_info / pf_org_user / pf_resource
+- [ ] act_* 40+ 张
+- [ ] pf_job_* 定时任务
+
+### 7️⃣ 代码规范（Conventions）
+- [ ] 5 个包路径偏差修正（ILogPostService / BpmEngine / LogDesc 系列）
+- [ ] 6 个方法名修正（NacosUtils 5 个 + Sm2Utils.getKey）
+- [ ] 3 个调用方式修正（实例方法）
+- [ ] 命名规范（XxxController / IxxxService / XxxServiceImpl）
+- [ ] 6 个审计字段（CREATE_BY/TIME、UPDATE_BY/TIME、VERSION、IS_DELETED）
+- [ ] SECRET_LEVEL 密级字段
+
+## 🛠️ 故障排查
+
+| 错误 | 原因 | 修复 |
+|------|------|------|
+| `请提供正确格式的序列号!` | `${MERIT_HOME}` 路径错或证书缺失 | 设置 `MERIT_HOME` 指向真实证书目录 |
+| `Could not find artifact cloud-module-bpm` | 6.13.2 没有这个 artifactId | 改用 `cloud-system-bpm-module-core` |
+| `error:0308010C OpenSSL` | Node 17+ 与老 webpack 冲突 | 加 `cross-env NODE_OPTIONS=--openssl-legacy-provider` |
+| `Cannot resolve cloud-module-base` | npm 私有 registry 错 | 改用 `https://registry.npmmirror.com` |
+| `login-success=false` | 凭证无效 | 联系平台 admin 重置 |
+| `Field sessionUtils required a bean` | SessionUtils 未注入 | 在 Controller 加 `@Autowired` |
+
+更多问题见 `references/fix-guide.md`。
+
+## 📊 输出报告示例
+
+```bash
+=== 1️⃣ 基础设施 (MySQL/Redis/Nacos/平台服务) ===
+✅ MySQL: 可连接，版本 8.0.39
+✅ cloud 库: 存在，139 张表
+✅ Redis 端口: localhost:6380 可达
+⚠️ Nacos 凭据 403
+...
+
+通过: 6 / 警告: 15 / 失败: 0
+```
+
+## 📚 参考文献
+
+- 美林平台《微服务前后端公共资产清单》文档
+- 美林平台《微服务外部接口清单》文档
+- 美林平台 6.x 各版本 release notes
+- `references/checklist.md` — 详细 60+ 项检查清单
+- `references/fix-guide.md` — 修复指南（5 包路径偏差 + 6 方法名修正）
+
+## 📝 维护说明
+
+- 本 skill 是**只读**检查工具，不会修改任何项目文件
+- 适用于所有美林 6.x 平台项目（基线 6.13.2）
+- 数据源类型自动适配（MySQL / Oracle / PostgreSQL）
+- 历史报告归档到**项目根目录的报告输出目录**（可自定义路径）供版本对比
+- 修改 `SKILL.md` 或 scripts 后，重新跑 `run-all.sh` 验证
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-07-24 | 初版（60+ 项检查 + 自动配置加载） |

package/skills/meritdata-platform-2nd-dev-check/SKILL.md

@@ -1,38 +1,224 @@
 ---
 name: meritdata-platform-2nd-dev-check
-description: 二开项目合规扫描（4 铁律 + 命名 + 软删除）。当用户说"二开合规 / 平台合规 / 合规扫描 / 上线检查 / check / lint"时使用。
+description: 二开项目就绪度体检。用于上线前/接入前的项目自检，覆盖 7 类 60+ 项门禁（依赖/版本/命名/包结构/数据边界/集成/前端），输出 GAP 清单和修复建议。
 metadata:
   version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
   risk: low
-  layer: L4
-  sub-layer: L4-T
-  stack: tool
+  allowed-tools: Read, Grep, Glob, Bash
 ---
 
-# meritdata-platform-2nd-dev-check
+## ⭐ MUST DO
 
-## 触发
+**对二开项目做就绪度体检，覆盖 7 类 60+ 项门禁，未通过项必须显式输出 GAP 并提供修复建议。**
 
-- 用户说"二开合规 / 上线检查 / 合规扫描 / lint"
-- PR 提交前 / 流水线门禁
-- 平台升级前兼容性扫描
+## 触发条件 / 不适用
 
-## 不触发
+**适用**：
+- 用户说 `meritdata-platform-2nd-dev-check`
+- 新项目接入 skill 套件前
+- 存量项目升级/接入前
+- 上线前的就绪度自检
+- 季度安全审计
 
-- 业务逻辑 code review（→ `meritdata-platform-code-review`）
-- 数据访问深度审查（→ `meritdata-platform-data-access-review`）
-- 测试用例设计（→ `meritdata-platform-test-case`）
+**不适用**：
+- 纯文档查询（参考 `cloud-dev`）
+- 单点代码问题排查（参考对应领域 skill）
 
-## 前置约束
+## ⭐ 调用前必查：项目根目录
 
-- 扫描对象：二开服务的 `src/main/` 目录
-- 4 条铁律详情见 [`rules/meritdata-platform-data-boundary.md`](../../rules/meritdata-platform-data-boundary.md)
-- 5 条硬规则见 [`rules/meritdata-platform-domain-model-rules.md`](../../rules/meritdata-platform-domain-model-rules.md)
-- 软删除规则见 [`rules/code-dev-rules.md §八`](../../rules/code-dev-rules.md)
-- 违反**阻断 PR**（CI exit 1）
+> ⚠️ **关键前提**：本 skill 的所有检查都依赖**项目根目录**（后端代码目录 / 前端代码目录 / Nacos 配置目录 / 报告输出目录）。
 
-## 路由
+### 调用流程
 
-- [guide.md](references/guide.md) — 命令清单 + 输出格式
-- [rules-checklist.md](references/rules-checklist.md) — 9 条规则逐条检查项
-- [ci-integration.md](references/ci-integration.md) — GitLab/GitHub Actions 集成
+```
+1. AI 调用本 skill 前，**必须**先检查用户是否指定了项目根目录
+2. 如果**未指定**（最常见），AI 必须**反问用户**：
+   "请提供要检查的项目根目录绝对路径（如 D:/projects/my-2nd-dev）"
+3. 用户提供路径后，AI 按以下映射设置环境变量（统一使用正斜杠）：
+   - 后端目录    = <项目根>/后端
+   - 前端目录    = <项目根>/前端
+   - Nacos 配置目录 = <项目根>/Nacos 导出目录（默认 `nacos_config_export/`，可自定义）
+   - 报告输出目录  = <项目根>/报告输出目录（默认 `examples/`，可自定义）
+```
+
+### 环境变量约定
+
+| 变量 | 用途 | 默认值 |
+|---|---|---|
+| `PROJECT_ROOT` | 项目根目录绝对路径 | **必填**，用户反问后提供 |
+| `BACKEND_DIR` | 后端代码目录 | `${PROJECT_ROOT}/后端` |
+| `FRONTEND_DIR` | 前端代码目录 | `${PROJECT_ROOT}/前端` |
+| `NACOS_EXPORT_DIR` | Nacos 导出目录 | `${PROJECT_ROOT}/nacos_config_export` |
+| `REPORT_OUTPUT_DIR` | 体检报告输出目录 | `${PROJECT_ROOT}/examples` |
+
+### 反问模板（必须使用）
+
+> 好的，体检前请提供：
+> 1. **项目根目录**（绝对路径）：如 `D:/projects/my-2nd-dev`
+> 2. 确认目录结构：
+>    - 后端代码目录 = `<项目根>/后端`（如 `D:/projects/my-2nd-dev/后端`）
+>    - 前端代码目录 = `<项目根>/前端`
+>    - Nacos 配置目录 = `<项目根>/nacos_config_export`
+> 3. 如果目录名不一样（如 backend/ 而非 后端/），请告诉我实际路径
+
+## 工作方式（Step 1-6）
+
+### Step 1：加载项目根目录（用户反问）
+
+如"调用前必查"所述，先确认 `PROJECT_ROOT` 是否已设置。
+
+### Step 2：环境检查（7 大类 60+ 项）
+
+1. **基础环境**（5 项）
+2. **依赖与版本**（10 项）
+3. **包结构与命名**（10 项）
+4. **代码规范**（15 项）
+5. **集成与配置**（10 项）
+6. **前端工程**（5 项）
+7. **安全与审计**（5 项）
+
+### Step 3-6（体检执行 + 报告输出）
+
+按各脚本（`check-*.sh`）自动执行，结果输出到 `${REPORT_OUTPUT_DIR}`（默认 `<项目根>/examples/`，可自定义）。
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+| 依赖与版本检查 | [`checklists/dependency.chk.json`](checklists/dependency.chk.json) |
+| 命名规范检查 | [`checklists/naming.chk.json`](checklists/naming.chk.json) |
+| 包结构检查 | [`checklists/package-structure.chk.json`](checklists/package-structure.chk.json) |
+| 集成与接口检查 | [`checklists/integration.chk.json`](checklists/integration.chk.json) |
+| 前端工程检查 | [`checklists/frontend.chk.json`](checklists/frontend.chk.json) |
+| 安全合规检查 | [`checklists/security.chk.json`](checklists/security.chk.json) |
+| 检查清单 schema | [`checklists/checks.schema.json`](checklists/checks.schema.json) |
+
+## 工作方式（Step 1/2/3/4）
+
+### Step 1：识别目标项目
+
+```yaml
+target:
+  path: <绝对路径>
+  vcs: git | svn | none
+  project_mode: new | existing | existing-legacy
+  platform_version: 6.13.2 | 6.12.1 | ...
+```
+
+### Step 2：执行 7 类检查
+
+| # | 类别 | 项数 | 阻塞等级 |
+|---|------|:----:|---------|
+| 1 | 依赖与版本 | 10 | 🔴 阻塞 |
+| 2 | 命名规范 | 8 | 🟠 警告 |
+| 3 | 包结构 | 9 | 🟠 警告 |
+| 4 | 数据边界 | 11 | 🔴 阻塞 |
+| 5 | 集成与接口 | 8 | 🟠 警告 |
+| 6 | 前端工程 | 7 | 🟠 警告 |
+| 7 | 安全合规 | 9 | 🔴 阻塞 |
+
+### Step 3：分类汇总
+
+```yaml
+results:
+  pass: 42
+  warn: 12
+  fail: 6
+  total: 60
+```
+
+### Step 4：输出 GAP 修复建议
+
+每个 fail 项必须含：
+- 检测规则
+- 失败原因
+- 修复建议（具体到代码片段或配置项）
+- 影响范围（仅本项目 / 跨服务）
+
+## 代码示例
+
+### 检查项示例（数据边界）
+
+```json
+{
+  "id": "DB-001",
+  "category": "dependency",
+  "level": "block",
+  "title": "二开库不得包含 PF_ 前缀表",
+  "rule": "find . -name '*.sql' -exec grep -l 'CREATE TABLE PF_' {} \\;",
+  "expected": "无匹配",
+  "fix": "删除或重命名为 T_ 前缀"
+}
+```
+
+### 用户输入
+
+```text
+meritdata-platform-2nd-dev-check --target ./my-project
+```
+
+### 输出示例
+
+```yaml
+project: ./my-project
+vcs: git
+platform_version: 6.13.2
+
+results:
+  pass: 42
+  warn: 12
+  fail: 6
+  total: 60
+
+by_category:
+  dependency:    pass=8  warn=1  fail=1
+  naming:        pass=7  warn=1  fail=0
+  package-structure: pass=8  warn=1  fail=0
+  integration:   pass=7  warn=1  fail=0
+  frontend:      pass=6  warn=2  fail=0
+  security:      pass=5  warn=0  fail=3  ← 🔴
+
+gap_items:
+  - id: DB-001
+    title: 二开库包含 PF_ 前缀表
+    fix: |
+      DROP TABLE PF_LEGACY_USER;
+      -- 迁移数据到 T_USER
+  - id: SEC-003
+    title: application.yml 含明文密码
+    fix: |
+      spring:
+        datasource:
+          password: ${DB_PASSWORD}  # 改为环境变量
+```
+
+## 📚 详细文档
+
+- [`checklists/dependency.chk.json`](checklists/dependency.chk.json)
+- [`checklists/naming.chk.json`](checklists/naming.chk.json)
+- [`checklists/package-structure.chk.json`](checklists/package-structure.chk.json)
+- [`checklists/integration.chk.json`](checklists/integration.chk.json)
+- [`checklists/frontend.chk.json`](checklists/frontend.chk.json)
+- [`checklists/security.chk.json`](checklists/security.chk.json)
+- [`checklists/checks.schema.json`](checklists/checks.schema.json)
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 跳过数据边界检查 | 上线后出现跨库 JOIN 故障 | 阻塞级门禁，必须通过 |
+| 只检查 PASS 项不修 FAIL 项 | 体检失去意义 | fail 项必须输出 fix |
+| 在 fix 建议中要求用户提供源码 | 违反"运行时只读"门禁 | 仅基于已发布证据给建议 |
+| 把 warn 当 pass 输出 | 隐藏潜在风险 | 显式列出 warn 项 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 单点代码问题 → 对应领域 skill
+  - 性能优化 → `meritdata-platform-deploy`
+  - 安全审计的合规性解读 → 法务/安全团队
+- **强制要求**：fail 项不修复则不允许进入上线流程