Jyotisha/TASK-cloud-truth-convergence-20260901.md

任务书 · 本地/云端双份真相收敛（2026-09-01）

基线：origin/staging @ 924f4202（开工时以 origin/staging 最新为准）。这是 BUG-464 / BUG-465 之后的第三轮：前两轮把聊天消息和会话选择的真相收归了服务端，本轮收剩下的三块——星盘库、合盘历史、会话置顶/归档。与任何同期改 frontend/src/app/page.tsx 的轮次不得并行。

---

为什么要做（事故实证）

下面所有行号基于 924f4202，只是线索，按符号定位。

1. 星盘库：云端保存失败会制造"假成功"，下次刷新静默丢数据。 saveOtherChart（page.tsx:2690-2721）在云端 save 抛错时走 catch，把带客户端 UUID 的记录写进本地 state + localStorage，提示"已保存到本地星盘库"。但启动合并逻辑（page.tsx:1528-1537）是云端列表整体替换本地（cloudLibrary.filter(...) 重建，非并集）——那条云端没有的本地记录在下次刷新时无提示消失。用户以为存上了，其实最多活到下一次刷新。
2. 星盘库：云端删除失败会复活。 deleteOtherChart（page.tsx:2733-2755）云端删失败时只删本地，提示文案自己承认"稍后云端可能仍显示旧记录"——下次启动云端替换本地，记录原样回来。
3. 合盘历史：并集合并，删不掉也同步不全。 启动逻辑（page.tsx:1539-1550）把本地和云端按 id 取并集再截 10 条：服务端删掉的记录会从设备本地复活；saveCloudSynastryReport 失败时（page.tsx:3202-3211）记录只进本地，在这台设备靠并集永远活着，换台设备永远看不到。
4. 置顶/归档只存本地。 jyotisha-session-controls:${accountId}:pinned/archived 两个键（page.tsx:1483-1485、1504-1507）没有任何云端对应物：换设备/清浏览器数据，置顶和归档状态全部归零。会话本身早在云端，管理它的状态却在设备上。
5. 历史旁证：仓里存在 20260718100000_repair_missing_chart_profiles.sql、20260718101000_repair_missing_synastry_reports.sql 两个"修数"迁移——这套双份真相已经造过一次事故并被人工修过。

决策记录（产品授权，2026-09-01）

1. 云端为唯一真相。 星盘库与合盘历史的一切读取以云端返回为准；云端写失败 = 操作失败，明确报错、保留用户输入以便重试，不再有"已保存到本地"的降级假成功。现有的 best-effort 文案与行为被本决策推翻。
2. 置顶/归档升级为账户数据（授权本轮加表列，这是三轮里第一次动表结构）：chat_sessions 加 pinned boolean not null default false、archived_at timestamptz null。
3. 一次性导入：首次启动时把本地 pinned/archived 键的存量尽力导入云端（失败静默、不阻塞启动），成功后停写并删除本地键。星盘库/合盘历史的 localStorage 键直接停写停读、启动时清除旧键。
4. 两个合法的本地存留不动：每日星语缓存（day+fingerprint 的当日缓存，服务端每天重新生成，语义就是缓存）；activeChartId（设备级 UI 偏好）。

硬红线

