签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,140 @@
+:::tip 本章概要
+代码生成器的整体架构、核心模块和生成流程概述。
+:::
+
+# 概述与架构
+
+代码生成器是项目的核心效率工具，能够根据数据库表结构自动生成完整的后端三层模块代码和前端 Vue 页面代码，并自动注册路由和菜单权限节点。
+
+## 生成能力总览
+
+| 维度 | 生成内容 |
+|:----|:----|
+| 后端模块 | `__init__.py` / `models.py` / `schema.py` / `repository.py` / `service.py` / `router.py` |
+| 前端页面 | `index.vue` / `edit.vue` / `detail.vue` / `columns.ts` / `querySchemas.ts` / `api.ts` |
+| 菜单权限 | 自动创建菜单节点 + 10 个权限节点 |
+
+## 两种使用方式
+
+| 方式 | 入口 | 适用场景 |
+|:----|:----|:----|
+| CLI 命令行 | `python generator.py <表名>` | 开发阶段，快速生成单个模块 |
+| Web 管理界面 | 开发工具 → 代码生成 | 运维阶段，可视化操作，支持批量生成 |
+
+两种方式共享同一套引擎代码（`src/modules/generator/`），生成结果完全一致。
+
+## 文件结构
+
+```
+项目根目录
+├── generator.py                          # CLI 命令行入口
+└── src/modules/generator/
+    ├── parser.py                         # 表结构解析器
+    ├── code_generator.py                 # 代码生成引擎
+    ├── service.py                        # Web API 业务逻辑
+    ├── __init__.py
+    └── templates/                        # Jinja2 模板目录
+        ├── __init__.py.tpl               # 模块初始化
+        ├── models.py.tpl                 # ORM 模型
+        ├── schema.py.tpl                 # WTForms 表单
+        ├── repository.py.tpl             # 数据访问层
+        ├── service.py.tpl                # 业务逻辑层
+        ├── router.py.tpl                 # 路由定义层
+        ├── ui/                           # 普通分页列表模板（6 个）
+        │   ├── index.vue.tpl
+        │   ├── edit.vue.tpl
+        │   ├── detail.vue.tpl
+        │   ├── columns.ts.tpl
+        │   ├── querySchemas.ts.tpl
+        │   └── api.ts.tpl
+        └── ui2/                          # 树状列表模板（3 个）
+            ├── index.vue.tpl
+            ├── edit.vue.tpl
+            └── detail.vue.tpl
+```
+
+## 核心组件
+
+### parser.py — 表结构解析器
+
+从 `information_schema` 读取表元数据，输出标准化配置字典。智能识别图片字段、富文本字段、状态字段、排序字段、枚举字段、查询条件等。
+
+### code_generator.py — 代码生成引擎
+
+接收配置字典，通过 Jinja2 渲染模板，写入文件，并自动注册路由和菜单权限。
+
+### service.py — Web API 业务逻辑
+
+提供表分页查询、表详情、字段查询、单表/批量生成等服务方法，供 HTTP 端点调用。
+
+### templates/ — 模板目录
+
+Jinja2 模板文件，分为后端模板（6 个）和前端模板（ui/ 6 个 + ui2/ 3 个）。含 `parent_id` / `pid` 字段的表自动切换为树形模板（ui2/）。
+
+## 生成流程
+
+```
+                    ┌─────────────────────────────────────┐
+                    │          数据库 information_schema     │
+                    └──────────────────┬──────────────────┘
+                                       │
+                                       ▼
+                    ┌─────────────────────────────────────┐
+                    │  parser.py（表结构解析器）              │
+                    │  ─ 智能识别字段类型/图片/富文本/状态    │
+                    │  ─ 生成标准化配置字典                  │
+                    └──────────────────┬──────────────────┘
+                                       │ 配置字典
+                                       ▼
+                    ┌─────────────────────────────────────┐
+                    │  code_generator.py（代码生成引擎）      │
+                    │  ─ normalize_config() 标准化          │
+                    │  ─ Jinja2 模板渲染                    │
+                    └───┬──────────┬──────────┬──────────┘
+                        │          │          │
+                        ▼          ▼          ▼
+              ┌──────────┐ ┌──────────┐ ┌──────────────┐
+              │ 后端模块  │ │ 前端页面  │ │ 自动注册      │
+              │ models   │ │ index.vue│ │ v1.py        │
+              │ schema   │ │ edit.vue │ │ flask_menu   │
+              │ repository│ │ columns  │ │ 权限节点     │
+              │ service  │ │ api.ts   │ │ 清除缓存     │
+              │ router   │ │ ...      │ │              │
+              └──────────┘ └──────────┘ └──────────────┘
+```
+
+## 使用限制
+
+:::warning 使用前提
+1. **数据库要求**：Web 管理界面的「代码生成」功能基于 MySQL 的 `information_schema` 查询表结构，仅支持 MySQL 数据库。CLI 命令行同样依赖 `information_schema`，需在 MySQL 环境下使用。
+2. **表结构要求**：不支持复合主键、外键关联等复杂表结构，建议使用单主键（自增 id）的标准业务表。
+3. **目录冲突**：生成前会校验目标模块目录不存在，已存在时需先手动删除。
+:::
+
+## 演示表
+
+本章以 `flask_example` 表为贯穿案例：
+
+```sql
+CREATE TABLE `flask_example` (
+  `id` int NOT NULL AUTO_INCREMENT,
+  `name` varchar(100) NOT NULL COMMENT '案例名称',
+  `code` varchar(50) NOT NULL COMMENT '案例编码',
+  `type` int DEFAULT 1 COMMENT '案例类型：1-类型1 2-类型2 3-类型3',
+  `status` int DEFAULT 1 COMMENT '案例状态：1-正常 2-停用',
+  `sort` int DEFAULT 0 COMMENT '排序',
+  `cover` varchar(255) DEFAULT NULL COMMENT '封面图',
+  `content` text COMMENT '案例内容',
+  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
+  `create_user` varchar(50) DEFAULT NULL,
+  `create_time` datetime DEFAULT NULL,
+  `update_user` varchar(50) DEFAULT NULL,
+  `update_time` datetime DEFAULT NULL,
+  `is_delete` int DEFAULT 0,
+  PRIMARY KEY (`id`)
+) COMMENT='案例表';
+```
+
+## 总结
+
+代码生成器通过解析数据库表结构，自动生成符合项目规范的完整模块代码。CLI 适合开发阶段快速生成，Web 界面适合运维阶段批量管理。模板使用 Jinja2 语法，可自由定制生成结果。