Genarrative/docs/technical/PUZZLE_DRAFT_SESSION_RESTORE_2026-04-23.md

拼图草稿恢复 Agent 会话设计

日期：2026-04-23

1. 背景

当前拼图链已经具备：

1. puzzle_agent_session / puzzle_agent_message 作为聊天真相。
2. get_puzzle_agent_session(sessionId) 可按会话恢复完整消息。
3. puzzle_work_profile 作为创作中心与广场的作品列表投影。

但现状仍有两个断点：

1. compile_puzzle_agent_draft 只把结果页草稿写回 session，没有同步生成 draft 态 puzzle_work_profile。
2. 创作中心点击拼图草稿卡时，只会走“查看详情”，没有利用 sourceSessionId 恢复聊天会话。

这导致“进入创作草稿恢复聊天记录”在拼图链上并不完整。

2. 目标

本轮只实现以下闭环，不扩展到用户级历史列表：

1. 拼图 Agent 编译出结果页草稿后，创作中心必须出现对应草稿卡。
2. 草稿卡必须带 sourceSessionId，作为恢复聊天记录的唯一索引。
3. 点击拼图草稿卡时：
   • 若 session 仍存在且已带 draft，优先进入 puzzle-result。
   • 若 session 存在但尚无 draft，进入 puzzle-agent-workspace。
4. 恢复后继续复用同一个 puzzleSession，返回聊天工作区时能看到完整历史消息。

3. 真相源与投影边界

3.1 真相源

拼图聊天历史、锚点、阶段、结果页草稿仍以 puzzle_agent_session 为准。

3.2 投影

puzzle_work_profile 只承担：

1. 创作中心作品卡展示。
2. 结果页 / 详情页入口锚点。
3. 通过 source_session_id 反查 Agent session。

它不是新的聊天真相，不承担额外会话列表职责。

4. 后端落地

4.1 编译草稿时同步 upsert draft 作品

compile_puzzle_agent_draft 除了更新 session 外，还要：

1. 依据当前 draft 创建或更新一条 PuzzlePublicationStatus::Draft 的 puzzle_work_profile。
2. source_session_id 固定写当前 session id。
3. work_id / profile_id 使用稳定的 session 派生规则，避免同一 session 每次编译都生成新卡。

4.2 图片相关操作持续同步 draft 作品

save_puzzle_generated_images、select_puzzle_cover_image 会改变结果页草稿真相，因此也要同步更新对应 draft 作品记录，保证创作中心卡片封面、摘要、标签与当前草稿一致。

4.3 发布时升级同一条作品记录

publish_puzzle_work 不再新生成随机 work_id / profile_id，而是复用 session 派生的稳定 ID，把同一条 draft 作品升级为 published：

1. 避免创作中心出现“草稿卡 + 已发布卡”两条重复记录。
2. 保持 source_session_id 连续可追溯。

5. 前端落地

5.1 创作中心卡片语义

拼图草稿卡主按钮从 查看详情 改为 继续创作。

5.2 打开拼图草稿

平台壳层新增拼图草稿恢复入口：

1. 读 PuzzleWorkSummary.sourceSessionId。
2. 用现有 getPuzzleAgentSession(sourceSessionId) 拉回 session。
3. 若 session.draft 存在：
   • 写入 puzzleSession
   • 切到 puzzle-result
4. 若 session.draft 不存在：
   • 写入 puzzleSession
   • 切到 puzzle-agent-workspace

5.3 失败回退

如果 sourceSessionId 缺失或对应 session 已失效：

1. 刷新拼图作品列表。
2. 停留在创作中心。
3. 通过现有错误 banner 提示，不新增独立说明 UI。

6. 验收

1. 编译拼图结果页草稿后，创作中心出现 draft 态拼图卡。
2. 草稿卡点击后会恢复对应 puzzleSession.messages。
3. 已有 draft 的 session 恢复后直达结果页，点击返回能看到原聊天记录。
4. 发布后不会额外生成第二条重复作品记录。