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

package/skills/meritdata-platform-cloud-dev/agents/openai.yaml

@@ -0,0 +1,40 @@
+display_name: "MeritData Cloud 综合开发"
+short_description: "MeritData Cloud 6.x 综合开发入口，22 个能力模块"
+default_prompt: |
+  meritdata-platform-cloud-dev 是综合开发入口（领域入口而非编排入口）。
+
+  适用场景：
+  - 平台能力查询（"平台有哪些缓存接口？"）
+  - 方案设计（"如何设计一个采购模块？"）
+  - 新建工程（project_mode: new）
+  - 存量增量（project_mode: existing）
+
+  使用方式：
+  ```
+  meritdata-platform-cloud-dev <需求>
+  ```
+
+  22 个内部模块（references/modules/）：
+  - gen：代码生成（new/existing）
+  - platform：平台能力图谱
+  - domain-model：多表聚合建模
+  - data-boundary：数据边界
+  - feign-api：Feign 跨服务契约
+  - meritdata-platform-entities：同 JVM 平台实体
+  - ui：前端语义组件
+  - code-spec：代码规范
+  - cache / config / datasource / utils / logging
+  - webapi / masterdata-sync / msg-job
+  - services / impexp / file
+  - http-client
+
+  项目模式：
+  - new：全新工程 → 生成 scaffold
+  - existing：已有 pom.xml + src/ → 不生成 scaffold，最小修改
+  - existing-legacy：5.x 旧版 → 强制先 2nd-dev-check 体检
+
+  强制约束：
+  - 不暴露模块选择给用户（按 references/modules/ 自动路由）
+  - 不要求用户提供平台源码/解压 Jar
+  - 二开库不得连接或映射 cloud 平台表
+  - 不输出 AI 开发 Journal，不执行 Git/SVN 提交

package/skills/meritdata-platform-cloud-dev/references/modules/bpm.md

@@ -0,0 +1,39 @@
+---
+name: meritdata-platform-mod-bpm
+description: meritdata cloud 工作流 API 参考（非代码生成器，搭工程用 meritdata-platform-mod-gen）：BpmEngine 启动、完成、退回拟稿人、审批意见、流程查询和追踪；节点监听、动态审批人、待办同步门户与流程追踪嵌入。需要生成可编译审批模块时使用 meritdata-platform-mod-gen。
+---
+
+# 工作流能力路由
+
+## 核心边界
+
+- `BpmEngine` 是 6.12.1/6.13.2 已核验的统一入口，包为 `com.meritdata.cloud.bpm.core.BpmEngine`，artifact 为 `cloud-system-bpm-module-core`，不是 starter/module-base。
+- 6.13.2 比 6.12.1 增加批量业务 ID/流程定义 key 查询；生成前按 `cloud_version` 选择签名。
+- Controller 使用具名 DTO，在应用层转换为 Map；禁止直接暴露任意 Map 入参。
+- 二开业务只保存业务主键、流程实例/任务稳定标识和必要状态，不直查 Camunda/平台流程表。
+- 生成前后端审批模块、依赖和测试时转 `meritdata-platform-mod-gen`；本 Skill 只提供工作流契约与场景决策。
+
+## 按场景加载参考
+
+- 启动、完成、审批意见、流程查询、退回、删除、追踪和状态常量：读取 core-api.md（参考：，待补充）。
+- 节点监听、动态审批人、门户待办同步和业务页面嵌入追踪：读取 extension-scenarios.md（参考：，待补充）。
+
+## 强制设计顺序
+
+1. 明确 `procDefKey`、业务主键、流程状态字段和业务事务边界。
+2. 确认目标版本及依赖证据，再选择 BpmEngine 签名。
+3. 定义提交、审批、退回、撤回/删除、意见和追踪的权限与幂等行为。
+4. 本地业务保存成功后再启动/流转；远程流程失败时记录可重试状态，避免长事务包住远程调用。
+5. 动态审批人与监听器返回稳定账号/编码；人员信息通过已核验平台服务获取，禁止跨库查询。
+6. 输出接口、Nacos/部署配置、流程设计器配置、负向用例和联调 GAP。
+
+## 高影响流程操作
+
+删除流程实例、退回拟稿人、跨服务待办同步和批量状态变更前，必须明确业务授权、影响范围、幂等键、审计事件和失败补偿。不得以 URL 白名单或匿名路径绕过用户会话与数据权限。
+
+## 验收重点
+
+- 重复提交不会启动两条流程或重复完成任务。
+- 退回目标、意见类型、按钮值和 variables key 有业务/版本证据。
+- 流程平台不可用、超时或返回未知结果时，不把业务状态误标为成功。
+- 流程追踪和待办同步只暴露授权范围内的数据，不记录敏感 variables。

package/skills/meritdata-platform-cloud-dev/references/modules/cache.md

@@ -0,0 +1,28 @@
+---
+name: meritdata-platform-mod-cache
+description: 使用 Meritdata Cloud 平台缓存封装实现 KV/Hash/批量读取、TTL、原子计数、幂等键、队列和发布订阅，并按 6.12.1/6.13.2 版本选择可用方法。用于业务缓存、重复提交防护、计数器、轻量队列、缓存失效和 Redis 平台接入；不将平台 setIfAbsent 能力误当成可靠分布式锁。
+---
+
+# Merit Cloud 缓存
+
+## 工作流
+
+1. 确认目标工程实际依赖的 `cloud-module-cache` 版本，不根据平台大版本猜测。
+2. 判断需求属于缓存、幂等、计数、队列还是发布订阅；先读 API 与版本矩阵（参考：`api-and-versions.md`，待补充）。
+3. 设计 key 前缀、租户/环境隔离、TTL、序列化类型和失效时机。
+4. 直接调用平台 `SysCacheServiceFacade`/`CacheServiceFacade`，不要另建 `RedisTemplate` 旁路。
+5. 涉及并发、重复消费或故障恢复时，读 模式与反模式（参考：`patterns.md`，待补充）。
+6. 按 场景验收（参考：`acceptance.md`，待补充） 验证过期、并发、空值、降级和版本兼容。
+
+## 强制边界
+
+- 缓存不是事实源；写数据库成功后再失效或更新缓存。
+- 所有业务缓存必须设置 TTL，除非有明确、可审计的永久缓存理由。
+- key 必须包含应用、模块、用途；多租户系统必须包含租户标识。
+- `setIfAbsent` 没有所有权 token、续租和 compare-and-delete，**不是可靠分布式锁**。
+- 6.12.1 不生成 6.13.2 才存在的队列、扫描、Hash 计数和带超时原子写调用。
+- 不缓存密码、token、私钥、完整身份证等敏感明文。
+
+## 交付内容
+
+输出调用代码时同时给出：依赖版本、key 格式、TTL、空值策略、失效策略、失败降级和并发测试。若需求必须使用可靠分布式锁，停止套用本 Skill，改用公司已批准的锁组件并说明平台缓存 Facade 不满足条件。

