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

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

• 版本：v10
• 更新日期：2026-06-19
• 目标读者：后端 / 前端 / 架构 / 测试
• 阅读时间：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	用户智能体、市场智能体或工作流智能体替换保护节点
MetaSchema	逻辑 owner 是 Admin/Governance；物理表即便放在 content，也只能经 governance facade 写版本	content/app API 把 MetaSchema 当普通动态字段结构任意改
Tool Grant / Runtime Permission	Governance / Security facade 签发工具和外发授权，AI runtime 只消费权限包	yudao-module-ai、Prompt、模型输出或智能体自述给自己扩权
Handoff	market 只写 Authorization / Install / 来源侧 handoff token / 授权摘要 / 跳转审计，目标 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 拥有导入任务、文件、章节上下文和正文初始化；AI 拥有 Parse Job / Chapter Parse Result；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 Token、授权摘要和跳转审计；Content / Knowledge / AI 拥有目标 precheck/session 和目标事实	targetPrecheckId + 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. 实时校验来源版本：比对候选记录的 source_version 与当前来源实际版本，校验 qualityResultVersion、输出合规结果、静态检查结果、Authorization Snapshot、Source Snapshot、Source Status、market feature gate、workAssetUsePrecheckId 和 idempotencyKey。
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 冲突：返回可恢复冲突信息，不静默覆盖。
• 来源版本不匹配、质量结果版本不匹配、输出合规或静态检查 blocked：返回阻断原因、来源归因和可重试入口，不写正文。
• 失败响应必须保留 blockSourceAttribution、blockedReasons、sourceStatusReasons、reasonAttributions、authorizationSnapshotId、qualityResultVersion 和 nextActions，不能把 stale / revoked / unauthorized 来源压缩成普通失败。
• outbox 或投影失败：不得回滚已成功的正文主事务，但必须可重试、可观察、可审计。

4A. 正文保存后知识提取

正文保存成功后，系统可触发知识提取链路，将正文变更转化为知识草稿供用户确认。

Block 保存成功（Content owner）
-> AFTER_COMMIT 写 outbox 事件（BlockSavedEvent）
-> AI/Knowledge 消费事件
-> AI 创建知识提取任务（extraction task）
-> AI 调用模型提取实体/关系/事件
-> AI 生成 Knowledge Draft（Shadow）
-> 用户在知识草稿入口确认
-> Knowledge 写 Local KB Canonical

流程职责拆分：

阶段	Owner	说明
Block 保存和 outbox 事件	content	正文保存主事务成功后，AFTER_COMMIT 写 BlockSavedEvent 到 outbox，包含 workId、chapterId、blockId、revision、changeSource
事件消费和提取任务创建	ai	消费 BlockSavedEvent，按策略判断是否需要提取（例如 revision 变化量、章节完成度、用户配置），创建 extraction task
知识提取执行	ai	调用模型提取实体、关系、事件，生成 Shadow 结果
Knowledge Draft 生成	knowledge	AI 提取完成后，通过 Knowledge facade 请求创建或刷新 Knowledge Draft
用户确认	knowledge	用户在知识草稿入口确认后写 Local KB Canonical

约束：

• 正文保存主事务不等待知识提取完成；提取是异步 followup task。
• 提取失败不回滚已保存正文。
• 提取结果只能进入 Knowledge Draft（Shadow），不能直接写 Local KB Canonical。
• 提取任务按 workId + chapterId + blockId + revision 幂等；同一 revision 不重复提取。
• Block 保存响应可包含 followupTasks 字段，告知前端有知识提取任务已触发（见 后端-05 4.3 节 PUT /blocks/{blockId} 响应说明）。

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
-> AI Parse Job
-> AI Chapter Parse Result
-> Chapter Review
-> Knowledge Draft
-> 用户知识确认
-> Local KB Canonical

约束：

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

导入预检(import inspect)安全姿态（决策见 架构-03-关键决策与原则(ADR).md ADR-019）：

• 外部来源拉取强制 SSRF 白名单(allowlist)，命中白名单外的主机、协议或地址段直接拒绝，不发起回源请求。
• 扫描状态以服务端权威结果(server-authoritative scanStatus)为准，失败关闭(fail-closed)：不接受客户端自报扫描结论。
• 扫描器接入前，所有导入按 scan_blocked 处理，不创建 Parse Job；需向用户回传可解释原因和后续放行路径。

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

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

用户意图
-> 输入合规
-> 权限和来源预检
-> Agent Runtime Permission Envelope
-> Context Assembly
-> 开放槽位子智能体
-> Provisional Shadow Candidate
-> 静态检查 / 来源状态校验
-> Quality Gate
-> Output Compliance
-> Shadow Candidate（记录 source_version）
-> 用户决策（接受时实时对比来源版本）

后端职责：

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

Agent / Tool Grant / Runtime Permission Envelope 责任拆分：

