Genarrative/docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md

拼图生成图片资源代理修复

日期：2026-04-27

背景

拼图结果页的“生成或更换图片”会在 api-server 中调用 DashScope 生成图片，再把候选图上传到 OSS，最终以 /generated-puzzle-assets/... 旧兼容路径写回 PuzzleGeneratedImageCandidate.image_src 与草稿封面字段。

本次排查发现拼图图片写入路径已经进入 platform-oss::LegacyAssetPrefix::PuzzleAssets，但后端 Axum 旧资源代理和 Vite 本地代理没有挂载 /generated-puzzle-assets。这会导致候选图或正式图无法读取；后续如果把已有候选图作为参考图继续更换图片，也会让参考图读取链路失效。

修复口径

1. server-rs/crates/api-server/src/legacy_generated_assets.rs 增加 proxy_generated_puzzle_assets(...)，复用统一的 OSS 签名读取逻辑。
2. server-rs/crates/api-server/src/app.rs 挂载 /generated-puzzle-assets/{*path}，与角色、大鱼、自定义世界图片资源前缀保持一致。
3. vite.config.ts 增加 /generated-puzzle-assets dev proxy，保证本地网页端不会因为 Vite 代理缺口读不到后端资源。

后续约束

1. 任何新增 LegacyAssetPrefix 都必须同时检查：
   • platform-oss 前缀枚举
   • api-server 旧资源代理路由
   • Vite dev proxy
   • 前端 isGeneratedLegacyPath(...) 是否能识别
2. 拼图候选图 JSON 仍保持 SpacetimeDB 持久化结构 PuzzleGeneratedImageCandidate 的 snake_case 字段，不把 HTTP camelCase 响应结构写入 draft_json。
3. 图片生成、OSS 读写和外部参考图解析继续留在 api-server，不能下沉到 SpacetimeDB reducer。

验收

1. npm run check:encoding
2. cargo check -p api-server --manifest-path server-rs/Cargo.toml
3. npm run api-server:maincloud 重启后，点击拼图结果页“生成或更换图片”，候选图应能写回并正常展示。