diff --git a/RuoYi-Vue/docs/superpowers/specs/2026-05-21-easycode-front-workbench-design.md b/RuoYi-Vue/docs/superpowers/specs/2026-05-21-easycode-front-workbench-design.md new file mode 100644 index 0000000..04a1228 --- /dev/null +++ b/RuoYi-Vue/docs/superpowers/specs/2026-05-21-easycode-front-workbench-design.md @@ -0,0 +1,491 @@ +# 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` 调用。 +- 新增前台用户和项目草稿表。 +- 第一版优先保证生成链路闭环，再扩展在线部署、套餐和模板市场。