492 lines
11 KiB
Markdown
492 lines
11 KiB
Markdown
# EasyCode 前台生成工作台设计
|
||
|
||
## 目标
|
||
|
||
新增一个独立前台项目 `easycode-web`，面向普通用户提供从项目需求输入、数据库表生成、表结构编辑、项目代码预览到源码下载的生成工作台。
|
||
|
||
现有 `ruoyi-ui` 继续作为后台管理端，用于管理员维护模板、代码片段、项目配置、用户数据和平台设置。前台用户不跳转到后台登录页，前台登录、项目生成和预览都在 `easycode-web` 内完成。
|
||
|
||
## 范围
|
||
|
||
本次设计覆盖：
|
||
|
||
- 独立前台工程 `easycode-web`
|
||
- 前台用户登录注册
|
||
- 项目草稿数据表
|
||
- 后端前台接口
|
||
- `AiGenerateService` 调用 DeepSeek 生成 MySQL 表结构
|
||
- 数据库结构展示和编辑
|
||
- 后端项目、前台前端、后台前端三类项目结构预览
|
||
- 文件级代码预览
|
||
|
||
不在第一阶段实现：
|
||
|
||
- 前台直接调用 DeepSeek
|
||
- 在线部署运行生成项目
|
||
- 支付、套餐、限流计费
|
||
- 多人协作编辑
|
||
|
||
## 架构
|
||
|
||
系统分为三层：
|
||
|
||
- `easycode-web`：独立 Vue 3 + Vite 前台应用，负责首页、登录、项目生成流程、表结构编辑和代码预览。
|
||
- `ruoyi-admin`：提供前台认证、项目草稿、AI 生成、代码预览和下载接口。
|
||
- `ruoyi-generator`：继续承担模板渲染、项目结构解析、文件内容生成等能力，供前台接口复用。
|
||
|
||
DeepSeek 调用只允许发生在后端：
|
||
|
||
```text
|
||
easycode-web
|
||
-> ruoyi-admin front API
|
||
-> AiGenerateService
|
||
-> DeepSeek API
|
||
-> 结构化结果校验
|
||
-> 项目草稿表 / 生成器元数据
|
||
-> easycode-web 展示和编辑
|
||
```
|
||
|
||
## 前台页面
|
||
|
||
### 首页
|
||
|
||
路径：`/`
|
||
|
||
参考 `easycode_home_prototype.html`，整理为真实中文文案和组件化结构：
|
||
|
||
- 顶部导航：Logo、首页、功能介绍、模板市场、在线预览、价格方案、帮助文档、登录
|
||
- 首屏生成入口：输入项目名称或需求描述，点击“立即生成”
|
||
- 代码预览展示：模拟后端、前台、后台、SQL 项目结构
|
||
- 核心功能区：后端代码生成、前端页面生成、数据库脚本、在线预览、权限系统、源码下载
|
||
- 生成流程区：输入需求、生成数据库、编辑确认、预览项目、下载源码
|
||
- 模板市场区：车辆管理、订单管理、OA、仓库管理等示例
|
||
|
||
点击“登录”进入前台登录页。点击“立即生成”进入前台项目生成页；未登录时先进入前台登录页，登录成功后回到项目生成页。
|
||
|
||
### 登录注册页
|
||
|
||
路径：
|
||
|
||
- `/login`
|
||
- `/register`
|
||
|
||
前台用户和后台用户分离。前台登录成功后保存前台 token，只用于 `/front/**` 接口。
|
||
|
||
### 项目生成页
|
||
|
||
路径：`/generate`
|
||
|
||
页面采用步骤条：
|
||
|
||
1. 生成数据库并编辑表结构
|
||
2. 预览项目
|
||
3. 下载源码
|
||
|
||
第一步表单字段：
|
||
|
||
- 项目名称
|
||
- 项目描述
|
||
- 行业模板，可选
|
||
- 技术栈偏好，可选
|
||
- 额外需求描述
|
||
|
||
点击“生成数据库”后调用后端 AI 生成接口。生成完成后展示表结构和 SQL。
|
||
|
||
### 数据库编辑区
|
||
|
||
展示内容：
|
||
|
||
- 表列表
|
||
- 当前表字段列表
|
||
- SQL 预览
|
||
|
||
可编辑字段：
|
||
|
||
- 表名
|
||
- 表备注
|
||
- 字段名
|
||
- 字段类型
|
||
- Java 类型
|
||
- 是否主键
|
||
- 是否自增
|
||
- 是否必填
|
||
- 是否插入
|
||
- 是否编辑
|
||
- 是否列表展示
|
||
- 是否查询字段
|
||
- 查询方式
|
||
- 显示控件
|
||
- 字典类型
|
||
- 默认值
|
||
- 字段备注
|
||
|
||
保存时后端重新校验表名、字段名、字段类型和 SQL 安全性，再写入项目草稿表。
|
||
|
||
### 项目预览页
|
||
|
||
路径：`/project/:projectId/preview`
|
||
|
||
预览页左侧是项目结构树，右侧是代码预览。
|
||
|
||
结构树分为四个根节点：
|
||
|
||
- 后端项目
|
||
- 前台前端
|
||
- 后台前端
|
||
- SQL 脚本
|
||
|
||
点击文件节点，调用文件内容接口并在右侧展示代码。代码预览支持 Java、XML、SQL、Vue、JavaScript、JSON、YAML、Markdown 的语法高亮。
|
||
|
||
## 后端接口
|
||
|
||
接口统一放在 `/front/**` 下，和后台管理接口分离。
|
||
|
||
### 前台认证
|
||
|
||
```text
|
||
POST /front/auth/register
|
||
POST /front/auth/login
|
||
POST /front/auth/logout
|
||
GET /front/auth/profile
|
||
```
|
||
|
||
### 项目草稿
|
||
|
||
```text
|
||
POST /front/project/create
|
||
GET /front/project/list
|
||
GET /front/project/{projectId}
|
||
PUT /front/project/{projectId}
|
||
DELETE /front/project/{projectId}
|
||
```
|
||
|
||
### 数据库生成和编辑
|
||
|
||
```text
|
||
POST /front/project/{projectId}/generate-database
|
||
GET /front/project/{projectId}/database
|
||
PUT /front/project/{projectId}/database
|
||
POST /front/project/{projectId}/database/validate
|
||
```
|
||
|
||
`generate-database` 输入：
|
||
|
||
```json
|
||
{
|
||
"projectName": "车辆管理系统",
|
||
"projectDesc": "管理车辆、司机、维修、保险和年检",
|
||
"industryTemplate": "vehicle",
|
||
"extraRequirements": "需要车辆维修记录和年检提醒"
|
||
}
|
||
```
|
||
|
||
后端返回结构化表设计和 SQL：
|
||
|
||
```json
|
||
{
|
||
"projectId": 1001,
|
||
"tables": [
|
||
{
|
||
"tableName": "car_info",
|
||
"tableComment": "车辆信息表",
|
||
"columns": [
|
||
{
|
||
"columnName": "car_id",
|
||
"columnType": "bigint(20)",
|
||
"javaType": "Long",
|
||
"javaField": "carId",
|
||
"isPk": "1",
|
||
"isIncrement": "1",
|
||
"isRequired": "1",
|
||
"columnComment": "车辆ID"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"sql": "CREATE TABLE ..."
|
||
}
|
||
```
|
||
|
||
### 项目预览
|
||
|
||
```text
|
||
POST /front/project/{projectId}/preview
|
||
GET /front/project/{projectId}/structure
|
||
GET /front/project/{projectId}/file-content
|
||
GET /front/project/{projectId}/download
|
||
```
|
||
|
||
`file-content` 参数：
|
||
|
||
- `templateType`：`backend`、`frontend`、`admin_frontend`、`sql`
|
||
- `nodeId`
|
||
- `tableId`
|
||
- `category`
|
||
|
||
## 数据表
|
||
|
||
新增前台用户和项目草稿相关表，避免 AI 生成的半成品直接污染后台正式生成配置。
|
||
|
||
### front_user
|
||
|
||
前台用户表。
|
||
|
||
关键字段：
|
||
|
||
- `user_id`
|
||
- `username`
|
||
- `password`
|
||
- `nickname`
|
||
- `email`
|
||
- `phone`
|
||
- `status`
|
||
- `del_flag`
|
||
- `last_login_time`
|
||
- `create_time`
|
||
- `update_time`
|
||
|
||
### front_project
|
||
|
||
前台项目草稿表。
|
||
|
||
关键字段：
|
||
|
||
- `project_id`
|
||
- `user_id`
|
||
- `project_name`
|
||
- `project_file_name`
|
||
- `package_name`
|
||
- `version`
|
||
- `project_desc`
|
||
- `industry_template`
|
||
- `front_framework`
|
||
- `back_framework`
|
||
- `generate_status`
|
||
- `preview_status`
|
||
- `status`
|
||
- `create_time`
|
||
- `update_time`
|
||
|
||
### front_project_table
|
||
|
||
前台项目表设计。
|
||
|
||
字段参考 `gen_table`，增加草稿状态和用户归属：
|
||
|
||
- `table_id`
|
||
- `project_id`
|
||
- `user_id`
|
||
- `table_name`
|
||
- `table_comment`
|
||
- `class_name`
|
||
- `module_name`
|
||
- `business_name`
|
||
- `function_name`
|
||
- `tpl_category`
|
||
- `tpl_web_type`
|
||
- `options`
|
||
- `create_table_sql`
|
||
- `sort`
|
||
- `status`
|
||
|
||
### front_project_column
|
||
|
||
前台项目字段设计。
|
||
|
||
字段参考 `gen_table_column`：
|
||
|
||
- `column_id`
|
||
- `table_id`
|
||
- `project_id`
|
||
- `column_name`
|
||
- `column_comment`
|
||
- `column_type`
|
||
- `java_type`
|
||
- `java_field`
|
||
- `is_pk`
|
||
- `is_increment`
|
||
- `is_required`
|
||
- `is_insert`
|
||
- `is_edit`
|
||
- `is_list`
|
||
- `is_query`
|
||
- `query_type`
|
||
- `html_type`
|
||
- `dict_type`
|
||
- `default_value`
|
||
- `sort`
|
||
|
||
### front_project_generation
|
||
|
||
生成记录表，用于审计 AI 调用和排查问题。
|
||
|
||
关键字段：
|
||
|
||
- `generation_id`
|
||
- `project_id`
|
||
- `user_id`
|
||
- `generate_type`
|
||
- `provider`
|
||
- `prompt_summary`
|
||
- `request_payload`
|
||
- `response_payload`
|
||
- `success`
|
||
- `error_message`
|
||
- `token_usage`
|
||
- `elapsed_ms`
|
||
- `create_time`
|
||
|
||
### front_project_file
|
||
|
||
项目预览文件缓存表，可按需启用。第一版可以不缓存，实时调用生成器生成；如果预览性能不足，再落库缓存。
|
||
|
||
关键字段：
|
||
|
||
- `file_id`
|
||
- `project_id`
|
||
- `template_type`
|
||
- `node_id`
|
||
- `table_id`
|
||
- `file_name`
|
||
- `file_path`
|
||
- `file_content`
|
||
- `content_hash`
|
||
- `create_time`
|
||
- `update_time`
|
||
|
||
## AiGenerateService
|
||
|
||
新增 `AiGenerateService`，职责如下：
|
||
|
||
- 读取 DeepSeek 配置
|
||
- 组装数据库生成 Prompt
|
||
- 调用 DeepSeek API
|
||
- 要求模型返回 JSON
|
||
- 解析并校验 JSON
|
||
- 规范化表名、字段名、字段类型和 Java 字段名
|
||
- 生成 MySQL DDL
|
||
- 写入 `front_project_table` 和 `front_project_column`
|
||
- 写入 `front_project_generation`
|
||
|
||
配置项：
|
||
|
||
- `deepseek.apiKey`
|
||
- `deepseek.baseUrl`
|
||
- `deepseek.model`
|
||
- `deepseek.timeout`
|
||
- `deepseek.maxTables`
|
||
- `deepseek.maxColumnsPerTable`
|
||
|
||
安全规则：
|
||
|
||
- 前端不保存 DeepSeek key
|
||
- 前端不直接访问 DeepSeek
|
||
- 表名和字段名只允许小写字母、数字、下划线
|
||
- 禁止生成 `drop`、`truncate`、`alter user`、`grant`、`revoke` 等危险语句
|
||
- 字段类型只允许白名单内的 MySQL 类型
|
||
- 每次 AI 结果必须后端校验后才能保存
|
||
|
||
## 生成器复用
|
||
|
||
前台预览不重写一套代码生成逻辑，复用 `ruoyi-generator`。
|
||
|
||
适配方式：
|
||
|
||
1. 将 `front_project_table` 和 `front_project_column` 转换为 `GenTable` 和 `GenTableColumn` 结构。
|
||
2. 根据前台项目选择的模板类型，加载后台维护的模板和项目结构。
|
||
3. 调用现有项目结构构建和文件内容生成能力。
|
||
4. 返回结构树和文件内容给 `easycode-web`。
|
||
|
||
模板类型约定：
|
||
|
||
- `backend`：后端项目
|
||
- `frontend`：前台前端项目
|
||
- `admin_frontend`：后台前端项目
|
||
- `sql`：SQL 脚本
|
||
|
||
## 错误处理
|
||
|
||
前端显示明确状态：
|
||
|
||
- AI 生成中
|
||
- 生成成功
|
||
- 生成失败，可重试
|
||
- 表结构校验失败
|
||
- 预览生成失败
|
||
- 文件加载失败
|
||
|
||
后端错误分层：
|
||
|
||
- 参数错误：返回具体字段错误
|
||
- AI 服务错误：记录日志并返回可重试提示
|
||
- AI JSON 解析错误：保存原始响应到生成记录
|
||
- SQL 安全校验失败：返回失败原因和问题表字段
|
||
- 预览生成失败：返回模板文件、表名和异常摘要
|
||
|
||
## 测试
|
||
|
||
后端测试：
|
||
|
||
- `AiGenerateService` JSON 解析测试
|
||
- 表名和字段名安全校验测试
|
||
- MySQL 类型白名单测试
|
||
- 项目草稿保存测试
|
||
- 草稿表转换为 `GenTable` 测试
|
||
- 文件结构和文件内容预览测试
|
||
|
||
前端测试：
|
||
|
||
- 首页跳转
|
||
- 未登录进入生成页时跳前台登录
|
||
- 登录后回到生成页
|
||
- 数据库生成步骤状态切换
|
||
- 表字段新增、编辑、删除
|
||
- 项目结构点击文件并展示代码
|
||
|
||
手工验收：
|
||
|
||
1. 访问前台首页。
|
||
2. 输入“车辆管理系统”，点击立即生成。
|
||
3. 登录前台账号。
|
||
4. 进入项目生成页。
|
||
5. 点击生成数据库。
|
||
6. 页面展示车辆相关 MySQL 表结构。
|
||
7. 编辑字段并保存。
|
||
8. 点击预览项目。
|
||
9. 左侧展示后端项目、前台前端、后台前端和 SQL 脚本。
|
||
10. 点击文件名，右侧展示对应代码。
|
||
|
||
## 分期实施
|
||
|
||
### 一期：前台壳和静态流程
|
||
|
||
- 新增 `easycode-web`
|
||
- 首页、登录注册页、项目生成页、预览页
|
||
- 使用 mock 数据展示数据库结构和代码预览
|
||
- 不调用 DeepSeek
|
||
|
||
### 二期：项目草稿和 AI 数据库生成
|
||
|
||
- 新增前台用户表和项目草稿表
|
||
- 新增前台认证接口
|
||
- 新增项目草稿接口
|
||
- 新增 `AiGenerateService`
|
||
- 接 DeepSeek 生成数据库表结构
|
||
- 前台支持编辑并保存表结构
|
||
|
||
### 三期：生成器预览和下载
|
||
|
||
- 前台草稿表转换为生成器模型
|
||
- 复用后台模板和项目结构
|
||
- 实现后端项目、前台前端、后台前端、SQL 预览
|
||
- 实现源码打包下载
|
||
|
||
## 决策
|
||
|
||
- 前台使用独立项目 `easycode-web`。
|
||
- 前台登录不跳转后台。
|
||
- “立即生成”进入前台项目生成页。
|
||
- DeepSeek 只由后端 `AiGenerateService` 调用。
|
||
- 新增前台用户和项目草稿表。
|
||
- 第一版优先保证生成链路闭环，再扩展在线部署、套餐和模板市场。
|