Genarrative/docs/technical/ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md

资产对象业务实体绑定 reducer 设计

日期：2026-04-21

1. 文档目的

这份文档用于冻结 M6 中“对象绑定业务实体 reducer”的首版落地方案。

当前已经完成：

1. 浏览器可通过 PostObject 把文件直传到私有 OSS。
2. POST /api/assets/objects/confirm 已能确认对象存在。
3. asset_object 已按 bucket + object_key 写入 SpacetimeDB。

下一步要补上的最小闭环是：

1. 已确认的 asset_object 能绑定到某个业务实体。
2. 绑定关系由 SpacetimeDB 持久化。
3. Axum 提供最小 HTTP facade，避免前端直接拼 SpacetimeDB reducer 参数。

2. 当前阶段不直接创建强业务表的原因

当前先落通用 asset_entity_binding，不直接创建 character_visual_asset / scene_image_asset / sprite_sheet_asset。

原因固定如下：

1. 角色、场景、精灵等强业务表的完整字段还没有冻结。
2. 当前最紧急的工程闭环是“确认后的对象能被实体引用”，不是完整发布模型。
3. 通用绑定表可以先承接旧接口迁移中的 entityId + slot 关系，后续再由强业务表逐步替换或派生。

3. 表设计

首版新增 private table：

1. asset_entity_binding

字段如下：

字段名	类型	必填	说明
binding_id	String	是	主键，固定 assetbind_ 前缀。
asset_object_id	String	是	被绑定的 asset_object.asset_object_id。
entity_kind	String	是	业务实体类型，例如 character、scene、profile。
entity_id	String	是	业务实体 ID。
slot	String	是	实体上的资产槽位，例如 primary_visual、cover、sprite_sheet。
asset_kind	String	是	资产类型，例如 character_visual。
owner_user_id	Option<String>	否	归属用户，当前仅作为服务端传入的记录字段。
profile_id	Option<String>	否	归属 profile。
created_at	Timestamp	是	首次绑定时间。
updated_at	Timestamp	是	最近绑定更新时间。

索引如下：

1. entity_kind + entity_id + slot 用于按实体槽位查当前绑定。
2. asset_object_id 用于按对象反查被哪些业务实体引用。

4. 幂等规则

绑定写入按以下规则执行：

1. asset_object_id 必须已存在于 asset_object。
2. entity_kind + entity_id + slot 作为首版幂等定位键。
3. 同一实体槽位重复绑定时，不新增第二行。
4. 重复绑定会复用原 binding_id 与 created_at，更新 asset_object_id / asset_kind / owner_user_id / profile_id / updated_at。
5. 不同槽位可以绑定同一个 asset_object_id。

5. reducer / procedure 设计

SpacetimeDB 新增：

1. bind_asset_object_to_entity reducer，只返回 Result<(), String>，供后续模块内部复用。
2. bind_asset_object_to_entity_and_return procedure，面向 Axum 同步接口返回最终绑定快照。

procedure 返回结构采用：

1. ok
2. record
3. error_message

与 asset_object 确认 procedure 保持一致，便于 spacetime-client 做统一错误映射。

6. Axum HTTP facade

首版新增接口：

POST /api/assets/objects/bind

请求体：

字段名	类型	必填	说明
assetObjectId	String	是	已确认对象 ID。
entityKind	String	是	业务实体类型。
entityId	String	是	业务实体 ID。
slot	String	是	资产槽位。
assetKind	String	是	资产类型。
ownerUserId	String	否	当前阶段由后端调用方显式传入。
profileId	String	否	当前阶段由后端调用方显式传入。

响应体核心字段：

1. bindingId
2. assetObjectId
3. entityKind
4. entityId
5. slot
6. assetKind
7. ownerUserId
8. profileId
9. createdAt
10. updatedAt

7. 当前阶段安全边界

当前接口是 Axum facade，不是前端直接调用 SpacetimeDB reducer 的最终权限模型。

约束如下：

1. 当前不把长期 OSS AK/SK 下发给客户端。
2. 当前不让客户端直接写 private table。
3. owner_user_id 当前只作为记录字段，不作为可信授权依据。
4. 后续接入 SpacetimeDB 身份透传后，绑定 reducer 的授权必须改为基于可信身份，不信任客户端传入的用户 ID。

8. 完成定义

首版完成条件：

1. module-assets 提供绑定输入、快照、结果结构与字段校验。
2. spacetime-module 新增 asset_entity_binding 表与绑定 reducer/procedure。
3. spacetime-client 生成最新 Rust bindings 并封装绑定 procedure。
4. api-server 暴露 POST /api/assets/objects/bind。
5. 本地测试覆盖字段错误与 “asset_object 不存在不能绑定”。

9. 一句话结论

当前阶段先用通用 asset_entity_binding 把已确认 OSS 对象绑定到业务实体槽位，强业务资产表等字段稳定后再继续拆分。