# 跨空间 Handoff —— P3(content owner)asset_use 从零建评审版

> 版本:v0.1(P3 单阶段评审) · 日期:2026-06-22 · 目标读者:架构/产品拍板人 + 实现 agent · 类型:评审版(结论+拍板点+blast radius+验收,不预写代码细节)
> 上游:[handoff 顶层评审](2026-06-22-handoff跨空间统一接入-review.md) · [执行版 §4.2/§五 P3](2026-06-22-handoff跨空间统一接入-execution.md) · 承 [P2 agent 评审](2026-06-22-handoff-P2-agent放宽-review.md)(已实施)
> 依据:本评审现状基于 2 路只读调研(content 后端代码 + design-docs SSOT,file:line 锚点见正文),非 summary 推断。

---

## 〇、本版定位

handoff 最后一 owner(content)。把 SSOT 已定义表名/职责/索引(后端-04 `muse_content_work_asset_use_precheck`)、但**建表 SQL 未写 + 代码完全缺失 + 产品-02F 标注 feature gate 关闭**的 content asset_use,从零建为真实两段式闭环:token 红线兑现(verify+consume)+ 落"作品使用市场资产作参考/AI 上下文"的授权凭证。

**P3 与 P1/P2 的关键差异(降风险)**:
1. asset_use **语义=使用凭证记录,非物化**(后端-04 L135"作品资产用于参考、模板或 AI 上下文";产品-02F L456:不写入正文/参考来源/规划项/局域 kb)→ **不涉及 P1/P2 共缺的"market 资产物化"维度**,P3 范围天然干净、无"最小验证 vs 完整物化"分裂。
2. **无独立绑定事实表**(后端-04 只定义 precheck 表 + precheck_id 唯一索引 L1081;asset_use 的"真实使用"经 `muse_ai_candidate_decision_archive.work_asset_use_precheck_id` 引用 precheckId 体现 L849)→ asset_use 兑现落点与 knowledge(独立 binding 表)/agent(slot binding)**不同**,见拍板点 Q1。
3. sourceAssetId 直接是真实 market asset id(已存在)→ e2e **不需 seed 目标实体 fixture**(不像 P2 seed market agent),可做完整闭环(来源侧发起 + 落地兑现 + 真实 asset 落库断言)。

---

## 一、现状(2 路调研实证)

### content 侧完全缺失(file:line)
- content 模块零 asset_use/handoffToken/asset-use-precheck 代码(grep 全量零命中,muse-module-content -server/-api)。无 DO/Mapper/Service/Controller/ReqVO。
- `content-server/pom.xml` 缺 `muse-module-market-api`(现仅 meta-api/infra-api)。
- content 错误码已用至 `1_041_001_003`,下一可用段 **`1_041_002_xxx`**。

### SSOT 已定义(权威,但未建表)
- 后端-04 L135:表 `muse_content_work_asset_use_precheck`(content target owner service 写,"参考/模板/AI 上下文目标预检;阶段 7 默认 feature disabled")。
- 后端-04 L1081:唯一索引 `muse_content_work_asset_use_precheck(precheck_id)`。
- 后端-04 L849:`muse_ai_candidate_decision_archive` 字段含 `work_asset_use_precheck_id`(AI 接受候选时引用此预检 = asset_use 的真实"被使用"载体)。
- 后端-04a 完整建表 SQL(13 表,含 work/chapter/block/narrative_state)**未含 asset_use**→ P3 须建表(V28?)。
- 产品-02F L183-185:`workAssetUsePrecheckId` + feature gate 关闭;L456:asset_use 约束(不写入正文/参考来源/规划项/局域 kb)。
- 专题-03 L181-182:`allowedPurpose`(上下文检索/生成参考/绑定/导出/确认知识)、`forbiddenPurpose`(**市场作品资产模板化**/受限导出/二次分发);L188:授权必须按用途校验。

### 可照搬参照(完备)
- **两段式蓝本=knowledge**(MuseKnowledgeBindingService:precheck 72-127 + binding 130-177 + consumeMarketHandoff 273-284 + requireUsablePrecheck 300-318;MuseKnowledgeBindPrecheckDO 17 字段)——P2 agent 已第二次照搬,P3 第三次复用同形态(收益:三 owner 兑现侧形态统一)。
- **content 写命令约定**:commandId 幂等(ContentCommandServiceImpl.reserveCommand + insertIgnore)+ expectedRevision 乐观锁(ContentRevisionGuard.requireRevision,ContentAppServiceImpl.updateWork 133-167)。
- **market 端口**:MarketHandoffTokenApi.verify/consume(P1/P2 已用,进程内 Bean)。

---

## 二、设计骨架(实现期对齐真实 RespVO,不预写代码)

### 两段式(token 红线,照 knowledge/P2 同款)
- **precheck**:`POST /muse/works/{workId}/asset-use-prechecks`,ReqVO:commandId/handoffToken/sourceAssetId/sourceVersion/authorizationSummaryId/purposes。逻辑:commandId 幂等→market 来源调 `verify`(targetOwner=content,action=asset_use)+`consume`(**token 明文仅此阶段持有、核销**)→落 `muse_content_work_asset_use_precheck`(status active)。
- **create**:`POST /muse/works/{workId}/asset-uses`,ReqVO:commandId/assetUsePrecheckId/expectedWorkRevision。逻辑:requireUsablePrecheck→expectedWorkRevision 乐观锁→落"使用事实"(形态见 Q1)→标 precheck consumed;**token 已在 precheck 核销,本段凭 precheckId**(同 P1/P2 自审修正:token 明文不进 create 段)。

### 前端 + e2e
- ContentHandoffLanding 落地组件 + useContentHandoff hooks(useAssetUsePrecheck/useCreateAssetUse)+ HandoffLandingPage 加 content dispatch。
- 02F MarketAssetDetailPage 加 targetOwner=content/action=asset_use 发起(asset_use 不依赖物化、sourceAssetId=真实 asset id,**可做完整发起入口**)。
- handoff-content.spec 真后端:正路 bind-precheck(content)→createHandoff→assetUsePrecheck verify+consume→createAssetUse 落库;负路伪造 token 被 verify 拒、0 写。

---

## 三、blast radius

- **纯新增**:content asset_use 两段式(DO/Mapper/Service/Controller/ReqVO/错误码 + 表迁移),不改 content 现有写路径(work/block/planning/merge)。
- content-server 加 market-api 依赖(同 knowledge/ai,BcBoundaryArchTest 通用规则已覆盖、0 新 @Test;后端-04 L908/L1030 明确"目标 owner 自校验落 precheck")。
- 前端:复用 P0 基座(HandoffLandingPage + HandoffStore + 02F createHandoff),加 content 分支。
- DDL:新建 `muse_content_work_asset_use_precheck`(+ 使用事实表若 Q1 选独立表)迁移 V28,全新表向后兼容。⚠️ 应用共享 muse_slice_live = **人类 gate**(同 V27)。

---

## 四、风险/失败路径

1. **原子性(load-bearing,同 P1/P2)**:precheck 落库 + consume token 同事务(content-server @Transactional + market-api consume REQUIRED 传播)。
2. **token 红线**:伪造/过期/跨属主 token 在 content 服务端被 verify 拒(fail-closed),0 写。
3. **asset_use 不越界(产品-02F L456 硬约束)**:只落"使用授权凭证",**不写入正文/参考来源/规划项/局域 kb**——实现须守边界(不触 content/knowledge 写路径)。
4. **purposes 授权校验 + 禁模板化**:按 purposes 校验授权;**market 作品资产模板化属 forbiddenPurpose**(专题-03 L182),purpose 白名单须排除 template。

---

## 五、拍板点(请你定)

| # | 拍板点 | 选项 | 评审建议 |
|---|---|---|---|
| **Q1** | **asset_use "使用事实"落库形态** | (A) **单表**:precheck 表即事实载体(active→consumed 即"作品可用此资产"凭证,AI archive 引用 precheckId)/ (B) **独立使用事实表** `muse_content_work_asset_use`(与 knowledge binding 对称,便于按 work 聚合已用资产) | **倾向 A**(SSOT 只定义 precheck 表 + AI archive 引用的是 `work_asset_use_precheck_id`=precheckId,非独立 asset_use_id;A 最贴 SSOT、最小)。若产品要"作品已用资产清单"读模型,可在 A 上加投影,不必独立事实表 |
| **Q2** | **asset_use 兑现的用户价值锚点(产品)** | asset_use 落库后不拉内容/不写正文,用户怎么感知"用了这个资产"? (A) 仅记录"作品已授权使用市场资产 X 作参考/AI 上下文",后续 AI 生成时作上下文来源(价值在 AI 链)/ (B) 加可见的"作品已关联资产"展示区 | 待你定(关系 P3 是否有即时可见价值,还是"记录就绪、价值在后续 AI 上下文消费";若选 A,P3 验收=记录+红线,AI 消费另立) |
| **Q3** | **purposes 白名单** | reference(参考)/ai_context(上下文检索)/generate_reference(生成参考);**排除 template/模板化**(forbiddenPurpose) | **确认即可**(SSOT 专题-03 L182 + 产品-02F L456 已定模板化禁止) |
| **Q4** | **P3 范围** | (A) **完整闭环**(来源侧发起 02F + 落地兑现 + 真实 asset e2e,因不依赖物化)/ (B) 仅兑现侧(同 P2 最小) | **倾向 A**(asset_use 不物化、sourceAssetId 真实,P3 可比 P1/P2 更完整、无 fixture 替身) |
| **Q5** | revision 挂级 | work 级(expectedWorkRevision) | **确认即可**(SSOT 后端-01 L60 + knowledge binding targetVersion 一致) |

---

## 六、验收

- handoff-content.spec 真后端:正路完整闭环(发起→落地→asset_use 落库)+ 负路伪造 token 拒,2 passed + 幂等。
- content asset_use Service 单测(verify 接入 + consume 核销 + 同事务回滚 + 伪造/缺 token/禁用 purpose 拒)。
- BcBoundaryArchTest 0 违例(content→market-api)。
- 前端 tsc/eslint+vitest + 全量 e2e 不回归;V28 应用共享库(人类 gate)。
- 总账回写。

---

## 七、回滚

- content asset_use 纯新增,可整段移除(DO/Mapper/Service/Controller/错误码 + 前端组件 + V28 表)。
- 02F content 发起入口 feature-gate。
- 不影响 content 现有写路径 + P0/P1/P2。

> 下一步:确认 Q1-Q5(尤 Q1 落库形态 + Q2 用户价值锚点 = 真正需拍板)后,按 P2 同款流程实现(后端→前端→e2e→回写)。

---

## 八、拍板结论(2026-06-22)

- **Q1 落库形态 = 单表(SSOT 对齐)**:`muse_content_work_asset_use_precheck` 表即事实载体(active→consumed = 作品可用此资产凭证),AI archive 引用 precheckId(L849)。**不建独立使用事实表**;若后续需"作品已用资产清单"读模型可加投影。
- **Q2 用户价值锚点 = 记录 + AI 上下文消费**:asset_use 落"作品已授权用市场资产作参考/AI 上下文",价值在后续 AI 生成链(作上下文来源)。**P3 验收 = 记录 + token 红线**,AI 消费链另立(不在 P3)。
- **Q3 purposes = reference/ai_context/generate_reference**(禁 template/模板化,forbiddenPurpose,专题-03 L182 + 产品-02F L456)。
- **Q4 范围 = 完整闭环**:来源侧发起(02F MarketAssetDetailPage targetOwner=content)+ 落地兑现 + 真实 asset e2e(不依赖物化、sourceAssetId 真实,比 P1/P2 更完整、无 fixture 替身)。
- **Q5 revision = work 级**(expectedWorkRevision,SSOT 后端-01 L60 + knowledge binding targetVersion 一致)。

实现顺序(P2 同款):后端(pom + V28 建表 + DO/Mapper/Service/Controller/ReqVO + `1_041_002_xxx` 错误码 + verify/consume + 单测)→ 前端(ContentHandoffLanding + useContentHandoff hooks + HandoffLandingPage content dispatch + 02F 发起 + vitest)→ V28 DDL 人类 gate + handoff-content.spec 完整闭环 e2e + 全量回归 → 总账/总览/review 回写。

---

## 九、实施状态(2026-06-22 ✅ 已交付)

Q1-Q5 拍板全落地。**后端**:V28 建表 `muse_content_work_asset_use_precheck`(单表)+ 两段式 `MuseContentAssetUseService`(verify/consume + purposes 白名单 + work 级乐观锁)+ `1_041_002_xxx` 错误码;`MuseContentAssetUseServiceTest` 8/0 + BcBoundaryArchTest 0 违例(content→market-api 经端口)。**前端**:ContentHandoffLanding + useContentHandoff hooks + HandoffLandingPage content dispatch + 02F MarketAssetDetailPage 来源侧发起入口;tsc/eslint 绿 + vitest 97→101(ContentHandoffLanding 4)。**e2e**:V28 已应用共享 muse_slice_live(flyway now at v28、用户拍板、rebuild jar + 重启 48080)+ handoff-content.spec 2 passed(正路真后端全链兑现 + 负路伪造 token 拒)+ 全量 e2e 50→52(1 flaky 单跑绿、非回归)。

**诚实范围**:asset_use = 「使用授权事实记录」非资产物化(sourceAssetId 直引真实 asset、无物化步骤),故来源侧发起天然完整、无 fixture 替身;Q2 锚点「AI 上下文消费」(经 `muse_ai_candidate_decision_archive.work_asset_use_precheck_id`)另立、不在 P3。至此 handoff token 红线三 owner(knowledge P1 / agent P2 / content P3)全覆盖;剩 market→knowledge/agent 资产物化独立主线。详见 `docs/mvp/进度总账.md` 2026-06-22 P3 条。