# M6：assets / 阿里云 OSS 任务清单

说明：

1. `editor` 已于 `2026-04-21` 被确认为遗留无用模块，不再纳入本轮 Rust 后端重写范围。
2. 本文件保留原文件名仅用于延续既有任务编号与链接，不再继续安排 editor 迁移项。

## 1. OSS 基础设施

- [x] 创建 OSS bucket 方案
- [x] 设计对象键前缀
- [x] 设计 `object_key -> cdn_url` 解析策略
- [x] 设计 public / private 对象访问策略
- [x] 设计签名 URL 输出策略
- [x] 设计 `x-oss-meta-*` 元数据规范
- [x] 设计内容 hash / 版本字段规范（Stage 1 明确为 `asset_object.content_hash: Option<String>` + `version = 1`，后续强 hash 单独阶段再扩）

## 2. 上传与对象确认

- [x] 实现浏览器 `PostObject` 直传签名接口
- [x] 实现 STS 临时授权接口
- [x] 实现服务端上传 helper
- [x] 实现上传完成后的对象确认接口
- [x] 实现对象绑定业务实体 reducer

补充说明：

1. 自 `2026-04-21` 起，当前重写节奏允许在 `M3/M4/M5` 之前先前置落地 `M6` 的 OSS 基础设施。
2. 当前已在 `server-rs/crates/platform-oss` 与 `server-rs/crates/api-server` 落下最小可用链路：
   - `PostObject` 直传签名能力
   - `/api/assets/direct-upload-tickets`
   - `/api/assets/objects/confirm`
   - 兼容旧 `/generated-*` 前缀的对象键规划
   - `.env/.env.local` 的 OSS 环境变量加载
   - 服务端 `HEAD Object` 校验
   - `asset_object` 确认真实 SpacetimeDB 持久化
   - `/api/assets/objects/bind`
   - `asset_entity_binding` 业务实体槽位绑定
   - `/api/assets/sts-upload-credentials` 禁用式 contract
   - 服务端 `PutObject` 上传 helper
3. 当前 bucket 已明确为私有读写；后续正式存储口径改为 `bucket + object_key` 双列，不再把匿名公开 URL 当成真相。
4. 当前 STS 接口按“服务器上传、Web 只下载”的需求固定为 `403` 禁用式 contract，不向浏览器下发 OSS 写权限。
5. `2026-04-21` 已通过 live test 验证：真实 OSS 上传后，`/api/assets/objects/confirm` 能把 `xushi-dev + object_key` 写入本地 `genarrative-dev.asset_object`，并可继续通过 `/api/assets/objects/bind` 绑定到业务实体槽位。

## 3. 资产任务系统

- [x] 设计 `asset_job`（Stage 1 明确不新增重复表，AI 资产任务先复用 `AiTaskService / ai_task` 口径）
- [x] 设计 `asset_object`
- [x] 设计 `asset_manifest`（Stage 1 使用 OSS JSON manifest + `asset_object` 表达集合对象，不新增结构化表）
- [x] 设计 `character_visual_asset`（Stage 1 使用 `asset_entity_binding: character / primary_visual`，强业务表延后）
- [x] 设计 `character_animation_asset`（Stage 1 使用 `asset_entity_binding: character / animation_set` 绑定总 manifest，强业务表延后）
- [x] 设计 `scene_image_asset`（Stage 1 使用 `asset_entity_binding: custom_world_landmark / scene_image`，强业务表延后）
- [x] 设计 `sprite_sheet_asset`（Qwen 独立工具已清理，Stage 1 仅保留历史 `/generated-qwen-sprites/*` 读取兼容）

补充说明：

1. `asset_object` 当前已冻结核心存储口径为：
   - `bucket`
   - `object_key`
2. 详细设计见：
   - [../docs/technical/SPACETIMEDB_ASSET_OBJECT_STORAGE_DESIGN_2026-04-21.md](../docs/technical/SPACETIMEDB_ASSET_OBJECT_STORAGE_DESIGN_2026-04-21.md)
   - [../docs/technical/SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md](../docs/technical/SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md)
   - [../docs/technical/ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md](../docs/technical/ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md)
   - [../docs/technical/M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md](../docs/technical/M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md)
