109 lines
5.0 KiB
Markdown
109 lines
5.0 KiB
Markdown
# 项目一键生成任务总览与跨会话恢复设计
|
|
|
|
**状态：** 已确认并实施
|
|
|
|
## 1. 背景
|
|
|
|
一键生成页已经能够展示生成阶段、进度、失败原因、重试、源码预览和下载，但任务恢复依赖浏览器 `localStorage`。用户清理缓存、换浏览器或从“我的项目”重新进入时，无法可靠定位服务器上的生成任务。
|
|
|
|
“我的项目”也只展示草稿、已生成数据库和已预览等静态状态，不能回答三个最重要的问题：项目是否正在生成、生成到了哪一步、点击后能否继续查看同一个任务。
|
|
|
|
本轮回到 AI Software Factory 的用户主流程，不继续扩展 Plugin 交付基础设施。
|
|
|
|
## 2. 目标
|
|
|
|
- “我的项目”展示每个项目最新的一键生成任务状态、进度和当前步骤。
|
|
- 用户点击进度入口后，生成页通过服务器任务 ID 恢复同一个任务。
|
|
- 新建一键生成任务后立即把任务 ID 写入路由，刷新或分享当前地址仍能定位任务。
|
|
- `localStorage` 继续作为旧入口的兼容兜底，但不再是唯一任务来源。
|
|
- 总览接口保持轻量，不返回请求提示词、生成结果、阶段清单或检查点大字段。
|
|
- 生成进度接口失败时，“我的项目”仍能正常展示项目数据。
|
|
|
|
## 3. 非目标
|
|
|
|
- 不修改一键生成 Pipeline、Stage Handler、Prompt 或模型调用语义。
|
|
- 不新增数据库表或执行数据库迁移。
|
|
- 不在项目列表直接执行重试、取消、预览或下载；这些操作仍由生成工作台承接。
|
|
- 明文开发凭据和跳过 TLS 校验按用户决定继续暂缓，本轮不修改相关配置。
|
|
|
|
## 4. 用户体验
|
|
|
|
“我的项目”新增“一键生成”列。每行固定展示状态文本、进度条、当前步骤或失败原因，以及一个紧凑图标入口。没有任务时入口用于开始生成；运行中用于查看进度；失败或等待重试时用于恢复处理；成功后用于查看结果。
|
|
|
|
入口路由格式为：
|
|
|
|
```text
|
|
/generate?projectId={projectId}&mode=one-click&taskId={taskId}
|
|
```
|
|
|
|
没有历史任务时省略 `taskId`。生成页优先按路由任务 ID 查询服务器；没有路由任务 ID 时才读取本地缓存中的旧任务记录。
|
|
|
|
## 5. 服务端契约
|
|
|
|
新增接口：
|
|
|
|
```http
|
|
GET /front/project/ai-tasks/one-click-overview
|
|
```
|
|
|
|
接口从当前登录用户身份取数，并为每个项目返回 `generate_type = one_click_project` 的最新任务。最新任务按递增 `task_id` 判定，重试仍更新同一任务，不会制造额外列表项。
|
|
|
|
响应项只包含：
|
|
|
|
| 字段 | 用途 |
|
|
| --- | --- |
|
|
| `taskId` | 恢复具体任务 |
|
|
| `projectId` | 与项目列表关联 |
|
|
| `generateType` | 防止任务类型混用 |
|
|
| `status` | 状态展示与动作判断 |
|
|
| `progress` | 进度条 |
|
|
| `currentStep` | 当前阶段摘要 |
|
|
| `errorMessage` | 失败摘要 |
|
|
| `attempts` / `maxAttempts` | 重试信息 |
|
|
| `createTime` / `updateTime` | 排序和审计摘要 |
|
|
|
|
`requestPayload`、`resultPayload`、Prompt 身份、Stage Manifest 和 Checkpoint 不进入该响应。
|
|
|
|
## 6. 数据流
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as 用户
|
|
participant L as 我的项目
|
|
participant A as FrontProject API
|
|
participant G as 生成工作台
|
|
|
|
U->>L: 打开项目列表
|
|
par 项目数据
|
|
L->>A: GET /front/project
|
|
and 最新一键任务
|
|
L->>A: GET /front/project/ai-tasks/one-click-overview
|
|
end
|
|
A-->>L: 项目与轻量任务总览
|
|
U->>L: 点击生成进度入口
|
|
L->>G: projectId + mode + taskId
|
|
G->>A: GET /front/project/{projectId}/ai-tasks/{taskId}
|
|
A-->>G: 完整任务状态
|
|
G->>G: 恢复进度、结果或轮询
|
|
```
|
|
|
|
## 7. 错误与并发处理
|
|
|
|
- 总览接口失败时只提示“生成进度暂时无法加载”，项目列表继续使用项目接口结果。
|
|
- 路由任务不存在、无权访问或类型不是一键生成时，生成页保留项目草稿并显示恢复错误。
|
|
- 项目切换时取消旧轮询；任务路由监听会忽略正在加载的项目和当前已显示的同一任务，避免重复轮询。
|
|
- 同一项目切换到另一个任务时先使旧轮询失效；即使新目标已经终态，旧轮询也不能覆盖路由指定任务。
|
|
- 新任务创建后先写入当前任务状态和本地兼容缓存，再同步路由并开始轮询。
|
|
- 路由同步失败不会中止已经在服务器创建的生成任务。
|
|
|
|
## 8. 验收标准
|
|
|
|
- 项目列表一次加载即可展示每个项目最新的一键生成状态。
|
|
- 点击列表入口后，地址包含对应 `projectId` 和 `taskId`。
|
|
- 清除本地任务缓存后，使用该地址仍能从服务器恢复任务。
|
|
- 新建任务后地址中的 `taskId` 更新为新任务，不会在刷新后恢复旧任务。
|
|
- 同一项目切换不同 `taskId` 后，旧轮询不能覆盖当前任务或清除新任务的生成状态。
|
|
- 总览响应不包含请求和结果 Payload。
|
|
- 进度接口失败不影响项目列表主体。
|
|
- 前端契约测试、后端服务与控制器测试、生产构建全部通过。
|