@specpow/framework 0.5.22 → 0.5.24

package/builtin/schemas/mes-prd-to-code/templates/test-gen.md

@@ -0,0 +1,77 @@
+# 测试生成报告: {{changeName}}
+
+> 输入: 任务清单 (tasks.md) 中的 ServiceImpl 代码
+> 生成日期: {{date}}
+
+---
+
+## 1. 测试文件清单
+
+| # | 测试文件 | 被测类 | Mock 依赖 | 测试方法数 |
+|:-:|----------|--------|-----------|:----------:|
+| 1 | `src/test/java/{package}/XxxServiceImplMockTest.java` | XxxServiceImpl | Mapper, DetailService | N |
+
+---
+
+## 2. 测试详情
+
+### 2.1 XxxServiceImplMockTest
+
+**被测类**: `com.twsz.mom.xxx.service.impl.XxxServiceImpl`
+
+**Mock 依赖**:
+| # | 字段 | 类型 | 说明 |
+|:-:|------|------|------|
+| 1 | xxxMapper | XxxMapper | 主表 Mapper |
+| 2 | detailService | XxxDetailService | 子表 Service |
+
+**测试用例**:
+
+| # | @Nested 分组 | 方法名 | 场景 | 断言 |
+|:-:|-------------|--------|------|------|
+| 1 | saveModel方法测试 | should_insert_when_idIsNull | 新增成功 | verify(mapper).insert(any) |
+| 2 | saveModel方法测试 | should_update_when_idNotNull | 编辑成功 | verify(mapper).updateById(any) |
+| 3 | saveModel方法测试 | should_throw_when_optimisticLockFails | 乐观锁冲突 | assertThrows(BaseException) |
+| 4 | deleteByIds方法测试 | should_deleteByIds_when_givenIds | 批量删除 | verify(mapper).deleteBatchIds(any) |
+| 5 | search方法测试 | should_returnPage_when_search | 分页查询 | assertNotNull(result) |
+| 6 | list方法测试 | should_returnList_when_list | 列表查询 | assertNotNull(result) |
+
+**测试代码结构**:
+
+```java
+@ExtendWith(MockitoExtension.class)
+class XxxServiceImplMockTest {
+
+    @Mock
+    private XxxMapper xxxMapper;
+
+    @Mock
+    private XxxDetailService detailService;
+
+    @InjectMocks
+    private XxxServiceImpl xxxService;
+
+    @BeforeEach
+    void setUp() {
+        ReflectionTestUtils.setField(xxxService, "baseMapper", xxxMapper);
+    }
+
+    @Nested
+    @DisplayName("saveModel方法测试")
+    class SaveModelTests {
+        @Test
+        @DisplayName("新增成功")
+        void should_insert_when_idIsNull() { ... }
+    }
+}
+```
+
+---
+
+## 3. 统计
+
+| 维度 | 数量 |
+|------|:----:|
+| 测试文件数 | N |
+| 测试方法总数 | N |
+| Mock 依赖总数 | N |

package/builtin/schemas/prd-to-tech-doc/schema.yaml

