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

package/skills/meritdata-platform-playbook/references/full-workflow.md

@@ -0,0 +1,299 @@
+# 端到端完整开发流程
+
+> **示例：加一个"合同管理"业务模块**（已与 platform 6.13.2 jar 字节码实测对齐，2026-09-10 重写）
+>
+> ⚠️ **本流程是示例骨架**，具体接口路径以 `meritdata-platform-integration/references/external-api/full/` 文档为准
+
+## Phase 0：规划（先看再写）
+
+```text
+0.1 加载 playbook → 触发 cloud-dev → 读 references/modules/gen.md 确认脚手架约定
+0.2 读 sql-naming-rules.md（表名大写+下划线+业务前缀 T_xxx）
+0.3 读 data-boundary-rules.md（二开库不连平台库、不跨库 JOIN、不分页循环 Feign、不掩盖故障）
+0.4 触发 2nd-dev-check 做二开就绪度体检（必须 0 FAIL 才能进入开发）
+```
+
+---
+
+## Phase 1：前置接入（必做）
+
+### 1.1 SSO 接入
+
+| 步骤 | 操作 | 触发 |
+|------|------|------|
+| 1.1.1 | pom.xml 加 `cloud-starter-core`（**必须第一位**）| `meritdata-platform-sso` |
+| 1.1.2 | bootstrap.properties 配 `CLOUD_HOME` | `meritdata-platform-sso` |
+| 1.1.3 | 实现 `IPortalSSOApi.getUserIdAndToken` | `meritdata-platform-sso` |
+
+### 1.2 二开就绪度检查
+
+```bash
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/run-all.sh
+# 必须 0 FAIL 项才能进入开发
+```
+
+---
+
+## Phase 2：建表（数据库）
+
+### 2.1 SQL 命名规范（权威）
+
+> 表名大写 + 下划线 + 业务前缀（如 `T_CONTRACT`），字段大写 + 下划线（如 `CONTRACT_NAME`）
+> 详见 `.claude/rules/sql-naming-rules.md`
+
+### 2.2 业务表 DDL
+
+```sql
+CREATE TABLE T_CONTRACT (
+    ID              BIGINT          NOT NULL    AUTO_INCREMENT  COMMENT '主键ID',
+    CONTRACT_NO     VARCHAR(32)     NOT NULL                    COMMENT '合同编号',
+    CONTRACT_TYPE   VARCHAR(32)     NULL                        COMMENT '合同类型（字典：CONTRACT_TYPE）',
+    AMOUNT          DECIMAL(15,2)   NULL                        COMMENT '合同金额',
+    STATUS          TINYINT         NOT NULL    DEFAULT 0       COMMENT '审批状态（字典：APPROVE_STATUS）',
+    APPLICANT_ID    VARCHAR(32)     NULL                        COMMENT '申请人 ID',
+    DEPT_ID         VARCHAR(32)     NULL                        COMMENT '部门 ID',
+    REMARK          VARCHAR(500)    NULL                        COMMENT '备注',
+
+    -- 审计字段（CloudBaseEntity 已含，此处仅作文档说明）
+    -- CREATOR_ID  VARCHAR(64)   创建人
+    -- CREATE_TIME DATETIME      创建时间
+    -- REVISER_ID  VARCHAR(64)   修改人
+    -- UPDATE_TIME DATETIME      修改时间
+    
+    PRIMARY KEY (ID),
+    UNIQUE KEY UK_CONTRACT_NO (CONTRACT_NO),
+    KEY IDX_CONTRACT_APPLICANT (APPLICANT_ID),
+    KEY IDX_CONTRACT_DEPT (DEPT_ID)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='合同主表';
+```
+
+> ❌ **不要自建 `SECRET_LEVEL INT DEFAULT 1`** — 业务表应继承 `CloudBaseEntity`，自动获得 `DATA_SECRET BIGINT` 字段（5 级密级 10/20/30/40/50）。详见 `meritdata-platform-data-secret/references/secret-level-spec.md`。
+
+---
+
+## Phase 3：后端开发
+
+### 3.1 Session 工具（实测 `com.meritdata.cloud.utils.SessionUtils`）
+
+> ⚠️ **方法名是 `getUserId()` / `getDeptId()`**，**没有 `getCurrent*` 前缀**。照着写会编译失败。
+
+```java
+import com.meritdata.cloud.utils.SessionUtils;
+
+String userId = SessionUtils.getUserId();
+String deptId = SessionUtils.getDeptId();
+```
+
+### 3.2 人员 / 部门查询（`meritdata-platform-integration`）
+
+> ❌ **没有 `meritdata-platform-org-user-api` 这个 skill**，能力已合入 `meritdata-platform-integration/references/external-api/full/`。
+
+**真实 Feign 路径**（详见 `full/25-35_2.1-2.6组织人员维护.md`）：
+
+```java
+@FeignClient(name = "cloud-system-manage")
+public interface OrgUserFeignClient {
+    // 部门下人员
+    @GetMapping("/api/ou/user/listByDept")
+    ResultBody<List<UserVO>> listUsersByDept(@RequestParam String deptId);
+    // 角色列表
+    @GetMapping("/api/ou/role/list")
+    ResultBody<List<RoleVO>> listRoles();
+}
+```
+
+### 3.3 字典查询（`meritdata-platform-integration`）
+
+> ❌ **没有 `meritdata-platform-dict-api` 这个 skill**，且**接口路径不是 `/api/dict/item/listByType`**。
+
+**真实路径**（详见 `full/38_3.11基础数据.md`）：
+
+```java
+@FeignClient(name = "cloud-system-manage")
+public interface DictFeignClient {
+    @GetMapping("/api/basic/lookup/lookupsEnable")
+    ResultBody<List<DictItemVO>> listByType(@RequestParam String typeCode);
+}
+```
+
+### 3.4 数据密级（`meritdata-platform-data-secret`）
+
+```java
+// Entity 继承 CloudBaseEntity，自动获得 DATA_SECRET 字段
+@Entity
+@Table(name = "T_CONTRACT")
+public class Contract extends CloudBaseEntity {
+    @Column(length = 32)
+    private String contractNo;
+    // ... 其他字段
+}
+```
+
+> **唯一可用注解**：`@EnableDataSecretFilter` 标在**查询方法**上（不是启动类），启用该方法的密级过滤
+> - 全工程开关是 Nacos 配置 `meritdata.cloud.use-platform-secret` / `emp-data-secret` / `resource-data-secret`（任一为 `false` 时 `DataSecretInterceptor` 跳过）
+> - ~~`@EnableDataSecretFilter`~~（**不存在**） / `EnableSecretFilter` 也是方法级标注
+>
+> 详见 `meritdata-platform-data-secret/references/secret-level-spec.md`
+
+### 3.5 操作日志（`meritdata-platform-logging`）
+
+```java
+@LogOperation(type = "合同管理-新增")
+@PostMapping("/api/contract")
+public ResultBody<ContractVO> add(@RequestBody ContractDTO dto) {
+    return contractService.add(dto);
+}
+```
+
+### 3.6 缓存（`meritdata-platform-cache`）
+
+```java
+@Cacheable(value = "contract", key = "#id")
+public Contract getById(String id) {
+    return contractRepository.findById(id).orElse(null);
+}
+```
+
+### 3.7 消息（`meritdata-platform-messaging`）
+
+```java
+@Resource
+private CloudFeignMessageClient messageClient;
+// 审批通过后通知
+messageClient.sendToUser(applicantId, msg);
+```
+
+### 3.8 电子签章（`meritdata-platform-crypto-gm`）
+
+```java
+String sign = Sm2Utils.sign(privateKey, hash);
+String cipher = Sm4Utils.encrypt(sm4Key, contractText);
+```
+
+### 3.9 资源授权（`meritdata-platform-resource-auth`）
+
+```java
+@PreAuthorize("hasAuthority('contract_api_add')")
+@PostMapping("/api/contract")
+public ResultBody<ContractVO> add(@RequestBody ContractDTO dto) {
+    return contractService.add(dto);
+}
+```
+
+---
+
+## Phase 4：流程（BPM，按需）
+
+> ❌ **没有 `meritdata-bpm-2nd-dev` 这个 skill**，能力在 `meritdata-platform-bpm`。
+
+```java
+// 触发审批流程
+@Autowired(required = false)
+    private BpmEngine bpmClient;
+ResultBody result = bpmClient.startProcess("contract_approval", contractData);
+```
+
+---
+
+## Phase 5：前端开发
+
+### 5.1 选人 / 选部门（`meritdata-platform-ui-components`）
+
+> 组件 props 与 catalog 严格对齐，详见 `meritdata-platform-ui-components/references/components-catalog.md`
+
+```vue
+<user-select v-model="applicantId" :multiple="false" />
+<dept-select v-model="deptId" />
+```
+
+### 5.2 字典下拉
+
+```vue
+<el-select v-model="contractType">
+  <el-option v-for="item in dictItems"
+    :key="item.itemCode" :label="item.itemName" :value="item.itemCode" />
+</el-select>
+```
+
+### 5.3 流程按钮
+
+```vue
+<bpm-grid-buttons-new :proc-inst-id="procInstId" :task-id="taskId" />
+```
+
+---
+
+## Phase 6：挂载菜单
+
+> ❌ **没有 `meritdata-platform-menu-resource` 这个 skill**，能力在 `meritdata-platform-menu-config`（**团队私有 skill**）或 `meritdata-platform-resource-auth`。
+
+```bash
+# 触发 meritdata-platform-menu-config
+# 或通过 Nacos common-contract.properties 配置：
+meritdata.cloud.menu.contract.enabled=true
+meritdata.cloud.menu.contract.path=/contract
+meritdata.cloud.menu.contract.icon=icon-contract
+```
+
+---
+
+## Phase 7：测试 + 上线
+
+### 7.1 单元测试
+
+```bash
+mvn -s "D:/apache-maven-3.9.14/conf/settings.xml" test
+```
+
+### 7.2 二开就绪度复检
+
+```bash
+bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/run-all.sh
+```
+
+### 7.3 部署
+
+```bash
+mvn -s "..." spring-boot:run
+```
+
+---
+
+## 🎯 全流程 checklist
+
+- [ ] Phase 0: 读完 sql-naming-rules + data-boundary-rules
+- [ ] Phase 1: SSO 接入 + 2nd-dev-check 0 FAIL
+- [ ] Phase 2: 建表（大写+下划线+T_前缀）
+- [ ] Phase 3: 后端 9 个 skill（session/integration/cache/logging/messaging/data-secret/crypto-gm/resource-auth）
+- [ ] Phase 4: BPM 流程（meritdata-platform-bpm，按需）
+- [ ] Phase 5: 前端 3 个 skill（ui-components + el + bpm）
+- [ ] Phase 6: 挂菜单（meritdata-platform-menu-config）
+- [ ] Phase 7: 测试 + 2nd-dev-check 复检 + 部署
+
+---
+
+## 🔗 相关 skill 速查
+
+| 能力 | skill | 文档 |
+|------|-------|------|
+| 编排入口 | meritdata-platform-playbook | SKILL.md |
+| 综合开发 | meritdata-platform-cloud-dev | references/modules/ |
+| 体检 | meritdata-platform-2nd-dev-check | scripts/run-all.sh |
+| SSO | meritdata-platform-sso | — |
+| Session | meritdata-platform-session | — |
+| 人员/字典/外部接口 | meritdata-platform-integration | references/external-api/full/ |
+| 密级 | meritdata-platform-data-secret | references/secret-level-spec.md |
+| 日志 | meritdata-platform-logging | — |
+| 缓存 | meritdata-platform-cache | — |
+| 消息 | meritdata-platform-messaging | — |
+| 国密 | meritdata-platform-crypto-gm | — |
+| 资源授权 | meritdata-platform-resource-auth | — |
+| 流程 | meritdata-platform-bpm | — |
+| 前端组件 | meritdata-platform-ui-components | references/components-catalog.md |
+| 菜单挂载 | meritdata-platform-menu-config | — |
+
+---
+
+**修订说明（2026-09-10 第二轮）**：删除 `versionNo`（实测 CloudBaseEntity 只有 4 个字段：`createTime`/`updateTime`/`creatorId`/`reviserId`，无 `versionNo`）；删除 `@EnableDataSecretFilter` 注解（实测 jar 中**不存在** `@EnableDataSecretFilter`，只有 `@EnableDataSecretFilter` / `@EnableSecretFilter`，且**两者都标在方法上而非启动类**）；全工程开关改为 Nacos `use-platform-secret` / `emp-data-secret` / `resource-data-secret`。
+
+**首轮修订（2026-09-10）**：依据 platform 6.13.2 jar 实测。修正 SessionUtils 方法名（`getUserId`/`getDeptId`，无 `Current` 前缀）、CloudBaseEntity 字段名（`creatorId`/`reviserId`/`createTime`/`updateTime`）、密级字段（`DATA_SECRET BIGINT`，非 `SECRET_LEVEL INT`）、4 个下线 skill（`dict-api`/`org-user-api`/`bpm-2nd-dev`/`menu-resource`）的真实去向、字典 Feign 真实路径。

package/skills/meritdata-platform-playbook/references/git-integration.md

@@ -0,0 +1,111 @@
+
+`meritdata-platform-playbook` 与 Git 项目集成时遵循**只读契约**：仅读取状态，不修改任何东西。
+
+## 允许的操作
+
+### 1. 检查 Git 仓库
+
+```bash
+# 检测 .git/ 目录
+[ -d ".git" ] && echo "git-managed"
+
+# 获取远程 URL
+git remote get-url origin
+```
+
+### 2. 读取工作区状态
+
+```bash
+# 工作区变更
+git status --porcelain
+
+# 修改/新增/删除 文件清单
+git status --short
+```
+
+### 3. 读取差异
+
+```bash
+# 工作区 vs HEAD
+git diff
+
+# 工作区 vs staged
+git diff --cached
+
+# 当前分支 vs main
+git diff main...HEAD
+```
+
+### 4. 读取分支信息
+
+```bash
+# 当前分支
+git branch --show-current
+
+# 所有分支
+git branch -a
+
+# 最近 5 个 commit
+git log --oneline -5
+```
+
+### 5. 读取提交历史
+
+```bash
+# 当前分支历史
+git log --oneline -10
+
+# 单文件历史
+git log --oneline -- src/main/java/Example.java
+```
+
+## 禁止的操作
+
+| 操作 | 原因 |
+|------|------|
+| `git add` | 不自动暂存 |
+| `git commit` | 不自动提交 |
+| `git push` | 不自动推送 |
+| `git checkout` | 不自动切换分支 |
+| `git merge` | 不自动合并 |
+| `git rebase` | 不自动变基 |
+| `git reset` | 不自动重置 |
+| 修改 `.git/` 内部 | 破坏 Git 完整性 |
+
+## 输出格式
+
+playbook 检测 Git 项目后的输出：
+
+```yaml
+vcs:
+  type: git
+  status: clean | modified | untracked
+  branch: feature/leave-module
+  remote: git@internal-git:team/project.git
+
+files_changed:
+  modified:
+    - src/main/java/Example.java
+  added:
+    - src/main/java/NewFile.java
+  deleted: []
+
+suggested_commit_message: |
+  feat(leave): 添加请假模块
+  - LeaveController
+  - LeaveService
+  - LeaveRepository
+  - SQL migration: 2026-09-01-create-leave.sql
+
+manual_steps:
+  - git add .
+  - 用户手动执行 commit（由用户执行，skill 不自动）
+```
+
+## 异常处理
+
+| 场景 | 处理 |
+|------|------|
+| `.git/` 损坏 | 报错，要求用户修复 |
+| 当前分支已 detached | 提示用户切回分支 |
+| 工作区有未提交修改 | 输出 diff，建议用户先 commit 或 stash |