package/skills/meritdata-platform-cloud-dev/references/modules/config.md

@@ -0,0 +1,31 @@
+---
+name: meritdata-platform-mod-config
+description: meritdata cloud 配置中心与系统功能：Nacos 配置读取/热更新/动态刷新(@RefreshScope/@ConfigurationProperties)、国际化多语言中英文切换(i18n)、密级/敏感数据保护(禁打印/禁导出/人员密级)。注：单点登录/CAS/SSO 集成归 meritdata-platform-mod-gen
+---
+
+# Merit Cloud 配置、国际化与密级管理
+
+## 路由
+
+- Nacos、动态刷新、批量配置和平台配置 Bean：读取 references/nacos-and-properties.md（参考：，待补充）；需求明确操作 Nacos 配置中心 API 时再读取 references/nacos-utils.md（参考：，待补充）。
+- 前后端多语言：读取 references/i18n.md（参考：，待补充）。
+- 页面密级、人员密级、运行参数、数据密级过滤和产品模块授权：读取 references/runtime-security-boundaries.md（参考：，待补充）。
+- SSO/CAS/token 认证集成转 `meritdata-platform-mod-gen`；数据源连接转 `meritdata-platform-mod-datasource`。
+
+## 执行流程
+
+1. 区分部署配置（Nacos）、平台数据库运行参数（`IParmeterService`）和业务数据库配置，不混用。
+2. 从当前版本 POM、配置清单和真实源码确认 key、Bean、接口与刷新机制。
+3. 对 Secret、租户、密级、授权和并发上下文采用安全边界；未验证能力标记 GAP。
+4. 验证启动默认值、配置刷新、非法配置、并发隔离和权限拒绝路径。
+
+## 高影响配置操作
+
+修改 Nacos、密级策略、租户权限或认证相关配置前，必须确认目标环境、变更范围、最小权限、回读校验和回滚方案。生产配置不得用本地默认值覆盖；缓存清理、会话踢出等关联操作分别转对应专项模块并保留审计证据。
+
+## 强制边界
+
+- Secret 不进入普通参数表、示例、日志或响应。
+- `@RefreshScope` 只放在需要动态刷新的受管 Bean 上；不可变基础设施配置谨慎刷新。
+- 前后端语言选择应复用平台语言上下文，不各自推导出不一致结果。
+- 密级 UI 禁用不是后端授权；查询、导出、下载仍必须服务端校验。

package/skills/meritdata-platform-cloud-dev/references/modules/data-boundary.md

@@ -0,0 +1,44 @@
+---
+name: .claude/rules/data-boundary-rules.md
+description: 约束 meritdata Cloud 平台库与二开业务库的数据隔离。用于二开项目建模、建表、多表查询、人员组织角色字典等平台数据引用、数据源配置和代码审核；禁止业务 Repository/JPA/SQL 直接访问 cloud 微服务平台表，要求只保存稳定 ID/code，并通过已核验 Feign/API 批量查询平台数据。
+---
+
+# Cloud 数据边界
+
+## 强制原则
+
+1. 将 cloud 库视为平台微服务私有存储，不是二开项目的共享数据库。
+2. 二开项目只在自身业务库创建和关联业务表；业务事务不得跨 cloud 库。
+3. 人员、组织、部门、角色、用户、字典、资源等平台引用只保存稳定 ID/code，不建立数据库外键，不复制平台 Entity/Repository。
+4. 读取平台当前数据时使用目标版本已核验的 Feign/API；写平台数据只调用明确开放的写契约。
+5. 列表查询先分页业务数据，再合并去重平台 ID，按能力支持批量 Feign 查询；禁止逐行远程调用。
+6. 平台不可用时区分失败、显式降级和历史快照；不得把空名称伪装成平台查询成功。
+
+## 实施流程
+
+1. 按 ownership-and-access.md（参考：，待补充） 给每张表和字段标注 owner。
+2. 业务表之间可用 JPA/QueryDSL 关联；任何 platform/cloud owner 节点从本地 JOIN 图移除，改成应用层装配。
+3. 用 `meritdata-platform-mod-feign-api` 核验 service、contextId、路径、完整签名、依赖和版本；没有可靠证据时输出 GAP，不臆造 Client。
+4. 涉及人员/组织/角色/字典时读取 meritdata-platform-mod-patterns.md（参考：，待补充），确定 ID、快照、批量装配与失败策略。
+5. 生成或改动后运行：
+
+```text
+python scripts/validate_boundary.py <manifest.json|project-dir>
+python scripts/test_validate_boundary.py
+```
+
+6. 按 acceptance.md（参考：，待补充） 覆盖架构师、后端、前端、DBA、安全和测试角色验收。
+
+## 错误级门禁
+
+- SQL 出现 `cloud.<table>`、跨 schema JOIN 或已知平台核心表 JOIN。
+- 业务代码导入平台持久化 Entity/QEntity 并建立 Repository/JPA 关系。
+- `multi-table-query` 引用当前 manifest 未声明的业务模块，或节点标为 `platform/cloud`。
+- 业务库对平台 ID 建数据库外键、跨库事务或双写平台表。
+- Controller 接受任意 SQL/数据源参数后直连 cloud 库。
+
+`meritdata-platform-mod-datasource` 只用于受控数据源管理和元数据能力，不能作为绕过本边界、查询 cloud 平台业务表的后门。
+
+## Python 依赖边界
+
+本 Skill 的架构规则和模式可直接阅读使用，不依赖 Python。验证脚本只是可选的 CI/批量门禁；关键规则必须同时存在于本文件和 references 中。

