@specpow/framework 0.5.21 → 0.5.23

package/builtin/schemas/mes-crud-module/schema.yaml

@@ -0,0 +1,158 @@
+# MES CRUD Module Schema
+# 基于 MES 项目（mom-master + implat-ui）真实代码模式定制
+# 工件流: proposal → specs → design → tasks → api-docs → menu-register → apply
+
+name: mes-crud-module
+description: |
+  MES 系统专属 CRUD 模块生成器。
+  基于 mom-master（Spring Boot + MyBatis-Plus + Oracle）后端
+  和 implat-ui（Vue2 + ViewUI + VXETable）前端的真实代码模式。
+  生成的代码直接匹配项目约定，无需二次适配。
+
+apply:
+  requires:
+    - tasks    # 实施前必须完成所有工件
+
+artifacts:
+  - id: proposal
+    name: 模块提案
+    description: 描述要生成的 CRUD 模块（实体、字段、业务规则）
+    requires: []
+    template: proposal.md
+    instruction: |
+      根据用户描述，生成 MES CRUD 模块提案。
+      包含：模块名称、所属业务中心（modules-center）、核心实体、表名、
+      CRUD 操作列表、字段清单、业务规则。
+
+      注意 MES 项目约定：
+      - 后端位于 modules-center/{module}-center/
+      - 包名: com.twsz.mom.{module}
+      - 实体继承 BaseModel（雪花 ID + 审计字段自动填充）
+      - 表名使用下划线命名，可选模块前缀
+      - 状态字段统一用 is_effect (1=启用, 0=停用)
+    output: proposal.md
+
+  - id: specs
+    name: 接口规范
+    description: 定义 MES 标准 CRUD 接口行为契约
+    requires: [proposal]
+    template: spec.md
+    instruction: |
+      创建 MES 标准 CRUD 接口规范。使用 Delta Spec 格式。
+
+      MES 项目接口约定（必须遵守）：
+      - POST /{entity}/search — 分页查询（请求体: PageForm<{Entity}>）
+      - POST /{entity}/add — 新增（请求体: Entity）
+      - PUT /{entity}/update — 修改（请求体: Entity）
+      - DELETE /{entity}/delete — 批量删除（请求体: Long[] ids）
+      - GET /{entity}/get/{id} — 详情查询
+      - POST /{entity}/list — 不分页列表（请求体: Entity）
+      - POST /{entity}/export — Excel 导出（EasyExcel）
+
+      响应统一使用 ResponseWrapper<T>。
+      分页使用 PageForm<T>（size + current + condition）。
+
+      前端接口约定：
+      - API 文件位于 src/api/{domain}/{entity}.js
+      - 使用 import axios from '@/libs/request'
+      - search 发送 { size, current, condition } 接收 { records, total }
+      - delete 传 ID 数组（支持批量）
+
+      规范是行为契约，描述系统做什么，不描述怎么做。
+      每个需求必须可验证（Given/When/Then）。
+    output: specs/{{entity}}/spec.md
+
+  - id: design
+    name: 模块设计
+    description: 数据库表设计 + 前后端代码结构 + 接口定义
+    requires: [proposal, specs]
+    template: design.md
+    instruction: |
+      创建 MES CRUD 模块设计文档。包含：
+
+      1. 数据库设计（Oracle）
+         - 表结构（遵循 BaseModel 审计字段约定）
+         - 主键: id NUMBER(19) 雪花算法
+         - 审计字段: created_by, created_date, last_updated_by, last_updated_date
+         - 状态字段: is_effect NUMBER(1) DEFAULT 1
+
+      2. 后端代码结构
+         - Entity: 继承 BaseModel，@TableName，@Data
+         - Mapper: 继承 BaseMapper<T>，XML 含 Columns/Where/Joins 片段
+         - Service: 继承 IService<T>
+         - ServiceImpl: 继承 ServiceImpl<Mapper, Entity>
+         - Controller: @RestController，返回 ResponseWrapper<T>
+
+      3. 前端代码结构
+         - API: src/api/{domain}/{entity}.js
+         - 列表页: src/views/{domain}/{entity}/index.vue（indexPage mixin + search-table）
+         - 表单页: src/views/{domain}/{entity}/{entity}-form.vue（master-sub + BaseMixin）
+
+      4. 接口定义表
+
+      如果变更较小（< 3 个文件），可以跳过此工件。
+    output: design.md
+    conditional: true
+
+  - id: tasks
+    name: 任务列表
+    description: 按 MES 项目约定拆分的实现任务（SDD 引擎逐个执行）
+    requires: [proposal, specs, design]
+    template: tasks.md
+    instruction: |
+      创建 MES CRUD 模块实现任务列表。每个任务应：
+      1. 包含精确的文件路径（匹配项目包结构）
+      2. 包含完整的代码模板或明确的修改指令
+      3. 包含验证步骤
+      4. 任务之间尽量独立（便于 SDD 并行）
+
+      MES 后端任务顺序：
+      1. 建表 SQL（Oracle 语法）
+      2. Entity 实体类（继承 BaseModel）
+      3. Mapper 接口 + XML（含 Columns/Where/Joins 片段）
+      4. Service 接口 + 实现
+      5. Controller
+
+      MES 前端任务顺序：
+      6. API 接口文件
+      7. 列表页（index.vue + indexPage mixin）
+      8. 表单页（{entity}-form.vue + master-sub）
+      9. 菜单注册（c_sys_resource SQL）
+
+      格式：
+      - [ ] Task N: <标题>
+        <详细描述，包含精确文件路径和代码>
+        验证: <如何验证>
+    output: tasks.md
+
+  - id: api-docs
+    name: API 接口文档
+    description: MES 标准 RESTful 接口文档（含请求/响应示例）
+    requires: [design]
+    template: api-docs.md
+    instruction: |
+      生成 MES 标准 API 接口文档：
+      - 接口概览表
+      - 每个接口的请求参数和响应示例（JSON 格式）
+      - 使用 ResponseWrapper 包装格式
+      - PageForm 分页请求格式
+      - 通用错误码说明（使用 HttpStatus 枚举）
+    output: api-docs.md
+
+  - id: menu-register
+    name: 菜单注册
+    description: c_sys_resource 表菜单 + 按钮权限注册 SQL
+    requires: [tasks]
+    template: menu-register.md
+    instruction: |
+      生成 MES 菜单注册配置：
+      - c_sys_resource 表 INSERT 语句（菜单 + 按钮权限）
+      - 前端路由配置参考
+      - 权限标识约定: {module}:{entity}:{action}
+
+      MES 菜单注册约定：
+      - type=1 路由菜单, type=2 按钮权限, type=3 API 资源
+      - component 字段为 Vue 组件路径（如 "pm/entity/index"）
+      - permission 字段为权限标识（如 "pm:entity:add"）
+      - 路由由后端动态返回，前端通过 addRoutes 注册
+    output: menu-register.md