package/skills/meritdata-platform-playbook/references/governance.md

@@ -0,0 +1,97 @@
+---
+name: merit-skill-governance
+description: 治理公司级 Meritdata Cloud Skill 套件的目录边界、语义版本、事实证据、平台兼容、确定性测试、评审发布和退役。用于新增或升级 Skill、引入脚本、声明 API/组件能力、版本迁移、发布前审计、证据过期复核和生产事故追溯。
+---
+
+# 企业级 Skill 治理
+
+> ⚠️ **本治理文档于 2026-09-10 修订**：移除 7 个不存在的下级文件引用（`automation-policy.md` / `evidence-policy.md` / `release-policy.md` / `directory-contract.md` / `role-scenario-gates.md` / `version-profile-integration.md` / `version-profiles.json`），治理摘要直接写入本文档。修正原文档"只能有 1 个 SKILL.md"等不实约束（实际 24 个公司级 skill + 3 个团队私有 skill）。
+
+将 Skill 视为可发布的软件资产，而不是提示词集合。先盘点事实，再做变更；未经证据支持的接口不得进入稳定发布通道。
+
+## 治理对象与边界
+
+**当前套件规模**（v2.0.0）：
+
+| 层级 | 数量 | 命名规范 |
+|------|:---:|---------|
+| 公司级 skill | **21** | `meritdata-platform-<name>`（如 `meritdata-platform-bpm`）|
+| 团队私有 skill | **3** | `{team}-meritdata-platform-<x>` 或本工程内统一 `meritdata-platform-<x>` |
+| 项目级 rules | **13** | `.claude/rules/<name>-rules.md`（含 `data-boundary-rules.md`）|
+| 总元素 | **37** | — |
+
+> **每个 skill 独立拥有 `SKILL.md` 入口**（共 24 个），不是"只能有 1 个"。本文档的"目录契约"已修正。
+
+## 治理流程（7 步）
+
+| # | 步骤 | 工具/产物 |
+|---|------|---------|
+| 1 | 建立清单 | 记录每个 skill 的名称、所有者、领域、平台版本、依赖、自动化等级、生命周期 |
+| 2 | 判断执行形态 | 零脚本 / 可选脚本 / 确定性脚本 三档；**不要默认使用 Python**（用户级编码规范） |
+| 3 | 建立证据 | 每个 API/组件/依赖必须有：来源、定位、摘要、采集日期、置信度 |
+| 4 | 评估兼容 | 平台、JDK、Spring、前端组件、调用方式 5 维矩阵 |
+| 5 | 执行测试 | 覆盖结构、引用、证据、契约、生成幂等、编译、代表性业务场景；失败即阻断 |
+| 6 | 评审发布 | 领域所有者 + 治理维护者双人审批，生成不可变发布包、摘要、回滚点 |
+| 7 | 监控退役 | 证据过期 / 平台升级 / 事故触发复核；先 `deprecated` 再移除 |
+
+## 目录契约（修正版）
+
+```text
+skills/meritdata-platform-<name>/
+├── SKILL.md                 # 唯一可发现入口（每个 skill 1 个，套件 24 个）
+├── agents/openai.yaml       # 唯一 UI 入口元数据
+└── references/              # 内部能力文档（取代原 modules/ 目录约定）
+    ├── *.md                 # 主题文档
+    ├── external-api/        # 外部接口（仅 integration skill）
+    └── api/                 # 内部 API 文档
+```
+
+> **历史说明**：原文档声明"内部模块用 `module.md` 放在 `modules/` 目录"，但实际 `meritdata-platform-cloud-dev` 使用的是 `references/modules/*.md` 平铺结构。**本治理承认现有结构**，不再要求改为 `module.md`。
+
+**禁止在 Skill 内新增 README、CHANGELOG 等旁路文档**。发布记录属于套件级注册表或制品库。详细事实只放一处，其他位置使用链接引用。
+
+## 发布门禁（修正版）
+
+- **每个 skill 必须有 1 个 `SKILL.md`**（共 24 个，不是 1 个）
+- **内部模块平铺到 `references/` 下**（`references/modules/*.md` 或 `references/external-api/*.md`）
+- 所有相对链接可解析，**不存在 TODO、占位符、乱码、重复事实源**
+- 每条稳定 API/组件事实存在可定位证据；二进制核验记录必须包含制品坐标、版本、签名摘要和 SHA-256，取证过程不作为 Skill 能力发布
+- **本地 Bean、Feign、网关 HTTP、前端组件** 4 类调用边界不得混淆
+- 声明的每个平台版本至少有一个契约测试；生成类 Skill 必须验证同输入同输出
+- 确定性脚本必须固定运行时、参数、退出码和输出格式，并提供非 Python 兼容入口或清晰先决条件
+- 重大变更通过新主版本发布；不得原地覆盖已发布制品
+
+## 命名规范（速查）
+
+| 类别 | 规则 | 示例 |
+|------|------|------|
+| Skill（公司级）| `meritdata-platform-<name>` | `meritdata-platform-bpm` |
+| Skill（团队私有）| `{team}-meritdata-platform-<x>` 或 `meritdata-platform-<x>` | `oil-meritdata-platform-well-log` |
+| references 文件 | kebab-case | `api-reference.md` |
+| Java 类 | PascalCase | `YarnLogController` |
+| 数据库表 | 大写 + 下划线 + 业务前缀 | `T_USER` / `T_CONTRACT` |
+| 禁用前缀 | ❌ `merit-cloud-*` / ❌ 裸 `platform-*` / ❌ `meritdata-*`（无 `-platform-` 中缀） | — |
+
+## 输出契约
+
+治理审计必须输出：**资产清单** / **脚本决策** / **证据缺口** / **兼容矩阵** / **测试结果** / **风险等级** / **发布或阻断结论** / **责任人**。
+
+缺少真实验证时明确写"未验证"，**不得推断为通过**。
+
+## 验证工具
+
+| 工具 | 用途 | 路径 |
+|------|------|------|
+| 元数据校验 | 6 大校验项 | `tools/validate-skills.ps1` |
+| 旧前缀检查 | 检测 3 类禁用前缀 | `tools/check-old-prefix.sh` |
+| 跨 skill 协作测试 | 12 个场景 | `tools/test-cross-skill.ps1` |
+| 路由表 | 22 个 skill 路由 | `playbook/references/public-entry-map.json` |
+| 二开体检 | 7 类 60+ 项 | `meritdata-platform-2nd-dev-check/scripts/run-all.sh` |
+
+---
+
+**修订说明（2026-09-10）**：
+- 删除 7 个不存在的下级文件引用（原 `references/automation-policy.md` 等）— 全部治理摘要内联到本文档
+- 修正"只能有 1 个 SKILL.md"为"每个 skill 必须有 1 个 SKILL.md"（共 24 个）
+- 承认现有 `references/modules/*.md` 平铺结构（原"module.md"约束不实施）
+- 新增"当前套件规模"表格（21 公司级 + 3 团队私有 + 13 rules = 37 元素）