package/skills/meritdata-platform-cloud-dev/references/modules/datasource.md

@@ -0,0 +1,30 @@
+---
+name: meritdata-platform-mod-datasource
+description: 使用 Meritdata Cloud 数据源 Feign Client 查询数据源、校验连接、浏览 catalog/schema/table/column 元数据、采样查询和受控 DDL，并指导数据源类型扩展。用于数据源选择、元数据发现、跨源集成和连接适配；处理 V6.13.2 发行包实际携带 6.12.1 datasource artifact 的版本异常，默认禁止业务调用任意 DDL。
+---
+
+# Merit Cloud 数据源
+
+## 工作流
+
+1. 检查目标环境实际 Jar；V6.13.2 发行目录已发现 `cloud-starter-datasource-6.12.1.jar`，不得写死 6.13.2 坐标。
+2. 按需求选择 Query、Metadata、Cluster、SQL 或基础 Client；读 API 与版本证据（参考：`api-and-versions.md`，待补充）。
+3. 确认 `cloud-datasource-server` 已注册、Feign 扫描生效，并对密码/Secret 做脱敏。
+4. 先校验连接，再按 catalog → schema → table → column 顺序发现元数据。
+5. 采样查询必须限制行数、超时和允许语句类型；DDL 默认关闭。
+6. 扩展新数据源类型时读 调用与安全模式（参考：`patterns.md`，待补充），不要只加页面图标。
+7. 按 场景验收（参考：`acceptance.md`，待补充） 验证权限、故障、性能和多数据库差异。
+
+## 强制边界
+
+- `IDataSource*Client` 是指向 `cloud-datasource-server` 的 Feign Client，不是本地数据库 Repository。
+- 数据源管理/元数据 API 不能用于绕过 `.claude/rules/data-boundary-rules.md` 读取 cloud 平台业务表；二开业务账号不得持有 cloud 库表权限。
+- 数据源密码、Secret、Kerberos 信息不得出现在日志、异常、示例或前端响应。
+- `IDataSourceSqlClient.executeDDL` **默认禁用**；只有管理员专用、服务端白名单、审计和审批齐全时才可开放。
+- 不接受浏览器提交任意 SQL 后透传 Feign。
+- Jar 中存在某方言不等于业务 SQL 已兼容；至少做目标数据库真实迁移和查询测试。
+- 数据源删除前必须调用引用检查，不能产生悬空任务或元数据。
+
+## 交付内容
+
+输出集成方案时列出实际 artifact 版本、Client/contextId、调用路径、参数 DTO、超时/熔断、Secret 处理、权限和验收证据。数据源扩展需同时交付配置、驱动、连接校验、元数据适配和部署说明。

package/skills/meritdata-platform-cloud-dev/references/modules/domain-model.md

@@ -0,0 +1,40 @@
+---
+name: meritdata-platform-mod-domain-model
+description: 公司微服务企业业务领域建模与多表关联设计。用于从需求识别实体、值对象、聚合根、一对多、多对多、树、主子表、跨模块引用和外部平台实体；按大写+下划线+业务前缀（sql-naming-rules.md）设计业务表、索引、外键策略、事务边界、QueryDSL 联表/投影/分页、DTO 与接口，并把人员组织字典附件流程等语义路由到平台公共 Skill。适用于中大型业务系统、复杂查询、数据库设计和生成代码前的模型校验。
+---
+
+# 企业业务领域与多表建模
+
+先建模，后生成。避免将所有关联都直接写成 JPA 双向关系。
+
+## 流程
+
+1. 提取角色、命令、状态、业务规则和查询用例。
+2. 划分聚合；只允许聚合内强事务，跨聚合使用 ID 引用和应用服务编排。
+3. 先用 `.claude/rules/data-boundary-rules.md` 判定表所有权；cloud 平台表不得进入二开库的 JPA/SQL 关系图。
+4. 按 relationship-patterns.md（参考：，待补充） 选择一对多、多对多、树或跨服务模式。
+5. 识别平台语义：人员/组织/角色/字典/附件/流程/权限不是普通字符串，路由到对应 Skill。
+6. 输出实体关系、表结构、索引、唯一约束、删除策略、事务和查询模型。
+7. 用 review-checklist.md（参考：，待补充） 审查，再交给 `meritdata-platform-mod-gen`。
+
+## 输出契约
+
+- 聚合清单与职责；每个聚合只有一个写入口。
+- ER 关系及基数、所有权、是否级联、删除策略。
+- 表/字段/索引/唯一约束：二开业务表和字段默认使用**大写 + 下划线 + 业务前缀**（如 `T_CONTRACT`），禁止沿用平台 `PF_` 前缀；实体类使用大驼峰。历史/特殊主表需同时声明例外开关与不可改名原因，新业务列和关联表不随主表例外放宽。详见 `.claude/rules/sql-naming-rules.md`。
+- 写模型与查询 DTO/VO；复杂列表优先 QueryDSL 投影，不返回持久化关系图。
+- 平台语义字段的组件、服务、存储值和显示值映射。
+- 正常、并发、空集合、重复提交、越权和外部服务失败测试。
+
+## 平台语义路由
+
+| 语义 | 存储建议 | UI/服务 |
+|---|---|---|
+| 责任人/申请人/经办人 | `*_USER_ID`，必要时快照姓名 | `meritdata-platform-mod-ui` 人员弹框；二开服务通过已核验 Feign/API 批量装配 |
+| 部门/组织 | `*_ORG_ID` / `*_DEPT_ID` | 部门/组织树组件 |
+| 角色 | 角色 ID/编码 | 角色选择组件；授权用 `IAssignService` |
+| 状态/类型 | 稳定字典 code | `ILookupService` + 字典选择器 |
+| 附件 | 业务附件关联表，不把二进制放主表 | 平台上传组件 |
+| 审批状态 | 业务状态与流程实例 ID 分离 | `meritdata-platform-mod-bpm` |
+
+不得把人员、组织名称作为唯一关联键；不得跨服务建立数据库外键；不得从二开库 JOIN cloud 平台表。

package/skills/meritdata-platform-cloud-dev/references/modules/feign-api.md

@@ -0,0 +1,41 @@
+---
+name: meritdata-platform-mod-feign-api
+description: meritdata Cloud 6.12.1/6.13.2 跨微服务 Feign 与平台 HTTP API 检索、选型和安全集成。用于查找真实可编译的 Feign 类/方法签名、service/contextId/path、Maven 依赖与版本，生成调用封装、超时/重试/熔断/fallback，或对接组织人员、权限密级、日志、定时调度、SSO/ISC 及基础数据申请等公共能力；当用户提到 Feign/跨服务/公共接口/平台 API/服务调用或需要判断应用本地 Bean 还是远程 API 时使用。
+---
+
+# Merit Cloud Feign 接口
+
+## 执行流程
+
+1. 确认平台版本、调用方与提供方、读写性、是否在同一 JVM。信息不全时可读取目标项目 `pom.xml`/父 POM/源码作为项目上下文；平台公共接口只使用随 Skill 发布的离线知识库，不要求员工环境存在平台源码、源码 Jar 或反编译工具。
+2. 先做调用面判定：
+   - 同进程且已依赖 `cloud-system-manage-module`：优先本地 Service Bean，并使用 `meritdata-platform-mod-services`。
+   - 跨服务且已有平台 Feign 类：直接注入平台接口，禁止复制同名类。
+   - 只有对外 HTTP 文档：核对当前服务 OpenAPI/提供方源码后再建项目级 Client；文档中的 V6.8 示例不得直接当作 6.13.2 真实签名。
+3. 运行 `python scripts/search_api.py <关键字>` 检索已发布目录。命中后读 references/api-catalog.md（参考：，待补充）；需要写新 Client 或做容错时再读 references/integration-patterns.md（参考：，待补充）。跨域总览可读 `meritdata-platform-mod-platform/references/interface-knowledge-base.md`。
+   平台主动通知二开服务的租户、权限、用户或组织变更场景，额外读取 references/meritdata-platform-mod-change-notification.md（参考：，待补充）。
+   平台主动通知二开服务的租户、权限、用户或组织变更场景，额外读取 references/meritdata-platform-mod-change-notification.md（参考：，待补充）。
+4. 将来源分级为 `PROJECT_SOURCE/POM` > `OFFLINE_KB_VERIFIED/BINARY_VERIFIED` > `VERSIONED_DOC` > `LEGACY_HTTP_DOC` > `INFERENCE`。`OFFLINE_KB_VERIFIED` / `BINARY_VERIFIED` 表示维护阶段已登记的签名摘要，使用者不参与内部取证。产出中标注证据级别；不得把旧版 HTTP/Swagger 记录伪装成可注入 Java 接口。
+5. 产出最小集成包：Maven 坐标/版本来源、启用条件、真实类名和签名、调用封装、失败语义、配置项、测试。
+6. 执行编译或契约测试；启动时再验证服务名、注册中心及远程返回包装。若本地/服务端环境没有平台 Jar，不阻断生成，但必须保留 `GAP_REVERIFY_REQUIRED` 或在发布前 CI 中补做核验。
+
+本 Skill 的维护期接口证据摘要见 references/verification-evidence.md（参考：，待补充）；运行时只消费已登记摘要，不要求使用者执行 Jar 或字节码取证。
+
+平台服务需求只有在 `contract_evidence` 已核验且 `contract_ref` 能定位到具体契约时才算闭环；`PROJECT_SOURCE` 证据还必须确认源文件实际存在。任一条件不满足时标记 `GAP_REVERIFY_REQUIRED`，不得生成猜测接口或宣称集成完成。
+
+## 强制边界
+
+- 不硬编码 token、Cookie、app-key、app-token、租户或人员标识；不复制 PDF 中的调试凭据。
+- 不为写操作配置自动重试，除非接口具有经确认的幂等键。GET/查询也只对瞬态连接故障有界重试。
+- fallback 不得返回“空集合/成功/false”来伪装正常业务结果。权限、认证、密级默认失败关闭；非关键展示查询可降级为明确的 `DEGRADED` 状态。
+- 不把 `@DisableTenant`/`@DisableEncrypt` 当作普通开关添加。只能复用平台原接口已有的注解；自建接口需安全评审。
+- Feign 层不直接向 Controller 泄漏底层异常或远程响应；由业务 Service 转换为可观测、可国际化的领域错误。
+- 不得假设所有平台 Feign 均返回 `ResultBody<T>`。实际契约同时存在 `ResultBody<T>`、实体、`List/Map`、`boolean/void`等；必须逐方法按目标 Jar 签名处理。
+
+## 交付检查
+
+- 说明为何选 Feign、本地 Bean 或 HTTP Client。
+- 给出 `groupId:artifactId:version`，版本继承时说明 BOM/父 POM。
+- 列出 service name、contextId、HTTP method/path、完整 Java 签名、返回包装。
+- 明确超时、重试、熔断、fallback、幂等、认证/租户/密级边界。
+- 覆盖成功、4xx、5xx/超时、熔断以及写操作“远程成功但本地超时”的不确定结果。

package/skills/meritdata-platform-cloud-dev/references/modules/file.md

