adspecs 0.1.19 → 0.1.21

package/skills/adspecs-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: "adspecs-plan"
 description: "基于 PRD 文件一次性完成需求分析与系统设计（OOA+OOD），输出统一设计文档（_system-design.md）和建表 SQL（_schema.sql）"
 argument-hint: "指定 PRD 文件路径，如 docs/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md"
-compatibility: "需要 docs/ 目录体系，含 03-系统设计模板.md v1.2、项目约定文档、ECP 编码规范"
+compatibility: "需要 docs/ 目录体系，含 03-系统设计模板.md v1.2、项目后端编码规范（由 docs/40-project_conventions/end-integration/index.md 提供）"
 metadata:
   author: "qingwen"
 user-invocable: true
@@ -37,24 +37,22 @@ $ARGUMENTS
 读取用户指定的 PRD 文件（`{PRD_DIR}/`），一次性完成系统设计（OOD），生成 **2 个输出**：
 
 1. **统一系统设计文档**（`.md`）— 按 `03-系统设计模板.md` v1.2 单阶段 13 部分生成，覆盖 OOA+OOD 全部内容
-2. **建表 SQL**（`.sql`）— 完整 DDL，遵循 ECP 审计字段规范（经 Liquibase 管理）
+2. **建表 SQL**（`.sql`）— 完整 DDL，遵循项目后端规范（审计字段、DB 迁移格式等）
 
 ## 输入
 
 ### 必读文件（按顺序）
 
-| 序号 | 文件                                                                          | 用途                                                                     |
-| ---- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| 1    | `{PRD_DIR}/{用户指定的 PRD 文件}`                                             | 需求来源 — 提取用户故事（US-ID）、业务规则（BR-ID）、功能清单、验收标准  |
-| 2    | `CLAUDE.md`                                                                   | 项目技术栈、模块结构、ECP 编码约定                                       |
-| 3    | `.adspecs/templates/03-系统设计模板.md`                                       | **统一设计模板 v1.2**（单阶段 13 部分，含 gushen-demo 角色管理填写示例） |
-| 4    | `docs/40-project_conventions/end-integration/后端分层开发与数据库设计规范.md` | ECP 编码规范：Entity/DTO/Ro/DAO+XML/Service/Controller 标准              |
-| 5    | `docs/40-project_conventions/end-integration/多语言及全局异常处理规范.md`     | 错误码格式、ResponseMsgCode 枚举、i18n 文件规范                          |
-| 6    | `docs/40-project_conventions/end-integration/Liquibase 数据库变更管理规范.md` | 建表 SQL 规范（DDL/DML 幂等、changeset 命名）                            |
+| 序号 | 文件                                                   | 用途                                                                                |
+| ---- | ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| 1    | `{PRD_DIR}/{用户指定的 PRD 文件}`                      | 需求来源 — 提取用户故事（US-ID）、业务规则（BR-ID）、功能清单、验收标准             |
+| 2    | `CLAUDE.md`                                            | 项目技术栈、模块结构                                                                |
+| 3    | `.adspecs/templates/03-系统设计模板.md`                | **统一设计模板 v1.2**（单阶段 13 部分，填写示例仅作参考，实际以 index.md 规范为准） |
+| 4    | `docs/40-project_conventions/end-integration/index.md` | 后端编码规范索引（按其中推荐顺序加载全部规范）                                      |
 
 ### 参考文件（按需）
 
-- `gushen-demo/` 参考代码 — 已有的包路径、基类、IotBaseRole 标准写法范例
+- 项目已有参考代码（如有）— 已有的包路径、基类标准写法范例
 - `{PRD_DIR}/` 下的其他 PRD 文件 — 了解关联模块的业务
 
 ## 执行前检查
@@ -106,11 +104,17 @@ $ARGUMENTS
    - 读取 `.adspecs/templates/03-系统设计模板.md`，获取系统设计的完整结构
    - 如果模板不存在，使用内置的分析结构（见下方"## 工作流程"）
 
-3. **加载项目上下文**（可选）：
+3. **加载后端编码规范**（必选）：
+   - 读取 `docs/40-project_conventions/end-integration/index.md`
+   - 按 `index.md` 中"推荐读取顺序"依次加载所有关联规范文件
+   - 后续所有设计决策（实体命名、基类选择、注解使用、审计字段、响应包装、异常处理、DB 迁移格式等）均以该规范为准
+   - 如该目录不存在或 `index.md` 缺失，中止执行并提示先运行 `/project-init` 选择技术栈
+
+4. **加载项目上下文**（可选）：
    - 如果 `CLAUDE.md` 存在，读取以了解项目背景
    - 如果 `docs/{PRD_DIR}/` 下有相关文档，读取以补充需求背景
 
