# 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。