@@ -0,0 +1,161 @@
+# PRD to Tech Doc Schema
+# 将需求文档（PRD）转换为技术文档
+# 工件流: analysis → tech-design → tech-tasks
+
+name: prd-to-tech-doc
+description: |
+  需求文档转技术文档工作流。
+  输入一份业务需求文档（PRD），输出结构化的技术设计文档和实施任务清单。
+  适用于：已有功能需求文档，需要转化为开发团队可执行的技术方案。
+
+  与 mes-crud-module 的区别：
+  - mes-crud-module：从零生成 CRUD 模块代码（模板化）
+  - prd-to-tech-doc：从需求文档出发，分析现有代码，产出技术方案（定制化）
+
+apply:
+  requires:
+    - tech-tasks    # 实施前必须完成所有工件
+
+artifacts:
+  - id: analysis
+    name: 需求分析
+    description: 解析 PRD，识别功能点、影响范围和技术约束
+    requires: []
+    template: analysis.md
+    instruction: |
+      读取用户提供的需求文档（PRD），完成以下分析：
+
+      1. 功能点提取
+         - 从 PRD 中提取所有功能点，编号列出
+         - 区分：CRUD 操作 / 业务规则 / 导入导出 / 状态流转 等类型
+         - 标注每个功能点的优先级（P0=必须 / P1=重要 / P2=可选）
+
+      2. 数据模型分析
+         - 根据 PRD 中的字段说明，推断数据库表结构
+         - 识别：实体名、表名、字段列表、字段类型、约束
+         - 识别外键关系（如有关联表）
+         - 标注审计字段（created_by, created_date, last_updated_by, last_updated_date）
+
+      3. 现有代码扫描
+         - 搜索项目中是否已有相关代码（实体、表、接口、页面）
+         - 如果已有：标注哪些可以直接复用，哪些需要修改
+         - 如果没有：标注需要新建
+         - 使用 codegraph_explore 查找相关符号
+
+      4. 技术约束识别
+         - 项目技术栈约束（Spring Boot 2.7 / MyBatis-Plus / Oracle / Vue2 / ViewUI）
+         - 编码规范约束（BaseModel 继承、ResponseWrapper 响应、LambdaQueryWrapper 等）
+         - 与现有模块的集成点（如本功能被哪些模块消费）
+
+      5. 影响范围
+         - 受影响的后端模块（modules-center 下的哪个 center）
+         - 受影响的前端目录（views/ 和 api/ 下的路径）
+         - 受影响的数据库 schema
+
+      输出格式：结构化的分析报告，包含以上 5 个部分。
+    output: analysis.md
+
+  - id: tech-design
+    name: 技术设计
+    description: 数据库设计 + API 设计 + 代码结构设计 + 业务逻辑流程
+    requires: [analysis]
+    template: tech-design.md
+    instruction: |
+      基于需求分析报告，生成完整的技术设计文档。
+
+      1. 数据库设计
+         - 表结构 DDL（Oracle 语法）
+         - 字段类型映射规则：
+           - 文本 → VARCHAR2(n)
+           - 数字（整数）→ NUMBER(19) 或 NUMBER(10)
+           - 数字（小数）→ NUMBER(19,4)
+           - 日期 → DATE 或 TIMESTAMP
+           - 开关 → NUMBER(1) DEFAULT 1
+         - 主键: id NUMBER(19) 雪花算法（ASSIGN_ID）
+         - 审计字段: created_by, created_date, last_updated_by, last_updated_date
+         - 索引建议
+         - 如使用 dbx MCP 工具，优先通过 dbx 建表
+
+      2. API 接口设计
+         - 接口清单表（Method / Path / 描述 / 请求体 / 响应体）
+         - MES 项目标准接口模式：
+           - POST /{entity}/search — 分页查询（PageForm<Entity>）
+           - POST /{entity}/add — 新增（或 POST /{entity}/save 统一保存）
+           - PUT /{entity}/update — 修改
+           - DELETE /{entity}/delete — 批量删除
+           - POST /{entity}/export — Excel 导出
+           - POST /{entity}/uploadExcel — Excel 导入（如有）
+         - 响应统一使用 ResponseWrapper<T>
+         - 每个接口给出请求示例和响应示例（JSON）
+
+      3. 后端代码结构
+         - Entity 类设计（继承 BaseModel，字段注解）
+         - Mapper 接口 + XML 设计（resultMap/resultType、查询条件）
+         - Service 接口设计（方法签名、返回值）
+         - ServiceImpl 关键逻辑（校验、唯一性、事务）
+         - Controller 设计（路径、方法、参数校验）
+         - 给出每个类的关键代码模板
+
+      4. 前端代码结构
+         - API 文件（src/api/{domain}/{entity}.js）
+         - 列表页（index.vue — search-table + indexPage mixin）
+         - 表单页（{entity}-form.vue — master-sub + Form）
+         - 给出关键配置（表格列定义、表单字段、校验规则）
+
+      5. 业务逻辑流程
+         - 用流程图（ASCII）描述核心业务流程
+         - 标注校验点和异常处理
+         - 如有状态流转，画出状态机
+
+      6. 集成点
+         - 本模块被哪些其他模块调用
+         - 需要暴露哪些 Feign 接口
+         - 需要注册哪些菜单权限
+
+      注意：
+      - 代码模板必须匹配 MES 项目的真实编码规范
+      - 实体继承 BaseModel，使用 @Data + @TableName
+      - Mapper XML 位于 resources/mapper/{module}/ 目录
+      - 前端组件使用 View Design 4 组件库
+    output: tech-design.md
+
+  - id: tech-tasks
+    name: 实施任务
+    description: 可执行的技术实施任务清单（SDD 引擎可逐个执行）
+    requires: [analysis, tech-design]
+    template: tech-tasks.md
+    instruction: |
+      基于技术设计文档，拆分为可执行的实施任务列表。
+
+      任务拆分原则：
+      1. 每个任务足够小（2-5 分钟完成）
+      2. 包含精确的文件路径
+      3. 包含完整的代码或明确的修改指令
+      4. 包含验证步骤
+      5. 任务之间尽量独立（便于 SDD 并行）
+
+      任务顺序约定：
+      1. 数据库建表（DDL）
+      2. 后端 Entity
+      3. 后端 Mapper + XML
+      4. 后端 Service 接口
+      5. 后端 ServiceImpl
+      6. 后端 Controller
+      7. 前端 API 文件
+      8. 前端列表页
+      9. 前端表单页
+      10. 菜单注册 SQL
+
+      每个任务格式：
+      - [ ] Task N: <标题>
+        文件: <精确路径>
+        描述: <具体实现指令，包含代码模板>
+        验证: <如何验证>
+        依赖: Task-X（如有）
+
+      注意：
+      - 如果需求文档中有导入功能，增加 uploadExcel 相关任务
+      - 如果需求文档中有导出功能，增加 export 相关任务
+      - 如果有状态流转，增加状态操作接口任务
+      - 使用 dbx MCP 建表时，在建表任务中标注
+    output: tech-tasks.md