责任	Owner	不能做
Agent 配置	AI 管理应用服务，管理员或用户按可见范围创建版本	夹带新工具授权、外发白名单或越权上下文
Tool Grant authority	Governance / Security facade，写版本、审批、用途、预算、外发策略和审计	由 yudao-module-ai、Prompt、模型输出或用户智能体自授
安全 facade	汇总权限、来源状态、授权快照、账户权益、市场许可和保护节点要求	只信任前端传入的 targetOwner、sourceStatus 或预算
运行时执行器	消费 Agent 版本和 Tool Grant 投影，生成不可扩权的 Runtime Permission Envelope	在执行中追加工具、扩大上下文、变更外发目标或绕过审计
审计	动作 owner + audit/outbox	把运行日志替代高危业务审计

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 token、授权摘要和跳转审计。
2. 目标 owner 模块基于 handoff token 或授权摘要重新校验 actor、owner、目标对象、动作、授权快照、来源状态、返回点和幂等键，并生成自己的 target precheck/session 或签名消费凭证。
3. 目标 owner 完成用户确认后原子消费自己的 precheck/session，并写自己的事实：Agent Slot Binding、Knowledge Source Binding、Block Source Attribution 或目标 owner 的使用状态。
4. token 缺失、已消费、过期、来源状态变化、目标 owner 不存在、目标凭证不匹配或 feature gate 关闭时拒绝写入，并返回 market 刷新状态。
5. market 只能通过目标 owner 事件或状态回执更新展示状态，不能补写目标事实或目标 precheck。

9. 导出交付

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

导出前必须重验：

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

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

下载交付与脱敏姿态（决策见 架构-03-关键决策与原则(ADR).md ADR-019，模型不变式见 架构-02-核心数据结构与双轨模型.md Download Credential / Export Package）：

• 下载一律走后端字节代理(byte-proxy)，以稳定存储路径(stable storage path)取流，不向客户端签发对象存储签名 URL；存储对象按租户/用户命名空间隔离，凭证只解析 owner 范围内的稳定路径，避免 IDOR。
• 账户导出(Account export)在 Account BC 内组装本人数据，再按脱敏级别(standard / strict)处理后落包；脱敏级别未知时按 strict 失败关闭(fail-closed)，不输出未脱敏数据。
• 字节代理不可用时按 UPSTREAM_UNAVAILABLE 处理，不暴露存储路径、内部地址或凭据。

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	SourceEventType，例如 source_updated、source_revoked、asset_recalled、asset_delisted、asset_blocked、owner_missing、authorization_revoked、authorization_expired、license_changed、processing_failed、recheck_required
sourceStatus	SourceStatus，例如 active、stale、revoked、recalled、delisted、blocked、owner_missing、unauthorized
actionPolicy	SourceActionPolicy：allowed、read_only、blocked、needs_recheck（注：needs_recheck 是 ActionPolicy 层面的动作策略结论，不是 SourceStatus 枚举值）
reasonCode	治理、授权、版本、权利、合规或处理失败原因
reasonAttribution	reasonCode 对应的来源 owner、授权快照、治理动作或处理任务
affectedScopes	候选、草稿、绑定、安装、运行任务、导出、下载、个人中心记录等影响范围
occurredAt	来源事件发生时间
idempotencyKey	来源 owner 生成的幂等键

命名映射：

事件来源	SourceEventType	SourceStatus	SourceActionPolicy
授权撤销	authorization_revoked	unauthorized	blocked
来源主动撤权	source_revoked	revoked	blocked
市场资产召回	asset_recalled	recalled	blocked
市场资产下架但历史授权可读	asset_delisted	delisted	read_only
治理封禁	asset_blocked	blocked	blocked
owner 缺失或不可见	owner_missing	owner_missing	blocked
版本、许可或处理状态变化	license_changed / processing_failed / recheck_required	stale	needs_recheck

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

12. P1 跨模块补充契约

• Candidate Decision Archive owner 单一化：AI 拥有归档表，Content Accept 只能通过 AI decision facade 消费后拿 decisionArchiveId 引用，不在 Content 表复制候选决策事实。接受时实时校验来源版本，不再依赖预计算的 Envelope。
• Download Credential 必须承载来源传播结果：来源 revoked / recalled / blocked / unauthorized 后，已签发凭证进入 disabled 状态，下载时再次校验授权快照和 source event version。凭证只解析 owner 范围内的稳定存储路径并经字节代理取流，不签发签名 URL（见 §9 和 ADR-019）。
• Local KB entity / relation / event 必须保存来源快照、授权快照和 source status 摘要；来源事件不删除正式知识，但阻断新检索、新生成、新确认和受限导出。
• New-API binding、quota request、call attribution 必须有本地幂等记录、correlationId、重试组和用户可见归属状态；Muse 不复制 Provider、路由、成本和原始日志 authority。
• Pay callback / refund 只通过支付引用和幂等事件传播到 account entitlement 可变表和审计日志；退款、撤销和补偿通过反向变更更新可变表并写审计日志记录。
• 文件上传必须绑定 owner、用途、大小、MIME、hash、扫描状态、保留期、清理策略和来源快照；Yudao infra 只提供文件能力，不拥有导入、知识资料或市场素材的业务事实。

13. 关联阅读

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