fix: repair api server merge fallout

docs/technical/API_SERVER_MERGE_COMPILE_FIX_2026-05-02.md

@@ -0,0 +1,66 @@
+# api-server 合并后编译修复记录
+
+日期：`2026-05-02`
+
+## 背景
+
+`codex/ddd` 合入 `master` 后，`api-server` 编译失败。问题集中在合并后的跨 crate 契约缺口：`api-server` 已引用新接口或新字段，但对应的领域 crate 与 HTTP 转接层没有同步补齐。
+
+## 修复范围
+
+1. `module-auth` 补齐个人资料更新契约：
+   - 新增 `UpdateProfileInput` 与 `UpdateProfileResult`。
+   - `AuthUser` 增加 `avatar_url` 与 `created_at`，并通过 `serde(default)` 兼容旧认证快照。
+   - `PasswordEntryService::update_profile` 统一校验昵称与头像 data URL，并写回认证快照。
+2. 微信绑定手机号结果补齐 `activated_new_user`：
+   - 待绑定微信账号绑定新手机号时返回 `true`，用于注册奖励发放。
+   - 待绑定微信账号合并到已有手机号账号时返回 `false`。
+3. 拼图运行态补齐 HTTP 转接：
+   - `POST /api/runtime/puzzle/runs/{run_id}/drag` 读取 `DragPuzzlePieceRequest`。
+   - 转发到 SpacetimeDB client 的 `drag_puzzle_piece_or_group` procedure 包装。
+4. runtime story 聊天接口改用当前 shared contract：
+   - 旧 `runtime_story::RuntimeStorySnapshotPayload` 已删除。
+   - `api-server` 侧临时别名到 `story::StoryRuntimeSnapshotPayload`，保持现有请求结构不漂移。
+5. `api-server` 全量测试修复：
+   - `custom_world_foundation_draft` 的 mock LLM 响应仍是旧 Chat Completions 结构。
+   - 当前 `LlmClient` 默认走 Responses API，测试 mock 已改为 `output[].content[].text` 结构。
+6. 前端全量测试期望补齐：
+   - 自定义世界结果页的第二幕场景预览断言改为校验第二幕生成图。
+   - 拼图下一关交互测试保留后端下一关调用断言，并明确只调用一次。
+   - 拼图正式 run 客户端补回 `/drag` 调用包装，测试 mock 同步走正式 run 的 `swap/drag` 服务路径。
+7. 前端门禁合并缺口修复：
+   - 拼图测试运行前更新作品时同步提交 `levels`，对齐当前 `updatePuzzleWork` 契约。
+   - 大鱼和 Match3D 测试 mock 对齐当前共享契约，避免 typecheck 阻塞。
+   - 移除 Vite dev proxy 中重复的 `/api/creation` key，避免 build gate 将 warning 视为失败。
+
+## 验证
+
+本次修复应至少通过：
+
+```powershell
+cargo check -p module-auth --manifest-path server-rs\Cargo.toml
+cargo check -p api-server --manifest-path server-rs\Cargo.toml
+cargo test -p module-auth --manifest-path server-rs\Cargo.toml
+cargo test -p api-server --manifest-path server-rs\Cargo.toml
+npm run check:encoding
+npm test
+npm run typecheck
+npm run build
+npm run check:content
+```
+
+后端代码变更后，按项目约束还需要用 `npm run api-server:maincloud` 做一次启动验证。
+
+本轮最终结果：
+
+- `cargo test -p module-auth --manifest-path server-rs\Cargo.toml` 已通过，结果为 `17 passed; 0 failed`。
+- `cargo test -p api-server --manifest-path server-rs\Cargo.toml` 已通过，结果为 `237 passed; 0 failed; 4 ignored`。
+- `cargo test --manifest-path server-rs\Cargo.toml` 已通过，结果同 `api-server` 默认测试。
+- `npm test` 已通过，结果为 `160 passed` 个测试文件、`704 passed` 个用例。
+- `npm run typecheck`、`npm run build`、`npm run check:content`、`npm run check:encoding`、`git diff --check` 已通过。
+- `npm run api-server:maincloud` 已完成启动烟测，`/healthz` 返回 `200`；期间 Maincloud 订阅恢复出现 `503` warning，但未阻止服务启动。
+
+仍需单独处理的非本轮阻塞：
+
+- `cargo test --workspace --manifest-path server-rs\Cargo.toml` 在 Windows 原生测试链接 SpacetimeDB module crate 时失败，缺失 `bytes_sink_write`、`console_log`、`table_id_from_name`、`identity`、`datastore_table_scan_bsatn` 等 SpacetimeDB 宿主符号；这是 module crate 原生 Windows test 链接环境问题。
+- `npm run check` 当前仍会停在全仓 `lint:eslint`，涉及大量既有 import 排序、未使用符号和 hook dependency lint debt；本轮触碰文件已清掉 lint error，仅 `PlatformEntryFlowShellImpl.tsx` 保留既有 hook dependency warnings。