package/builtin/schemas/prd-to-tech-doc/templates/analysis.md

@@ -0,0 +1,133 @@
+# 需求分析: <功能名称>
+
+> 输入: <PRD 文档路径>
+> 分析日期: <日期>
+
+---
+
+## 1. 功能点提取
+
+| 编号 | 功能点 | 类型 | 优先级 | PRD 章节 | 说明 |
+|:----:|--------|------|:------:|----------|------|
+| F-01 | | CRUD / 业务规则 / 导入导出 / 状态流转 | P0/P1/P2 | | |
+| F-02 | | | | | |
+
+### 功能点说明
+
+#### F-01: <功能名称>
+
+- **描述**: <做什么>
+- **触发条件**: <何时触发>
+- **处理逻辑**: <如何处理>
+- **输出结果**: <产生什么>
+
+---
+
+## 2. 数据模型分析
+
+### 2.1 实体识别
+
+| 实体名 | 表名 | 类型 | 说明 |
+|--------|------|------|------|
+| | | 主表 / 子表 / 字典 / 关联表 | |
+
+### 2.2 字段清单
+
+#### 实体: <EntityName>
+
+| 字段名 | 中文名 | 类型 | 必填 | 默认值 | 约束 | 说明 |
+|--------|--------|------|:----:|--------|------|------|
+| id | 主键 | Long | ✅ | 雪花算法 | PK | |
+| | | | | | | |
+
+**审计字段**（自动填充）:
+- created_by, created_date, last_updated_by, last_updated_date
+
+### 2.3 表关系
+
+```
+<表关系图（ASCII）>
+```
+
+---
+
+## 3. 现有代码扫描
+
+### 3.1 已有代码
+
+| 组件 | 路径 | 状态 | 说明 |
+|------|------|:----:|------|
+| Entity | | 已有 / 需新建 / 需修改 | |
+| Mapper | | | |
+| Service | | | |
+| Controller | | | |
+| 前端 API | | | |
+| 前端页面 | | | |
+
+### 3.2 可复用部分
+
+- <列出可以直接复用的代码>
+
+### 3.3 需要新建/修改的部分
+
+- <列出需要新增或修改的代码>
+
+---
+
+## 4. 技术约束
+
+| 维度 | 约束 | 来源 |
+|------|------|------|
+| 技术栈 | Spring Boot 2.7 / MyBatis-Plus / Oracle / Vue2 / ViewUI | 项目规范 |
+| 实体基类 | 继承 BaseModel | CLAUDE.md |
+| 响应格式 | ResponseWrapper<T> | CLAUDE.md |
+| 查询方式 | LambdaQueryWrapper | CLAUDE.md |
+| 编号生成 | @AutoGenCode（如为单据） | 项目规范 |
+| 前端组件 | search-table + indexPage / master-sub | 项目规范 |
+| 数据库操作 | dbx MCP（优先） / SQL 脚本 | 项目规范 |
+
+---
+
+## 5. 影响范围
+
+### 5.1 后端影响
+
+| 模块 | 路径 | 影响说明 |
+|------|------|----------|
+| | modules-center/{module}-center/ | |
+
+### 5.2 前端影响
+
+| 目录 | 路径 | 影响说明 |
+|------|------|----------|
+| API | src/api/{domain}/ | |
+| 页面 | src/views/{domain}/ | |
+
+### 5.3 数据库影响
+
+| Schema | 操作 | 说明 |
+|--------|------|------|
+| | 新建表 / 修改表 | |
+
+### 5.4 集成点
+
+| 集成方 | 方式 | 说明 |
+|--------|------|------|
+| | Feign / 直接调用 / 消息 | |
+
+---
+
+## 6. 风险与疑问
+
+| 编号 | 类型 | 描述 | 建议 |
+|:----:|------|------|------|
+| R-01 | 风险 / 疑问 | | |
+
+---
+
+## 7. 结论
+
+- **新建实体数**: 
+- **新建接口数**: 
+- **新建页面数**: 
+- **预估任务数**: 

