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

状态： 已确认并实施

1. 背景

一键生成页已经能够展示生成阶段、进度、失败原因、重试、源码预览和下载，但任务恢复依赖浏览器 localStorage。用户清理缓存、换浏览器或从“我的项目”重新进入时，无法可靠定位服务器上的生成任务。

“我的项目”也只展示草稿、已生成数据库和已预览等静态状态，不能回答三个最重要的问题：项目是否正在生成、生成到了哪一步、点击后能否继续查看同一个任务。

本轮回到 AI Software Factory 的用户主流程，不继续扩展 Plugin 交付基础设施。

2. 目标

“我的项目”展示每个项目最新的一键生成任务状态、进度和当前步骤。
用户点击进度入口后，生成页通过服务器任务 ID 恢复同一个任务。
新建一键生成任务后立即把任务 ID 写入路由，刷新或分享当前地址仍能定位任务。
localStorage 继续作为旧入口的兼容兜底，但不再是唯一任务来源。
总览接口保持轻量，不返回请求提示词、生成结果、阶段清单或检查点大字段。
生成进度接口失败时，“我的项目”仍能正常展示项目数据。

3. 非目标

不修改一键生成 Pipeline、Stage Handler、Prompt 或模型调用语义。
不新增数据库表或执行数据库迁移。
不在项目列表直接执行重试、取消、预览或下载；这些操作仍由生成工作台承接。
明文开发凭据和跳过 TLS 校验按用户决定继续暂缓，本轮不修改相关配置。

4. 用户体验

“我的项目”新增“一键生成”列。每行固定展示状态文本、进度条、当前步骤或失败原因，以及一个紧凑图标入口。没有任务时入口用于开始生成；运行中用于查看进度；失败或等待重试时用于恢复处理；成功后用于查看结果。

入口路由格式为：

/generate?projectId={projectId}&mode=one-click&taskId={taskId}

没有历史任务时省略 taskId。生成页优先按路由任务 ID 查询服务器；没有路由任务 ID 时才读取本地缓存中的旧任务记录。

5. 服务端契约

新增接口：

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. 数据流

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

5.0 KiB Raw Permalink Blame History