# module-assets 独立模块 package 占位说明

日期：`2026-04-20`

## 1. package 职责

`module-assets` 是资产任务与对象绑定模块 package，后续负责：

1. `asset_job`、`asset_object`、`asset_manifest` 等资产状态模型
2. 角色形象、动作、Qwen 精灵表、场景图、封面图等资产任务编排
3. 业务实体与 OSS 对象的绑定关系
4. 与 `apps/api-server` 的 assets 兼容接口对接
5. 与 `apps/spacetime-module` 的资产表、reducer、view 聚合对接

## 2. 当前阶段说明

当前提交尚未进入完整资产状态建模，但已完成与本模块直接相关的前置基础设施与首版 schema 骨架：

1. `api-server` 已具备 `POST /api/assets/direct-upload-tickets`
2. `platform-oss` 已具备旧 `/generated-*` 前缀兼容的 `PostObject` 签名能力
3. 资产对象引用口径已冻结为 `bucket + object_key` 双列
4. `module-assets` 已落地：
   - `AssetObjectAccessPolicy`
   - `asset_object` 字段校验 helper
   - `assetobj_` ID 前缀与初始版本常量
   - `asset_entity_binding` 输入、快照、返回记录与字段校验 helper
   - `assetbind_` ID 前缀

当前 `asset_object` 表的字段、索引与可编码约束见：

1. [../../../docs/technical/SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md](../../../docs/technical/SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md)
2. [../../../docs/technical/ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md](../../../docs/technical/ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md)
3. [../../../docs/technical/ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md](../../../docs/technical/ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md)

当前还已补齐：

1. `AssetObjectService`
2. 私有 bucket `HEAD Object` 后的对象确认写入
3. 当前阶段的进程内 `asset_object` 去重存储

后续与本 package 直接相关的任务包括：

1. 设计 `asset_job`、`asset_object`、`asset_manifest`
2. 设计角色、动作、场景、精灵表相关资产表
3. 对齐资产生成、发布、对象确认与兼容接口链路
4. 接入 OSS 对象写入与绑定编排

## 3. 边界约束

1. `module-assets` 负责资产任务状态、对象引用关系与模块级编排，不把二进制对象本身放回本地持久化目录真相中。
2. OSS 上传、签名、对象读写等副作用通过平台适配完成，状态最终回写到 `apps/spacetime-module` 聚合的状态模型中。
3. 前端兼容接口由 `apps/api-server` 暴露，但资产任务状态与对象绑定关系不能再次散落到本地文件判断逻辑里。
4. 后续 `SpacetimeDB` 中的对象引用统一按 `bucket + object_key` 两列建模，不存完整 URL 作为真相字段。