package/builtin/schemas/mes-crud-module/templates/api-docs.md

@@ -0,0 +1,238 @@
+# MES API 接口文档: {{Entity}}
+
+> 模块: {{module}} | 实体: {{Entity}} | 基础路径: `/{{entity}}`
+> 响应格式: `ResponseWrapper<T>` | 分页格式: `PageForm<T>`
+
+---
+
+## 接口概览
+
+| Method | Path | 描述 | 认证 |
+|--------|------|------|------|
+| POST | `/{{entity}}/search` | 分页查询 | 需要 |
+| GET | `/{{entity}}/get/{id}` | 详情查询 | 需要 |
+| POST | `/{{entity}}/add` | 新增 | 需要 |
+| PUT | `/{{entity}}/update` | 修改 | 需要 |
+| DELETE | `/{{entity}}/delete` | 批量删除 | 需要 |
+| POST | `/{{entity}}/list` | 不分页列表 | 需要 |
+| POST | `/{{entity}}/export` | Excel 导出 | 需要 |
+
+---
+
+## 1. 分页查询
+
+**请求**: `POST /{{entity}}/search`
+
+**请求体** (`PageForm<{{Entity}}>`):
+```json
+{
+  "size": 20,
+  "current": 1,
+  "condition": {
+    "isEffect": 1
+  }
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| size | number | 否 | 每页条数，默认 20 |
+| current | number | 否 | 页码，默认 1 |
+| condition | object | 否 | 查询条件（实体字段） |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "records": [
+      {
+        "id": "1234567890123456789",
+        "isEffect": 1,
+        "createdBy": "admin",
+        "createdDate": "2025/01/01 00:00:00",
+        "lastUpdatedBy": "admin",
+        "lastUpdatedDate": "2025/01/01 00:00:00"
+      }
+    ],
+    "total": 100,
+    "size": 20,
+    "current": 1
+  }
+}
+```
+
+> **注意**: id 为 Long 类型，序列化为字符串（`@JsonSerialize(using = ToStringSerializer.class)`）避免 JS 精度丢失。
+
+---
+
+## 2. 详情查询
+
+**请求**: `GET /{{entity}}/get/{id}`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | number | 是 | 记录 ID（路径参数） |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "id": "1234567890123456789",
+    "isEffect": 1,
+    "createdBy": "admin",
+    "createdDate": "2025/01/01 00:00:00",
+    "lastUpdatedBy": "admin",
+    "lastUpdatedDate": "2025/01/01 00:00:00"
+  }
+}
+```
+
+---
+
+## 3. 新增
+
+**请求**: `POST /{{entity}}/add`
+
+**请求体**:
+```json
+{
+  "isEffect": 1
+}
+```
+
+> id、createdBy、createdDate、lastUpdatedBy、lastUpdatedDate 由系统自动填充，无需传入。
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": null
+}
+```
+
+---
+
+## 4. 修改
+
+**请求**: `PUT /{{entity}}/update`
+
+**请求体**:
+```json
+{
+  "id": "1234567890123456789",
+  "isEffect": 1
+}
+```
+
+> lastUpdatedBy、lastUpdatedDate 由系统自动更新。
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": null
+}
+```
+
+---
+
+## 5. 批量删除
+
+**请求**: `DELETE /{{entity}}/delete`
+
+**请求体**:
+```json
+[1, 2, 3]
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| body | Long[] | 是 | 待删除记录 ID 数组 |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": null
+}
+```
+
+---
+
+## 6. 不分页列表
+
+**请求**: `POST /{{entity}}/list`
+
+**请求体**:
+```json
+{
+  "isEffect": 1
+}
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": [
+    { "id": "1234567890123456789", "isEffect": 1 }
+  ]
+}
+```
+
+> 默认限制最多返回 10000 条（可通过 entity.rowNum 覆盖）。
+
+---
+
+## 7. Excel 导出
+
+**请求**: `POST /{{entity}}/export`
+
+**请求体**: 同查询条件（实体字段）
+
+**响应**: Excel 文件流（`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`）
+
+---
+
+## 通用错误码（HttpStatus 枚举）
+
+| 错误码 | 常量名 | 说明 |
+|--------|--------|------|
+| 200 | SUCCESS | 操作成功 |
+| 600 | ERROR | 系统错误 |
+| 601 | UNAUTHORIZED | 未认证 |
+| 608 | PARAM_NULL | 参数为空 |
+| 620 | OBJECT_EXIST | 对象已存在 |
+| 621 | OBJECT_INSERT_FAIL | 新增失败 |
+| 622 | OBJECT_UPDATE_FAIL | 修改失败 |
+| 623 | OBJECT_DELETE_FAIL | 删除失败 |
+| 634 | OBJECT_NOT_EXIST | 对象不存在 |
+
+**错误响应格式**:
+```json
+{
+  "code": 621,
+  "message": "新增失败",
+  "data": null
+}
+```
+
+---
+
+## ResponseWrapper 结构
+
+```java
+{
+  "code": 200,          // int — HttpStatus 枚举值
+  "message": "操作成功", // String — 提示信息
+  "data": T              // 泛型 — 业务数据
+}
+```