-4. **识别二级模块**：
+5. **识别二级模块**：
    - 扫描 `{ARCH_DIR}/` 目录，查找 `01-*_business_scenarios.md` 或 `01-*_business_architecture.md` 文件（业务功能架构文档，两者命名均可能出现）
    - 如果找到，读取文件内容，重点关注：
      - **二、系统模块总览** → **2.2 子模块清单**：获取所有主模块（M00~M{N}）及其下属的二级模块（子模块，编号格式如 M03-01、M03-02、SYS-01 等）
@@ -124,7 +128,7 @@ $ARGUMENTS
    - 将匹配到的二级模块编号记为 `MODULE_ID`（如 `M03-02`），对应的主模块编号记为 `PARENT_MODULE`（如 `M03`）
    - 如果架构文档不存在，跳过此步骤，`MODULE_ID` 留空，输出目录不包含模块子目录
 
-5. **确定输出路径**：
+6. **确定输出路径**：
    - 输出根目录：`{OUTPUT_DIR}/`（由路径配置加载阶段解析，默认 `docs/{DESIGN_DIR}/`）
    - 如果 `MODULE_ID` 已识别（非空）：
      - 输出子目录：`{OUTPUT_DIR}/{MODULE_ID}/`（如 `docs/{DESIGN_DIR}/M03-02/`）
@@ -191,23 +195,11 @@ $ARGUMENTS
 
 #### 0.2 加载模板和约定
 
-按上表序号 2-7 依次读取必读文件。重点理解：
+按上表序号 2-4 依次读取必读文件。重点理解：
 
 - `03-系统设计模板.md`的 13 个部分结构（§1~§13 必填）及填写示例
-- **ECP 平台核心约定**：
-  - **Entity**: 继承 `BaseEntity<T>`，`@TableName` 反引号，每字段 `@TableField` + `@Schema`，主键 `Long` + `IdType.ASSIGN_ID`。**BaseEntity 已含审计字段，Entity 中禁止重复声明**
-  - **DTO**: 继承 `ReqeustCommonDataBean`（注意平台拼写），Date 字段 `@JSONField(format = "yyyy-MM-dd HH:mm:ss")`，校验分组为 DTO 内部接口
-  - **Ro**: 简单 POJO + `implements Serializable` + `serialVersionUID`，手动声明所有字段，位于 `model/entity/readonly/`
-  - **DAO**: 继承 `BaseCommonDAO_HI`，**所有 SQL 通过 MyBatis XML，禁止 QueryWrapper/LambdaQueryWrapper**
-  - **Service**: 接口 `II{Entity}`（双 I 前缀），实现 `@Component("{camel}Service")` 继承 `BaseCommonServer`
-  - **Controller**: 继承 `CommonAbstractService`，重写 `getBaseCommonServer()`，标准 5 端点，全端点 `@CheckToken`
-  - **Save 用 FastJSON**: `JSONObject.parseObject(JSONObject.toJSONString(dto), Entity.class)`
-  - **Update 用 Spring BeanUtils**: `BeanUtils.copyProperties(dto, entity, "createdBy", "creationDate", "versionNum")`
-  - **子表更新**: 先删后增策略 — `deleteBy{父}Id(id)` → `saveListBy{父}Id(id, list)`
-  - **异常在 Service 层抛出**（`RecordNotExistsException`、`GushenRuntimeException`），Controller 仅做参数空校验
-  - **错误码格式**: `{port}_{table_snake}_{三位序号}`，定义在 `ResponseMsgCode` 枚举中，**禁止硬编码字符串**
-  - **注入方式**: `@Autowired` + `@Component("{camel}Name")`
-  - **表规范**: `delete_flag` 默认 0，`version_num` 默认 0，不使用外键，主键雪花 ID
+- **核心约定**：
+  - 按照`index.md`文件约定读取相关规范
 
 ---
 
@@ -228,19 +220,19 @@ $ARGUMENTS
 
 从 PRD 业务实体中直接落地为三类对象的完整字段表：
 
-- **Entity 字段表**：Java 类型、DB 类型、长度、必填、默认值、注解、说明。审计字段继承自 BaseEntity，禁止重复声明
-- **DTO 字段表**：校验注解、必填、说明。标注 `extends ReqeustCommonDataBean`，验证分组 `save{Entity}` / `update{Entity}`
-- **Ro 字段表**：Java 类型、注解（`@DateTimeFormat` + `@JsonFormat`）、说明。标注 `implements Serializable` + `serialVersionUID`
+- **Entity 字段表**：类型、DB 类型、长度、必填、默认值、注解、说明。审计字段继承自基类（按后端规范），禁止重复声明
+- **DTO 字段表**：校验注解、必填、说明。按后端规范标注 DTO 基类与验证分组
+- **Ro 字段表**：类型、注解、说明。按后端规范定义只读视图对象的字段与序列化
 
-**每个实体标注来源需求 ID、表名（反引号）、主键（ASSIGN_ID）、索引、关联关系。**
+**每个实体标注来源需求 ID、表名、主键策略、索引、关联关系。**
 
 #### §3 数据模型（必填，设计）
 
 基于 §2 的实体定义：
 
 - 绘制 Mermaid classDiagram（标注 1:N 等关系基数）
-- 完整的 DDL 字段表（含 ECP 8 个审计字段：tenant_id / creation_date / created_by / last_update_date / last_updated_by / last_update_login / delete_flag / version_num）
-- MyBatis XML 结构（BaseResultMap、Base_Column_List、BASE_QUERY_CONDITION、findPagination，含 `WHERE delete_flag = 0`）
+- 完整的 DDL 字段表（含后端规范定义的审计字段）
+- ORM 映射结构（按后端规范，含软删除过滤条件）
 - DAO 接口定义（类路径、继承、自定义方法签名）
 
 #### §4 业务行为与 Service 设计（必填，分析→设计）
@@ -249,19 +241,19 @@ $ARGUMENTS
 - Mermaid flowchart 业务流程图
 - Mermaid stateDiagram 状态机图（如有状态流转）
 - Service 接口方法表（方法签名、入参、出参、事务标注）
-- Service 实现伪代码（save/update/delete 的关键步骤 + FastJSON/BeanUtils 转换说明）
-- 事务边界汇总表（哪些方法需 `@Transactional(rollbackFor = Exception.class)`）
+- Service 实现伪代码（save/update/delete 的关键步骤 + 对象转换策略，按后端规范）
+- 事务边界汇总表（哪些方法需事务注解，按后端规范）
 
 #### §5 接口与 Controller 设计（必填，设计）
 
 - 标准 5 端点 + 自定义端点清单（HTTP 方法、路径、说明、请求/响应包装、校验分组）
-- Controller 完整 Java 代码骨架（`@Tag`、`@RestController`、`CommonAbstractService`、`@CheckToken`、`ResponseData`）
+- Controller 完整代码骨架（含认证注解、响应包装，按后端规范）
 - 权限矩阵
 
 #### §6 枚举与数据字典（必填，分析→设计）
 
 - 枚举值定义表（枚举值、编码、显示名称、说明、使用场景），标注存储类型和类路径
-- 数据校验规则表（数据项、Java 类型、必填、取值范围、校验注解、消息码）
+- 数据校验规则表（数据项、数据类型、必填、取值范围、校验注解、消息码）
 
 #### §7 异常处理（必填，分析→设计）
 
@@ -271,8 +263,8 @@ $ARGUMENTS
 
 #### §8 缓存与性能（必填）
 
-- 仅当有明确缓存需求时填写，使用 DawnRedis + ICacheKey
-- 并发控制策略（乐观锁 version_num + 分布式锁 @Klock）
+- 仅当有明确缓存需求时填写，按后端规范选择缓存组件
+- 并发控制策略（乐观锁 + 分布式锁，按后端规范）
 
 #### §9 测试场景（必填）
 
@@ -289,15 +281,15 @@ $ARGUMENTS
 
 ### 阶段 2：生成建表 SQL
 
-按 `Liquibase 数据库变更管理规范.md` 规范生成：
+按 `docs/40-project_conventions/end-integration/index.md` 中指定的 DB 迁移规范生成：
 
-- SQL 文件头含 `--liquibase formatted sql` 和 changeset 注释
-- 每张表包含完整业务字段 + ECP 标准审计字段（8 个）
-- 每列必须带 `COMMENT`
-- `delete_flag` 默认 0，`version_num` 默认 0
-- 索引命名：`uk_{table}_{field}`（唯一）、`idx_{field}`（普通）
+- SQL 文件按后端规范的迁移格式编写（含版本控制注释）
+- 每张表包含完整业务字段 + 后端规范定义的审计字段
+- 每列必须带 `COMMENT`（或后端规范等效的字段说明方式）
+- 软删除字段和版本字段默认值按后端规范
+- 索引命名规则按后端规范
 - 不使用外键约束
-- DDL/DML 必须幂等：`CREATE TABLE IF NOT EXISTS` / `REPLACE INTO`
+- DDL/DML 必须幂等（按后端规范的幂等语法）
 
 ---
 
@@ -324,32 +316,31 @@ $ARGUMENTS
 
 - [ ] 04 号模板必填部分（§1~§9）全部覆盖
 - [ ] 需求 ID 映射表记录了 PRD 中所有 US/BR 编号
-- [ ] 所有 Entity 标注 `@TableName` 反引号 + `@TableId(type = IdType.ASSIGN_ID)`，**未重复声明 BaseEntity 审计字段**
-- [ ] DTO 标注 `extends ReqeustCommonDataBean`，校验分组为内部接口
-- [ ] Ro 标注 `implements Serializable` + `serialVersionUID`
+- [ ] 所有 Entity 按后端规范标注表名和主键策略，**未重复声明基类审计字段**
+- [ ] DTO 按后端规范标注基类和校验分组
 - [ ] 实体关系有 Mermaid classDiagram，标注关系基数
 - [ ] 核心业务流程有 Mermaid flowchart
 - [ ] 状态流转有 Mermaid stateDiagram（如有）
-- [ ] DAO 继承 `BaseCommonDAO_HI`，所有查询通过 MyBatis XML
-- [ ] Controller 继承 `CommonAbstractService`，每个方法 `@CheckToken`
-- [ ] 接口出参统一为 `ResponseData<T>`，Controller 取参用 `requestData.getParams()`
-- [ ] 错误码遵循 `{port}_{table_snake}_{三位序号}` 格式，定义在 `ResponseMsgCode` 枚举中
-- [ ] Service 方法标注是否需要 `@Transactional(rollbackFor = Exception.class)`
-- [ ] Save 用 FastJSON，Update 用 Spring BeanUtils 排除审计字段
-- [ ] 子表更新采用先删后增策略
-- [ ] 异常在 Service 层通过 `RecordNotExistsException` / `GushenRuntimeException` 抛出
+- [ ] DAO 按后端规范继承基类，所有查询通过 ORM 映射文件
+- [ ] Controller 按后端规范继承基类，每个方法含认证注解
+- [ ] 接口出参统一为后端规范的响应包装类型
+- [ ] 错误码按后端规范定义的格式和枚举类
+- [ ] Service 方法标注是否需要事务注解
+- [ ] Save/Update 按后端规范的对象转换策略执行
+- [ ] 子表更新采用先删后增策略（或后端规范等效策略）
+- [ ] 异常在 Service 层按后端规范抛出
 - [ ] 每个业务行为有业务规则（引用 BR-ID）和异常处理
-- [ ] ResponseData 使用 `ResponseMsgCode` 枚举消息码，**禁止硬编码字符串**
+- [ ] 响应使用后端规范的消息码枚举，**禁止硬编码字符串**
 - [ ] 服务名称和端口命名规范严格遵循`02-*_system_architecture.md`中的`技术架构`章节内容
 - [ ] 测试场景覆盖正常/异常/边界情况必须100%覆盖，每种至少 3 条
 
 ### 建表 SQL 检查
 
-- [ ] 文件含 `--liquibase formatted sql` 和 changeset
-- [ ] 每张表包含完整 ECP 审计字段（8 个）
-- [ ] 每列有 `COMMENT`
-- [ ] `delete_flag` 默认 0，`version_num` 默认 0
-- [ ] 索引命名符合规范（`uk_` / `idx_`）
+- [ ] 文件按后端规范的 DB 迁移格式编写
+- [ ] 每张表包含完整后端规范审计字段
+- [ ] 每列有 `COMMENT`（或后端规范等效的字段说明方式）
+- [ ] 软删除和版本字段默认值按后端规范
+- [ ] 索引命名符合后端规范
 - [ ] 无外键约束
 - [ ] DDL/DML 幂等
 
