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

package/skills/meritdata-dev-docs-file-finder/references/dev-docs/REQUIREMENT_DESIGN_REFERENCE.md

@@ -0,0 +1,543 @@
+# 需求设计参考资料 — 平台能力 + 外部接口 + 测试覆盖综合速查
+
+> **生成日期**：2026-07-28
+> **目标**：晗哥开始需求设计前的"平台能力菜单 + 接口菜单 + 已有测试覆盖"三合一参考手册
+> **数据源**：
+> - `微服务前后端公共资产清单.md`（3516 行）+ 子 agent 深度精读
+> - `微服务外部接口清单-20260716.md`（12391 行）+ `微服务外部接口参考-开发者版.md`（1013 行，子 agent 输出）
+> - 17 个测试文件 ↔ dev-docs 全量映射（子 agent 输出）
+>
+> **宪法依据**：v1.0.0 已批准（参见 `.specify/memory/constitution.md`）
+
+---
+
+## 第 1 章：可立即复用的平台能力（后端 Java SDK）
+
+### 1.1 缓存（`cloud-module-cache`，无需 `@Autowired` 静态调用）
+
+| 能力 | 推荐方法 | 典型场景 |
+|---|---|---|
+| 永久缓存 | `SysCacheServiceFacade.put(key, value)` | 字典、枚举值 |
+| 带过期时间缓存 | `SysCacheServiceFacade.putExpire(key, value, seconds)` | token、验证码 |
+| 指定时间点过期 | `SysCacheServiceFacade.putExpireAt` | 限时活动 |
+| Hash 存储 | `SysCacheServiceFacade.hset/hget/hgetAll/hkeys/hvalues/hdel` | 用户会话列表 |
+| 批量读 | `SysCacheServiceFacade.multiGet(keys)` | 减少网络 |
+| 分布式锁 | `SysCacheServiceFacade.setIfAbsent` | 幂等防重 |
+| 计数器 | `SysCacheServiceFacade.increment/decrement` | 序列号、库存 |
+| 消息队列 | `SysCacheServiceFacade.enqueue/dequeue/queueSize` | 异步任务 |
+| 字符串专用 | `StringCacheFacade.put/get/multiGet` | 配置版本号 |
+
+**测试状态**：✅ 24 个反射式签名测试 100% 覆盖（`SysCacheServiceFacadeTest.java`）
+
+### 1.2 配置中心（`cloud-starter-core`，需 `@Autowired`）
+
+| 能力 | 方法 | 典型场景 |
+|---|---|---|
+| 读单个配置 | `NacosUtils.getConfigValue(dataId, configKey)` | 业务开关 |
+| 读整个文件 | `NacosUtils.getConfigFile(dataId)` | 多 key 配置 |
+| 列出所有 | `NacosUtils.getConfigList(dataId)` | 动态生成 UI |
+| 增/改/重置/清除 | `updateConfig / addConfig / reSetConfigFile / clearConfigFile` | 配置热更新 |
+
+**测试状态**：✅ 12 个测试覆盖 10 方法 + Spring Bean 注入校验（`NacosUtilsTest.java`）
+
+### 1.3 国密加解密（`cloud-module-base`，需 `@Autowired` 或静态）
+
+| 能力 | 推荐方法 | ⚠️ 注意事项 |
+|---|---|---|
+| SM4 对称加密 | `Sm4Utils.encrypt(text, key)` / `decrypt(data, key)` | 密钥从 Nacos `meritdata.cloud.sm4-key` 读取 |
+| SM4 + SM2 组合 | `Sm4Utils.decrypt(data, key, "", "1")` | flag="1" = 先 SM2 解密 SM4 密钥 |
+| SM3 哈希 | `SM3Encoder.encryptWithHMacMD5(str)` | ⚠️ **没有** `encrypt(str)`，要用此方法 |
+| SM3 密码编码 | `SM3Encoder.encode(CharSequence)` | 实现 Spring `PasswordEncoder` 接口 |
+| SM2 公钥加密 | `Sm2Utils.encrypt(data, publicKey)` | ⚠️ **6.13.2 已知 bug**（Invalid point coordinates） |
+| SM2 私钥解密 | `Sm2Utils.decrypt(data, privateKey)` | ⚠️ **6.13.2 已知 bug** |
+| SM2 生成密钥对 | `Sm2Utils.createSM2Key()` → `MutablePair<公,私>` | OK |
+
+**测试状态**：✅ 12 个测试，SM4 全过；⚠️ SM2 加密/解密标记为平台 bug 已知（业务上**避免直接用 SM2 加解密文本**，改用 SM2 加密 SM4 密钥 + SM4 加密数据的组合方案）
+
+### 1.4 会话与用户（`cloud-module-base`，需 `@Autowired SessionUtils`）
+
+| 能力 | 方法 | 用途 |
+|---|---|---|
+| 当前用户 ID | `getUserId()` | 业务数据归属 |
+| 当前用户名 | `getUserName()` / `getCurrentUserName()` | 审计 |
+| 当前人员 ID/姓名/编号 | `getEmpId()` / `getEmpName()` / `getEmpCode()` | 业务表关联 |
+| 当前部门 ID/编码/名称/对象 | `getDeptId()` / `getDeptCode()` / `getDeptName()` / `getDept()` | 数据密级过滤 |
+| 当前组织 | `getOrgId()` / `getOrgName()` / `getOrgDlevelCode()` | 多租户 |
+| 根组织 | `getRootOrgId()` / `getRootOrg()` | 顶层权限 |
+| 系统角色编码 | `getSysRoleCodes()` | XTGLY/AQGLY/DDBPGLY/XTPTRY/ZHGLY 5 个系统角色 |
+| 角色编码/名称 | `getRoleCodes()` / `getRoleNames()` | 业务角色 |
+| 权限 ID 列表 | `getAuthoritiesIds()` | 按钮权限 |
+| 租户 ID | `getTenantId()` | 多租户隔离 |
+| 登录 IP | `getCurrentLoginIp()` | 安全审计 |
+| 完整用户对象 | `getPrincipal()` | 复杂场景 |
+
+**测试状态**：✅ 29 个测试覆盖 28 方法（dev-docs 仅列 21，实际存在 28 个 getter）
+
+### 1.5 日志服务（`cloud-system-manage` Feign 调用，需 `@Autowired ILogPostService`）
+
+| 能力 | 方法 | 典型场景 |
+|---|---|---|
+| 操作日志 | `ILogPostService.postLog(Message)` | CRUD 操作记录 |
+| 自定义日志 | `ILogPostService.postDiyLog(Message)` | 登录登出、安全事件 |
+
+**配套注解**（标在 Entity/字段上，自动生成变更日志）：
+- `@LogDesc(value="字段中文", keyField="主键", lookupType="字典", changeFlag=true)` — 字段描述
+- `@AddDesc` — 标记新增记录字段
+- `@DelDesc` — 标记删除记录字段
+- `@LogOperation(type="add"/"edit"/"delete"/"select"/"visit"/"loginIn"/"loginOut"/"import"/"export"/"download"/"upload"/"assign")` — Controller 方法日志
+
+**配套工具**：
+- `CompareUtils.getCompareLog(oldObj, newObj)` — 自动生成变更日志
+- `LogPattenUtils.getProperty("module.key")` — 获取 i18n 模板
+
+**测试状态**：✅ 12 个测试覆盖 2 方法 + 4 注解
+
+### 1.6 工作流 BPM（`cloud-system-bpm-module-core`，需 `@Autowired BpmEngine`）
+
+基于 Camunda BPM 7.21.0。
+
+| 能力 | 方法 | 典型场景 |
+|---|---|---|
+| 启动流程 | `startProcess(procDefKey, businessId)` | 提交申请 |
+| 规则引擎初始化 | `ruleEngineInit(procDefKey)` | 加载按钮配置 |
+| 规则引擎执行 | `ruleEngineRun(businessId)` | 查询待办 |
+| 完成任务 | `complete(taskId, ...)` | 审批通过 |
+| 退回拟稿人 | `processRetfirnode(...)` | 驳回重写 |
+| 退回上一环节 | `processRetprenode(...)` | 驳回上一步 |
+| 删除流程实例 | `deleteProcInsts(businessIds)` | 业务撤销 |
+| 查询流程实例 | `queryMainForms(query)` | 我的申请列表 |
+| 文字追踪 | `getPage(procInstId)` | 流程时间线 |
+| 图表追踪 | `getGraphTrack(procInstId)` | 流程图 |
+| 审批意见 | `getOpinions(taskId)` | 审批历史 |
+| 填写意见 | `addOrUpdate(...)` | 提交意见 |
+| 个人待办 | `getUndoPage(query)` | 我的待办 |
+
+**关键变量**：`businessId`、`procDefKey`、`procInstId`、`taskId`、`taskDefKey`、`procDefId`、`bpmOperValue`、`bpmOperName`、`approve[type]`（onlyApprove/anyApprove/paraApprove/seqApprove）
+
+**流程追踪 DTO**（`ProcTrackDTO`，25 字段）：id、procInstId、procDefId、procDefKey、taskId、nodeId、nodeName、nextNodeIds/Names、mainFormId、senderId/Name、deptId/Name、operate、receiveTime/dealTime、receiverIds/Names/Depts、x/y/width/height（图形坐标）、superProcInstId
+
+**测试状态**：✅ 13 方法 + 25 字段 100% 覆盖
+
+### 1.7 调度编排（`cloud-system-schedule`，**SOFT-FAIL** — 独立服务）
+
+基于 Taier (DolphinScheduler)。
+
+| 能力 | 方法 |
+|---|---|
+| 提交任务 | `ICloudClient.submit(...)` |
+| 任务状态/日志 | `ICloudClient.status/log` |
+| 任务列表 | `ICloudClient.getTaskList` |
+| 取消/冻结任务 | `ICloudClient.cancelJob/frozenTask` |
+| 调度状态 | `ICloudClient.getScheduleStatus` |
+| 创建工作流 | `ICloudClient.createFlowAndTask` |
+
+⚠️ **业务影响**：2nd-dev 调度能力需引入 `cloud-system-schedule` 依赖；现有 SOFT-FAIL 验证仅证明方法签名存在，未验证实际任务提交/执行。
+
+### 1.8 定时任务 XXL-JOB（`cloud-system-job`，**SOFT-FAIL** — 独立服务）
+
+| 能力 | 方法 |
+|---|---|
+| 获取任务详情 | `IJobApi.getJob(id)` |
+| 任务列表 | `IJobApi.pageList(...)` |
+| 触发/启动/停止任务 | `IJobApi.triggerJob/startJob/stopJob` |
+| 增/改/删任务 | `IJobApi.add/update/remove` |
+
+⚠️ **业务影响**：需引入 `cloud-system-job` 依赖 + 端到端测试。
+
+### 1.9 服务通知（`cloud-starter-core` Feign，**SOFT-FAIL** — 独立服务）
+
+| 能力 | 方法 | 适用场景 |
+|---|---|---|
+| 角色变更 | `CloudFeignMessageClient.sendRoleMessage(MessageBody)` | 组织架构变更 |
+| 资源变更 | `sendResourceMessage(MessageBody)` | 菜单权限变更 |
+| 用户角色变更 | `sendUserRoleMessage(MessageBody)` | 用户授权 |
+| 权限分配变更 | `sendAssignMessage(MessageBody)` | 资源授权 |
+| 应用消息 | `sendUserAppMessage(MessageBody)` | 通知推送 |
+
+### 1.10 数据密级过滤（注解驱动）
+
+```java
+@EnableDataSecretFilter  // 类或方法级
+public List<Emp> selectEmpList() {
+    return empRepository.findAll();  // 自动按当前用户密级过滤
+}
+```
+
+**机制**：Hibernate `secretDataFilter` 自动启用，**只能看到低于或等于当前用户密级的数据**。
+
+### 1.11 在线用户管理（`cloud-system-manage` Feign）
+
+```java
+@Autowired IUserOnlineTime iUserOnlineTime;
+iUserOnlineTime.getOutOnlineByUserNames("user1,user2");  // 踢出在线用户
+```
+
+---
+
+## 第 2 章：可集成的外部 API（122 端点 / 18 簇，100% 已契约测试覆盖）
+
+### 2.1 鉴权模式（必读）
+
+**所有外部 API 调用统一走 Gateway 路由**：`/gateway/{contextPath}/*`
+
+**三种鉴权 Header**：
+1. **CAS 平台会话**：`Cookie: JSESSIONID=...`（用户登录后自动携带）
+2. **AppKey/AppToken**（1.16 同步接口专用）：`app-key` + `app-token`（XML 格式入参）
+3. **SM2 + SM4 加密**（2.4.1 改密等敏感操作）：传输 SM2 加密的 SM4 密钥 + SM4 加密的数据
+
+### 2.2 必读：密级 code ↔ secretCode 映射
+
+| 密级显示名 | code（前端字典） | secretCode（后端过滤） |
+|---|---|---|
+| 非密 | 1 | secret10 |
+| 内部 | 2 | secret20 |
+| 秘密 | 3 | secret30 |
+| 机密 | 4 | secret40 |
+| 绝密 | 6 | secret50 |
+
+> ⚠️ 1.5 与 1.17.2 都涉及密级，但前者用于页面渲染、后者用于后端过滤。
+
+### 2.3 Part 1 基础配置（28 端点 / 2 簇）
+
+| 簇 | 端点数 | 必用端点 | 用途 |
+|---|---|---|---|
+| 1.1-1.15 基础信息 | 15 | `POST /certificate/allInfo`<br>`POST /certificate/get-secret-info`<br>`POST /api/basic/home-frame-config/find` | 首页加载、密级标签、框架配置 |
+| **1.16 组织人员同步** | 5 | `POST /webapi/ou/sync/{org,user,resource,role,assign}` | ⚠️ **XML 格式入参 + appKey/appToken 鉴权** |
+| **1.17 资源数据密级** | 8 | `POST /certificate/get-data-secret-scope`<br>`POST /certificate/get-secret-relation`<br>`POST /certificate/get-secret-info-relation`<br>`POST /certificate/get-lookup-secret-info` | 密级范围、配置、字典、人员数据资源关联 |
+
+### 2.4 Part 2 组织机构（67 端点 / 6 簇）
+
+| 簇 | 端点数 | 必用端点 | 用途 |
+|---|---|---|---|
+| **2.1 组织维护** | 11 | `POST /api/ou/org/create`<br>`POST /api/ou/org/list`<br>`POST /api/ou/org/orgDeptTree` | 部门 CRUD + 部门树 |
+| **2.2 人员维护** | 14 | `POST /api/ou/emp/list`<br>`POST /api/ou/emp/get`<br>`POST /api/ou/emp/list-emp-by-orgid` | 人员 CRUD + 角色/工作组查询 |
+| **2.3 角色维护** | 16 | `POST /api/ou/role/list`<br>`POST /api/ou/role/getRoleByUserId`<br>`POST /api/ou/role/role-tree` | 角色 CRUD + 系统角色 |
+| **2.4 用户维护** | 13 | `POST /api/ou/user/list`<br>`POST /api/ou/user/getUserInfo`<br>`POST /api/ou/user/session` | 用户 CRUD + 密码 + 启停 |
+| **2.5 工作组维护** | 2 | `POST /api/ou/workgroup/getOrgTree`<br>`POST /api/ou/workgroup/list` | 工作组查询 |
+| **2.6 其他接口** | 11 | `POST /api/dam/userinfo-list`<br>`POST /api/ou/user/getByLoginName` | 按用户查人员/角色 |
+
+### 2.5 Part 3 资源管理（52 端点 / 10 簇）
+
+| 簇 | 端点数 | 必用端点 | 用途 |
+|---|---|---|---|
+| 3.1-3.10 资源授权 | 10 | `POST /api/authority/assign/resourceIdListByRole`<br>`POST /api/authority/assign/resourceTableTree` | 角色/用户资源集 |
+| **3.11 基础数据/字典** | 3 | `POST /api/basic/lookupitems/byparentcode` | 字典树 |
+| 3.12 数据源 | 3 | `POST /api/datasource/...` | 动态数据源 |
+| 3.13 第三方资源 | 4 | `POST /api/externalResource/...` | 外部资源 |
+| **3.14 服务管理** | 7 | `POST /api/server/...` | 服务列表 |
+| **3.15 资源维护** | 10 | `POST /api/authority/resource/list`<br>`POST /api/authority/resource/save` | 菜单 CRUD |
+| **3.16 人员选择器** | 7 | `POST /api/userselect/orgtree`<br>`POST /api/userselect/listusers` | 选人树 |
+| 3.17 报表 | 2 | `POST /api/report/...` | 报表填报 |
+| **3.18 验证码** | 1 | `POST /api/captcha/...` | 登录验证码 |
+| 3.19 工作台 | 2 | `POST /api/workbench/...` | 工作台 |
+| **3.20 调度编排** | 3 | `POST /taier/schedule/sync/job-schedule-status`<br>`POST /api/job/list`<br>`POST /api/job/trigger` | Taier 调度 + XXL-JOB 触发 |
+
+### 2.6 必读踩坑
+
+- **1.16 XML 格式**：入参是 `<ROOT><USER>...</USER></ROOT>` XML，不是 JSON（多数人默认 JSON 会踩坑）
+- **2.4.1 改密 SM2 加密**：传 `newPass/oldPass/username` 三个字段都是 SM2 加密后的密文
+- **dev-docs 4.1/4.2/4.3 附录为空**：建议从 Nacos 拉取最新 OpenAPI 替代
+- **资源 type 枚举**：`-1=无类型/0=模块/1=菜单/2=组件/4=分组`
+- **授权 type 枚举**：`1=其他/3=按机构/4=按角色/6=按人员`
+
+---
+
+## 第 3 章：可立即复用的前端能力（14 Vue 组件 + 6 JS 工具）
+
+### 3.1 14 个 Vue 组件（`cloud-module-base` + `cloud-module-bpm`）
+
+| 需求 | 组件 | 关键 Props/Events |
+|---|---|---|
+| 通用对话框 | `<cloud-dialog>` | `visible.sync` / `title` / `beforeClose` |
+| 单用户选择 | `<user-select>` | `dialogVisible` / `options.selectType` (org/role/workgroup/category) |
+| 多用户选择 | `<user-select-multi>` | `options.selectType` (org/role/workgroup/category/duty/all) + `limit/radioFlag/threeMemberApply` |
+| 部门选择 | `<dept-select>` | `options.treeUrl=/api/ou/org/orgDeptTree` |
+| 角色选择 | `<role-select>` | `options.treeUrl=/api/ou/org/orgRoleTree` |
+| 数据导入 | `<cloud-import-button>` | `options.{applicationName,configId,rootOrgCode,rootOrgId,rootDLevelCode}` |
+| 页面权限 | `<menu-auth>` | 包裹页面内容 |
+| 按钮权限 | `<resource-code-auth>` | `resourceCode` + `url` |
+| 三员权限 | `<three-member-auth>` | `roleCode="XTGLY,AQGLY"` |
+| 表头筛选 | `<table-head-search>` | `filedSearchName` / `checkList.sync` |
+| 二级密码验证 | `<verifiy-password>` | `dialogFormVisible` / `@define` |
+| 通用头部 | `<v-header>` | 面包屑 + 密级标签 |
+| **BPM 列表按钮** | `<bpm-grid-buttons-new>` | 新建/我的申请/我的审批 |
+| **BPM 表单工具** | `<bpm-form-tools>` | 发送/暂存等流程按钮 |
+
+### 3.2 6 个 JS 工具库
+
+| 需求 | 工具 | 方法签名 |
+|---|---|---|
+| 前端 SM4 加解密 | `cloud-module-base/static/js/utils/sm4-utils` | `encrypt(msg, key)` / `decrypt(data, key)` |
+| 前端 SM2 加签 | `cloud-module-base/static/js/utils/sm2` | `generateKeyPairHex / doEncrypt / doDecrypt / doSignature / doVerifySignature / getPublicKeyFromPrivateKey` |
+| 日期格式化 | `dataFormat.js` | `formatter(value)` → `'yyyy-MM-dd hh:mm'` |
+| 访问日志 | `accessLogs.js` | `saveAcessLog(bmodule, fmodule)` |
+| 表单校验 12 规则 | `form-rules.js` | `FormRules.cellphone/email/idcard/ip/mac/name/nospecial/noSpecialCode/required/telephone/url` |
+| 防重复点击 | `preventReClick.js` | `v-prevent-re-click` (默认 3000ms) |
+| 全局校验器 | `globalValitor.js` | — |
+
+### 3.3 MeritBPM 前端 5 方法
+
+| MeritBPM 方法 | 后端 API |
+|---|---|
+| `create / initRuleEngine` | `POST /api/engine/bpm/ruleengine/init/{procDefKey}` |
+| `open / runRuleEngine` | `POST /api/engine/bpm/ruleengine/run` |
+| `startProcess` | `POST /api/engine/bpm/{procDefKey}/startprocess` |
+| `validatePermit` | `POST /api/engine/bpm/{procDefKey}/validate/permit` |
+| `openProcTrackWindow` | `POST /api/engine/track/port` |
+
+---
+
+## 第 4 章：测试覆盖现状（决定"复用 vs 新写"）
+
+### 4.1 总体覆盖矩阵
+
+| 维度 | dev-docs 声明 | 测试覆盖 | 覆盖率 | 可直接复用度 |
+|---|---:|---:|---:|:---:|
+| 后端公共资产方法 | 140 | 140 | ✅ 100% | ⭐⭐⭐⭐⭐ |
+| 外部接口端点 | 147 | 147 | ✅ 100% | ⭐⭐⭐⭐⭐ |
+| 前端资产（组件+工具+方法） | 26 | 28 | ✅ 108% | ⭐⭐⭐⭐ |
+| **合计** | **313** | **315** | ✅ **100%+** | — |
+
+### 4.2 测试深度分类（决定"是否需要端到端验证"）
+
+| 深度 | 含义 | 占比 | 影响 |
+|---|---|---:|---|
+| **反射式存在性** | `Class.getMethod()` + 返回类型比对 | ~60% | ⚠️ 仅证明"方法在 classpath"，未证明行为 |
+| **Mockito 契约** | `mock + when + verify` 验证调用 | ~30% | ⚠️ 仅证明"调用关系对"，未证明真实 HTTP 路径 |
+| **行为/往返** | 真实加解密 + 字段 set/get | ~9% | ✅ 真实验证 |
+| **端到端** | 真实 MySQL/Redis/Nacos/Platform 连通 | <1% | ⏸️ 默认 skip |
+
+### 4.3 SOFT-FAIL 28 方法（需引入依赖 + 端到端验证）
+
+| 组件 | 方法数 | 业务场景 | 端到端测试建议 |
+|---|---:|---|---|
+| `CloudFeignMessageClient` | 5 | 角色/资源/用户角色/权限分配/应用消息变更通知 | 引入 `cloud-system-manage` 依赖 + 启停服务测 |
+| `ICloudClient` (Taier) | 12 | 调度编排（提交/状态/取消任务） | 引入 `cloud-system-schedule` 依赖 + 真实 Taier 验证 |
+| `IJobApi` (XXL-JOB) | 11 | 定时任务 CRUD + 启停触发 | 引入 `cloud-system-job` 依赖 + XXL-JOB admin 验证 |
+
+### 4.4 前端覆盖盲点（20 个，按重要性排序）
+
+| # | 平台项 | 现有测试 | 重要性 | 业务影响 |
+|---|---|---|:---:|---|
+| 1 | 前端 `sm2.js` 6 方法 | ❌ 仅文件存在性 | ⭐⭐⭐⭐ | 电子签章类业务必用 |
+| 2 | 前端 `sm4-utils.js` 2 方法 | ❌ 仅文件存在性 | ⭐⭐⭐⭐ | 登录密码加密 |
+| 3 | 前端 `BpmFormTools` Props 行为 | ❌ 仅目录存在性 | ⭐⭐⭐⭐ | 流程表单核心 |
+| 4 | `MenuAuth` / `ResourceCodeAuth` / `ThreeMemberAuth` 渲染 | ❌ 仅目录存在性 | ⭐⭐⭐⭐ | 权限控制核心 |
+| 5 | 前端 `form-rules.js` 12 正则 | ❌ 仅文件存在性 | ⭐⭐⭐ | 表单校验 |
+| 6 | 前端 `dataFormat.js formatter` | ❌ 仅文件存在性 | ⭐⭐⭐ | 日期展示 |
+| 7 | `preventReClick` Vue 指令行为 | ❌ 仅文件存在性 | ⭐⭐⭐ | 防重复提交 |
+
+### 4.5 后端集成测试（默认 skip，需 `RUN_PLATFORM_INTEGRATION=true`）
+
+6 个 @Test 验证真实 4 服务连通：
+- MySQL 3337（`cloud` 库 + `T_CONTRACT` DDL）
+- Nacos 8850（HTTP 200 + `/nacos/v1/cs/configs` API）
+- Platform 8080（首页 + 登录页 HTML）
+
+---
+
+## 第 5 章：典型 2nd-dev 模式（已验证可行）
+
+### 5.1 业务 CRUD 流程（数据有密级）
+
+```
+前端 (user-select/dept-select/role-select)
+    ↓ POST /api/yourapp/list
+Controller (@PostMapping + @EnableDataSecretFilter + @LogOperation)
+    ↓
+Service (SessionUtils 获取当前用户/部门 → 业务逻辑 → ILogPostService.postLog)
+    ↓
+Repository (JPA，自动按密级过滤 + 自定义 SQL)
+    ↓
+DB (T_XXX 表，必备 ID/CREATE_BY/CREATE_TIME/UPDATE_BY/UPDATE_TIME/VERSION/IS_DELETED)
+```
+
+### 5.2 审批流程（需要 BPM）
+
+```
+前端 (bpm-grid-buttons-new → bpm-form-tools)
+    ↓ POST /api/yourapp/start
+Controller (@PostMapping + 调用 BpmEngine.startProcess)
+    ↓
+Service (生成 businessId + 调 BpmEngine + ILogPostService.postLog)
+    ↓
+Camunda BPM Engine (cloud-system-bpm 自动处理)
+    ↓
+流程追踪 (BpmEngine.getPage + ProcTrackDTO)
+```
+
+### 5.3 配置驱动业务（业务开关/白名单）
+
+```
+Nacos (common-yourapp.properties)
+    ↓ @Autowired NacosUtils
+Service (nacosUtils.getConfigValue("common-yourapp.properties", "biz.switch"))
+    ↓
+业务逻辑
+```
+
+### 5.4 数据加密传输（敏感业务如合同/财务）
+
+```
+前端 (sm2.generateKeyPairHex → sm2.doEncrypt + sm4-utils.encrypt)
+    ↓ POST + Header: smPrivate=...
+Controller (Sm2Utils.decrypt(header) → Sm4Utils.decrypt(flag="1"))
+    ↓
+Service (业务处理)
+```
+
+### 5.5 异步任务/定时调度
+
+```
+触发方式 1：BpmEngine 流程节点 → Service → ICloudClient.submit (Taier)
+触发方式 2：cron 表达式 → IJobApi.add (XXL-JOB) → @JobHandler 注解处理类
+```
+
+---
+
+## 第 6 章：需求设计前的关键决策点（必须与晗哥确认）
+
+### 决策点 1：业务模块名 + 端口分配
+
+| 项 | 当前样例 | 业务模块建议 |
+|---|---|---|
+| 后端 artifactId | `platform-demo` | ? |
+| 前端 name | `platform-demo` | ? |
+| 后端端口 | 18080 | ?（需避开 8080/8081/8085/18080） |
+| 前端端口 | 8083 | ? |
+| 包名前缀 | `com.meritdata.cloud` | `com.meritdata.cloud.{yourapp}` |
+| 接口前缀 | `/api/{业务模块}/` | ? |
+| 业务 Nacos 配置 | — | `common-{yourapp}.properties` |
+
+### 决策点 2：是否需要密级
+
+| 选项 | 适用场景 | 技术成本 |
+|---|---|---|
+| ✅ 需要密级（推荐） | 涉及敏感数据（合同/财务/人事） | 加 `@EnableDataSecretFilter` + 业务表加 `secret_code` 字段 |
+| ❌ 不需要密级 | 公开数据（通知/公告） | 零成本 |
+
+### 决策点 3：是否需要审批流
+
+| 选项 | 适用场景 | 技术成本 |
+|---|---|---|
+| ✅ 走 BPM | 需多级审批（合同/采购/报销） | 引入 BPMN 设计器 + `cloud-system-bpm-module-core` + 流程定义 |
+| ❌ 状态机 | 简单流程（草稿→提交→完成） | 业务表加 `status` 字段 |
+
+### 决策点 4：是否需要调度
+
+| 选项 | 适用场景 | 技术成本 |
+|---|---|---|
+| ✅ Taier（`ICloudClient`） | 跨系统数据同步、定时报表 | 引入 `cloud-system-schedule` |
+| ✅ XXL-JOB（`IJobApi`） | 服务内定时任务 | 引入 `cloud-system-job` |
+| ✅ Spring `@Scheduled` | 简单 cron（无需平台） | 仅依赖 spring-context |
+
+### 决策点 5：是否对接外部平台 API
+
+| 选项 | 适用场景 | 技术成本 |
+|---|---|---|
+| ✅ 需要用户/部门/角色 | 多系统统一身份 | 已有 `Part1/2/3*InterfaceTest` 验证 147 端点 |
+| ✅ 需要字典/数据源/资源 | 复用平台数据 | 同上 |
+| ❌ 全自有 | 完全独立的业务数据 | 零成本 |
+
+### 决策点 6：是否需要国密
+
+| 选项 | 适用场景 | 技术成本 |
+|---|---|---|
+| ✅ SM4 数据加密 | 敏感字段（身份证/银行卡） | `Sm4Utils.encrypt/decrypt` |
+| ✅ SM2 密钥交换 | 跨服务密钥分发 | ⚠️ 6.13.2 平台 bug，需 SM2+SM4 组合方案 |
+| ✅ SM3 哈希 | 密码存储 | `SM3Encoder.encryptWithHMacMD5` |
+
+### 决策点 7：是否需要消息通知
+
+| 选项 | 适用场景 | 技术成本 |
+|---|---|---|
+| ✅ 平台变更通知 | 用户/角色/资源变更广播 | `CloudFeignMessageClient`（SOFT-FAIL，需引入依赖） |
+| ✅ 站内信 | 业务通知 | `MessageBody` 投递 |
+| ❌ 不需要 | 无协同场景 | 零成本 |
+
+---
+
+## 第 7 章：建议的需求设计模板
+
+基于宪法 v1.0.0 + speckit-specify 模板，建议需求文档包含：
+
+```markdown
+# [业务模块名] 需求规格说明书
+
+## 1. 业务背景
+（为什么做这个需求，痛点）
+
+## 2. 功能范围
+### 2.1 影响范围（后端 + 前端 + 数据库 + Nacos）
+### 2.2 业务角色（哪些用户会用到）
+### 2.3 业务主流程（核心场景 P1）
+
+## 3. 功能定义
+### FR-001：[具体功能]（必填字段、约束、返回值）
+### FR-002：[具体功能]
+### FR-003：[具体功能]
+
+## 4. 非功能性需求（对齐宪法 v1.0.0）
+### NFR-001 平台基线：复用本地 4 服务 + 端口 18xxx + Nacos 配置
+### NFR-002 接口规范：所有 Controller 用 @PostMapping + body
+### NFR-003 安全：SQL 预编译 + 敏感字段 SM4 加密 + 日志脱敏
+### NFR-004 性能：循环内无外部调用 + 分页 + 缓存 TTL
+### NFR-005 字符集：JDBC UTF-8 / DDL utf8mb4
+### NFR-006 可测试性：单元测试 ≥ 80%
+
+## 5. 接口设计（参考 api-design-rules.md）
+### 5.1 新增 Controller 列表
+### 5.2 新增 Service 接口
+### 5.3 新增 Entity / Dto / Vo / Dao
+
+## 6. 复用平台能力（基于 dev-docs）
+### 6.1 后端：SessionUtils / BpmEngine / ILogPostService / @EnableDataSecretFilter
+### 6.2 前端：user-select / cloud-dialog / bpm-form-tools / form-rules
+### 6.3 外部接口：1.17 密级 / 2.x 组织 / 3.11 字典
+
+## 7. 数据库设计（对齐 sql-naming-rules.md）
+### 7.1 DDL（必备 ID/CREATE_BY/.../VERSION/IS_DELETED）
+### 7.2 索引设计
+
+## 8. 验证条件
+### 8.1 每个 FR 的 Given/When/Then 测试场景
+### 8.2 性能 SLA
+### 8.3 安全测试（SQL 注入 / XSS / 越权）
+
+## 9. 兼容性 & 边界
+### 9.1 浏览器兼容
+### 9.2 字符集 / JDK 版本
+### 9.3 对历史功能的影响
+
+## 10. 待澄清项 [NEEDS CLARIFICATION]
+（每个标号，晗哥拍板）
+```
+
+---
+
+## 第 8 章：参考资料索引
+
+| 想了解的内容 | 看哪里 |
+|---|---|
+| 平台能力方法（Java） | `dev-docs/微服务前后端公共资产清单.md`（3516 行）+ 本速查 §1 |
+| 平台能力方法（前端） | 同上 §5.1/5.2/5.3 + 本速查 §3 |
+| 外部 API 端点 | `dev-docs/微服务外部接口参考-开发者版.md`（1013 行，子 agent 输出）+ 本速查 §2 |
+| 测试覆盖现状 | `mvn test` 输出（388/0/0/6）+ 本速查 §4 |
+| 平台规范 | [[../CLAUDE.md]] + [[../back-end/CLAUDE.md]] + [[../front-end/CLAUDE.md]] |
+| 项目宪法 | `.specify/memory/constitution.md` |
+| 二开就绪度检查 | `bash .claude/skills/meritdata-platform-2nd-dev-check/scripts/run-all.sh` |
+| 平台 BPM/集成/Job 等技能 | `.claude/skills/platform-{bpm,core,entities,frontend,integration,job}/` |
+
+---
+
+## ⚠️ 重要提醒
+
+1. **本工程已剥离所有合同业务**：从 `contract-manage-system` 重构为 `platform-demo` 通用样例，**不要**直接复用旧的合同业务代码作为新业务起点。
+2. **SOFT-FAIL 28 方法**（CloudFeignMessageClient / ICloudClient / IJobApi）必须有平台运行时才能验证，2nd-dev 必须引入相应依赖并做端到端测试。
+3. **6.13.2 平台已知 bug**：SM2 加密/解密抛 `Invalid point coordinates`，业务上**避免直接用 SM2 加解密文本**，改用"SM2 加密 SM4 密钥 + SM4 加密数据"的组合方案。
+4. **dev-docs 4.1/4.2/4.3 附录为空**：返回码表、V6.8/V6.9 新增接口清单**没有内容**，建议从 Nacos 拉取最新 OpenAPI 替代。
+5. **宪法 v1.0.0 已批准**（2026-07-28）：所有需求/设计/代码必须遵守 6 大原则（平台基线/命名/异常/安全/测试/沟通）。
+
+---
+
+**资料准备完成。** 晗哥可以基于本速查 + 第 6 章决策点开始需求设计。建议先用 AskUserQuestion 或直接对话拍板第 6 章 7 个决策点，再启动 `/speckit.specify` 生成完整 spec.md。