3. 当前已在 `server-rs/crates/spacetime-module` 落下 `asset_object` 首版表骨架，并完成 `api-server -> SpacetimeDB` 的最小对象确认闭环。
4. 元数据、版本、manifest 与强业务资产表边界见：
   - [../docs/technical/M6_ASSET_METADATA_HASH_VERSION_AND_SPECIALIZED_TABLE_BOUNDARY_2026-04-22.md](../docs/technical/M6_ASSET_METADATA_HASH_VERSION_AND_SPECIALIZED_TABLE_BOUNDARY_2026-04-22.md)

## 4. 资产生成链路

- [x] 迁移角色主形象生成（Stage 1 已接通 Rust `generate / jobs / publish` 最小 OSS 主链，当前仍为 SVG 占位生成，不代表真实 DashScope 图片模型已迁完）
- [x] 迁移角色动作生成（Stage 1 已接通 Rust `generate / jobs / publish` 最小 OSS 主链，当前 `image-sequence` 为 SVG 占位帧，视频类策略优先复用参考视频或仓库占位预览，不代表真实视频模型已迁完）
- [x] 迁移动作模板查询（Stage 1 已接通 Rust 内置模板列表兼容接口）
- [x] 迁移视频导入（Stage 1 已接通 Data URL 视频导入到 OSS 草稿区，不再写本地 `public/`）
- [x] 迁移工作流缓存（Stage 1 已接通 Rust `GET/POST character-workflow-cache` 到 OSS JSON 草稿对象，不再写本地 `public/`）
- [x] 迁移场景图生成（已完成 Stage 2：custom world `scene-image` 走真实 DashScope 图片生成，并继续写入 `OSS + asset_object + asset_entity_binding`）
- [x] 迁移封面图上传（已完成 Stage 2：custom world `cover-image / cover-upload` 已补齐真实 DashScope 生成与 `cropRect + 16:9 + WebP 压缩`）
- [x] 首批收口 custom world `scene-image / cover-image / cover-upload` 到正式 `OSS + asset_object + asset_entity_binding` 主链（保持旧 `/generated-*` 返回 contract，不再写仓库 `public/`）

补充说明：

1. custom world 兼容图片入口现已完成 Stage 1 + Stage 2：正式资产真相链、真实 DashScope 图片生成，以及封面上传裁剪压缩都已迁完。
2. 详细边界见：
   - [../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md](../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md)
3. 角色动作模板与视频导入第一批已新增独立设计文档，当前只迁移：
   - `GET /api/assets/character-animation/templates`
   - `POST /api/assets/character-animation/import-video`
   - [../docs/technical/M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md](../docs/technical/M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md)
4. 角色资产工作流缓存第一批已新增独立设计文档，当前把旧本地 `workflow-cache.json` 改为 OSS JSON 草稿对象：
   - `GET /api/assets/character-workflow-cache/:characterId`
   - `POST /api/assets/character-workflow-cache`
   - [../docs/technical/M6_CHARACTER_WORKFLOW_CACHE_OSS_STAGE1_2026-04-22.md](../docs/technical/M6_CHARACTER_WORKFLOW_CACHE_OSS_STAGE1_2026-04-22.md)
5. `2026-04-22` 复核确认：旧独立 `qwen-sprite-tool + qwenSpriteRoutes.ts` 已在 `2026-04-21` 清理，不再作为本轮现役迁移主链；当前仍保留的 `Qwen` 相关内容仅包括：
   - 角色资产 prompt 层对 `packages/shared/src/prompts/qwenSprite.ts` 的复用
   - 历史资源前缀 `/generated-qwen-sprites/*` 的读取兼容
6. custom world 图片链 Stage 2 已完成：
   - `scene-image / cover-image` 已替换为真实 DashScope 图片生成
   - `cover-upload` 已补回 Node 旧链路中的 `cropRect + 16:9 + WebP 压缩`
   - 详细口径与验证结果见 [../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md](../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md)

## 5. 路径兼容

