yidaima/RuoYi-Vue/docs/superpowers/specs/2026-05-21-easycode-front-workbench-design.md

# 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` 调用。
- 新增前台用户和项目草稿表。
- 第一版优先保证生成链路闭环，再扩展在线部署、套餐和模板市场。