@specpow/framework 0.5.21 → 0.5.23

package/builtin/schemas/mes-crud-module/templates/design.md

@@ -0,0 +1,422 @@
+# MES CRUD 模块设计: {{Entity}}
+
+> 模块: {{module}} | 业务中心: {{module}}-center | 表: {{table_name}}
+
+---
+
+## 1. 数据库设计（Oracle）
+
+### 建表 SQL
+
+```sql
+CREATE TABLE {{table_name}} (
+  id                    NUMBER(19)      NOT NULL,
+  -- ============================================================
+  -- 业务字段（根据提案中的字段清单补充）
+  -- ============================================================
+  is_effect             NUMBER(1)       DEFAULT 1,
+  -- ============================================================
+  -- 审计字段（BaseModel / TimeModel 自动填充）
+  -- ============================================================
+  created_by            VARCHAR2(64)    DEFAULT '',
+  created_date          TIMESTAMP       DEFAULT SYSTIMESTAMP,
+  last_updated_by       VARCHAR2(64)    DEFAULT '',
+  last_updated_date     TIMESTAMP       DEFAULT SYSTIMESTAMP,
+  -- ============================================================
+  CONSTRAINT pk_{{table_name}} PRIMARY KEY (id)
+);
+
+COMMENT ON TABLE {{table_name}} IS '{{table_comment}}';
+-- COMMENT ON COLUMN {{table_name}}.xxx IS 'xxx';
+
+-- 雪花算法 ID 序列（可选，若由应用层生成则不需要）
+-- CREATE SEQUENCE seq_{{table_name}} START WITH 1 INCREMENT BY 1 NOCACHE;
+```
+
+---
+
+## 2. 后端代码结构
+
+### 目录布局
+
+```
+modules-center/{{module}}-center/{{module}}-service/
+└── src/main/java/com/twsz/mom/{{module}}/
+    ├── controller/
+    │   └── {{Entity}}Controller.java
+    ├── service/
+    │   ├── {{Entity}}Service.java
+    │   └── impl/
+    │       └── {{Entity}}ServiceImpl.java
+    ├── mapper/
+    │   └── {{Entity}}Mapper.java
+    └── model/
+        └── {{Entity}}.java
+
+└── src/main/resources/
+    └── mapper/
+        └── {{Entity}}Mapper.xml
+```
+
+### Entity（继承 BaseModel）
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@TableName("{{table_name}}")
+public class {{Entity}} extends BaseModel {
+    // 业务字段（审计字段由 BaseModel → TimeModel 提供）
+    private Integer isEffect;
+    // ... 根据提案补充
+}
+```
+
+> **BaseModel 继承链**: `ViewModel`（fields/columns/orderBy/动态查询）→ `TimeModel`（审计字段自动填充）→ `BaseModel`（id 雪花算法）
+
+### Mapper（继承 BaseMapper）
+
+```java
+@Mapper
+public interface {{Entity}}Mapper extends BaseMapper<{{Entity}}> {
+    IPage<{{Entity}}> pageSearch(Page<{{Entity}}> page, @Param("entity") {{Entity}} entity);
+    List<{{Entity}}> list(@Param("entity") {{Entity}} entity);
+}
+```
+
+### Mapper XML（标准片段模板）
+
+```xml
+<mapper namespace="com.twsz.mom.{{module}}.mapper.{{Entity}}Mapper">
+    <resultMap id="BaseResultMap" type="com.twsz.mom.{{module}}.model.{{Entity}}"/>
+
+    <!-- 动态列（支持 ViewModel.fields 部分列查询） -->
+    <sql id="{{Entity}}Columns">
+        <choose>
+            <when test="entity.fields != null">
+                <foreach collection="entity.columns" item="it" separator=",">t.${it}</foreach>
+            </when>
+            <otherwise>t.*</otherwise>
+        </choose>
+    </sql>
+
+    <!-- 动态 WHERE（每个字段一个 if 判断） -->
+    <sql id="{{Entity}}Where">
+        <where>
+            <if test="entity.id != null">AND t.id = #{entity.id}</if>
+            <if test="entity.isEffect != null">AND t.is_effect = #{entity.isEffect}</if>
+            <!-- 根据字段清单补充 -->
+        </where>
+        <choose>
+            <when test="entity.orderBy != null and entity.orderBy != ''">
+                ORDER BY t.${entity.orderBy}
+            </when>
+            <otherwise>ORDER BY t.id DESC</otherwise>
+        </choose>
+    </sql>
+
+    <sql id="{{Entity}}Joins"></sql>
+
+    <select id="pageSearch" resultMap="BaseResultMap">
+        SELECT <include refid="{{Entity}}Columns"/>
+        FROM {{table_name}} t
+        <include refid="{{Entity}}Joins"/>
+        <include refid="{{Entity}}Where"/>
+    </select>
+
+    <select id="list" resultMap="BaseResultMap">
+        SELECT * FROM (
+            SELECT <include refid="{{Entity}}Columns"/>
+            FROM {{table_name}} t
+            <include refid="{{Entity}}Joins"/>
+            <include refid="{{Entity}}Where"/>
+        ) tt WHERE rownum &lt;=
+        <choose>
+            <when test="entity.rowNum != null">#{entity.rowNum}</when>
+            <otherwise>10000</otherwise>
+        </choose>
+    </select>
+</mapper>
+```
+
+### Service 接口
+
+```java
+public interface {{Entity}}Service extends IService<{{Entity}}> {
+    ResponseWrapper<String> insert({{Entity}} entity);
+    ResponseWrapper<String> update({{Entity}} entity);
+    ResponseWrapper<String> deleteByIds(Collection<Long> ids);
+    ResponseWrapper<Page<{{Entity}}>> search(PageForm<{{Entity}}> pageForm);
+    List<{{Entity}}> list({{Entity}} entity);
+}
+```
+
+### Service 实现
+
+```java
+@Slf4j
+@Service
+public class {{Entity}}ServiceImpl extends ServiceImpl<{{Entity}}Mapper, {{Entity}}>
+        implements {{Entity}}Service {
+
+    @Override
+    public ResponseWrapper<String> insert({{Entity}} entity) {
+        if (super.save(entity)) {
+            return ResponseWrapper.defaultSuccess();
+        }
+        return ResponseWrapper.ofStatus(HttpStatus.OBJECT_INSERT_FAIL);
+    }
+
+    @Override
+    public ResponseWrapper<String> update({{Entity}} entity) {
+        if (super.updateById(entity)) {
+            return ResponseWrapper.defaultSuccess();
+        }
+        return ResponseWrapper.ofStatus(HttpStatus.OBJECT_UPDATE_FAIL);
+    }
+
+    @Override
+    public ResponseWrapper<String> deleteByIds(Collection<Long> ids) {
+        if (super.removeByIds(ids)) {
+            return ResponseWrapper.defaultSuccess();
+        }
+        return ResponseWrapper.ofStatus(HttpStatus.OBJECT_DELETE_FAIL);
+    }
+
+    @Override
+    public ResponseWrapper<Page<{{Entity}}>> search(PageForm<{{Entity}}> pageForm) {
+        Page<{{Entity}}> p = new Page<>(pageForm.getCurrent(), pageForm.getSize());
+        baseMapper.pageSearch(p, pageForm.getCondition());
+        return ResponseWrapper.ofSuccess(p);
+    }
+
+    @Override
+    public List<{{Entity}}> list({{Entity}} entity) {
+        return baseMapper.list(entity);
+    }
+}
+```
+
+### Controller
+
+```java
+@Slf4j
+@RestController
+@RequestMapping("/{{entity}}")
+public class {{Entity}}Controller {
+
+    @Resource
+    private {{Entity}}Service {{entity}}Service;
+
+    @PostMapping(value = "add")
+    public ResponseWrapper<String> add(@RequestBody {{Entity}} entity) {
+        return {{entity}}Service.insert(entity);
+    }
+
+    @PutMapping(value = "update")
+    public ResponseWrapper<String> update(@RequestBody {{Entity}} entity) {
+        return {{entity}}Service.update(entity);
+    }
+
+    @PostMapping(value = "search")
+    public ResponseWrapper<Page<{{Entity}}>> search(@RequestBody PageForm<{{Entity}}> pageForm) {
+        return {{entity}}Service.search(pageForm);
+    }
+
+    @DeleteMapping(value = "delete")
+    public ResponseWrapper<String> delete(@RequestBody Long[] ids) {
+        return {{entity}}Service.deleteByIds(Arrays.asList(ids));
+    }
+
+    @GetMapping(value = "get/{id}")
+    public ResponseWrapper<{{Entity}}> get(@PathVariable Long id) {
+        return ResponseWrapper.ofSuccess({{entity}}Service.getById(id));
+    }
+
+    @PostMapping(value = "list")
+    public ResponseWrapper<List<{{Entity}}>> list(@RequestBody {{Entity}} entity) {
+        return ResponseWrapper.ofSuccess({{entity}}Service.list(entity));
+    }
+
+    @PostMapping(value = "export")
+    public void export(@RequestBody {{Entity}} condition, HttpServletResponse response) throws IOException {
+        // EasyExcel 导出
+    }
+}
+```
+
+---
+
+## 3. 前端代码结构
+
+### 目录布局
+
+```
+src/
+├── api/{{domain}}/
+│   └── {{entity}}.js
+└── views/{{domain}}/{{entity}}/
+    ├── index.vue          # 列表页
+    └── {{entity}}-form.vue  # 表单页
+```
+
+### API 接口文件
+
+```js
+import axios from '@/libs/request'
+import { exportExcel } from '../file'
+
+const apiPrefix = '/{{entity}}'
+
+const search{{Entity}} = data => {
+    return axios.request({ url: `${apiPrefix}/search`, method: 'POST', data })
+}
+
+const save{{Entity}} = data => {
+    const url = data.id ? `${apiPrefix}/update` : `${apiPrefix}/add`
+    const method = data.id ? 'PUT' : 'POST'
+    return axios.request({ url, method, data })
+}
+
+const delete{{Entity}} = ids => {
+    return axios.request({
+        url: `${apiPrefix}/delete`,
+        method: 'DELETE',
+        data: Array.isArray(ids) ? ids : [ids]
+    })
+}
+
+const list{{Entity}} = data => {
+    return axios.request({ url: `${apiPrefix}/list`, method: 'POST', data })
+}
+
+const export{{Entity}} = data => {
+    return exportExcel(`${apiPrefix}/export`, data)
+}
+
+export default { search{{Entity}}, save{{Entity}}, delete{{Entity}}, list{{Entity}}, export{{Entity}} }
+```
+
+### 列表页（index.vue）
+
+```vue
+<template>
+    <div class="master-index">
+        <search-table v-show="showIndexPage" ref="searchTable" :option="option" :columns="tableColumns">
+            <template #condition-form>
+                <Form ref="conditionForm" class="search-condition-form" label-colon @keyup.enter.native="refresh">
+                    <!-- 搜索条件表单字段 -->
+                </Form>
+            </template>
+        </search-table>
+        <tw-card v-show="!showIndexPage" :back="triggerBack">
+            <{{Entity}}Form :readonly="readonly" :form="formData" :key="instanceKey"
+                @on-success="handleSuccess" />
+        </tw-card>
+    </div>
+</template>
+
+<script>
+import { indexPage } from '_c/table-form/index-mixin'
+import {{Entity}}Api from '@/api/{{domain}}/{{entity}}'
+import {{Entity}}Form from './{{entity}}-form'
+
+export default {
+    mixins: [indexPage],
+    components: { {{Entity}}Form },
+    data() {
+        return {
+            option: {
+                tableName: '{{entity}}',
+                searchForm: {},
+                fixedTableHeight: true,
+                add:    { enable: true, method: this.add },
+                edit:   { enable: true, method: this.edit },
+                view:   { enable: true, method: this.view },
+                delete: { enable: true, method: {{Entity}}Api.delete{{Entity}} },
+                export: { enable: true, method: {{Entity}}Api.export{{Entity}} },
+                search: { query: {{Entity}}Api.search{{Entity}} },
+            },
+            tableColumns: [
+                { type: 'selection' },
+                // 表格列定义
+                { title: this.$t('operate||操作'), slot: 'operate' }
+            ]
+        }
+    }
+}
+</script>
+```
+
+### 表单页（{{entity}}-form.vue）
+
+```vue
+<template>
+    <master-sub :readonly="readonly">
+        <template v-if="!readonly" #master-header-toolbar>
+            <Button type="primary" :loading="loading" @click="doSubmit">{{ $t('submit||提交') }}</Button>
+        </template>
+        <template #master-form>
+            <Form ref="mform" :model="mform" :label-width="120" :disabled="readonly" class="form">
+                <!-- 表单字段 -->
+            </Form>
+        </template>
+    </master-sub>
+</template>
+
+<script>
+import { BaseMixin } from '@/mixin'
+import {{Entity}}Api from '@/api/{{domain}}/{{entity}}'
+
+export default {
+    mixins: [BaseMixin],
+    props: {
+        readonly: { type: Boolean, default: false },
+        form: { type: Object, default: () => ({}) }
+    },
+    data() { return { mform: {}, default: {} } },
+    created() {
+        this.mform = Object.assign({}, this.default, this.form)
+    },
+    methods: {
+        doSubmit() {
+            this.$refs.mform.validate(valid => {
+                if (valid) {
+                    this.asyncLoading({{Entity}}Api.save{{Entity}}(this.mform)).then(res => {
+                        this.$Message.success({ background: true, content: this.$t('submit.success||提交成功') })
+                        this.$emit('on-success', this.mform)
+                    })
+                }
+            })
+        }
+    }
+}
+</script>
+```
+
+---
+
+## 4. 接口定义
+
+| Method | Path | 描述 | 请求体 | 响应 |
+|--------|------|------|--------|------|
+| POST | /{{entity}}/search | 分页查询 | `PageForm<{{Entity}}>` | `ResponseWrapper<Page<{{Entity}}>>` |
+| POST | /{{entity}}/add | 新增 | `{{Entity}}` | `ResponseWrapper<String>` |
+| PUT | /{{entity}}/update | 修改 | `{{Entity}}` | `ResponseWrapper<String>` |
+| DELETE | /{{entity}}/delete | 批量删除 | `Long[]` | `ResponseWrapper<String>` |
+| GET | /{{entity}}/get/{id} | 详情 | — | `ResponseWrapper<{{Entity}}>` |
+| POST | /{{entity}}/list | 不分页列表 | `{{Entity}}` | `ResponseWrapper<List<{{Entity}}>>` |
+| POST | /{{entity}}/export | Excel 导出 | `{{Entity}}` | Excel 文件流 |
+
+---
+
+## 5. 前后端分工
+
+| 功能 | 前端 | 后端 |
+|------|------|------|
+| 列表页 | search-table + indexPage mixin | POST /search（PageForm 分页） |
+| 新增 | master-sub 表单 + save（无 id → add） | POST /add |
+| 编辑 | master-sub 表单 + save（有 id → update） | PUT /update |
+| 删除 | 确认弹窗 + delete(ids) | DELETE /delete |
+| 导出 | exportExcel Blob 下载 | POST /export（EasyExcel） |
+| 菜单 | 动态路由（后端返回 component 路径） | c_sys_resource 注册 |

package/builtin/schemas/mes-crud-module/templates/menu-register.md

@@ -0,0 +1,126 @@
+# 菜单注册: {{Entity}}
+
+> 模块: {{module}} | 实体: {{Entity}} | 组件路径: `{{domain}}/{{entity}}/index`
+
+---
+
+## 1. 菜单配置
+
+| 配置项 | 值 | 说明 |
+|--------|-----|------|
+| 菜单名称 | {{moduleName}} | 显示在侧边栏的名称 |
+| 父级菜单 | 根据实际选择 | c_sys_resource.pid |
+| 排序 | 100 | 同级菜单排序 |
+| 图标 | ios-folder | ViewUI 图标名称 |
+| 路由路径 | /{{domain}}/{{entity}} | 前端路由 |
+| 组件路径 | {{domain}}/{{entity}}/index | Vue 组件路径（相对 src/views/） |
+
+---
+
+## 2. c_sys_resource 表结构
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | bigint | 主键（雪花算法） |
+| title | varchar | 菜单/按钮显示名称 |
+| pid | bigint | 父级 ID（0 = 顶级） |
+| sort | int | 排序号 |
+| enable | int | 1=启用 |
+| type | int | 1=路由菜单, 2=按钮权限, 3=API 资源 |
+| path | varchar | URL 路径 |
+| component | varchar | Vue 组件路径 |
+| icon | varchar | 图标 |
+| permission | varchar | 权限标识 |
+
+---
+
+## 3. SQL 插入语句
+
+```sql
+-- ============================================================
+-- 菜单注册（c_sys_resource）
+-- ============================================================
+
+-- 1. 菜单项（type=1 路由菜单）
+-- 请先确认父级菜单 ID（替换下面的 @parentId）
+-- 可通过 SELECT id FROM c_sys_resource WHERE title = '父级菜单名' 获取
+
+INSERT INTO c_sys_resource (id, title, pid, sort, enable, type, path, component, icon, permission, created_by, created_date, last_updated_by, last_updated_date)
+VALUES (
+  -- id: 使用雪花算法生成，或手动指定一个不冲突的大数字
+  {{menu_id}},                    -- 菜单 ID（需唯一）
+  '{{moduleName}}',               -- 菜单名称
+  {{parent_id}},                  -- 父级菜单 ID（0=顶级）
+  100,                            -- 排序号
+  1,                              -- 启用
+  1,                              -- type=1 路由菜单
+  '/{{domain}}/{{entity}}',       -- 路由路径
+  '{{domain}}/{{entity}}/index',  -- 组件路径
+  'ios-folder',                   -- 图标
+  '{{module}}:{{entity}}:view',   -- 权限标识
+  'admin',
+  SYSTIMESTAMP,
+  'admin',
+  SYSTIMESTAMP
+);
+
+-- 2. 按钮权限（type=2 按钮）
+-- @menuId 替换为上面插入的菜单 ID
+
+INSERT INTO c_sys_resource (id, title, pid, sort, enable, type, path, component, icon, permission, created_by, created_date, last_updated_by, last_updated_date)
+VALUES
+-- 查询按钮
+({{menu_id}} + 1, '{{moduleName}}查询', {{menu_id}}, 1, 1, 2, '#', '', '', '{{module}}:{{entity}}:view', 'admin', SYSTIMESTAMP, 'admin', SYSTIMESTAMP),
+-- 新增按钮
+({{menu_id}} + 2, '{{moduleName}}新增', {{menu_id}}, 2, 1, 2, '#', '', '', '{{module}}:{{entity}}:add', 'admin', SYSTIMESTAMP, 'admin', SYSTIMESTAMP),
+-- 修改按钮
+({{menu_id}} + 3, '{{moduleName}}修改', {{menu_id}}, 3, 1, 2, '#', '', '', '{{module}}:{{entity}}:edit', 'admin', SYSTIMESTAMP, 'admin', SYSTIMESTAMP),
+-- 删除按钮
+({{menu_id}} + 4, '{{moduleName}}删除', {{menu_id}}, 4, 1, 2, '#', '', '', '{{module}}:{{entity}}:delete', 'admin', SYSTIMESTAMP, 'admin', SYSTIMESTAMP),
+-- 导出按钮
+({{menu_id}} + 5, '{{moduleName}}导出', {{menu_id}}, 5, 1, 2, '#', '', '', '{{module}}:{{entity}}:export', 'admin', SYSTIMESTAMP, 'admin', SYSTIMESTAMP);
+```
+
+---
+
+## 4. 权限标识
+
+| 权限标识 | 描述 | 前端使用方式 |
+|---------|------|-------------|
+| `{{module}}:{{entity}}:view` | 查看 | `v-hasPerm="'{{module}}:{{entity}}:view'"` |
+| `{{module}}:{{entity}}:add` | 新增 | `v-hasPerm="'{{module}}:{{entity}}:add'"` |
+| `{{module}}:{{entity}}:edit` | 修改 | `v-hasPerm="'{{module}}:{{entity}}:edit'"` |
+| `{{module}}:{{entity}}:delete` | 删除 | `v-hasPerm="'{{module}}:{{entity}}:delete'"` |
+| `{{module}}:{{entity}}:export` | 导出 | `v-hasPerm="'{{module}}:{{entity}}:export'"` |
+
+---
+
+## 5. 前端路由（参考）
+
+> MES 项目使用动态路由：后端通过 `c_sys_resource` 返回路由配置，前端通过 `router.addRoutes()` 注册。
+> 以下仅为参考，实际路由由后端 `GET /resource/listTreeByUser` 接口返回。
+
+```javascript
+// 后端返回的路由数据结构（resources）
+{
+  title: '{{moduleName}}',
+  path: '/{{domain}}/{{entity}}',
+  component: '{{domain}}/{{entity}}/index',  // 前端 import.meta.glob 解析
+  icon: 'ios-folder',
+  permission: '{{module}}:{{entity}}:view',
+}
+```
+
+---
+
+## 6. 刷新缓存
+
+执行 SQL 后，需要刷新 Redis 中的资源缓存：
+
+```bash
+# 通过 API 刷新
+curl -X GET http://localhost:8000/api/sys/resource/reloadCache \
+  -H "Authorization: Bearer <token>"
+```
+
+> **注意**: 执行 SQL 前请先确认 `pid` 的值（根据实际父级菜单调整），菜单 ID 需确保全局唯一。

package/builtin/schemas/mes-crud-module/templates/proposal.md

@@ -0,0 +1,64 @@
+# MES CRUD 模块提案
+
+## 模块信息
+
+| 配置项 | 值 |
+|--------|-----|
+| 模块名称 | {{moduleName}} |
+| 所属业务中心 | modules-center/{{module}}-center |
+| 后端包名 | com.twsz.mom.{{module}} |
+| 前端域 | src/views/{{domain}}/ |
+
+## 核心实体
+
+| 配置项 | 值 |
+|--------|-----|
+| 实体类名 | {{Entity}} |
+| 表名 | {{table_name}} |
+| 表注释 | {{table_comment}} |
+| 描述 | {{description}} |
+
+## CRUD 操作
+
+- [ ] 分页查询（POST /{{entity}}/search）
+- [ ] 详情查询（GET /{{entity}}/get/{id}）
+- [ ] 新增（POST /{{entity}}/add）
+- [ ] 修改（PUT /{{entity}}/update）
+- [ ] 批量删除（DELETE /{{entity}}/delete）
+- [ ] 不分页列表（POST /{{entity}}/list）
+- [ ] Excel 导出（POST /{{entity}}/export）
+
+## 字段清单
+
+| 字段名 | 数据库列名 | Oracle 类型 | Java 类型 | 必填 | 说明 |
+|--------|-----------|-------------|-----------|------|------|
+| id | id | NUMBER(19) | Long | 自动 | 主键（雪花算法，BaseModel 提供） |
+| — | created_by | VARCHAR2(64) | String | 自动 | 创建人（TimeModel 提供） |
+| — | created_date | TIMESTAMP | LocalDateTime | 自动 | 创建时间（TimeModel 提供） |
+| — | last_updated_by | VARCHAR2(64) | String | 自动 | 更新人（TimeModel 提供） |
+| — | last_updated_date | TIMESTAMP | LocalDateTime | 自动 | 更新时间（TimeModel 提供） |
+| | | | | | |
+| is_effect | is_effect | NUMBER(1) | Integer | 是 | 启用状态（1=启用, 0=停用） |
+
+> 请补充业务字段。审计字段（created_by 等）和主键（id）由 BaseModel 自动提供，无需在 Entity 中声明。
+
+## 业务规则
+
+1. 
+2. 
+3. 
+
+## 查询条件
+
+| 字段 | 查询方式 | 说明 |
+|------|---------|------|
+| | LIKE / = / BETWEEN / IN | |
+
+## 非目标
+
+- 不包含: 
+
+## 关联模块
+
+- 依赖: 
+- 被依赖: