Document one-click project generation design

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

@@ -0,0 +1,279 @@
+# 一键完整项目生成设计
+
+## 目标
+
+把 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` 返回结构化结果：
+
+```json
+{
+  "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
+  }
+}
+```
+
+失败时也返回阶段化信息：
+
+```json
+{
+  "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` 默认界面。
+- 生成成功后展示运行预览和下载入口。
+- 保留专家模式入口。
+
+第二阶段：
+
+- 支持从失败阶段继续。
+- 优化生成报告。
+- 增加模板项目库匹配能力。
+- 根据模板或行业包提升默认生成质量。
+
+## 自检
+
+- 范围聚焦在一键生成完整项目，不扩展到模板市场或生产部署。
+- 后端采用编排现有能力的方式，不重写生成器。
+- 成功标准明确为在线运行预览可访问。
+- 设计器能力保留为专家模式，不再作为普通用户主路径。
+- 失败处理保留阶段成果，避免运行预览失败导致全部成果不可用。