# 项目一键生成任务总览与跨会话恢复设计

**状态：** 已确认并实施

## 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。
- 进度接口失败不影响项目列表主体。
- 前端契约测试、后端服务与控制器测试、生产构建全部通过。