Genarrative/backend-rewrite-tasklist/M0_GENERATED_STATIC_PREFIX_BASELINE_2026-04-20.md

M0：/generated-* 静态资源前缀冻结基线

日期：2026-04-20

依据来源：

• ../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md
• server-node/src/modules/assets/characterAssetRoutes.ts
• server-node/src/modules/assets/qwenSpriteRoutes.ts
• server-node/src/services/sceneImageService.ts
• server-node/src/services/customWorldCoverAssetService.ts
• server-node/src/services/customWorldAgentAutoAssetService.ts
• ../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md

1. 文档目的

这份文档用于完成 M0 的第五条任务：

• 整理当前所有 /generated-* 静态资源前缀

这里的“整理”不是只列出几个目录名，而是要求冻结以下信息：

1. 当前哪些 /generated-* 前缀是正式业务前缀。
2. 每个前缀由哪条后端链路产出。
3. 每个前缀对应的当前路径模板是什么。
4. 哪些前缀只是未来设计名或测试噪音，不能误当成当前正式兼容面。

2. 冻结结论

当前工程里，正式业务使用的 /generated-* 静态资源前缀固定为以下 6 个：

前缀	当前状态	当前主要生产链路	当前典型路径模板	重写后兼容要求
/generated-character-drafts/*	正式前缀	角色主形象草稿、动作草稿、导入参考素材	/generated-character-drafts/{characterId}/{kind}/{jobId}/{file}	必须保留
/generated-characters/*	正式前缀	角色主形象正式发布、Agent 自动角色图回填	/generated-characters/{characterId}/visual/{assetId}/{file}	必须保留
/generated-animations/*	正式前缀	角色基础动作正式发布	/generated-animations/{characterId}/{animationSetId}/{action}/{file}	必须保留
/generated-custom-world-scenes/*	正式前缀	世界场景图生成、Agent 自动场景图回填	/generated-custom-world-scenes/{world}/{landmarkOrAct}/{assetId}/{file}	必须保留
/generated-custom-world-covers/*	正式前缀	世界封面图生成、封面上传	/generated-custom-world-covers/{world}/{assetId}/{file}	必须保留
/generated-qwen-sprites/*	正式前缀	Qwen 主图草稿、精灵表草稿、修帧草稿、最终保存	/generated-qwen-sprites/{assetKeyOrDraftScope}/{actionOrKind}/{assetId}/{file}	必须保留

额外结论：

1. 当前仓库里真实业务前缀是 6 个，不是 4 个也不是 5 个。
2. 其中 generated-animations 与 generated-custom-world-covers 是当前代码已正式使用、但早期重写设计里容易漏掉的两个前缀。
3. 当前 public/ 目录下已存在：
   • generated-character-drafts
   • generated-characters
   • generated-qwen-sprites
4. generated-animations、generated-custom-world-scenes、generated-custom-world-covers 当前按需惰性创建，不代表它们不是正式前缀。

3. 正式前缀清单

3.1 /generated-character-drafts/*

当前用途：

1. 角色主形象候选图草稿。
2. 角色动作草稿帧、草稿视频、导入参考素材。
3. 角色资产工作流缓存与任务记录。

当前主要生产链路：

1. POST /api/assets/character-visual/generate
2. POST /api/assets/character-animation/generate
3. POST /api/assets/character-animation/import-video
4. POST /api/assets/character-workflow-cache

当前典型路径模板：

1. /generated-character-drafts/{characterId}/visual/{jobId}/candidate-01.png
2. /generated-character-drafts/{characterId}/animation/{action}/{jobId}/preview.mp4
3. /generated-character-drafts/{characterId}/animation/{action}/{jobId}/frame-01.png
4. /generated-character-drafts/{characterId}-{cacheKey}/workflow-cache.json

冻结要求：

1. 它是“草稿态真相路径”，不是正式发布路径。
2. 重写为 OSS 后仍要保留这一层 HTTP 兼容前缀，哪怕底层已不是本地磁盘。

3.2 /generated-characters/*

当前用途：

1. 角色主形象正式发布路径。
2. Custom World Agent 自动回填的角色主图。

当前主要生产链路：

1. POST /api/assets/character-visual/publish
2. customWorldAgentAutoAssetService

当前典型路径模板：

1. /generated-characters/{characterId}/visual/{assetId}/master.png
2. /generated-characters/{characterId}/visual/{assetId}/preview-01.png

冻结要求：

1. 它是角色正式视觉资产前缀，不允许与草稿前缀混用。
2. 后续即使内部改成 OSS，也必须继续对前端暴露这一前缀。

3.3 /generated-animations/*

当前用途：

1. 角色基础动作正式发布路径。
2. CharacterAnimator 侧消费的核心动画资源前缀。

当前主要生产链路：

1. POST /api/assets/character-animation/publish

当前典型路径模板：

1. /generated-animations/{characterId}/{animationSetId}/{action}/frame-01.png
2. /generated-animations/{characterId}/{animationSetId}/{action}/preview.mp4
3. /generated-animations/{characterId}/{animationSetId}/{action}/manifest.json

冻结要求：

1. 当前正式动画并不挂在 /generated-characters/.../animation/... 下，而是独立前缀 /generated-animations/*。
2. 后续重写若想合并对象键，也必须先做兼容别名，不能直接改掉公开路径。

3.4 /generated-custom-world-scenes/*

当前用途：

1. 自定义世界场景图生成结果。
2. Agent 自动生成的场景图回填结果。

当前主要生产链路：

1. POST /api/custom-world/scene-image
2. customWorldAgentAutoAssetService

当前典型路径模板：

1. /generated-custom-world-scenes/{worldSegment}/{landmarkSegment}/{assetId}/scene.png
2. /generated-custom-world-scenes/{sceneSegment}/{actSegment}/{assetId}/scene.png

冻结要求：

1. 前缀里当前显式带 custom-world-scenes，不是通用 generated-scenes。
2. 后续世界资料库、世界编辑器和 Agent 卡片仍会依赖这一命名习惯。

3.5 /generated-custom-world-covers/*

当前用途：

1. 自定义世界封面图生成结果。
2. 自定义世界封面图上传后规范化结果。

当前主要生产链路：

1. POST /api/custom-world/cover-image
2. POST /api/custom-world/cover-upload

当前典型路径模板：

1. /generated-custom-world-covers/{worldSegment}/{assetId}/cover.png
2. /generated-custom-world-covers/{worldSegment}/{assetId}/manifest.json

冻结要求：

1. 当前正式前缀是 /generated-custom-world-covers/*，不是 /generated-cover-images/*。
2. 后续重写设计和 OSS key 规划必须以这个现状兼容面为准。

3.6 /generated-qwen-sprites/*

当前用途：

1. Qwen 精灵主图草稿。
2. Qwen 精灵表草稿。
3. Qwen 修帧草稿。
4. Qwen 精灵表最终保存结果。

当前主要生产链路：

1. POST /api/assets/qwen-sprite/master
2. POST /api/assets/qwen-sprite/sheet
3. POST /api/assets/qwen-sprite/frame-repair
4. POST /api/assets/qwen-sprite/save

当前典型路径模板：

1. /generated-qwen-sprites/_drafts/master/{draftId}/candidate-01.png
2. /generated-qwen-sprites/_drafts/sheet/{draftId}/candidate-01.png
3. /generated-qwen-sprites/_drafts/repair/{draftId}/candidate-01.png
4. /generated-qwen-sprites/{assetKey}/{actionKey}/{assetId}/sheet.png

冻结要求：

1. 这个前缀当前既承载草稿，也承载正式保存结果。
2. 如果未来要把草稿与正式对象拆桶，也必须先保留同一公开前缀兼容。

4. 非正式前缀与噪音项

以下命名当前不能当成“正式兼容前缀”：

名称	当前来源	处理结论
/generated-cover-images/*	仅出现在重写设计文档旧草案里	这是未来提案名，不是当前工程真实前缀。
/generated-role*	测试数据或示例 ID	不是正式静态资源前缀。
/generated-world*	测试数据或对象 ID	不是正式静态资源前缀。
/generated-ruins*	测试数据或对象 ID	不是正式静态资源前缀。

结论：

1. 后续做 Axum 静态资源兼容层时，只能以第 2 节和第 3 节里的 6 个前缀为正式基线。
2. 不能把测试里的字符串误判成真实资源入口。

5. 与重写设计的对齐要求

为避免后续按错路径重写，当前冻结以下对齐规则：

1. Axum 第一阶段必须兼容这 6 个公开资源前缀。
2. OSS 内部对象键可以调整，但对前端暴露的 URL 前缀不能少于这 6 个。
3. 设计文档里的对象键规划如果与这份基线冲突，以这份“当前工程冻结基线”为准，然后再在设计文档中补兼容说明。

6. 本轮冻结后的硬约束

后续迁移中，不允许出现以下情况：

1. 把 /generated-animations/* 直接并入 /generated-characters/* 却不保留兼容别名。
2. 把 /generated-custom-world-covers/* 擅自改成 /generated-cover-images/*。
3. 在未做兼容层前，删除 /generated-character-drafts/* 或 /generated-qwen-sprites/* 的草稿访问习惯。
4. 仅因为某个目录在当前仓库里尚未生成，就把它从正式前缀清单里删掉。

7. 本任务完成定义

当以下条件成立时，这条任务视为完成：

1. 当前正式 /generated-* 前缀已经有书面冻结清单。
2. 每个前缀都已明确：
   • 当前用途
   • 当前生产链路
   • 当前路径模板
   • 后续兼容要求
3. 已明确哪些“generated-*”字符串只是噪音，不属于正式前缀。

8. 后续直接依赖这份基线的任务

1. 设计 Axum 静态资源兼容层
2. 设计 OSS 对象键与 CDN 别名
3. 做 assets / custom world / editor 的路径回归测试