zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/design-docs/后端-03-关键流程实现与接口契约.md
zizi 33aad93bef 提交全维度文档review后的22项架构决策落地 
基于产品/架构/流程/前端/后端五维度并行review，澄清并落地22项关键决策：

架构层：Governance按消费者归属拆散、MetaSchema独立模块、
Source传播改为事件驱动自治、去掉Candidate Decision Envelope
和needs_recheck中间状态、Neo4j决策为依赖RAGFlow GraphRAG

后端层：Entitlement统一为可变表+审计日志、API版本策略采用
X-API-Version Header、知识实体唯一键加scope字段

前端层：SSE实时通信（AI stream独立+事件统一）、正文持久化
IndexedDB安全网、Block粒度为场景/小节级

产品层：范围不变UX解决复杂度、知识确认默认自动+冲突时人工
2026-05-24 04:28:52 +08:00

350 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 后端-03：关键流程实现与接口契约
- 版本：v9
- 更新日期：2026-05-24
- 目标读者：后端 / 前端 / 架构 / 测试
- 阅读时间：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 入口分流
```text
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. 正文保存后知识提取
正文保存成功后，系统可触发知识提取链路，将正文变更转化为知识草稿供用户确认。
```text
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 正文。
- 文件处理、章节拆分、失败记录可异步。
- 部分失败时保留已成功的章节和失败摘要，用户可删除后重试。
全书解析：
```text
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` 幂等。
## 7. AI 生成、解析和质量门控
AI 链路由 `yudao-module-ai` 二开承载。
```text
用户意图
-> 输入合规
-> 权限和来源预检
-> 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。
- 下载凭证有效期和访问主体。
导出任务异步执行，下载凭证短期有效。来源状态变化必须传播到导出任务和下载凭证，必要时禁用下载或要求重验。
## 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。
- 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-生成质量门控与创作健康度设计方案`
Reference in New Issue View Git Blame Copy Permalink