:::tip 本章概要
代码生成器的整体架构、核心模块和生成流程概述。
:::

# 概述与架构

代码生成器是项目的核心效率工具，能够根据数据库表结构自动生成完整的后端三层模块代码和前端 Vue 页面代码，并自动注册路由和菜单权限节点。

## 生成能力总览

| 维度 | 生成内容 |
|:----|:----|
| 后端模块 | `__init__.py` / `models.py` / `schemas.py` / `repository.py` / `service.py` |
| 后端路由 | `api/v1/endpoints/{module}.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 模型
        ├── schemas.py.tpl                # Pydantic 表单
        ├── repository.py.tpl             # 数据访问层
        ├── service.py.tpl                # 业务逻辑层
        ├── endpoint.py.tpl               # HTTP 端点
        ├── 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│ │ router.py    │
              │ schemas  │ │ edit.vue │ │ fastapi_menu │
              │ repository│ │ columns  │ │ 权限节点     │
              │ service  │ │ api.ts   │ │ 清除缓存     │
              │ endpoint │ │ ...      │ │              │
              └──────────┘ └──────────┘ └──────────────┘
```

## 使用限制

:::warning 使用前提
1. **数据库要求**：Web 管理界面的「代码生成」功能基于 MySQL 的 `information_schema` 查询表结构，仅支持 MySQL 数据库。CLI 命令行同样依赖 `information_schema`，需在 MySQL 环境下使用。
2. **表结构要求**：不支持复合主键、外键关联等复杂表结构，建议使用单主键（自增 id）的标准业务表。
3. **目录冲突**：生成前会校验目标模块目录不存在，已存在时需先手动删除。
:::

## 演示表

本章以 `fastapi_example` 表为贯穿案例：

```sql
CREATE TABLE `fastapi_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 语法，可自由定制生成结果。