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