1. 迁移只加列，不改不删既有列；照仓内既有 alter table ... add column if not exists 风格，走用户 RLS（chat_sessions_update_own 已存在，本轮不需要新 RPC、不改 grant）。
2. 不得破坏 BUG-464 的 PATCH 兼容层：/api/sessions/[id] PATCH 对含 messages 的旧请求仍须接受并忽略；chatSessionMetadataPatchSchema 允许扩展 pinned / archived_at 字段，但既有字段语义不变。
3. 数据库测试必须真跑。 本轮动了表结构，npm run test:db 需要 Docker；没有 Docker 就登记 BLOCKED.md 停下，不允许跳过。
4. 不得修改既有测试断言 —— 例外仅限锁住本轮要修缺陷本身的断言（本地降级保存、并集合并、localStorage pinned/archived）；须注释原值与原因，并在 PROGRESS 单列。
5. 推 staging 前必须 ./node_modules/.bin/tsc --noEmit 通过。不要用 npx tsc（空包 tsc@2.0.4 坑）。
6. 测试总数不得低于基线 2424，且 fail=0、skipped=0（有 Docker 环境）。无 Docker 既有缺口为 24 条数据库/部署类失败 + 10 skipped（清单与 924f4202 一致），逐条比对不得新增。
7. 不得改 .gitea/workflows/**。不得在脏工作树切分支。不得自行提升 main。next build 后 / 仍须 ○ Static。
8. 新增/改动的提示文案在浅色深色两套主题下检查。不得手写 useCallback / useMemo。

让步顺序：数据不损坏 > 功能与测试不回归 > 可验证的改进 > 代码整洁。

开工前置

git fetch origin --prune
git worktree add -b codex/cloud-truth-20260901 \
  ../.worktrees/cloud-truth-20260901 origin/staging

基线必须是 origin/staging。读 pre_work_error_ledger.md，跑 scripts/pre_work_check.py，读 frontend/AGENTS.md。改前在 docs/BUG_HISTORY.md 检索（BUG-464/465 是直接上游，两个 repair 迁移是本问题的前科）。

先读这几处再动手：

• page.tsx 星盘库/合盘历史全链路：storage 键（500-523）、启动合并 effect（1514-1560）、云端 helpers（615-690）、saveOtherChart（2680-2721）、deleteOtherChart（2733-2755）、合盘保存（3195-3215）。
• pinned/archived：读写（1483-1507）、消费（1394/1399/2402/4111-4112/4357）。
• frontend/src/app/api/sessions/route.ts 的 SESSION_LIST_COLUMNS 与 frontend/src/lib/chat-session-write-contract.ts 的 chatSessionMetadataPatchSchema（任务 3 的扩展点）。
• /api/chart-profiles、/api/synastry-reports 路由（云端 CRUD 已齐，本轮不需要新端点）。

任务分解

任务 1（P0）· 星盘库云端权威化

• 启动：只从 fetchCloudChartLibrary 取数（self 记录仍由 profile 重建）；本地 jyotisha_chart_library:* 键停读停写，启动时 removeItem 清理。云端拉取失败 → 显示可见错误态与重试入口，不再静默用本地副本。
• 保存/更新：云端成功才更新 state 与 UI；失败保留表单内容、报"保存失败，请重试"，不产生任何本地记录。删除 cloudSaved 双轨文案。
• 删除：云端成功才从 state 移除；失败报错、记录留在列表。
• 验收：断网（或 mock 500）保存一条 → 明确失败、表单未清空、刷新后列表与云端一致无孤儿。

任务 2（P0）· 合盘历史云端权威化

• 启动：云端列表整体替换（不再与本地并集）；本地 jyotisha_synastry_history:* 键停读停写并清理。
• 保存：saveCloudSynastryReport 失败 → 报告仍在当前页面展示（本次会话内存里），但明确提示"未能存入历史"，不写任何本地副本。
• 验收：在云端删一条记录 → 刷新后不复活；mock 保存失败 → 提示出现且刷新后历史里没有幽灵记录。

任务 3（P1）· 置顶/归档上云

• 迁移：chat_sessions 加 pinned、archived_at 两列（决策记录 2），补进 SESSION_LIST_COLUMNS 与列表响应解析。
• 写路径：扩展 chatSessionMetadataPatchSchema 接受 pinned: boolean、archived_at: string|null，置顶/归档动作走既有 PATCH（乐观更新，失败回滚 + 提示）。
• 一次性导入：启动读到本地 pinned/archived 键且非空 → 对存在的会话逐条 PATCH（尽力而为，失败静默），完成后删除本地键；导入只做一次（以本地键存在与否为标志）。
• UI 消费点（1394/1399/2402/4111-4112/4357）改读服务端字段；archived_at 非空即视为归档。
• 验收（db 测试真跑）：迁移幂等重放；PATCH 写入两列走 RLS 只能改自己的；旧 bundle 含 messages 的 PATCH 仍被接受忽略（BUG-464 合同测试保持绿灯）。

任务 4（P2）· 清理

• 删除 readChartLibrary / writeSynastryHistory 等失去用途的本地读写函数与 storage 键常量；page.tsx 里不再残留对三个已废弃键的引用（每日星语与 activeChartId 除外，见决策记录 4）。

总验收

1. tsc --noEmit 通过；测试满足红线 6；npm run test:db 真跑记录输出。
2. next build：/ 仍 ○ Static。
3. 行为实测逐条附进 PROGRESS（无登录态环境则用合同测试覆盖并如实标注）：假成功消失（任务 1）、幽灵复活消失（任务 2）、换设备视角的置顶/归档一致性（任务 3，可用两个浏览器 profile 模拟）、本地旧键被清理且导入只发生一次。
4. localStorage 审计：验收时在浏览器里列出该域名下全部键，除每日星语、activeChartId、jyotisha.session-url-return 及第三方库键外，不得再有本轮三个废弃键。

明确不做（不要顺手做）

• 不拆 page.tsx（P2b 另立任务书，等本轮落地）。
• 不动每日星语缓存与 activeChartId（决策记录 4）。
• 不做星盘库/合盘的离线队列或冲突合并——云端失败就是失败，这是本轮的语义简化，不要把复杂度加回来。
• 不删 BUG-464 的 PATCH 兼容层、不删 consult 的 history 请求字段（另一轮）。