@specpow/framework 0.5.21 → 0.5.23

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

@@ -0,0 +1,310 @@
+# 技术设计: <功能名称>
+
+> 输入: 解析报告 (parse.md) + 确认结果 (confirm-scope)
+> 设计日期: <日期>
+> 版本: v1.0
+
+---
+
+## 0. 确认结果
+
+| 维度 | 确认值 |
+|------|--------|
+| 项目根目录 | <绝对路径> |
+| 实施范围 | <模块列表> |
+| 后端 center | modules-center/{module}-center |
+| 后端包路径 | com.twsz.mom.{module}.{sub} |
+| 前端 API 目录 | src/api/{domain}/ |
+| 前端页面目录 | src/views/{domain}/{entity}/ |
+| 编号生成 | @AutoGenCode / 无 |
+| 状态流转 | 有(审核/弃审) / 无 |
+| 已有代码影响 | <列表或无> |
+
+---
+
+## 1. 数据库设计
+
+### 1.1 新建表
+
+#### 表: <table_name>
+
+```sql
+CREATE TABLE <table_name> (
+    id                NUMBER(19)      NOT NULL,
+    -- 业务字段
+    <column_name>     <oracle_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 脚本执行
+
+### 1.2 修改表（如有）
+
+#### 表: <existing_table_name>
+
+```sql
+ALTER TABLE <existing_table_name> ADD (
+    <new_column> <oracle_type> <constraint>
+);
+
+COMMENT ON COLUMN <existing_table_name>.<new_column> IS '<说明>';
+```
+
+---
+
+## 2. API 接口设计
+
+### 2.1 标准 CRUD 接口
+
+> 完整路径前缀: `/api/<api-path>/<entity>`
+
+| # | 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 | MultipartFile | — |
+
+### 2.2 外部接口（如有）
+
+| # | Method | Path | 调用方 | 描述 |
+|:-:|--------|------|--------|------|
+| E-1 | | | | |
+
+### 2.3 接口详情
+
+#### API-1: 分页查询
+
+- **路径**: `POST /api/<api-path>/<entity>/search`
+- **请求体**:
+```json
+{
+    "size": 20,
+    "current": 1,
+    "condition": {}
+}
+```
+- **响应体**:
+```json
+{
+    "code": 200,
+    "message": "success",
+    "data": {
+        "records": [],
+        "total": 0,
+        "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 关键片段**:
+```xml
+<sql id="Columns">
+    id, <业务字段>, created_by, created_date, last_updated_by, last_updated_date
+</sql>
+
+<sql id="Where">
+    <where>
+        <if test="entity.xxx != null and entity.xxx != ''">
+            AND xxx = #{entity.xxx}
+        </if>
+    </where>
+</sql>
+```
+
+### 3.3 Service
+
+**接口**: `.../{module}/service/{Entity}Service.java`
+
+```java
+public interface {Entity}Service extends IService<{Entity}> {
+    // <方法签名>
+}
+```
+
+**关键业务逻辑**:
+
+```
+insert({Entity} entity):
+    1. <校验规则描述>
+    2. <校验通过> → baseMapper.insert(entity)
+
+uploadExcel(List<{Entity}> list):
+    @Transactional(rollbackFor = Exception.class)
+    1. <导入校验描述>
+    2. 逐行 insert
+```
+
+### 3.4 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) { ... }
+
+    // <其他方法>
+}
+```
+
+---
+
+## 4. 前端代码结构
+
+### 4.1 API 文件
+
+**路径**: `src/api/{domain}/{entity}.js`
+
+```javascript
+import axios from '@/libs/request'
+import { exportExcel } from '../file'
+const root = '/<gateway-prefix>/api'
+
+// <API 方法列表>
+```
+
+### 4.2 列表页
+
+**路径**: `src/views/{domain}/{entity}/index.vue`
+
+- **Mixin**: `indexPage`
+- **搜索条件**:
+
+| 字段 | 控件 | 说明 |
+|------|------|------|
+| | Input / Select / DatePicker | |
+
+- **表格列**:
+
+| 列名 | key | slot | 说明 |
+|------|-----|------|------|
+| ☐ | selection | — | 复选框 |
+| | | | |
+| 操作 | — | operate | 编辑/查看/删除 |
+
+- **工具栏**: 新增 ✅ | 编辑 ✅ | 查看 ✅ | 删除 ✅ | 导出 ✅ | 导入 ✅
+
+### 4.3 表单页
+
+**路径**: `src/views/{domain}/{entity}/{entity}-form.vue`
+
+- **组件**: `master-sub`
+- **表单字段**:
+
+| 字段 | 控件 | 必填 | 校验规则 | 说明 |
+|------|------|:----:|----------|------|
+| | Input / Select / iSwitch / DatePicker | | | |
+
+- **提交逻辑**: 判断新增/编辑 → 调用 add/update API
+
+---
+
+## 5. 业务逻辑流程
+
+### 5.1 核心操作流程
+
+```
+<ASCII 流程图>
+```
+
+### 5.2 校验规则汇总
+
+| 编号 | 校验项 | 规则 | 错误提示 | 校验位置 |
+|:----:|--------|------|----------|----------|
+| V-01 | | | | 前端 + 后端 |
+
+### 5.3 状态流转（如有）
+
+```
+<状态机图>
+```
+
+---
+
+## 6. 集成点
+
+### 6.1 被调用方
+
+| 调用方 | 接口方式 | 说明 |
+|--------|----------|------|
+| | | |
+
+### 6.2 菜单权限
+
+| 菜单名 | 权限标识 | 类型 |
+|--------|----------|------|
+| | | 路由 / 按钮 / API |
+
+---
+
+## 7. 设计决策记录
+
+| 决策 | 选项 | 结论 | 原因 |
+|------|------|------|------|
+| | | | |

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. 结论
+
+- **新建实体数**: 
+- **新建接口数**: 
+- **新建页面数**: 
+- **预估任务数**: