签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,93 @@
+# 10.1 概述与架构
+
+:::tip 概述
+代码生成器根据表结构一键产出前后端全套文件，并同步创建菜单、权限节点、字典数据、路由注册行（全部幂等）。双入口：HTTP（管理页面）与 CLI（cmd/generator）。核心在 internal/logic/generator.go + generator_side.go。
+:::
+
+## 定位
+
+```text
+输入：表名列表（"表名|注释"）
+产出：
+  后端八件套（api/controller/logic/service + dao index/internal + entity + do）
+  前端文件（api/{域}/{模块}.ts + views/{域}/{模块}/ 五件或三件）
+  幂等副作用：菜单 + 权限节点 + 字典 + router.go 注册行
+约束：生成的 logic 是 ModuleSpec 基座风格的完整可用实现，
+     go build 后即可运行；复杂业务再手工扩展钩子
+```
+
+## 双入口
+
+```text
+HTTP（/api/generator，管理页面"代码生成"）：
+  GET  /api/generator/page           sys:generator:page          数据表清单（分页）
+  POST /api/generator/preview        sys:generator:generator     预览（不落盘）
+  POST /api/generator/generate       sys:generator:generator     一键生成
+  POST /api/generator/batchGenerate  sys:generator:batchGenerator 批量生成
+  日志 logType=generate（19 代码生成）
+
+CLI（仓库根目录，读同一份 config.yaml）：
+  go run ./cmd/generator -tables "goframe_example|案例演示表"
+  CLI 空白 import internal/logic 注册全部服务，直接调用 service.Generator()
+```
+
+## 总体流水线
+
+```text
+输入 tables[]（"表名|注释"）
+      │
+      ▼
+buildVars：TableFields 内省 → 类型/注释解析 → 字段分桶（列表/表单/筛选）
+      │            命名：module/Pascal/camelLower；域归属；ui|ui2 模板类型
+      ▼
+skipTables? ──是(role_menu/user_role)──▶ 仅 buildVars（副作用用），跳过文件
+      │ 否
+      ▼
+renderTable：逐模板渲染（后端 {{ }} / 前端 [[ ]]）→ go 产物 gofmt
+      │
+      ▼
+writeFile×N（四态：新写/跳过/覆盖/失败）
+      │
+      ▼
+副作用（幂等）：createMenu(+权限节点) → createDict(枚举字段) → registerRouter
+      │
+      ▼
+结果报告（Generated/Skipped/Overwritten/Failed + Menu/Dict/Route）
+      │
+      ▼
+提示：go build ./... 并重启服务
+```
+
+## 域归属与模板类型
+
+```text
+genDomainMap 域归属（决定前端 api/views 目录）：
+  user/role/menu/dept/level/position/tenant → system
+  config/param/dict/notice/city             → data
+  article/category/link                      → content
+  operation_log/login_log/job/…             → monitor
+  example/file_template/…                   → tool（默认）
+
+模板类型：有 parent_id/pid 列 → ui2（树形模板），否则 ui（普通列表模板）
+排序默认：有 sort 列 → "sort asc"，否则 "id desc"
+```
+
+## 与 gf gen dao 的分工
+
+| 工具 | 用途 |
+|------|------|
+| `gf gen dao -c hack/config.yaml` | **表结构变更**后刷新已有模块 dao（自定义模板挂钩子+Ctx；overwriteDao:false 保留手工扩展） |
+| 生成器 | **新模块**一键产出（dao 四件与 gf gen dao 同构，生成后统一 gofmt 可直接编译） |
+| `gf gen service` | **禁止整体运行**（service 接口为手工重组维护） |
+
+## 保护策略速览
+
+```text
+skipTables：仅关联表 role_menu/user_role 整表跳过文件生成
+           （副作用照常执行）
+文件粒度四态：缺失补生成（Generated）/ 已存在跳过（Skipped）
+            / 开覆盖时覆盖（Overwritten）/ 失败（Failed）
+覆盖开关唯一入口：generator.overwrite（config.yaml）
+```
+
+详见 [10.5 代码生成引擎](./code-engine) 与 [10.7 配置文件详解](./config)。