# 一键完整项目生成设计

## 目标

把 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` 默认界面。
- 生成成功后展示运行预览和下载入口。
- 保留专家模式入口。

第二阶段：

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

## 自检

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