fix: sync rust api-server runtime and bindings

docs/technical/API_SERVER_CHARACTER_VISUAL_EXTERNAL_GENERATION_RUNTIME_FIX_2026-04-23.md

@@ -0,0 +1,124 @@
+# API Server 角色主形象真实外部生成运行修复记录
+
+日期：`2026-04-23`
+
+## 1. 文档目的
+
+这份文档用于记录本次为了恢复 `api-server` 角色主形象真实外部生成链路而做的最小修复项，避免后续再次出现“源码已切到真实 DashScope + OSS，但实际运行的仍是旧二进制占位链”的误判。
+
+## 2. 背景
+
+在人工验证 `POST /api/assets/character-visual/generate` 时，运行中的本地 `api-server` 返回了 `.svg` 候选图，这与当前 `server-rs/crates/api-server/src/character_visual_assets.rs` 已切到 DashScope 真实图片生成的源码状态不一致。
+
+进一步核查发现，问题不在角色主形象实现本身，而在于当前工作区存在若干增量改动没有补齐编译链，导致 Rust `api-server` 无法重新编译启动，本地仍在运行旧版本二进制。
+
+## 3. 本次最小修复项
+
+### 3.1 `spacetime-client` 缺少 `serde` 依赖
+
+文件：
+
+`server-rs/crates/spacetime-client/Cargo.toml`
+
+现象：
+
+1. 新增 `BigFishWorkSummaryRecord` 时使用了 `serde::Serialize / serde::Deserialize`
+2. `Cargo.toml` 未声明 `serde`
+3. 导致 `cargo check -p api-server --bin api-server` 在依赖阶段直接失败
+
+修复：
+
+1. 为 `spacetime-client` 补充 `serde = { version = "1", features = ["derive"] }`
+
+### 3.2 `password_entry` 错误映射漏掉 `InvalidPublicUserCode`
+
+文件：
+
+`server-rs/crates/api-server/src/password_entry.rs`
+
+现象：
+
+1. `module-auth` 的 `PasswordEntryError` 新增了 `InvalidPublicUserCode`
+2. `api-server` 侧的错误映射 `match` 未覆盖该分支
+3. 导致 `api-server` 编译失败
+
+修复：
+
+1. 在 `map_password_entry_error(...)` 中补充 `InvalidPublicUserCode`
+2. 返回中文错误文案 `叙世号格式不正确`
+
+### 3.3 `module-custom-world` 的 `Display` 分支未覆盖新字段错误
+
+文件：
+
+`server-rs/crates/module-custom-world/src/lib.rs`
+
+现象：
+
+1. `CustomWorldFieldError` 新增了 `MissingPublicWorkCode`
+2. `impl fmt::Display for CustomWorldFieldError` 未覆盖该枚举分支
+3. 导致依赖 `module-custom-world` 的 `api-server` 编译链继续失败
+
+修复：
+
+1. 为 `MissingPublicWorkCode` 补充显示文案
+2. 文案口径为 `custom_world_gallery_detail.public_work_code 不能为空`
+
+### 3.4 `spacetime-module / spacetime-client` 绑定链路需要重新同步
+
+文件：
+
+1. `server-rs/crates/spacetime-module/src/lib.rs`
+2. `server-rs/crates/spacetime-module/src/big_fish/*.rs`
+3. `server-rs/crates/spacetime-client/src/lib.rs`
+4. `server-rs/crates/spacetime-client/src/module_bindings/*`
+
+现象：
+
+1. `custom_world` 新增 `public_work_code / author_public_user_code` 后，`spacetime-module` 与 `spacetime-client` 的手写 facade / 自动生成 bindings 不一致
+2. `spacetime generate` 无法顺利完成，导致 `spacetime-client` 继续引用过期 schema
+3. `Big Fish` 子模块拆分后，子文件缺少表 accessor trait 导入，阻断 wasm 构建与 bindings 生成
+
+修复：
+
+1. 补齐 `Big Fish` 子模块对表 accessor trait 的导入
+2. 补齐 `CustomWorldPublishWorldInput` 在 agent 发布动作中的新字段
+3. 补齐 `spacetime-client` 对 `publish_custom_world_profile` 与 `get_custom_world_gallery_detail_by_code` 的 facade 映射
+4. 重新执行：
+
+```powershell
+spacetime generate --no-config --lang rust --out-dir D:\Genarrative\server-rs\crates\spacetime-client\src\module_bindings --module-path D:\Genarrative\server-rs\crates\spacetime-module --include-private --yes
+```
+
+说明：
+
+1. 这一步完成后，`spacetime-client` 已重新拿到最新 `custom_world_*` / `big_fish_*` bindings
+2. `wasm-opt` 缺失只影响优化，不影响 bindings 生成与本地运行验证
+
+## 4. 修复后结论
+
+修复完成后，执行：
+
+```powershell
+cargo check -p api-server --bin api-server
+```
+
+已通过。
+
+## 5. 新运行结果
+
+在新的本地 `api-server` 实例上执行：
+
+`POST /api/assets/character-visual/generate`
+
+返回结果已经从旧 `.svg` 候选切换为真实 `.png`：
+
+`/generated-character-drafts/codex-direct-test-character-v2/visual/aitask_6501f99c694c3/candidate-01.png`
+
+同时通过 OSS 签名读取再次确认：
+
+1. `HTTP 200`
+2. `Content-Type: image/png`
+3. PNG 文件头校验通过
+
+这说明当前源码级的 Rust `api-server` 已具备重新启动并承载角色主形象真实外部图片生成链的条件，本地旧 SVG 返回问题的根因就是运行进程落后于当前源码与 bindings 状态。