Genarrative/docs/technical/API_SERVER_MERGE_COMPILE_FIX_2026-05-02.md

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 视为失败。

验证

本次修复应至少通过：

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。