共享记忆同步 #504 关闭口径：迁移归属与复核条件

- decision-log 2026-09-24 条目补充：#504 以 Reviewed/Won't Fix 关闭，跟踪交回迁移侧，复核与重新打开条件见 #504 关闭评论
- pitfalls 同条目处理口径补上 #504 关闭状态与重新打开路径

docs/project-memory/shared-memory/pitfalls.md

@@ -5952,7 +5952,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - **现象**：打开 AGC 项目后客户端短时间无响应，`/api/runtime/frontend-config`、`/api/llm/models`、`/api/profile/recharge-center` 报「请求超时（15000 ms）」；同时本地 api-server 日志被 `POST /api/agc/project-snapshots/files` 刷屏（全是 200、`latency_ms` 58~61ms、每 60ms 一条）。紧接着项目列表还会被钉成「检查失败」（#490）。
 - **原因**：本地快照索引整份只保存一个账号的基线，同步前按 `user_id` 判等，不等就换成空基线 → 换号后打开项目即整项目重传（春卷冲刺 2311 个文件、约 3 分钟）。对象键带内容摘要、服务端 HEAD 命中即 `200 + skipped`，这批请求全是白跑却完全静默，只有服务端日志量能看出来。真正超时的那一层在客户端：同一窗口服务端对三个接口都是 200、≤61ms，而客户端 webview 的 Tauri 定制协议 IPC 在重传压力下大面积失败（`IPC custom protocol failed … TypeError: Failed to fetch`，刷屏时 ≈0.7 次/秒，而空闲时段 847 行日志里只有 59 次；每次失败还写一行 ~330 字节日志），响应回不到 renderer，JS 侧 15s 计时器先到。
-- **处理（现行口径）**：暂不落地客户端修复——这条链路归入「数据与 IO 往后端挪」的架构迁移，客户端再单独做基线分桶会与之形成两套实现。按账号分桶的实现在分支 `fix/api-timeout`（commit `3be8e40bc`）完成并通过验证，PR #505 已按迁移方向关闭；迁移完成后若该问题仍在，可直接复用该分支或重开 PR。
+- **处理（现行口径）**：暂不落地客户端修复——这条链路归入「数据与 IO 往后端挪」的架构迁移，客户端再单独做基线分桶会与之形成两套实现。按账号分桶的实现在分支 `fix/api-timeout`（commit `3be8e40bc`）完成并通过验证，PR #505 已按迁移方向关闭、issue #504 已按 `Reviewed/Won't Fix` 关闭，跟踪交回迁移侧；迁移完成后若该问题仍在，可直接复用该分支或重开 PR。
 - **排障口径**：遇到「后端日志刷屏 + 客户端报超时」这种组合，先把两侧对齐到同一时间窗：客户端 `diagnostics/application.log` 的 `project_snapshot.sync.*`（看 `uploaded=` 是否等于项目文件数、`skippedRemote=` 是否接近它）对 `logs/api-server/api-server-*.log` 里各 route 的 `http.response`（状态码与 `latency_ms`）。客户端报超时但服务端 200 且毫秒级返回，说明堵在客户端侧，别只盯后端。
 - **验证**：分支 `fix/api-timeout` 上 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell project_snapshot` 26 passed / 0 failed（含「账号切换后基线互不覆盖」「切回旧账号差异为空」）；master 状态无该修复，运行态排障仍可用 `read_local_project_snapshot_state` 观察当前账号的 `fileCount` / `syncRevision`。
 - **关联**：issue #504、issue #490、PR #505（closed）、`apps/ai-game-creator-shell/src-tauri/src/project_snapshot/index.rs`、`docs/project-memory/shared-memory/decision-log.md`（2026-09-24 条目含迁移必须保留的三条约束）。