refactor(代码生成): 简化代码生成模块配置项和模板逻辑

移除不必要的配置字段如作者、模板类型等，优化字段初始化逻辑重构模板生成逻辑，移除主子表和树表模板支持优化前端代码生成页面，简化配置步骤和表单验证更新文档中的代码生成模块说明和快速开始指南
2026-09-21 04:46:26 +00:00 · 2025-11-03 01:27:12 +08:00
parent 2c7174db32
commit d02844dd70
18 changed files with 1101 additions and 1300 deletions
@@ -3,7 +3,7 @@ title: 后端开发指南
 ---
 # FastAPI Vue3 Admin 项目后端

-## 📖 后端项目介绍
+## 📖 项目介绍

 ### 项目概述

@@ -588,4 +588,165 @@ volumes:
 2. **后台任务**：耗时操作放入后台任务处理
 3. **并发控制**：合理控制并发数量

+## 🚀 快速开始
+
+### 环境要求
+
+ **Python**: >= 3.10
+ **MySQL**: >= 8.0
+ **Redis**: >= 7.0
+ **Git**: >= 2.0.0
+
+### 项目启动步骤
+
+1. **克隆项目**
+   ```bash
+   git clone https://gitee.com/tao__tao/fastapi_vue3_admin.git
+   ```
+
+2. **进入后端目录**
+   ```bash
+   cd fastapi_vue3_admin/backend
+   ```
+
+3. **安装依赖**
+   ```bash
+   pip3 install -r requirements.txt
+   ```
+
+4. **配置环境变量**
+   复制并修改环境配置文件：
+   ```bash
+   cp env/.env.dev.py.example env/.env.dev.py
+   # 编辑 env/.env.dev.py 文件，配置数据库和Redis连接信息
+   ```
+
+5. **初始化数据库**
+   ```bash
+   # 生成迁移文件
+   python3 main.py revision "初始化迁移" --env=dev
+   
+   # 应用迁移
+   python3 main.py upgrade --env=dev
+   ```
+
+6. **启动开发服务器**
+   ```bash
+   python3 main.py run --env=dev
+   ```
+
+7. **访问API文档**
+   打开浏览器访问 [http://localhost:8000/docs](http://localhost:8000/docs)
+
+> 默认账号：admin / 123456
+
+## 🧩 代码生成模块
+
+代码生成模块是本项目的核心功能之一，可以帮助开发者快速生成完整的 CRUD 代码，大幅提升开发效率。该模块基于 Jinja2 模板引擎，可生成前后端一体化的完整功能模块。
+
+### 代码生成架构
+
+代码生成模块位于 `backend/app/api/v1/module_generator/gencode/` 目录下，主要包括以下组件：
+
+1. **控制器层** (`controller.py`)：处理代码生成相关的 HTTP 请求
+2. **服务层** (`service.py`)：实现代码生成的核心业务逻辑
+3. **数据访问层** (`crud.py`)：处理代码生成表相关的数据库操作
+4. **数据模型层** (`model.py`)：定义代码生成相关的数据库模型
+5. **数据模式层** (`schema.py`)：定义代码生成相关的数据结构
+6. **参数模型层** (`param.py`)：定义代码生成相关的查询参数
+7. **模板工具类** (`jinja2_template_util.py`)：处理模板渲染和文件生成
+
+### 核心功能
+
+1. **表结构管理**：
+   - 导入数据库表结构
+   - 创建新表
+   - 同步数据库表结构
+   - 编辑表和字段配置
+
+2. **代码生成配置**：
+   - 配置生成参数，如包路径、模块名、业务名等
+   - 配置字段属性，如显示类型、查询方式、验证规则等
+   - 配置字典类型和菜单归属
+
+3. **代码预览**：预览生成的代码内容
+4. **代码生成**：根据配置生成完整的 CRUD 代码
+5. **代码下载**：将生成的代码打包下载
+
+### 代码生成流程
+
+1. **表结构导入**：
+   - 通过 `import` 接口导入数据库表结构
+   - 通过 `create` 接口创建新表
+
+2. **配置生成参数**：
+   - 在前端页面配置生成参数，包括包路径、模块名、业务名等
+   - 配置每个字段的属性和行为
+
+3. **保存配置**：调用 `update` 接口保存表和字段配置
+
+4. **预览代码**：调用 `preview` 接口预览生成的代码
+
+5. **生成代码**：
+   - 调用 `batch/output` 接口批量生成代码并打包为ZIP
+   - 调用 `output/{table_name}` 接口生成代码到指定路径
+
+6. **代码处理**：后端根据模板生成代码文件并打包
+
+7. **返回结果**：将生成的代码包返回给前端
+
+### 模板系统
+
+代码生成模块使用 Jinja2 模板引擎，模板文件位于 `backend/templates/` 目录下：
+
+1. **后端模板** (`templates/python/`)：
+   - 控制器模板 (`controller.py.j2`)
+   - 服务层模板 (`service.py.j2`)
+   - 数据访问层模板 (`crud.py.j2`)
+   - 数据模型模板 (`model.py.j2`)
+   - 数据模式模板 (`schema.py.j2`)
+   - 查询参数模板 (`param.py.j2`)
+
+2. **前端模板** (`templates/ts/`, `templates/vue/`)：
+   - API接口模板 (`api.ts.j2`)
+   - 页面组件模板 (`index.vue.j2`)
+
+3. **数据库模板** (`templates/sql/`)：
+   - 菜单SQL模板 (`sql.sql.j2`)
+
+### 模板变量
+
+模板中可使用的变量包括：
+
+- `table_name`：表名称
+- `function_name`：功能名称
+- `class_name`：实体类名称
+- `module_name`：模块名称
+- `business_name`：业务名称
+- `package_name`：包路径
+- `columns`：字段列表
+- `pk_column`：主键字段
+- `permission_prefix`：权限前缀
+
+### 自定义模板
+
+开发者可以根据需要自定义模板：
+
+1. **复制现有模板**：复制 `templates/` 目录下的模板文件
+2. **修改模板内容**：根据项目需求修改模板内容
+3. **更新模板列表**：在 `jinja2_template_util.py` 中更新 `get_template_list` 方法
+4. **更新文件名生成**：在 `jinja2_template_util.py` 中更新 `get_file_name` 方法
+
+## 🎯 总结
+
+**FastAPI Vue3 Admin** 后端项目提供了一套完整的企业级后台管理系统后端解决方案，具有以下优势：
+
+1. **高性能异步**：基于 FastAPI 异步框架，提供卓越的性能表现
+2. **安全可靠**：JWT 认证机制和 RBAC 权限控制模型，保障系统安全
+3. **易于扩展**：模块化设计，清晰的分层架构，便于功能扩展
+4. **开发友好**：完善的类型检查、自动文档生成和丰富的开发工具
+5. **生产就绪**：支持 Docker 部署、数据库迁移和性能监控
+
+通过本指南，您应该能够快速上手并开发出功能完善的后端服务。在开发过程中，建议遵循项目规范，合理利用现有组件和工具，以提高开发效率和代码质量。
+
 这个后端项目结构体现了现代 Python 后端项目的标准架构，具有良好的可维护性、可扩展性和开发体验。
@@ -3,7 +3,7 @@ title: 前端开发指南
 ---
 # FastAPI Vue3 Admin 项目前端

-## 📖 前端项目介绍
+## 📖 项目介绍

 ### 项目概述

@@ -1198,8 +1198,8 @@ const handleSearch = () => {

 ### 环境要求

-+ **Node.js**: >= 16.0.0
-+ **pnpm**: >= 7.0.0 (推荐)
+ **Node.js**: >= 20.0.0
+ **pnpm**: >= 8.0.0 (推荐)
 + **Git**: >= 2.0.0

 ### 安装依赖
@@ -1241,6 +1241,33 @@ pnpm run lint:format
 pnpm run clean:cache
 ```

+### 项目启动步骤
+
+1. **克隆项目**
+   ```bash
+   git clone https://gitee.com/tao__tao/fastapi_vue3_admin.git
+   ```
+
+2. **进入前端目录**
+   ```bash
+   cd fastapi_vue3_admin/frontend
+   ```
+
+3. **安装依赖**
+   ```bash
+   pnpm install
+   ```
+
+4. **启动开发服务器**
+   ```bash
+   pnpm run dev
+   ```
+
+5. **访问应用**
+   打开浏览器访问 [http://localhost:5173](http://localhost:5173)
+
+> 默认账号：admin / 123456
+
 ## 🔧 二次开发指南

 ## 🎯 动态菜单系统介绍
@@ -2377,6 +2404,112 @@ export default defineConfig({
 3. **高级特性** - 掌握性能优化和安全性配置（后续更新）
 4. **生产部署** - 完成项目上线

+## 🧩 代码生成模块
+
+代码生成模块是本项目的核心功能之一，可以帮助开发者快速生成完整的 CRUD 代码。该模块基于 Vue3 和 Element Plus 构建，提供了直观的用户界面来配置和生成代码。
+
+### 前端组件结构
+
+代码生成模块的前端组件位于 `src/views/gencode/backcode/index.vue`，采用了多步骤向导式界面：
+
+1. **基础配置步骤**：配置表的基本信息和生成参数
+2. **字段配置步骤**：配置每个字段的属性和行为
+3. **代码预览步骤**：预览将要生成的代码内容
+4. **代码生成步骤**：配置生成选项并执行代码生成
+
+### 核心功能
+
+1. **表管理**：
+   - 创建新表（通过SQL语句）
+   - 导入现有数据库表
+   - 编辑表结构和字段配置
+   - 删除代码生成配置
+
+2. **字段配置**：
+   - 配置字段的显示类型（文本框、下拉框、日期控件等）
+   - 设置字段的查询方式和查询条件
+   - 配置字段的验证规则和默认值
+   - 设置字段的字典类型用于下拉选项
+
+3. **代码预览**：
+   - 实时预览生成的后端代码（Python）
+   - 实时预览生成的前端代码（Vue/TypeScript）
+   - 实时预览生成的数据库脚本（SQL）
+   - 支持按类型筛选预览内容
+
+4. **代码生成**：
+   - 生成并下载ZIP压缩包
+   - 直接写入到项目目录中
+
+### API 接口
+
+代码生成相关的API接口定义在 `src/api/generator/gencode.ts` 文件中，主要包括：
+
+- `listTable`：查询代码生成业务表列表
+- `listDbTable`：查询数据库表列表
+- `importTable`：导入表结构
+- `getGenTableDetail`：获取业务表详细信息
+- `createTable`：创建表
+- `updateTable`：编辑业务表信息
+- `deleteTable`：删除业务表信息
+- `batchGenCode`：批量生成代码
+- `genCodeToPath`：生成代码到指定路径
+- `previewTable`：预览代码
+- `syncDb`：同步数据库
+
+### 使用流程
+
+1. **准备工作**：
+   - 在数据库中创建业务表
+   - 确保后端服务正常运行
+
+2. **导入表结构**：
+   - 进入代码生成页面
+   - 点击"导入"按钮
+   - 选择要导入的数据库表
+
+3. **配置生成参数**：
+   - 在基础配置步骤中填写：
+     - 生成包路径（package_name）
+     - 生成模块名（module_name）
+     - 生成业务名（business_name）
+     - 生成功能名（function_name）
+     - 选择上级菜单
+
+4. **配置字段属性**：
+   - 在字段配置步骤中设置每个字段的：
+     - 是否为主键、是否必填
+     - 是否为插入字段、编辑字段、列表字段、查询字段
+     - 显示类型和查询方式
+     - 字典类型（用于下拉选项）
+
+5. **预览代码**：
+   - 进入代码预览步骤
+   - 查看生成的后端、前端、数据库代码
+   - 确认代码内容无误
+
+6. **生成代码**：
+   - 进入代码生成步骤
+   - 选择生成方式（下载ZIP包或写入本地）
+   - 点击相应按钮执行代码生成
+
+7. **集成使用**：
+   - 如果选择了下载方式，解压ZIP包并按项目结构复制到对应目录
+   - 如果选择了写入本地方式，代码已直接写入项目目录
+   - 重启服务，新功能模块即可使用
+
+## 🎯 总结
+
+**FastAPI Vue3 Admin** 前端项目提供了一套完整的企业级后台管理系统解决方案，具有以下优势：
+
+1. **现代化技术栈**：基于 Vue3、Vite、TypeScript 等前沿技术构建
+2. **高度模块化**：清晰的项目结构，便于维护和扩展
+3. **开箱即用**：丰富的功能模块，减少重复开发工作
+4. **易于定制**：灵活的配置选项，适应不同业务需求
+5. **良好文档**：详细的开发指南，降低学习成本
+
+通过本指南，您应该能够快速上手并开发出功能完善的后台管理系统。在开发过程中，建议遵循项目规范，合理利用现有组件和工具，以提高开发效率和代码质量。
+
 ---

 **祝您开发愉快！使用这个模板构建出色的后台管理系统**