yidaima/RuoYi-Vue/docs/superpowers/specs/2026-06-27-one-click-project-generation-design.md

一键完整项目生成设计

目标

把 EasyCode 的默认体验拉回最初的产品初心：用户输入项目名称，点击一次“生成完整项目”，系统自动生成后端、用户前台、后台管理端和 SQL，并启动在线运行预览。

第一版成功标准不是“源码结构生成完成”，而是生成项目的在线运行预览达到可访问状态。生成完成页应优先展示用户前台地址、后台管理端地址、源码下载和生成报告。

背景

当前项目已经具备不少底层能力：

• 系统蓝图生成：角色、前台菜单、后台菜单、页面清单。
• 数据库生成与保存：AI 生成表结构、字段、SQL，并持久化到前台项目草稿。
• 业务流程生成：基于安全 DSL 生成状态流转、数量变化、插入、更新等业务动作。
• 页面设计器：支持前台和后台页面初始化、页面设计和业务块配置。
• 结构预览与下载：可生成 backend、frontend、admin_frontend、sql 四类源码结构。
• 在线运行预览：可解压生成源码，初始化预览数据库，启动后端和前端进程。

问题不是能力缺失，而是默认链路变成了“多个设计器和多个按钮的低代码工作台”。普通用户需要理解系统蓝图、数据库结构、业务动作、页面设计等中间概念，体验上偏离了“输入项目名，自动得到完整项目”。

已确认决策

• 第一版目标选 B：生成后能在线运行预览。
• 输入边界：项目名称必填，需求描述可选。只填“图书借阅系统”也应能生成默认可运行项目。
• 默认生成范围：后端、用户前台、后台管理端和 SQL。高级设置允许关闭用户前台。
• 流程策略：默认一键到底，不在中间强制用户确认；专家模式允许逐步查看和修正。
• 项目类型范围：带常见业务闭环的项目，不止 CRUD。第一版支持状态流转、提交、审核、取消、借还、归还、完成、库存或数量变化等安全 DSL 可覆盖的动作。
• 实现路线：以“后端新增一键生成编排任务”为主；模板项目库作为后续增强。

非目标

第一版不追求任意复杂业务逻辑，不允许 AI 生成任意 Java 或 SQL 片段，不建设完整行业模板市场，不做多人协作编辑，不做生产级部署发布。

模板优先生成是后续增强：未来可以先匹配模板或行业包，再由 AI 补齐字段、页面和业务动作；第一版先把通用一键生成编排器做稳。

用户体验

GenerateView 默认改成一键生成入口：

• 项目名称输入框。
• 可选需求描述输入框。
• 折叠的高级设置：是否生成用户前台、行业模板、后台模块选择。
• 主按钮：“生成完整项目”。
• 任务进度区。
• 生成结果区。

生成中页面展示阶段进度：

1. 规划项目。
2. 生成数据。
3. 生成业务。
4. 生成页面。
5. 生成源码。
6. 运行预览。

生成成功后，页面优先展示成果：

• 打开用户前台。
• 打开后台管理端。
• 进入完整预览页。
• 下载完整源码。
• 查看生成报告。

现有设计器不删除，改为专家模式入口。用户生成后不满意时，可以进入“调整项目 / 专家模式”修改系统蓝图、数据库结构、业务流程或页面设计，然后重新生成完整项目或重建预览。

后端架构

新增一键生成任务类型，例如 one_click_project。该任务复用现有 front_ai_generation_task 任务中心，不另建任务系统，以继续使用现有队列、重试、额度、生成记录和轮询接口。

任务由 AiGenerationTaskWorker 识别 one_click_project 后交给新的编排服务执行，例如 OneClickProjectGenerationService。编排服务只负责串联现有能力，不重新实现底层生成器。

建议依赖：

• IAiGenerateService：生成系统蓝图、数据库和业务动作。
• IFrontProjectService：保存或读取项目草稿和数据库。
• FrontendPageDesignService：初始化前台和后台页面设计。
• IFrontProjectPreviewService：校验源码结构、标记预览可用、下载源码。
• IFrontProjectRunPreviewService：启动并查询在线运行预览。

编排阶段

一键任务按固定阶段执行，并在每个阶段开始和结束时更新 progress、currentStep 和阶段信息。

1. 准备项目

确保项目归属正确，保存项目名称、需求描述、行业模板、是否生成用户前台等配置。默认启用用户前台。

2. 生成系统蓝图

调用 generateAppBlueprint，生成角色、前台菜单、后台菜单和前台页面清单。

验收标准：

• 角色列表不为空。
• 前台菜单或前台页面清单不为空，除非用户关闭用户前台。
• 后台菜单不为空。
• 前台页面包含可初始化页面所需的 pageCode、pageType 和业务表引用信息。

3. 生成数据库

调用 generateDatabase，根据项目名称、需求描述和确认后的系统蓝图生成表结构并持久化。

验收标准：

• 表数量大于 0。
• 每张表至少有主键和有效字段。
• 字段名、表名、类型通过现有安全校验。
• SQL 能被结构预览阶段使用。

4. 生成业务动作

调用 generateBusinessBlueprint，生成安全 DSL 业务动作。

验收标准：

• 业务动作可以为空，但如果项目名称明显包含流程型业务，应尽量生成至少一个业务动作。
• 所有 ownerTable、规则字段和影响字段必须存在于保存后的表结构。
• 只允许安全 DSL 支持的动作类型，如状态流转、插入、更新、数量增加或减少。

5. 初始化页面设计

调用 FrontendPageDesignService.initializePageDesigns(userId, projectId, "frontend") 和 "admin"。

验收标准：