- [x] 兼容 `/generated-character-drafts/*`
- [x] 兼容 `/generated-characters/*`
- [x] 兼容 `/generated-animations/*`
- [x] 兼容 `/generated-custom-world-scenes/*`
- [x] 兼容 `/generated-custom-world-covers/*`
- [x] 兼容 `/generated-qwen-sprites/*`

补充说明：

1. 第一批路径兼容由 Rust `api-server` 同源代理到私有 OSS 短期读签名，不回退本地 `public/`，详细边界见：
   - [../docs/technical/M6_LEGACY_GENERATED_PATH_OSS_READ_COMPAT_2026-04-22.md](../docs/technical/M6_LEGACY_GENERATED_PATH_OSS_READ_COMPAT_2026-04-22.md)
2. 当前 Stage 1 先全量代理对象内容，不实现视频 Range 分片；若后续真实视频体积变大，再按播放器需求补 Range。

## 6. 兼容接口

- [x] 兼容 `/api/assets/character-visual/generate`
- [x] 兼容 `/api/assets/character-visual/jobs/:taskId`
- [x] 兼容 `/api/assets/character-visual/publish`
- [x] 兼容 `/api/assets/character-animation/generate`
- [x] 兼容 `/api/assets/character-animation/jobs/:taskId`
- [x] 兼容 `/api/assets/character-animation/publish`
- [x] 兼容 `/api/assets/character-animation/import-video`
- [x] 兼容 `/api/assets/character-animation/templates`
- [x] 兼容 `/api/assets/character-workflow-cache`
- [x] 兼容 `/api/assets/character-workflow-cache/:characterId`
## 7. 阶段验收

- [x] OSS 直传对象可被服务端确认并写入 `asset_object`
- [x] 所有新生成资产都写入 OSS（Stage 1 覆盖当前现役角色主形象、角色动作、workflow cache、视频导入、custom world 场景图/封面图；历史清理掉的 Qwen 独立工具不再计入现役主链）
- [x] 前端仍能通过旧路径习惯访问资源（Stage 1 通过 Rust 同源代理私有 OSS 对象，开发期 Vite 代理已覆盖现役 generated 前缀）
- [x] 资产任务状态可查询（角色主形象与角色动作已通过 `jobs/:taskId` 复用 `AiTaskService`；同步上传/确认链路以接口返回结果为状态）
- [x] 已确认对象可绑定到业务实体槽位

补充说明：

1. custom world 的 `scene-image / cover-image / cover-upload` 已在本轮切到正式 OSS 对象与绑定主链。
2. 角色主形象第一批已新增独立设计文档与 Rust 最小闭环：
   - [../docs/technical/M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md](../docs/technical/M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md)
3. 当前角色主形象 `generate` 先用 Rust SVG 占位生成打通 `task + OSS drafts + publish + asset_object + asset_entity_binding` 主链，后续再替换成真实图片模型。
4. 角色动作模板与视频导入第一批已接入 Rust：
   - `templates` 返回旧内置模板 contract。
   - `import-video` 当前只接受 `data:video/*;base64,...`，并写入 OSS `generated-character-drafts/*` 草稿区。
5. 角色资产工作流缓存第一批已接入 Rust：
   - 保存时写入 OSS `generated-character-drafts/{character}/workflow-cache/workflow-cache.json`。
   - 读取时未命中返回 `cache: null`，保持旧前端 contract。
6. 角色动作第一批已接入 Rust：
   - `generate` 直接写入 OSS `generated-character-drafts/*`。
   - `jobs/:taskId` 从 `AiTaskService` 派生旧任务状态 contract。
   - `publish` 会把动作帧与总 manifest 写入 OSS `generated-animations/*`，并确认 `asset_object + asset_entity_binding`。
7. custom world 场景图、封面图、封面上传已在 `M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md` + `M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md` 范围内完成正式 `OSS + asset_object + asset_entity_binding` 主链、真实 DashScope 图片生成和封面上传裁剪压缩。
8. `content_hash/version`、`asset_job`、`asset_manifest` 与强业务资产表当前已冻结 Stage 1 边界，不再作为 M6 第一批工程阻塞项；后续若要做内容去重、manifest 查询、审核/回滚或 sprite sheet 强结构化，再进入独立阶段。