@@ -357,10 +348,9 @@ $ARGUMENTS
 
 - **按 04 号模板 §1~§10 顺序生成** — 每个部分从分析直接落地到设计，后文引用前文定义的内容，避免重复
 - **每个设计条目标注** `**来源需求**:` 引用 PRD ID（如 US-01、BR-02、FUNC-03），支撑全链路追溯
-- **严格遵循 ECP 编码规范** — 所有设计决策以 `docs/40-project_conventions/end-integration/` 中的规范文件为准
-- **禁止使用 sie-cloud 命名** — 不使用 `BaseDO`、`TenantBaseDO`、`BaseMapperX`、`LambdaQueryWrapperX`、`CommonResult<T>`、`@Resource`、`@PreAuthorize` 等术语
-- **禁止 QueryWrapper / LambdaQueryWrapper** — 所有 DB 操作设计为 MyBatis XML 实现
-- **禁止生成 Java 源码** — 仅生成设计文档和 SQL，不生成 Java 代码
+- **严格遵循项目后端规范** — 所有设计决策以 `docs/40-project_conventions/end-integration/` 中的规范文件为准
+- **模板填写示例仅作参考** — 实际设计以 `docs/40-project_conventions/end-integration/index.md` 规范为准，禁止照搬模板中的特定平台类名
+- **禁止生成源码** — 仅生成设计文档和 SQL，不生成后端源代码
 - **禁止虚构需求** — 设计内容必须来自 PRD，不自行添加未提及的功能
 - **禁止过度设计** — 简单 CRUD 不套用策略/工厂模式，选填部分仅在确需时填写
 - **文件系统操作使用绝对路径**；文档和 agent 上下文文件中的引用使用项目相对路径

package/skills/adspecs-prd/SKILL.md

@@ -185,12 +185,16 @@ $ARGUMENTS
    5. 生成功能需求
       每个需求必须是可测试的
       对未明确的细节使用合理的默认值（在假设部分记录假设）
+      按模块拆分，每个模块包含：触发条件、展示内容、操作规则、系统反馈。避免‘便捷、智能’等抽象词。涉及字段时列出名称、含义、来源
    6. 定义成功标准
+      按功能模块生成可验证的验收标准。格式：场景/操作/预期结果。覆盖正常、异常、权限、边界情况。
       创建可度量、与技术无关的成果
       包括量化指标（时间、性能、容量）和定性测量（用户满意度、任务完成率）
       每个标准必须可在不知道实现细节的情况下验证
    7. 识别关键实体（如果涉及数据）
-   8. 返回：成功（spec 可进入计划阶段）
+   8. 状态流转（待处理、处理中、已完成等）必须清晰列出进入/离开条件、触发人、前端展示、通知机制等
+   9. 异常处理表类似：异常场景、触发条件、用户可见内容、系统处理方式、重试机制、数据保存策略等
+   10. 返回：成功（spec 可进入计划阶段）
 
 7. 使用模板结构将规格说明书写入 `SPEC_FILE`，用从功能描述（参数）派生的具体细节替换占位符，同时保留章节顺序和标题。
 
@@ -216,19 +220,23 @@ $ARGUMENTS
 
    - [ ] 无 [NEEDS CLARIFICATION] 标记残留
    - [ ] 需求可测试且无歧义
-   - [ ] 成功标准可度量
-   - [ ] 成功标准与技术无关（无实现细节）
+   - [ ] 验收标准可验证可度量
+   - [ ] 验收标准与技术无关（无实现细节）
    - [ ] 所有验收场景已定义
-   - [ ] 边界情况已识别
+   - [ ] 状态流转是否完整（进入/离开/展示/通知）
+   - [ ] 异常和边界情况已识别且场景是否穷举主要情况
    - [ ] 范围界限清晰
+   - [ ] 功能描述是否具体到研发可直接实现
    - [ ] 依赖和假设已识别
+   - [ ] 权限、数据、兼容性是否说明
+   - [ ] 风险与待确认项是否列出
    - [ ] 一级模块名称和编号是否与 `docs\10-architecture\01-*_business_scenarios.md` 中对应的模块对齐一致性检查
    - [ ] 二级菜单/模块划分合理性检查
 
    ## 功能就绪
 
    - [ ] 所有功能需求有清晰的验收标准
-   - [ ] 用户场景覆盖主要流程
+   - [ ] 用户场景覆盖流程完整
    - [ ] 功能满足成功标准中定义的可度量成果
    - [ ] 无实现细节泄露到规格说明书中