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 调用只允许发生在后端：

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/** 下，和后台管理接口分离。

前台认证

POST /front/auth/register
POST /front/auth/login
POST /front/auth/logout
GET  /front/auth/profile

项目草稿

POST /front/project/create
GET  /front/project/list
GET  /front/project/{projectId}
PUT  /front/project/{projectId}
DELETE /front/project/{projectId}

数据库生成和编辑

POST /front/project/{projectId}/generate-database
GET  /front/project/{projectId}/database
PUT  /front/project/{projectId}/database
POST /front/project/{projectId}/database/validate

generate-database 输入：

{
  "projectName": "车辆管理系统",
  "projectDesc": "管理车辆、司机、维修、保险和年检",
  "industryTemplate": "vehicle",
  "extraRequirements": "需要车辆维修记录和年检提醒"
}

后端返回结构化表设计和 SQL：

{
  "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 ..."
}

项目预览

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