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

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

@@ -1,543 +0,0 @@
-# 需求设计参考资料 — 平台能力 + 外部接口 + 测试覆盖综合速查
-
-> **生成日期**：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。