签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,183 @@
+:::tip 本章概要
+代码生成器 CLI 模式的使用方法，包括单表生成、预览模式和配置导出。
+:::
+
+# CLI 命令行使用
+
+CLI 入口为项目根目录的 `generator.py`，内部包含 `TableSchemaParser` 解析器，并调用 `generator_config.py` 中的 `CodeGenerator` 引擎。适合开发阶段快速生成单个模块。
+
+## 基本用法
+
+```bash
+# 解析表结构并生成模块（最常用）
+python generator.py django_example
+```
+
+执行后自动完成：
+1. 从数据库解析 `django_example` 表结构
+2. 生成后端模块代码到 `application/example/`
+3. 生成前端页面到 `ui/src/views/tool/example/` 和 `ui/src/api/tool/example.ts`
+4. 自动追加路由到 `application/urls.py`
+5. 自动注册应用到 `settings.py` 的 `INSTALLED_APPS`
+6. 自动创建菜单和权限节点
+
+## 预览模式
+
+使用 `--dry-run` 仅解析表结构并打印配置摘要，不执行代码生成：
+
+```bash
+python generator.py django_example --dry-run
+```
+
+输出示例：
+
+```
+==============================================================
+数据库表结构解析和代码生成工具
+==============================================================
+正在解析表: django_example
+表结构解析成功
+
+------------------------------------------------------------
+生成配置摘要:
+------------------------------------------------------------
+  应用名称: example
+  模块名称: 案例
+  模型类名: Example
+  字段数量: 5
+  是否有排序: True
+  是否有状态: True
+
+字段列表:
+  - name: 案例名称 (CharField)
+  - avatar: 案例图片 (CharField)
+  - type: 案例类型：1-类型1 2-类型2 3-类型3 4-类型4 (IntegerField)
+    选项: [(1, '类型1'), (2, '类型2'), (3, '类型3'), (4, '类型4')]
+  - status: 案例状态：1-正常 2-禁用 (IntegerField)
+    选项: [(1, '正常'), (2, '禁用')]
+  - sort: 排序 (IntegerField)
+
+==============================================================
+预览模式 - 不执行代码生成
+==============================================================
+```
+
+## 导出配置
+
+使用 `--output` 将解析结果导出为 JSON 配置文件：
+
+```bash
+# 预览并导出配置
+python generator.py django_example --dry-run --output config.json
+
+# 生成代码并同时保存配置
+python generator.py django_example --output config.json
+```
+
+导出的 `config.json` 包含完整的生成配置，可手动编辑后重新使用。
+
+## 使用配置文件生成
+
+使用 `--config` 加载已有的 JSON 配置文件，跳过表解析：
+
+```bash
+python generator.py --config config.json
+```
+
+适用场景：
+- 需要微调字段配置后重新生成
+- 表结构已不存在但配置文件保留
+- 跨项目复用配置
+
+## 完整参数
+
+| 参数 | 简写 | 说明 |
+|:----|:----|:----|
+| `table_name` | - | 数据库表名（位置参数，可选） |
+| `--config` | `-c` | 使用已有的 JSON 配置文件（跳过表解析） |
+| `--dry-run` | `-d` | 仅生成配置，不执行代码生成 |
+| `--output` | `-o` | 将配置导出为 JSON 文件 |
+
+## 典型工作流
+
+### 快速生成
+
+```bash
+python generator.py django_example
+```
+
+### 预览 -> 微调 -> 生成
+
+```bash
+# 1. 预览配置
+python generator.py django_example --dry-run --output config.json
+
+# 2. 编辑 config.json（调整字段属性、注释等）
+vim config.json
+
+# 3. 用配置文件生成
+python generator.py --config config.json
+```
+
+### 仅保存配置
+
+```bash
+python generator.py django_example --output config.json
+```
+
+## 环境要求
+
+运行 CLI 前需确保：
+
+1. **数据库可访问**：CLI 复用 `.env` 中的数据库配置（通过 `config/env.py` 加载），需确保 MySQL 服务正常且连接信息正确
+2. **Python 依赖已安装**：`pip install -r requirements.txt`（包含 Jinja2、Django 等）
+3. **表已存在**：目标表需已在数据库中创建完成
+4. **Django 环境可用**：脚本会自动初始化 Django 环境（`django.setup()`）
+5. **编码要求**：Windows 环境下确保终端使用 UTF-8 编码（`chcp 65001`）
+
+:::warning 数据库要求
+CLI 命令行工具通过查询 MySQL 的 `information_schema` 获取表结构信息，**仅支持 MySQL 数据库**。
+:::
+
+## 常见错误
+
+### 表不存在
+
+```
+操作失败: 表 django_xxx 不存在或无业务字段
+```
+
+**原因**：数据库中不存在该表，或表名拼写错误。
+
+**解决**：确认表名正确，且表已在数据库中创建。
+
+### 数据库连接失败
+
+```
+Django环境初始化失败: (pymysql.err.OperationalError) (2003, "Can't connect to MySQL server...")
+```
+
+**原因**：`.env` 中的数据库配置错误，或 MySQL 服务未启动。
+
+**解决**：检查 `.env` 中的 `DATABASE_HOST`、`DATABASE_PORT`、`DATABASE_USER`、`DATABASE_PASSWORD` 配置。
+
+### 编码错误
+
+```
+SyntaxError: Non-UTF-8 code start with '\xc8' in file ...
+```
+
+**原因**：Windows 终端编码不是 UTF-8。
+
+**解决**：执行 `chcp 65001` 切换终端编码。
+
+## 注意事项
+
+1. **表名支持带前缀**：`django_example` 和 `example` 都可以，脚本会自动处理 `django_` 前缀（前缀由 `.env` 中的 `DATABASE_PREFIX` 配置）
+2. **数据库连接**：CLI 复用 `.env` 中的数据库配置，确保数据库可正常访问
+3. **编码要求**：Windows 环境下确保终端使用 UTF-8 编码（`chcp 65001`）
+4. **交互模式**：默认为交互模式，会询问是否执行迁移和创建菜单权限；Web 界面调用时使用自动模式（`auto=True`）
+
+## 总结
+
+CLI 命令行模式通过 `python generator.py` 启动，支持从数据库表解析生成、从配置文件生成、预览模式和配置导出。生成后自动追加路由、注册应用、创建菜单权限节点。