package/skills/meritdata-platform-playbook/references/legacy-detect.md

@@ -0,0 +1,154 @@
+
+`meritdata-platform-playbook` 通过 5 步自动识别判断目标项目的模式（`new` / `existing` / `existing-legacy`）。
+
+## 5 步识别流程
+
+### Step 1：检查版本控制（VCS）
+
+```bash
+# Git
+[ -d ".git" ] && echo "git-managed" || echo "no-git"
+
+# SVN
+[ -d ".svn" ] && echo "svn-managed" || echo "no-svn"
+```
+
+**判断**：
+
+| 结果 | 处理 |
+|------|------|
+| 仅 `.git/` | git-managed（默认） |
+| 仅 `.svn/` | svn-managed |
+| 两者都有 | **立即报错**（不支持混合） |
+| 都没有 | 警告，建议先初始化 VCS |
+
+### Step 2：检查包管理工具
+
+```bash
+# Maven
+[ -f "pom.xml" ] && echo "maven"
+
+# Gradle
+[ -f "build.gradle" ] && echo "gradle"
+
+# npm/pnpm
+[ -f "package.json" ] && echo "npm"
+```
+
+**判断**：
+
+| 结果 | 处理 |
+|------|------|
+| Maven | Java 工程（默认） |
+| Gradle | Java 工程（备选） |
+| npm | 前端工程（可能独立） |
+
+### Step 3：检查平台指纹（关键）
+
+```bash
+# 6.13.x 系列
+grep -r "meritdata-cloud-starter" pom.xml 2>/dev/null
+grep -r "cloud-system-bpm-module-core" pom.xml 2>/dev/null
+
+# 6.x 系列
+grep -r "com.meritdata.cloud" src/main/java/ 2>/dev/null
+
+# 5.x 旧版
+grep -r "com.meritdata" src/main/java/ 2>/dev/null
+```
+
+**判断**：
+
+| 结果 | 处理 |
+|------|------|
+| `meritdata-cloud-starter` 找到 | 6.13.x，`project_mode: existing` |
+| `cloud-system-bpm-module-core` 找到 | 6.x，`project_mode: existing` |
+| `com.meritdata.cloud.*` 找到 | 6.x，`project_mode: existing` |
+| 仅 `com.meritdata.*` | 5.x 旧版，`project_mode: existing-legacy` |
+| 都没有 | `project_mode: new` 或缺指纹 |
+
+### Step 4：检查项目模式
+
+```bash
+# 标准 Maven Web
+[ -d "src/main/java" ] && [ -d "src/main/webapp" ] && echo "maven-web"
+
+# 平台前端
+[ -d "src/pages" ] && echo "meritdata-platform-frontend"
+
+# 平台前端集成
+[ -d "node_modules/cloud-module-base" ] && echo "meritdata-platform-frontend-integrated"
+```
+
+**判断**：
+
+| 结果 | 处理 |
+|------|------|
+| `maven-web` | 标准 Java 工程 |
+| `meritdata-platform-frontend` | Vue 多页面工程 |
+| 两者都有 | 全栈项目 |
+
+### Step 5：检查存量标识文件
+
+```bash
+# 显式版本声明
+[ -f ".meritdata-platform-version" ] && cat .meritdata-platform-version
+
+# README 头部
+head -10 README.md | grep -i "MeritData Cloud"
+```
+
+**判断**：
+
+| 结果 | 处理 |
+|------|------|
+| `.meritdata-platform-version` 存在 | 显式声明版本，优先采用 |
+| README 含 "MeritData Cloud" | 已认领 |
+| 都没有 | 未声明，由 playbook 推断 |
+
+## 综合判断逻辑
+
+```python
+def detect_project_mode(target):
+    vcs = step1_check_vcs(target)
+    build = step2_check_build(target)
+    fingerprint = step3_check_platform_fingerprint(target)
+    project_type = step4_check_project_type(target)
+    declared = step5_check_declared(target)
+
+    # 决策树
+    if fingerprint == "none":
+        return "new"
+    elif fingerprint == "5.x":
+        return "existing-legacy"
+    elif fingerprint in ["6.x", "6.13.x"]:
+        return "existing"
+    else:
+        return "new"
+```
+
+## 与 Git/SVN 项目的契约
+
+### Git 项目
+
+- ✅ 读取 `git status` / `git diff`
+- ❌ 不触碰 `.git/` 内部
+- ❌ 不自动 `git commit` / `git push`
+
+### SVN 项目
+
+- ✅ 读取 `svn status` / `svn diff`
+- ❌ 不自动 `svn commit`
+
+### 详细契约
+
+详见 `git-integration.md` 和 `svn-integration.md`。
+
+## 错误处理
+
+| 错误 | 处理 |
+|------|------|
+| 同时存在 `.git/` 和 `.svn/` | 立即报错，提示用户二选一 |
+| 5.x 旧版 | 强制先走 `2nd-dev-check` 体检，提示升级 |
+| 无 VCS | 警告，建议初始化后再继续 |
+| 无法识别 | 输出 GAP，要求用户提供更多信息 |