签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,102 @@
+# 10.5 代码生成引擎
+
+:::tip 概述
+生成引擎按模板渲染全部产物：后端八件套（统一 gofmt）+ 前端五件/三件，然后经 writeFile 四态落盘决策，最后执行幂等副作用。本节给出产物清单与落盘决策。
+:::
+
+## 产物清单（renderTable）
+
+### 后端八件套（Go 产物统一 gofmt，format.Source 失败即报错）
+
+| 产物 | 模板 |
+|------|------|
+| api/v1/{module}.go | templates/api.tpl |
+| internal/controller/{module}.go | templates/controller.tpl |
+| internal/logic/{module}.go | templates/logic.tpl |
+| internal/service/{module}.go | templates/service.tpl |
+| internal/dao/{module}.go | templates/dao_index.tpl（挂钩子+Ctx） |
+| internal/dao/internal/{module}.go | templates/dao_internal.tpl |
+| internal/model/entity/{module}.go | templates/entity.tpl |
+| internal/model/do/{module}.go | templates/do.tpl |
+
+### 前端文件（模板定界符 [[ ]]，规避 Vue 插值冲突）
+
+```text
+ui 普通模板：
+  src/api/{域}/{moduleCamel}.ts
+  src/views/{域}/{moduleCamel}/
+    index.vue  edit.vue  detail.vue  columns.ts  querySchemas.ts
+
+ui2 树形模板：
+  src/api/{域}/{moduleCamel}.ts
+  src/views/{域}/{moduleCamel}/
+    index.vue  edit.vue  detail.vue
+```
+
+## 落盘决策（writeFile 四态）
+
+```text
+                   目标文件存在？
+                    /        \
+                  否           是
+                  │            │
+               写入          generator.overwrite?
+              Generated      /              \
+                           true            false/缺省
+                            │                │
+                         覆盖写            跳过保留
+                        Overwritten        Skipped
+                            \              /
+                          任一失败 → Failed（MkdirAll/WriteFile 错误）
+```
+
+覆盖开关唯一入口：`generator.overwrite`（config.yaml）——true=生成即覆盖，false/未配置=缺失补生成、存在跳过。
+
+## skipTables 保护
+
+```text
+skipTables：仅关联表 role_menu、user_role
+  跳过文件写入（这两个表无独立模块，关联逻辑归 role/user logic）
+  但幂等副作用（菜单/字典/路由）照常执行——buildVars 结果供副作用使用
+```
+
+## 生成产物质量保障
+
+```text
+* Go 产物统一 gofmt（format.Source 失败即报错不落盘——坏格式不入库）
+* 生成的 logic 是 ModuleSpec 基座风格完整实现（含筛选/树形/字典/导入导出声明）
+* dao 四件与 gf gen dao 同构（挂全局钩子 + Ctx 覆写）
+* service 接口含中文方法注释（与手维护风格一致）
+* 前端 api 函数含 JSDoc 注释
+```
+
+## 结果报告结构
+
+```text
+Generate（一键）：
+  Generated[] / Skipped[] / Overwritten[] / Failed[]
+  Menu{Success, MenuId, Message}
+  Dict[]{Dict, Name, Items, Status}
+  Route{Success, Message}
+
+BatchGenerate：
+  List[]{Table, Success, Generated, Skipped, Overwritten, Failed,
+         Message, Menu, Dict, Route}
+  Message="生成 N，跳过 N，覆盖 N，失败 N"
+
+Preview：
+  List[]{Path, Content}（渲染结果全文，不落盘）
+```
+
+## 生成后 Checklist
+
+```text
+□ go build ./... 编译通过
+□ 重启服务（路由/服务注册生效）
+□ 角色管理勾选新权限节点
+□ 租户级新表 → hooks.tenantTables 登记（再重启）
+□ 访问新菜单：增删改查/导入导出冒烟
+□ querySchemas options 改字典驱动（生成的是静态示例选项）
+□ 复杂列/复杂筛选手工扩展
+□ /api.json 核对接口清单
+```