• 用户前台启用时，前台至少有首页和业务页面。
• 后台至少有首页和业务管理页面。
• 初始化不会覆盖用户已经保存的同 pageCode 设计。

6. 生成源码结构

调用现有预览结构能力，确保 backend、admin_frontend、sql 可渲染；用户前台启用时还要校验 frontend。

验收标准：

• 四类结构中启用的部分都能返回文件树。
• 下载完整源码包可用。
• previewStatus 标记为可预览。

7. 启动在线运行预览

调用 IFrontProjectRunPreviewService.start 启动预览，然后轮询 status，直到状态为 RUNNING 或超时失败。

验收标准：

• 用户前台启用时，frontendUrl 可访问。
• 后台管理端 adminFrontendUrl 可访问。
• 后端地址、端口、工作区路径和日志可返回给前端。

任务结果

一键任务成功后，resultPayload 返回结构化结果：

{
  "projectId": 1001,
  "stage": "RUN_PREVIEW",
  "downloadReady": true,
  "backendUrl": "http://127.0.0.1:9001",
  "frontendUrl": "http://127.0.0.1:9002",
  "adminFrontendUrl": "http://127.0.0.1:9003",
  "previewStatus": "RUNNING",
  "report": {
    "tables": 6,
    "businessActions": 4,
    "frontendPages": 5,
    "adminPages": 6
  }
}

失败时也返回阶段化信息：

{
  "projectId": 1001,
  "stage": "RUN_PREVIEW",
  "downloadReady": true,
  "failedStage": "RUN_PREVIEW",
  "errorMessage": "后台前端进程已退出",
  "suggestedActions": ["RETRY_RUN_PREVIEW", "OPEN_LOGS", "DOWNLOAD_SOURCE", "OPEN_EXPERT_MODE"]
}

失败恢复

一键生成失败不等于所有成果作废。系统应保留已完成阶段的产物，并在报告里明确可用内容。

• AI 调用失败：沿用现有任务重试策略。
• 蓝图或数据库校验失败：展示校验原因，引导用户补充需求或进入专家模式。
• 页面初始化失败：允许进入专家模式修正系统蓝图或数据库。
• 源码结构失败：展示模板和文件类型相关错误。
• 运行预览失败：保留源码下载、结构预览和日志入口。

第一版可以先支持“重新运行一键生成”和“重试运行预览”。更细粒度的“从失败阶段继续”作为后续增强，但数据结构中应保留 stage 或 failedStage 字段。

前端改造

GenerateView 的默认职责变为：

• 创建或更新项目。
• 创建 one_click_project 任务。
• 轮询任务状态。
• 展示阶段进度。
• 展示成功结果或失败报告。
• 提供专家模式入口。

现有面板迁移到专家模式：

• AppBlueprintPanel：系统蓝图调整。
• DatabaseDesigner 和 ER 图：数据库结构调整。
• BusinessBlueprintPanel：业务动作调整。
• 页面设计入口：继续跳转到独立 PageDesignerView。
• PreviewView：继续负责完整源码结构、运行 iframe、日志和下载。

路由可以先保持 /generate?projectId=...，通过页面内模式切换实现普通模式和专家模式。后续如果需要更清晰的信息架构，再补 /project/:projectId/workspace。

测试策略

后端单测：

• one_click_project 任务类型可通过校验。
• 编排服务按顺序调用系统蓝图、数据库、业务动作、页面初始化、结构预览和运行预览。
• 每个阶段失败时，任务记录正确的 currentStep、失败阶段和错误信息。
• 运行预览达到 RUNNING 时才返回成功。
• 运行预览失败但源码已生成时，downloadReady 仍为 true。

后端集成测试：

• 使用固定项目名称“图书借阅系统”的假数据或 mock AI 响应，验证 backend、frontend、admin_frontend、sql 结构都能渲染。
• 验证业务动作 DSL 能进入生成模板上下文。
• 验证页面初始化后能生成前台和后台页面设计记录。

前端测试：

• GenerateView 默认展示一键入口，而不是默认展开数据库和业务流程设计器。
• 点击“生成完整项目”后创建 one_click_project 任务并轮询。
• 成功后展示用户前台、后台管理端、下载和预览入口。
• 失败后展示失败阶段、错误信息、日志或专家模式入口。
• 专家模式能展示现有蓝图、数据库、业务动作和页面设计入口。

人工验收：

1. 登录前台。
2. 进入生成页。
3. 输入“图书借阅系统”。
4. 不填写需求描述。
5. 点击“生成完整项目”。
6. 等待任务进入运行预览完成状态。
7. 打开用户前台，能看到图书或借阅相关页面。
8. 打开后台管理端，能看到对应管理菜单。
9. 下载源码包，确认包含后端、用户前台、后台管理端和 SQL。
10. 如果运行预览失败，页面能展示失败阶段、日志和源码下载入口。

分期

第一阶段：

• 新增 one_click_project 任务类型和后端编排服务。
• 复用现有任务轮询接口。
• 简化 GenerateView 默认界面。
• 生成成功后展示运行预览和下载入口。
• 保留专家模式入口。

第二阶段：

• 支持从失败阶段继续。
• 优化生成报告。
• 增加模板项目库匹配能力。
• 根据模板或行业包提升默认生成质量。

自检

• 范围聚焦在一键生成完整项目，不扩展到模板市场或生产部署。
• 后端采用编排现有能力的方式，不重写生成器。
• 成功标准明确为在线运行预览可访问。
• 设计器能力保留为专家模式，不再作为普通用户主路径。
• 失败处理保留阶段成果，避免运行预览失败导致全部成果不可用。