@@ -0,0 +1,30 @@
+---
+name: meritdata-platform-mod-file
+description: 集成 Merit Cloud 6.13.2 业务附件的上传、回显、下载、删除、复制、密级和生命周期管理。用于表单或业务聚合需要 joinId/fileId 关联、调用 IUploadService/IEnclosureService、设计附件表、清理孤儿文件、实现下载权限，或排查路径穿越、越权下载和文件残留；流程专属附件仍联动 meritdata-platform-mod-bpm，前端上传组件仍联动 meritdata-platform-mod-ui。
+---
+
+# Merit Cloud 文件与附件
+
+按 beta 契约实施文件能力。只使用已验证的 6.13.2 签名；不要根据旧版本、方法名或存储路径推断未公开语义。
+
+## 工作流
+
+1. 识别附件类型：普通业务附件、通用 enclosure、流程附件、消息附件或 Excel 导入导出。
+2. 识别部署边界：系统管理同进程才注入本地 Service；独立业务微服务应调用已验证的网关 HTTP 契约。
+3. 选择唯一文件 owner：普通业务附件优先 `IUploadService`；通用 enclosure 仅在调用参数语义已由当前项目证明时使用；流程附件转 `meritdata-platform-mod-bpm`。
+4. 设计 `joinId` 与 `fileId` 生命周期，读取 lifecycle.md（参考：，待补充）。
+5. 核对真实类、方法和实体字段，读取 api-contracts.md（参考：，待补充）。
+6. 实施密级、租户、下载授权、文件校验、路径和审计控制，读取 security.md（参考：，待补充）。
+7. 对照 examples.md（参考：，待补充） 检查正反例，不直接暴露物理路径。
+8. 按 acceptance.md（参考：，待补充） 完成角色和业务场景验收；缺少契约或测试时明确停止生成。
+
+## 调用边界
+
+- `IUploadService`：按 `joinId` 管理业务附件集合，按 `PfUpload.id` 管理单个附件。
+- `IEnclosureService`：独立 enclosure 契约，不能仅因存在 upload/download 方法就替代业务附件服务。
+- BPM/消息附件：由各自领域 Skill 持有业务规则，本 Skill 只提供通用安全和生命周期约束。
+- `AbstractFileOperation`：平台内部存储抽象。业务代码不得直接拼接 path、绕过元数据和权限层。
+
+## 输出契约
+
+每次方案或代码输出必须包含：附件类型、调用方式、版本证据、joinId/fileId 模型、上传/回显/下载/删除链路、权限与密级检查、失败补偿、孤儿清理、审计点和验收结果。不得只生成上传按钮或 Controller。

package/skills/meritdata-platform-cloud-dev/references/modules/gen.md

