feat: restore agent sessions from creation drafts

docs/technical/PUZZLE_DRAFT_SESSION_RESTORE_2026-04-23.md

@@ -0,0 +1,100 @@
+# 拼图草稿恢复 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. 发布后不会额外生成第二条重复作品记录。