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

资产历史接口补齐拼图封面素材类型

日期：2026-04-27

背景

拼图结果页会通过 /api/assets/history?kind=puzzle_cover_image 读取历史封面素材，供“生成或更换图片”面板复用旧图。

该链路与角色主视觉、场景图共用同一资产历史接口，因此后端白名单一旦漏掉 puzzle_cover_image，前端就会收到 400 Bad Request，表现为拼图封面历史素材列表无法打开。

本次口径

1. server-rs/crates/api-server/src/assets.rs 中的历史素材类型白名单统一收口为单一常量源。
2. HTTP 层错误文案与实际支持列表由同一函数生成，避免后续再出现“校验改了但提示文案还是旧口径”的漂移。
3. 增加 puzzle_cover_image 的回归测试，确保拼图封面素材不会再次被历史接口遗漏。

后续约束

1. 新增历史素材类型时，必须同时更新：
   • api-server 的 SUPPORTED_ASSET_HISTORY_KINDS
   • spacetime-module 的历史素材白名单
   • 对应前端调用常量与测试
2. 如果运行态仍返回旧白名单错误，优先检查本地 api-server.exe 是否已按最新源码重新编译并重启，而不是先回退前端类型参数。