@@ -0,0 +1,215 @@
+---
+name: meritdata-platform-mod-gen
+description: meritdata cloud 微服务增量开发与代码生成主编排器。用于新建工程，也用于现有 Git/SVN 项目新增业务模块、页面、字段、接口、查询、流程、认证、Feign、导入导出、附件、消息和调度功能；先检查存量代码并生成最小变更，自动联动 merit-code-spec 自查，不覆盖用户已有实现。
+---
+
+# 公司微服务规范化代码生成 Skill
+
+按目标平台版本生成后端、前端、Feign、认证、工作流、SQL、文档和验证证据。详细触发语义以 frontmatter description 为准。
+
+生成前必须向用户显示目标微服务版本。用户未指定时提示“默认按 6.13.2 生成，可填写其他已支持版本”，并将 `cloud_version: 6.13.2` 写入 manifest；用户指定时显示解析后的精确版本并按该版本适配依赖与代码。
+
+## 1. 平台规范基线（生成任何代码前必须遵守）
+
+完整规范见 meritdata-platform-mod-spec.md（参考：，待补充），以下为必须内化的硬约束。生成公共调用时读取 external-api-index.md（参考：，待补充）；需要核对平台类和方法时以 real-class-signatures.md（参考：，待补充） 为证据，不凭命名猜测。
+
+| 维度 | 规范 |
+|------|------|
+| 运行版本 | 支持已登记的 6.10/6.12/6.13 版本画像；JDK、Spring、Swagger、QueryDSL 必须由 `cloud_version` 与真实依赖共同确定 |
+| 服务治理 | Spring Cloud + Nacos（配置中心 + 注册中心），`bootstrap.properties` 指向 `meritdata.cloud.nacos-addr` |
+| 项目根包 | `com.meritdata.cloud.cets`（必须包含二开项目缩写），子包 `controller / service / impl / repository / entity` |
+| 持久层 | JPA（增删改）+ QueryDSL（查询），Repository 继承 `JpaRepository<T,String>` 与 `QuerydslPredicateExecutor<T>` |
+| 实体基类 | 业务实体 `extends CloudBaseEntity`（自带 多租户/创建时间/更新时间/作者/更新人/SECRET_CODE/TENANT_ID） |
+| 主键策略 | `@GenericGenerator(name="jpa-uuid", strategy="uuid")` + `@GeneratedValue(generator="jpa-uuid")`，String 型 UUID |
+| 表名 | 二开业务表默认**大写 + 下划线 + 业务前缀**（如 `T_PERSON`），不使用平台 `PF_` 前缀，字段大写下划线，实体大驼峰；历史/特殊主表必须同时声明 `allow_custom_table_name: true` 与 `custom_table_name_reason`（详见 `.claude/rules/sql-naming-rules.md`）|
+| 统一返回 | 所有 Controller 返回 `ResultBody<T>`：`{timestamp,status,message,stackmessage,path,data,extraInfo,success}` |
+| 分页查询 | 使用 `PageQuery` 统一规整分页入参，业务分页返回 `ResultBody<GridView<XxxVO>>`，配合 QueryDSL `offset/limit` 与动态条件；禁止 `GridView<XxxVO>` |
+| 配置项 | 业务配置写入 Nacos `common.properties`，命名 `meritdata.cloud.<功能>.<项>=...` |
+| 前端 | Vue + Element-UI，axios 实例名 `system-manager`，路由经网关 `/gateway/<服务名>/api/...` |
+
+## 2. 工作流程（新工程与存量项目共用）
+
+> 本 Skill 是主编排器。先判断 `project_mode: new|existing`。存量项目必须先读取 POM、包结构、现有实体/接口/页面和依赖，输出最小补丁，不得套用新工程脚手架覆盖现有文件。
+
+收到需求后，**严格按以下顺序**执行：
+
+```
+1) 生成依据   → 读取需求、概要设计、数据库设计；缺任一项时停止代码生成，让用户选择提供资料、先产出草案待确认，或补充缺失信息
+2) 项目识别   → 新工程使用 scaffold；现有工程读取源码与构建文件，形成 project_context，不生成 scaffold
+3) 需求解析   → 调用 sub-skills/analyze.md，输出《生成任务清单》(task manifest)
+4) 准入校验   → 读 sub-skills/pre-write-check.md 逐项核对 manifest（不合规直接报错，不生成）
+5) 规范基线   → 加载 references/meritdata-platform-mod-spec.md（平台 12 条硬约束）
+6) 路由生成   → 按清单类型分发到对应子 Skill：
+                  - 新建工程      → sub-skills/scaffold-project.md
+                  - 业务模块(后端) → sub-skills/gen-module-backend.md
+                  - 业务模块(前端) → sub-skills/gen-module-frontend.md
+                  - Feign 调用     → sub-skills/gen-feign-call.md
+                  - 认证集成       → sub-skills/gen-auth.md
+                  - 工作流集成     → sub-skills/gen-workflow.md
+                  - 多表关联查询   → 先调用 meritdata-platform-mod-domain-model，再生成 multi-table-query
+                  - 人员/附件/多选 → 自动追加 sub-skills/gen-semantic-closure.md，生成稳定 ID、批量名称装配、关联表与载荷适配闭环
+7) 生成/修改   → 新模块可渲染完整六件套；已有模块按真实源码最小修改，保留现有命名、继承、扩展点和用户代码
+8) 代码规范自查 → 已安装 `merit-code-spec` 时按其 checklist 联动；未安装时执行本 Skill 的 post-gen-check，并在结果中标记质量专项 GAP
+   → 违反本 Skill 或可用质量专项的强制项必须修复后重生成
+9) 后置校验   → 触发 `meritdata-platform-2nd-dev-check` 做 7 类 60+ 项体检（替代原 `hooks/post-gen-check.md`）；新工程执行完整构建，存量项目在合并补丁后执行原项目构建与相关回归
+10) 产出结果  → 输出新增/修改文件、数据库迁移、接口说明、验证结果和未决 GAP；不生成开发过程日志
+11) 用户提交  → 识别 Git/SVN 但不执行 add/commit/push/tag/合并请求，代码由用户手动提交
+```
+
+> 关键原则：**先识别项目、再做最小变更、生成后自检、产物带验证证据、不覆盖用户代码**。
+> 联动关系：本 Skill（生成/修改）→ merit-code-spec（规范自查）→ 相关平台专项 Skill（按业务语义触发）。
+> 工程质量目标：代码规范、一次编译通过、生成确定性、模块适配、可测试和可追溯。
+> 生成完成不代表版本库提交授权；无论项目使用 Git、SVN 或尚未纳入版本库，Skill 都不会自动提交代码。
+
+### 2.0 渲染器单一入口（错误级）
+
+- 正式生成必须使用同一份 manifest、内置模板目录 和 `tools/render.py`/`tools/renderer.py` 的版本派生规则；AI 手工增量修改也必须先读取同一 manifest 与版本 Profile。
+- 禁止为了批量生成、补字段或临时修复而在目标项目或工作目录新建 `generate_*.ps1`、`generate_*.py`、Node 脚本等第二套代码生成器。
+- 模板尚不支持的能力，先补正式模板和渲染器并增加回归样例；无法安全补齐时输出 GAP，不得以临时脚本绕过 `cloud_version`、结构契约、数据边界或生成后校验。
+- 版本命名空间、Swagger、QueryDSL、JDK 和依赖坐标均从 `version-profiles.json` 派生。6.13.2 必须直接生成 `jakarta.*`，不得先输出 `javax.*` 再做批量替换。
+
+### 2.1 生成依据门禁
+
+代码必须可追溯到三类输入：**需求、概要设计、数据库设计**。先读取用户提供的文档、表结构或现有源码，再把来源登记到 manifest：
+
+```yaml
+generation_basis:
+  requirement: {ref: docs/需求说明.md}
+  design: {ref: docs/概要设计.md}
+  database: {ref: docs/数据库设计.sql}
+```
+
+用户未提供完整资料时，只能询问其选择，不能猜测后直接写代码：
+
+1. 提供或引用现有需求、设计、数据库资料；
+2. 仅根据需求先产出设计和数据库草案，用户确认后再生成代码；
+3. 补充缺失的模块、字段、表、索引、关联和流程信息。
+
+已确认的 `design` 任务可作为三类依据的结构化记录，但其 `requirement`、`table_name` 和 `fields` 必须完整并与待生成模块对应。
+
+## 3. 模板与变量
+
+所有代码由**内置模板目录**下的模板 + 任务清单变量渲染而成（具体路径相对本 skill 内部）。变量定义见 variables.md（参考：，待补充）。核心变量：
+
+```yaml
+# 应用级
+app_name: cloud-system-item            # 应用名称
+app_code: cloud-system-item            # 应用编码(工程名)
+app_version: 1.0-SNAPSHOT              # 可选，项目自身 Maven 版本
+base_package: com.meritdata.cloud.cets # 完整项目根包，统一分层直接在此目录下生成
+project_package: cets                  # base_package 只填写 com.meritdata.cloud 时必填
+service_port: 8091                     # 启动端口
+cloud_version: 6.13.2                  # 可省略；默认 6.13.2，也可填写 6.10/6.12/6.13 已支持版本
+features: []                            # 功能模块选择（bpm/job/auth；workflow/auth 任务会自动推导依赖）
+code_structure:
+  backend: unified                     # 缺省 unified；modular=按 module_code 分包；unified=统一按技术层分包
+  package_segment: cets                # 可选；仅当基础包未含应用包段时填写，如 com.meritdata.cloud.cets.*；modular 时不得填写
+pagination:
+  page_size_max: 500                   # 生成器内置上限；兼容 pageNo/pageNumber、size/pageSize
+  default_sort: updateTime desc         # Service 层按字段白名单解析 sortField/sortOrder
+
+# 生成依据；没有完整资料时必须先走“设计草案待确认”流程，禁止直接生成代码
+generation_basis:
+  requirement: {ref: docs/需求说明.md}
+  design: {ref: docs/概要设计.md}
+  database: {ref: docs/数据库设计.sql}
+
+# 模块级
+module_name: 人员管理
+module_code: person                    # 业务模块编码、接口路径和前端页面路径；Java 包路径由 code_structure 决定
+table_name: T_PERSON                   # 二开业务表默认大写+下划线+业务前缀（sql-naming-rules.md）
+entity_name: Person                    # 实体类名
+template_type: single_table            # single_table|tree_list|tree_and_list|master_child|workflow
+fields:                                # 字段清单
+  - {name: name, type: String, column: name, label: 姓名, required: true, query: true, list: true, form: true}
+  - {name: age, type: Integer, column: age, label: 年龄}
+  - {name: ownerUserId, type: String, label: 责任人, semantic: person, form: true}
+
+# 流程模块（template_type=workflow 时必填）
+proc_def_key: Process_Person
+process_id: <系统管理-流程模块中的流程id>
+
+# 认证
+auth_mode: token|cas|oauth2|third_party
+
+# Feign
+feign_target: org                      # org|person|role|dict|menu|user...
+```
+
+## 4. 子 Skill 索引
+
+| 子 Skill | 触发 | 产出 | 模板 |
+|----------|------|------|------|
+| `sub-skills/analyze.md` | 任意需求 | 生成任务清单 | - |
+| `sub-skills/scaffold-project.md` | 新建工程 | 后端 + 前端骨架 | 内置模板目录/project/* |
+| `sub-skills/gen-module-backend.md` | 业务模块后端 | controller/service/impl/repository/entity + SQL | 内置模板目录/backend/* |
+| `sub-skills/gen-module-frontend.md` | 业务模块前端 | App/Index/Grid/Dialog/store/router | 内置模板目录/frontend/* |
+| `sub-skills/gen-feign-call.md` | 公共服务调用 | Feign 接口 + 调用封装 + DTO | 内置模板目录/feign/* |
+| `sub-skills/gen-auth.md` | 认证集成 | RSAUtils/SSOController/Filter + Nacos 配置 | 内置模板目录/auth/* |
+| `sub-skills/gen-workflow.md` | 工作流集成 | BpmEngine 统一入口 + 状态流转 + 意见 | 内置模板目录/workflow/* |
+| `sub-skills/gen-semantic-closure.md` | 字段含 person/attachment 或 multiple | 人员批量装配、人员/附件关联表、事务同步与前端载荷适配 | 内置模板目录/semantic-closure/* |
+
+前端生成已安装 `$meritdata-platform-mod-http-client` 时汇总 service requirements；未安装时只按本 Skill 的 endpoint 形状生成并报告 transport registry GAP。禁止修改共享 Axios defaults，所有 endpoint 显式声明响应形状。多方言建库升级使用 `cloud-starter-dbinit` 的目标版本规则，脚本必须幂等、有版本序号和回滚说明；V6.13.2 datasource artifact 异常仅在已安装 `$meritdata-platform-mod-datasource` 时由其判定，否则报告版本证据 GAP。
+
+完整页面同时生成中英文资源、`qinLang` 传递、keepAlive 路由 name 一致性和无权限页；树/主子表/流程组合先经 domain-model 决策，不把复杂布局继续塞进单表模板。
+
+多表任务使用 `type=multi-table-query`，输入根实体、join 关系和投影字段；生成 QueryDSL 查询服务与 VO。已安装 `meritdata-platform-mod-domain-model` 与 `.claude/rules/data-boundary-rules.md` 时先经其审查；未安装时仍强制所有 join 节点属于当前 manifest 声明的本项目业务模块，cloud 平台人员/组织/角色/字典只存稳定 ID/code、通过已核验 Feign/API 后置批量装配、禁止跨库 JOIN，并报告专项审查 GAP。
+
+## 5. Hooks 与验证（强制卡点）
+
+AI 可以直接读取规则与模板生成；Python/Node 工具用于确定性渲染、扫描和前端预检，环境允许时应执行，不再把“零 Python”作为目标。
+
+- **写盘前准入**（`sub-skills/pre-write-check.md`）：校验 manifest 命名/类型/字段/必填项；不通过则停止生成并反馈修正。
+- **生成后自检**（触发 `meritdata-platform-2nd-dev-check`，替代原 `hooks/post-gen-check.md`）：A-K 共 11 类检查——包结构/返回体/继承签名/表命名/配置/产物齐全/注释/测试覆盖/留痕/merit 代码规范；错误项修复重生成。
+- **前端依赖预检**：已安装 `meritdata-platform-mod-ui` 时执行其 `scripts/preflight.mjs`；未安装时不假定组件存在，附件/富文本能力标记 GAP，不能生成空壳适配器。
+
+## 5.1 存量项目增量规则
+
+- `project_mode: existing` 时，`project_context` 至少包含 `app_code`、`base_package`、`cloud_version`；版本优先从现有 POM 识别，无法识别才提示默认 6.13.2。
+- 新工程后端默认 `code_structure.backend=unified`，直接使用 `base_package`；仅当基础包未含应用包段时显式填写 `package_segment`。需要按业务模块分包时显式选择 `modular`。生成器将最终选择写入根目录 `generation-manifest.json`。
+- 后续增量生成优先读取 `project_context.generation_manifest` 指向的 `generation-manifest.json` 并继承其结构；显式结构与已固化契约不一致时必须停止，禁止切换包结构。
+- 新增模块：生成独立模块文件、SQL 迁移和接入清单，不生成父 POM、启动类或全局配置。
+- 扩展已有模块：先定位实体、DTO、Repository、Service、Controller、API、页面和测试，只修改需求涉及的符号；确定性命令行渲染器仅负责“新增模块补丁”，已有模块修改由 AI 基于实际源码实施。
+- 新增字段必须同时检查实体列、DTO/校验、查询条件、表单/列表、SQL migration、接口兼容和测试；不得重建表或覆盖现有数据。
+- 新增流程、Feign、附件、导入导出、消息、调度等功能时只追加所需依赖和配置，不重写现有 POM/Nacos/HTTP registry。
+- `ServiceImplTest` 和场景测试覆盖正常、边界、异常、空值；不以固定“用例数量”替代行为覆盖。
+- 重构可选执行 `python tools/refactor_gate.py before|after <project>`；必须使用项目配置的 Maven/JDK，前后测试均通过且用例不减少。
+
+## 6. 命令行渲染器（可选，CI/离线用）
+
+AI 路径可读取 SKILL、子任务和模板；确定性路径使用 Python 渲染、边界扫描和证据生成。两条路径必须服从同一 manifest 和门禁，不能未经字节级对比就宣称产物完全等价。
+
+企业落地分三档：
+
+1. 对话模式：由 AI 按模板生成，并用可用的 Python/Node/Maven 工具验证。
+2. 开发验证：使用 `tools/*.py` 快速复现、批量回归并采集工程证据。
+3. 企业 CI：建议把确定性渲染/扫描迁移为公司技术栈的 Java Maven Plugin 或 Node CLI；不得让 Python 成为开发人员安装 Skill 的前置条件。
+
+如需在 CI/无 AI 环境下确定性生成，仓库提供 `tools/render.py`（依赖 `tools/renderer.py` 渲染引擎）：
+```bash
+python tools/render.py <manifest 文件> -o <输出目录>
+```
+渲染器读同一套内置模板目录；同一 manifest 的确定性渲染结果通过 verification hash 证明可重复。
+
+## 7. 产物清单（每次生成必带）
+
+每次生成业务模块后，必须同时产出：
+
+1. **源码**：后端分层代码 + 前端页面（可一次编译通过）
+2. **建表 SQL**：二开业务表使用**大写 + 下划线 + 业务前缀**（如 `T_CONTRACT`）且无 `PF_` 前缀，含 `SECRET_CODE/TENANT_ID/CREATOR_ID/REVISER_ID` 公共字段（详见 `.claude/rules/sql-naming-rules.md`）
+3. **接口文档**：列出每个接口地址、方法、入参、出参和示例，作为契约测试依据
+4. **使用说明**：如何加入平台运行环境、菜单/路由/Nacos 配置、启动步骤
+5. **单元测试用例**：Service 层测试，需能在 CI 中自动执行
+6. **验证清单**：勾选项、预期效果和实际证据位置
+
+## 8. 快速开始（示例对话）
+
+```
+用户：帮我搭一个"资产管理"微服务，含一个"设备台账"模块，单表增删改查，字段：设备名/型号/责任人。
+→ 本 Skill：
+  1) analyze：清单 = {scaffold app=cloud-asset + module=equipment(single_table)}
+  2) scaffold-project：生成后端/前端骨架
+  3) gen-module-backend：EquipmentController/Service/Impl/Repository/Equipment + equipment.sql
+  4) gen-module-frontend：Grid/Dialog/App/Index/store/router
+  5) post-gen-check：校验通过，输出校验报告 + 接口文档 + 使用说明 + 单测 + 验证清单
+```

package/skills/meritdata-platform-cloud-dev/references/modules/governance.md

@@ -0,0 +1,51 @@
+---
+name: merit-skill-governance
+description: 治理公司级 Meritdata Cloud Skill 套件的目录边界、语义版本、事实证据、平台兼容、确定性测试、评审发布和退役。用于新增或升级 Skill、引入脚本、声明 API/组件能力、版本迁移、发布前审计、证据过期复核和生产事故追溯。
+---
+
+# 企业级 Skill 治理
+
+将 Skill 视为可发布的软件资产，而不是提示词集合。先盘点事实，再做变更；未经证据支持的接口不得进入稳定发布通道。
+
+## 治理流程
+
+1. 建立清单：记录唯一入口和内部模块的名称、所有者、领域、平台版本、依赖、自动化等级和生命周期。
+2. 判断执行形态：依据 automation-policy.md（参考：，待补充） 选择零脚本、可选脚本或确定性脚本；不要默认使用 Python。
+3. 建立证据：依据 evidence-policy.md（参考：，待补充） 为 API、组件、依赖、版本差异绑定来源、定位、摘要、采集日期和置信度。
+4. 评估兼容：依据 release-policy.md（参考：，待补充） 建立平台、JDK、Spring、前端组件与调用方式矩阵。
+5. 执行测试：至少覆盖结构、引用、证据、契约、生成幂等、编译和代表性业务场景；失败时阻断发布。
+6. 评审发布：由领域所有者和治理维护者双人审批，生成不可变发布包、摘要和回滚点。
+7. 监控退役：证据过期、平台升级或事故触发复核；先标记 deprecated，再移除。
+
+## 目录契约
+
+新增或调整 Skill 前先读取 directory-contract.md（参考：，待补充），以下仅保留摘要。
+
+```text
+skills/meritdata-platform-mod-dev/
+├── SKILL.md                 # 唯一可发现入口
+├── agents/openai.yaml       # 唯一 UI 入口元数据
+└── modules/meritdata-platform-mod-*/
+    ├── module.md            # 不可独立发现的内部能力
+    └── references|scripts|templates
+```
+
+禁止在 Skill 内新增 README、CHANGELOG 等旁路文档。发布记录属于套件级注册表或制品库。详细事实只放一处，其他位置使用链接引用。
+
+## 发布门禁
+
+- 全套只能存在一个 `SKILL.md`，且必须是 `meritdata-platform-mod-dev`；内部模块只能使用 `module.md`，不得包含 `agents/openai.yaml`。
+- 所有相对链接可解析，不存在 TODO、占位符、乱码、重复事实源。
+- 每条稳定 API/组件事实存在可定位证据；二进制核验记录必须包含制品坐标、版本、签名摘要和 SHA-256，取证过程不作为 Skill 能力发布。
+- 本地 Bean、Feign、网关 HTTP、前端组件四类调用边界不得混淆。
+- 声明的每个平台版本至少有一个契约测试；生成类 Skill 必须验证同输入同输出。
+- 确定性脚本必须固定运行时、参数、退出码和输出格式，并提供非 Python 兼容入口或清晰先决条件。
+- 重大变更通过新主版本发布；不得原地覆盖已发布制品。
+
+## 输出契约
+
+治理审计必须输出：资产清单、脚本决策、证据缺口、兼容矩阵、测试结果、风险等级、发布/阻断结论及责任人。缺少真实验证时明确写“未验证”，不得推断为通过。
+
+按角色和场景设计验收时读取 role-scenario-gates.md（参考：，待补充）。
+
+涉及平台版本、默认版本、JDK、命名空间或依赖选择时，读取 version-profiles.json（参考：，待补充）；涉及 renderer、validator、路由或文档集成时同时读取 version-profile-integration.md（参考：，待补充）。不得在消费者中新增重复版本常量。