package/builtin/schemas/prd-to-tech-doc/templates/tech-design.md

@@ -0,0 +1,263 @@
+# 技术设计: <功能名称>
+
+> 输入: 需求分析报告 (analysis.md)
+> 设计日期: <日期>
+
+---
+
+## 1. 数据库设计
+
+### 1.1 表结构
+
+#### 表: <table_name>
+
+```sql
+CREATE TABLE <table_name> (
+    id              NUMBER(19)      NOT NULL,
+    -- 业务字段
+    <column>        <type>          <constraint>,
+    -- 审计字段
+    created_by      VARCHAR2(64),
+    created_date    DATE            DEFAULT SYSDATE,
+    last_updated_by VARCHAR2(64),
+    last_updated_date DATE          DEFAULT SYSDATE,
+    CONSTRAINT pk_<table_name> PRIMARY KEY (id)
+);
+
+COMMENT ON TABLE <table_name> IS '<表中文名>';
+COMMENT ON COLUMN <table_name>.id IS '主键';
+-- 其他字段注释
+```
+
+**索引**:
+
+| 索引名 | 字段 | 类型 | 说明 |
+|--------|------|------|------|
+| | | UNIQUE / NORMAL | |
+
+**数据库操作方式**:
+- [ ] 优先使用 dbx MCP 工具建表
+- [ ] 备选: 执行 SQL 脚本
+
+---
+
+## 2. API 接口设计
+
+### 2.1 接口清单
+
+| # | Method | Path | 描述 | 请求体 | 响应体 |
+|:-:|--------|------|------|--------|--------|
+| 1 | POST | `/{entity}/search` | 分页查询 | PageForm<Entity> | Page<Entity> |
+| 2 | POST | `/{entity}/add` | 新增 | Entity | — |
+| 3 | PUT | `/{entity}/update` | 修改 | Entity | — |
+| 4 | DELETE | `/{entity}/delete` | 批量删除 | Long[] ids | — |
+| 5 | POST | `/{entity}/export` | 导出 Excel | Entity | file |
+| 6 | POST | `/{entity}/uploadExcel` | 导入 Excel | file | — |
+
+### 2.2 接口详情
+
+#### API-1: 分页查询
+
+- **路径**: `POST /{entity}/search`
+- **描述**: 分页查询<实体>列表
+- **请求体**:
+```json
+{
+    "size": 20,
+    "current": 1,
+    "condition": {
+        "<field1>": "<value>"
+    }
+}
+```
+- **响应体**:
+```json
+{
+    "code": 200,
+    "message": "success",
+    "data": {
+        "records": [...],
+        "total": 100,
+        "size": 20,
+        "current": 1
+    }
+}
+```
+
+<!-- 按需补充其他接口详情 -->
+
+---
+
+## 3. 后端代码结构
+
+### 3.1 Entity
+
+**路径**: `modules-center/{module}-center/{module}-service/src/main/java/com/twsz/mom/{module}/{sub}/model/{Entity}.java`
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = false)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@TableName("<table_name>")
+public class {Entity} extends BaseModel implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @TableId(type = IdType.ASSIGN_ID)
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long id;
+
+    // 业务字段（含 @ExcelProperty 注解）
+}
+```
+
+### 3.2 Mapper
+
+**接口路径**: `.../{module}/mapper/{Entity}Mapper.java`
+**XML 路径**: `resources/mapper/{module}/{Entity}Mapper.xml`
+
+```java
+@Mapper
+public interface {Entity}Mapper extends BaseMapper<{Entity}> {
+    IPage<{Entity}> pageSearch(Page<{Entity}> p, @Param("entity") {Entity} entity);
+    List<{Entity}> list(@Param("entity") {Entity} entity);
+}
+```
+
+**XML 关键片段**:
+- `<sql id="Columns">` — 字段列表
+- `<sql id="Where">` — 查询条件
+- `pageSearch` — 分页查询
+- `list` — 不分页列表
+
+### 3.3 Service
+
+**接口路径**: `.../{module}/service/{Entity}Service.java`
+
+```java
+public interface {Entity}Service extends IService<{Entity}> {
+    ResponseWrapper<?> insert({Entity} entity);
+    ResponseWrapper<String> update({Entity} entity);
+    ResponseWrapper<String> deleteByIds(Collection<BigDecimal> ids);
+    ResponseWrapper<Page<{Entity}>> search(PageForm<{Entity}> pageForm);
+    List<{Entity}> list({Entity} entity);
+}
+```
+
+### 3.4 ServiceImpl
+
+**路径**: `.../{module}/service/impl/{Entity}ServiceImpl.java`
+
+关键逻辑:
+- `insert()`: 校验唯一性等
+- `update()`: 校验存在性 + 唯一性
+- `deleteByIds()`: 批量删除
+- `search()`: 分页查询
+
+### 3.5 Controller
+
+**路径**: `.../{module}/controller/{Entity}Controller.java`
+
+```java
+@RestController
+@RequestMapping("/api/{api-path}/{entity}")
+public class {Entity}Controller {
+
+    @PostMapping("/search")
+    public ResponseWrapper<Page<{Entity}>> search(@RequestBody PageForm<{Entity}> pageForm) { ... }
+
+    @PostMapping("/add")
+    public ResponseWrapper<?> add(@RequestBody {Entity} entity) { ... }
+
+    @PutMapping("/update")
+    public ResponseWrapper<String> update(@RequestBody {Entity} entity) { ... }
+
+    @DeleteMapping("/delete")
+    public ResponseWrapper<String> delete(@RequestBody Collection<BigDecimal> ids) { ... }
+
+    @PostMapping("/export")
+    public void export(@RequestBody {Entity} entity, HttpServletResponse response) { ... }
+
+    @PostMapping("/uploadExcel")
+    public ResponseWrapper<?> uploadExcel(@RequestParam("file") MultipartFile file) { ... }
+}
+```
+
+---
+
+## 4. 前端代码结构
+
+### 4.1 API 文件
+
+**路径**: `src/api/{domain}/{entity}.js`
+
+```javascript
+import axios from '@/libs/request'
+import { exportExcel } from '../file'
+const root = '/mm/api'  // 根据实际微服务调整
+
+// search, add, update, delete, export, uploadExcel
+```
+
+### 4.2 列表页
+
+**路径**: `src/views/{domain}/{entity}/index.vue`
+
+- 组件: `search-table` + `indexPage` mixin
+- 搜索条件: <列出搜索字段>
+- 表格列: <列出列定义>
+- 工具栏: 新增 / 编辑 / 查看 / 删除 / 导出 / 导入
+
+### 4.3 表单页
+
+**路径**: `src/views/{domain}/{entity}/{entity}-form.vue`
+
+- 组件: `master-sub`
+- 表单字段: <列出字段及校验规则>
+- 提交逻辑: 判断新增/编辑 → 调用对应 API
+
+---
+
+## 5. 业务逻辑流程
+
+### 5.1 核心流程
+
+```
+<ASCII 流程图>
+```
+
+### 5.2 校验规则
+
+| 编号 | 校验项 | 规则 | 错误提示 |
+|:----:|--------|------|----------|
+| V-01 | | | |
+
+### 5.3 状态流转（如有）
+
+```
+<状态机图>
+```
+
+---
+
+## 6. 集成点
+
+### 6.1 被调用方
+
+| 调用方 | 接口方式 | 说明 |
+|--------|----------|------|
+| | | |
+
+### 6.2 菜单权限
+
+| 菜单名 | 权限标识 | 类型 |
+|--------|----------|------|
+| | | 路由 / 按钮 / API |
+
+---
+
+## 7. 设计决策记录
+
+| 决策 | 选项 | 结论 | 原因 |
+|------|------|------|------|
+| | | | |