docs: 记录当前版本模特库与演员数据流

docs/todo/模特库与我的演员数据流说明.md

@@ -0,0 +1,164 @@
+# 模特库与“我的演员”数据流说明
+
+> 版本备注：本文记录的是当前版本现状，用于后续“模特与演员合并”方案讨论前留档；不是最终目标设计。
+
+## 结论
+
+`/models` 的模特库和“图片生成 -> 选择模特 -> 我的演员”不是完全同一张表。
+
+- `/models` 读的是顶级 `Model` 实体表。
+- “我的演员”读的是 `Asset` 表里 `category=person` 的人物资产。
+- 图片生成里的“演员库”弹窗会把两类数据合并展示。
+
+一句话区分：
+
+- 演员 = `Asset(category=person)` 人物资产。
+- 模特库 = `Model` 顶级实体，通常由演员形象图 + 三视图收编而来。
+
+## Asset 与项目资产的关系
+
+`Asset` 不是只属于视频项目的“项目资产表”，它更像团队级素材总仓。
+
+`Asset` 里可以放：
+
+- 人物/演员图：`person`
+- 商品图：`product_image`
+- 场景图：`scene`
+- 模特上身图：`model_tryon`
+- 平台套图：`platform_kit`
+- 自由创作图：`free_create`
+
+“添加演员”里的 AI 生成和本地上传，生成后都先落到：
+
+- 表：`Asset`
+- category：`person`
+
+视频项目里的“项目资产”不是另一份图片数据，而是项目对 `Asset` 的引用关系。
+
+- 视频项目用 `BaseAssetGroup` 表示项目里的商品/人物/场景资产组。
+- `BaseAssetGroup.adopted_asset` 指向当前采用的 `Asset`。
+- `BaseAssetGroup.candidate_assets` 指向候选版本的 `Asset`。
+
+所以：
+
+- `Asset` = 团队素材总仓。
+- 视频项目资产 = 项目对素材总仓的引用。
+- 演员可以先独立存在于 `Asset` 里，不一定属于某个视频项目。
+
+## 演员的主要创建方式
+
+当前“演员”主要有两个创建入口：
+
+1. “添加演员”工作台里 AI 生成 / 上传人物，保存后进入“我的演员”。
+2. 视频项目基础资产流程里生成“角色/人物”，也会生成演员资产。
+
+这里生成的是 `Asset(category=person)`，所以它首先是“演员”，不是顶级模特库里的 `Model`。
+
+## 三视图与模特库的关系
+
+不是“有三视图才变成演员”，而是：
+
+- 人物立绘生成后，本来就是演员。
+- 演员生成三视图后，会被自动收编成模特库实体。
+- 收编后，原来的演员资产仍然存在，同时多一条 `Model` 记录。
+
+所以可以理解为：
+
+- 无三视图：只在“我的演员”里出现。
+- 有三视图：仍是演员，同时进入顶级“模特库”。
+
+目前三视图能力主要围绕“基础资产/角色人物”流程，演员库弹窗里也有生成三视图入口，本质也是给已有人物立绘补三视图。
+
+## 演员删除与影响
+
+“我的演员”没有独立表，删除时删的是 `Asset(category=person)`。
+
+当前删除是软删除：
+
+- 后端只是把 `Asset.is_deleted` 置为 `true`。
+- 数据库行和文件不会立刻物理删除。
+- 软删后，“我的演员”和资产库正常列表不再显示。
+- 软删资产会进入垃圾桶，可恢复。
+
+对视频项目的影响：
+
+- 视频项目基础资产组里保存的是对这个 `Asset` 的引用。
+- 软删后项目引用不一定马上断图，因为项目详情可能仍能通过引用拿到文件。
+- 但语义上它已经是“被删除资产仍被项目引用”，属于潜在不一致状态。
+
+对模特库的影响：
+
+- 删除“我的演员”不会自动删除 `Model` 表里的模特记录。
+- 如果该演员已经生成三视图并收编成模特库，`Model` 记录仍然存在。
+- 但如果 `Model.portrait_asset` 指向的正是这个被软删演员，模特库底层会引用一个已软删资产。
+- 因此模特可能仍可见/可访问，但数据关系已经不干净。
+
+待明确的产品规则：
+
+- 删除演员前，是否要检测它是否被视频项目或模特库引用。
+- 如果已被引用，是否阻止删除，或提示“删除会影响项目/模特库复用关系”。
+- 如果删除的是已收编模特的演员，是否同步软删对应 `Model`，还是只从“我的演员”隐藏。
+
+## 当前展示规则
+
+### 1. 顶级模特库
+
+入口：`/models`
+
+数据来源：
+
+- API：`/api/models/`
+- 表：`assets.Model`
+- 含义：正式入库的团队级模特实体。
+- 一条模特通常关联：
+  - `portrait_asset`：形象图资产
+  - `triview_asset`：三视图资产
+  - `is_official`：是否官方模板
+  - `source`：AI 生成 / 真人上传
+
+### 2. 图片生成里的演员库
+
+入口：`/asset-factory` -> 模特上身图 -> 选择模特
+
+弹窗内有两个 tab：
+
+- “模特库”：来自 `/api/models/`，把 `Model` 映射成可选演员卡。
+- “我的演员”：来自 `/api/assets/?category=person`，展示已入库的普通人物资产。
+
+前端分组核心规则：
+
+- `metadata.kind === "model"`：归到“模特库”。
+- 其他 `category=person` 且有图的资产：归到“我的演员”。
+
+## 为什么会出现在“我的演员”
+
+添加演员工作台生成或上传人物时，后端先创建的是：
+
+- 表：`Asset`
+- category：`person`
+- 默认不是 `Model` 实体
+
+点“保存人物”后，只是把这个人物资产标记为进入资产库，所以它会显示在“我的演员”。
+
+只有以下动作才会让它进入顶级模特库：
+
+- `/models` 页面真人上传
+- 图片创作结果点“加入模特库”
+- 人物生成三视图后自动收编为 `Model`
+
+## 当前容易误解的点
+
+“我的演员”里可能出现名字类似 `AI 生成 · 模特上身图 · 1` 的卡片，但它未必是正式模特库数据。
+
+原因是后端 `mode=model` 有两种语义：
+
+- 有商品：生成“模特上身图”，归类为 `model_tryon`
+- 无商品：生成“演员/人物”，归类为 `person`
+
+但部分命名仍沿用了“模特上身图”的文案，容易让人误以为它已经进了顶级模特库。
+
+## 简单判断
+
+- 想看正式模特库：看 `/models`，对应 `Model` 表。
+- 想看保存过的临时/项目人物：看“我的演员”，对应 `Asset(category=person)`。
+- 两边会互相引用，但不是同一层数据。