oh-my-muse/design-docs/后端-03-关键流程实现与接口契约.md

后端-03：关键流程实现与接口契约

• 版本：v7
• 更新日期：2026-05-23
• 目标读者：后端 / 前端 / 架构 / 测试
• 阅读时间：30-50 分钟
• 边界说明：本文件只讲关键链路、事务边界、失败模式和后端职责归属；精确路径、请求响应和错误码看 后端-05，状态机看 架构-04，工程模块看 后端-02。

1. 契约归属

阶段 7 后端文档分工：

文档	负责内容
后端-01	领域模型、聚合、owner module、不变式
后端-02	Yudao Cloud fork 工程结构、保留/裁剪模块、Muse 模块职责
后端-03	关键流程、事务边界、异步边界、失败恢复
后端-04	Muse 业务模块目标 Schema；Yudao 基础表只引用不重定义
后端-05	/admin-api/** 与 /app-api/** API 契约
架构-04	状态机、前后置条件、硬约束

2. API 入口分流

Vben Admin -> /admin-api/** -> yudao-gateway -> yudao-server -> module controller/admin
muse-studio -> /app-api/** -> yudao-gateway -> yudao-server -> module controller/app

约束：

• 管理后台只调用 /admin-api/**。
• 用户端只调用 /app-api/**。
• 两类入口可以调用同一个 application use case，但不能复制两套领域事实。
• 后端必须在 controller、application 和领域用例中做权限、owner、来源和状态校验。

3. 横切硬约束

阶段 7 后端实现必须先守住这些横切不变式，再拆具体接口：

约束	后端落点	不允许
用户主权	Content / Knowledge / AI application use case 强制校验用户决策	AI、市场、管理员或系统任务替用户确认作品事实
Shadow -> Canonical	AI 候选、知识草稿、规划候选先落 Shadow，再经用户决策进入 Canonical	候选生成成功后直接写正文、正式知识或正式规划
保护节点	Protected Node Registry 是唯一口径，至少包含 input_compliance、output_compliance、permission_filter、audit、chunking、rag_ingest、semantic_guardrail、static_check、quality_gate、source_status_check、shadow_to_canonical	用户智能体、市场智能体或工作流智能体替换保护节点
Handoff	market 只写 Authorization / Install / Handoff / Precheck 状态，目标 owner 消费预检后写自己的事实	市场安装/绑定直接写作品、知识、槽位或正文事实
Source Status Event	来源 owner 发布，受影响 owner 幂等处理	撤权、召回、blocked 后仍允许新生成、新确认、新绑定或受限导出
Account read model	account 聚合权益、用量、授权和发布记录摘要	account 反写作品、知识、智能体或市场事实
New-API 边界	Muse 只保存网关绑定引用、任务级摘要、调用归属、错误分类、幂等键和补偿状态	Muse 成为模型 Provider、供应商路由、成本策略或原始调用日志 authority

同步写入只覆盖用户确认、正文保存、知识确认、槽位绑定、知识绑定、Handoff/Precheck 消费等必须立即给出结果的 owner 事实。AI 调用、投影、索引、导出、评估、来源传播、New-API 归属和通知走异步任务，异步失败不得回滚已提交 Canonical。

3.1 关键流程 owner / 幂等 / 状态边界

流程	owner 边界	幂等键	状态边界
规划	AI 只写 Planning Candidate；Content 只写用户确认后的 Planning Canonical	workId + candidateId + decisionId	candidate 过期、来源失效、版本冲突或质量门控 blocked 时不写 Canonical
全书解析	Content 拥有导入任务、解析任务和章节解析状态；Knowledge 只接收章节确认后的 Knowledge Draft	workId + parseJobId + chapterId + reviewDecisionId	章节级失败可重试；章节确认不写 Local KB Canonical，只推进 Draft
知识库	Knowledge 拥有 KB、Knowledge Draft、Knowledge Source Binding 和投影状态	kbId + draftId + decisionId 或 kbId + sourceId + bindDecisionId	来源 revoked/recalled/blocked/owner_missing/unauthorized 时禁用新确认、新绑定和受限导出
市场资产使用	Market 只写 Authorization、Install、Handoff、Precheck 状态；Content / Knowledge / AI 写目标事实	precheckId + targetOwner + targetId + action	token 过期、已消费、来源变化、目标 owner 缺失或 feature gate 关闭时拒绝写入；market 通过事件刷新展示状态
New-API 用量	AI Task 记录网关调用引用和调用归属；Account 只做用户可见汇总；New-API 保持原始 authority	aiTaskId + gatewayRequestId	超时、限流、余额不足、回调失败按任务重试或补偿；Muse 不补写 Provider、路由、成本和原始调用日志

4. Accept Suggestion

Accept Suggestion 是正文候选进入正文 Canonical 的唯一合法入口。

主事务必须完成：

1. 校验用户对 Work / Chapter / Block / Suggestion 的权限。
2. 校验 Suggestion 仍处于 Active Shadow，未过期、未失效、未 blocked。
3. 校验 expectedRevision。
4. 校验 Candidate Decision Envelope，包含来源、授权、合规、质量、静态检查和市场作品资产 feature gate。
5. 写 Block 新 revision。
6. 写 Block Source Attribution。
7. 将 Suggestion 迁入 Archive。
8. 写审计、change log、outbox。

原样接受：

• 只写正文和候选归档。
• 关联 Knowledge Draft 继续保持待确认。
• 不自动写 Local KB。
• 不自动确认规划候选、知识草稿或来源绑定。

修改后合并：

• 写用户最终正文。
• 旧 Knowledge Draft 立即失效。
• AFTER_COMMIT 触发重新提取。
• 上游 lineage、授权快照、许可限制和召回状态默认继承，不能被 contentOverride 洗白。

失败边界：

• 来源 revoked / recalled / blocked / owner_missing / unauthorized：候选 blocked 或 invalidated，不写正文。
• 市场作品资产缺 workAssetUsePrecheckId 或 feature gate：不写正文。
• revision 冲突：返回可恢复冲突信息，不静默覆盖。
• outbox 或投影失败：不得回滚已成功的正文主事务，但必须可重试、可观察、可审计。

5. Knowledge Draft 确认

知识草稿确认由 yudao-module-knowledge owner 执行。

最小条件：

• 草稿仍 active，未过期、未失效。
• 来源快照、授权快照、source hash、目标版本仍有效。
• Source Status 不为 revoked、recalled、blocked、owner_missing、unauthorized。
• 用户对目标 Work / Local KB 有确认权限。
• 风险标记和冲突处理已完成或被用户显式处理。

确认结果：

• 写 Knowledge Canonical。
• 写 Knowledge Source Binding。
• 写知识变更历史。
• 写投影 outbox。

幂等与状态：

• 确认按 kbId + draftId + decisionId 幂等；重复提交只能返回同一确认结果或当前状态。
• Draft 进入 confirmed、invalidated、blocked、superseded 后不得再次确认。
• 投影、索引或检索侧失败只改变 Projection State，不回写 Knowledge Canonical。

禁止：

• Accept Suggestion 自动确认知识草稿。
• 全书解析章节确认直接写正式知识。
• 管理员替用户确认单作品知识事实。
• 市场知识库安装、绑定或授权记录直接写 Local KB。

6. 导入解析与全书解析

导入正文：

• 允许初始化 Work、Chapter、Block 的 Canonical 正文。
• 文件处理、章节拆分、失败记录可异步。
• 部分失败时保留已成功的章节和失败摘要，用户可删除后重试。

全书解析：

Import / Existing Blocks
-> Parse Job
-> Chapter Parse Result
-> Chapter Review
-> Knowledge Draft
-> 用户知识确认
-> Local KB Canonical

约束：

• Chapter Review 只表示章节解析结果进入后续知识草稿处理。
• 章节审阅不写 Local KB，不写 Narrative State。
• 拆分切块、静态检查、入 RAG 是保护节点，用户智能体不可替换。
• 批量选择和一键确认全部可确认章节只是操作效率，不允许跨章节半提交污染事实。
• 章节确认成功只产生或推进章节范围内的 Knowledge Draft；正式知识仍必须由用户在知识确认入口逐项确认或按明确批量确认规则确认。
• Content 记录 parse job、chapter result、review status 和失败摘要；Knowledge 只在章节确认后接收 draft 写入请求。
• 解析任务按 workId + parseJobId + chapterId 幂等；章节审阅按 workId + parseJobId + chapterId + reviewDecisionId 幂等。

7. AI 生成、解析和质量门控

AI 链路由 yudao-module-ai 二开承载。

用户意图
-> 输入合规
-> 权限和来源预检
-> Agent Runtime Permission Envelope
-> Context Assembly
-> 开放槽位子智能体
-> Provisional Shadow Candidate
-> 静态检查 / 来源状态校验
-> Quality Gate
-> Output Compliance
-> Candidate Decision Envelope
-> 用户决策

后端职责：

• 固化 actor、work、agent version、slot、tool grant、context scope、budget、authorization snapshot。
• 只写 AI Task、Suggestion、Knowledge Draft、Planning Candidate、Risk Marker、Quality Result。
• 不直接写正文、正式规划或 Local KB。
• New-API 只作为外部模型网关；Muse 不保存密钥明文、完整 Prompt/Response、私有正文全文、模型 Provider、供应商路由、成本策略或原始调用日志 authority。
• Muse 侧只保存网关绑定引用、任务级摘要、调用归属、错误分类、幂等键和补偿状态。
• Agent Runtime Permission Envelope 必须由服务端生成和校验，不能接受前端或智能体自报权限。
• 质量门控可以阻断、标记风险或触发 Shadow 内有限重写，但不能替用户做接受、知识确认或规划确认。

8. 市场资产使用

市场资产使用必须走 handoff。

场景	预检	消费方
市场智能体关联作品槽位	agentSlotPrecheckId	yudao-module-ai / Agent Slot Binding
市场知识库绑定作品	kbBindPrecheckId	yudao-module-knowledge
市场作品资产作为参考或上下文	workAssetUsePrecheckId	yudao-module-content / yudao-module-ai
发布市场资产	marketPublishCheckId	yudao-module-market

阶段 7 默认：作品资产 feature gate 未开启前，只允许阅读、收藏和授权记录，不允许模板化、参考写入或进入 AI 上下文。

市场安装不等于绑定，绑定不等于写入作品事实。

handoff 处理规则：

1. 市场模块校验资产、许可、版本、治理状态和发起人后，只写 Authorization、Install、Handoff、Precheck 状态，并生成一次性 handoff token 或预检请求。
2. 目标 owner 模块重新校验 actor、owner、目标对象、动作、授权快照、来源状态、返回点和幂等键。
3. 目标 owner 完成用户确认后原子消费预检，并写自己的事实：Agent Slot Binding、Knowledge Source Binding、Block Source Attribution 或目标 owner 的使用状态。
4. token 缺失、已消费、过期、来源状态变化、目标 owner 不存在或 feature gate 关闭时拒绝写入，并返回 market 刷新状态。
5. market 只能通过目标 owner 事件或状态回执更新展示状态，不能补写目标事实。

9. 导出交付

导出由 Content / Knowledge / Market / Account 协作完成。

导出前必须重验：

• 用户对作品的权限。
• 导出范围。
• Block Source Attribution。
• Knowledge Source Binding。
• 市场资产授权和许可限制。
• 来源 revoked / recalled / blocked / owner_missing。
• 下载凭证有效期和访问主体。

导出任务异步执行，下载凭证短期有效。来源状态变化必须传播到导出任务和下载凭证，必要时禁用下载或要求重验。

10. 账户、权益和用量

Account/Member 只提供用户可见权益和汇总，不替代业务 owner。

• 配额和权益用于 AI 任务、市场安装、导出等前置检查。
• 用量记录来自 AI Task、New-API 网关调用引用、调用归属、市场交易、导出任务和审计摘要。
• New-API 的模型 Provider、供应商路由、成本策略和原始调用日志仍以 New-API 为准。
• AI Task 失败、超时、限流或回调失败时，Muse 只更新错误分类、幂等重试和补偿状态；Account 只刷新用户可见摘要。
• 个人中心只展示 read model 和跳转入口，不拥有作品、知识、市场资产事实。

11. Source Status Event

来源变化必须通过事件传播：

• AI Suggestion / Planning Candidate
• Knowledge Draft
• Chapter Parse Result
• Knowledge Source Binding
• Agent Slot Binding
• Installed Agent / Installed KB
• Running Task
• Export Task / Download Credential
• Personal Center Summary
• Marketplace / Publisher Record

传播失败时，新使用 fail-default 禁用，并提供治理重试入口。

事件最小合同：

字段	说明
eventId	幂等事件 ID
sourceType / sourceId / sourceVersion	来源对象和版本
eventType	revoked / recalled / blocked / owner_missing / needs_recheck / delisted 等
reasonCode	治理、授权、版本、权利、合规或处理失败原因
affectedScopes	候选、草稿、绑定、安装、运行任务、导出、下载、个人中心记录等影响范围
occurredAt	来源事件发生时间
idempotencyKey	来源 owner 生成的幂等键

处理结果不得改写已确认 Canonical。允许的动作是禁用新使用、标记需重验、作废未确认对象、取消或阻断运行中任务、失效下载凭证、刷新个人中心摘要和写审计。

12. 关联阅读

• 管理员系统流程：流程-02A-管理员系统处理流程(系统视角).md
• 普通用户系统流程：流程-02B-普通用户系统处理流程(系统视角).md
• 状态机：架构-04-状态机与约束清单.md
• Accept 专题：专题-01-正文建议接受(Accept Suggestion)实现规范.md
• AI 编排专题：专题-03-AI编排上下文与质量评测实现规范.md
• 质量门控专题：专题-04-生成质量门控与创作健康度设计方案