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

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

• 版本：v6
• 更新日期：2026-05-13
• 目标读者：后端/前端/架构
• 阅读时间：30-50 分钟
• 边界说明：这里只讲关键链路、事务边界、失败模式和后端职责归属；精确 API(接口)路径、请求/响应字段、错误码与异步轮询契约统一以 后端-05-统一API契约-v1.md 为准。本文件描述目标后端行为，不代表当前代码都已实现。

1. 契约归属（别再两边各写一份）

后端文档分工如下：

文档	负责内容
架构-02	模型级不变式：双轨、Revision、Meta-driven(元结构驱动)、全局/局域知识边界、用户可见投影
流程-02	系统链路、事件触发关系、同步/异步边界
架构-04	精确状态机、表级约束、端点前后置条件
后端-04	精确 Schema(结构定义)、表结构职责、索引和待确认表
后端-05	精确 API(接口)分组、路径、请求/响应字段、错误码、轮询协议

本文件只保留“为什么事务边界要这么切”和“哪类接口应该存在”的后端视角总结。

1.1 v1 接口面归纳

• Admin APIs：元数据、Prompt、Agent、全局知识库、访问策略、New-API 用户同步、评测集、用户、系统日志。
• User Workspace APIs：作品、章节、文本块、写作、作品规划、局域知识库、全局知识库授权检索、导入解析、导出交付、生成候选。
• Personal Center APIs：个人信息、Token 使用、生成记录总览、配额、套餐和授权摘要。

普通用户不能访问 Admin APIs；管理员配置接口也不能替普通用户写单个作品事实。精确路径、字段与错误结构统一看 后端-05-统一API契约-v1.md。

2. 导入事务边界（分阶段提交，方案 C）

导入是一次性动作，但必须允许部分失败可恢复，因此不要把导入做成一个巨型事务。

• 提交策略：先创建空 Work(作品)，再逐章写入 Chapter(章节) / Block(文本块)，每章独立提交。
• 失败处理：任一阶段失败，保留 Work 与已成功提交的章节/Block，并记录导入失败原因。用户可删除 Work 后重试。
• 不做：不覆盖、不追加、不续传、不从中断处继续。

导入正文可以初始化 Canonical(规范数据)正文；导入后的全书解析(Full Parse)结果仍必须进入 Shadow(待审层)，等待章节级确认。

3. 待审对象与知识草稿

后端不引入 RawExtraction 一类对普通用户不可解释的长期概念。Active(活跃层) Shadow 与 Archive(归档层)的精确表结构统一看 后端-04-统一数据库Schema-v1.md。

• Suggestion(建议)：对正文的候选内容。
• Proposal(提案) / Knowledge Draft(知识草稿)：对知识、叙事状态或规划项的候选变更。
• Risk Markers(风险标记)：冲突、过期、重复、来源失效、质量风险等说明。

知识草稿进入 Canonical 的最小条件：

• 有明确来源快照(Source Snapshot)。
• 未过期、未被替代、未被丢弃。
• 通过来源校验和必要冲突校验。
• 用户确认，或在原样接受建议时由后端按绑定关系同步确认且满足状态机约束。

4. 系统链路的后端职责

后端职责是让每阶段输出变成可恢复、可追溯的结果。

链路	后端职责	不允许
元数据与配置	保存 MetaSchema、MetaField、PromptVersion、AgentConfig、全局知识库授权、New-API 绑定、评测集等配置版本或变更记录	把配置散落在业务代码或普通用户作品数据里
上下文组装	从 Canonical 正文、正式作品知识、规划项、授权全局知识和配置快照组装 Context(上下文)	把未确认草稿、未授权全局资料或过期投影当作事实
创作生成	创建 GenerationJob，调用外部 Agent 服务，成功后写 Suggestion 和必要知识草稿到 Shadow	外部 AI 调用进入正文合并主事务
解析提取	以 ExtractionJob 从正文、候选、导入内容或规划项中提取知识草稿	提取失败回滚已保存正文
校验确认	做来源、冲突、去重和风险校验，最终仍以用户确认进入 Canonical	后台绕过用户确认写正式作品知识
投影与记录	写 outbox、审计、任务记录和用户可见使用记录	投影失败反向覆盖事实源

补充硬约束：

• Accept Suggestion(接受建议)的事务语义分两条：
  • 原样 Accept：Canonical 正文合并、待审对象迁 Archive、关联且未 stale 的知识草稿可同步确认入库、写审计和 outbox。
  • 修改后合并：Canonical 正文合并、待审对象迁 Archive、旧 Draft 作废、写审计；新的知识草稿在事务提交后重新提取。
• AFTER_COMMIT 只负责触发异步消费，不负责补建主事务内必须完成的事实。
• 外部 AI、NER(命名实体识别)、提取、校验、投影或导出不得塞进 Canonical 合并主事务。
• /ai/ner 只是预览接口，不参与持久化写入。
• Stale draft 校验：Accept / 确认前校验 source snapshot，不匹配则拒绝确认。
• “修改后合并”不新增 Active 状态；旧 Draft 不得继续沿用。

5. 管理员配置变更如何影响生成链路

管理员(Admin)通过管理员控制台(Admin Console)修改系统能力时，后端必须把变更转成可追溯配置，而不是让运行链路读一堆可变全局变量。

管理员修改配置
  -> 写入配置版本或变更记录
  -> 激活或停用配置
  -> 普通用户触发生成/提取/校验/规划
  -> 权限校验
  -> 读取配置快照
  -> 组装上下文
  -> 调用 Agent / New-API
  -> 写任务状态、待审对象、审计和使用记录

配置影响面：

配置	影响生成链路的位置	后端要求
MetaSchema / MetaField	规划表单、提取结构、校验规则、用户可见投影、上下文注入	可见性字段变化要触发投影重建或失效
PromptVersion	生成、提取、校验、规划和检索提示	任务记录必须能追溯使用的版本
AgentConfig	Agent 启停、超时、重试、fallback 和能力路由	失败必须可恢复，不能直接污染正文或知识
GlobalKnowledgeAccessPolicy	全局知识库能否展示、检索或用于生成	默认不可越权使用；来源必须可区分
NewApiUserBinding / NewApiPlanMapping	用户是否可调用模型、分组、配额、套餐、绑定状态	同步必须幂等、可重试、可审计；模型供应商和成本日志仍以 New-API 为准
EvaluationDataset / EvaluationRun	系统质量评估和回归对比	评测结论不替代用户对正文和作品知识的确认

已启动任务必须使用启动时读取到的配置快照，中途不能混用新旧配置。配置回滚影响后续任务，不改写历史任务解释。

6. 用户作品工作台所需后台能力

作品工作台(Work Workspace)不是单个编辑器接口，它需要一组后台能力共同支撑。

6.1 作品规划数据保存

• 作品设定、章节大纲、世界设定、角色关系、文风检查和章节叙事规划优先复用 MetaSchema、narrative_states、knowledge_entities、knowledge_relations 和 Work / Chapter 字段。
• 不为“作品设定 / 章节大纲 / 世界设定 / 角色关系 / 文风检查”每个 UI 面板新建孤立表。
• 规划项确认后才可作为后续生成上下文；来源和用户取舍必须可追溯。

6.2 AI 辅助规划生成

• AI 生成、补全、整理、检查、给多组选项或从正文提取规划内容时，输出先进入 Shadow。
• 用户确认后，规划项才能写入对应 Canonical 载体或成为正式上下文。
• 章节叙事规划使用“情节节拍 / 场景推进”这类产品语言，但模型归入章节叙事规划，不引入小说场景(Scene)独立模型。

6.3 全局知识库授权检索

• 每次检索或生成前都必须校验 GlobalKnowledgeAccessPolicy。
• 返回结果必须标明来源是当前作品的局域知识库，还是被授权全局知识库。
• 全局知识库参与生成不等于写入局域知识库，除非用户后续确认成作品事实。

6.4 局域知识库自动维护

• 触发源：正文保存、候选确认、规划确认、导入解析章节确认、手动知识修正。
• 自动提取结果仍是知识草稿；用户确认后才进入正式作品知识。
• 修改后合并、来源快照失效或章节确认失败时，不得把旧草稿写入局域知识库。

6.5 用户可见投影生成

• 用户可见投影(User-visible Projection)只展示元数据允许展示、编辑、检索、导出的实体、关系、字段和摘要。
• 投影不是事实源，不能反向覆盖 Canonical。
• 投影落后时，读路径需要水位标记、覆盖层或等价策略；投影失败必须可重试、可观察、可审计。

6.6 用户使用日志

• 普通用户看到的是生成记录、任务记录、失败原因、Token 使用和成本提示。
• 管理员看到的是系统审计、任务失败、同步失败和运行观察。
• New-API 的模型消耗日志是权威来源；Muse 只保存与自身用户、作品、任务和授权相关的摘要或引用。
• 是否新增 usage_logs 独立表待 后端-04 确认；不能在 API 文档里先假定已经存在。

7. 外部集成边界

7.1 LLM(大语言模型)/模型网关与 Agent 服务

调用链路：Muse 后端 → Agent 服务 → New-API → LLM。

• Muse 后端负责权限、配置快照、上下文组装、Agent Dispatcher 调用、结果消费、待审对象写入和任务状态。
• Agent 服务承载生成、提取、校验、规划、检索等能力执行。
• New-API 负责模型供应商、模型路由、用户分组限流、成本策略和消耗日志。
• 业务代码不直接依赖具体 LLM 厂商。
• 外部失败必须以可恢复错误暴露，不能吞错。
• 如果保留直连 New-API fallback，也只能作为 Agent 服务不可用时的降级路径，不改变 New-API 作为模型网关的职责。

安全边界：

• Agent 服务和 Muse 后端部署在受信任后端边界内，不暴露公网。
• 如需传递用户级 New-API token，日志必须脱敏，不得持久化 token，不得把 token 传给除 New-API 以外的第三方。
• request_id / trace_id / user_id / work_id 全链路透传。
• Muse 记录任务级 usage summary、失败原因和同步状态；模型消耗明细以 New-API 为准。

7.2 任务编排/检索（可选）

如果引入 RAGFlow、Graph Query Provider 或任务编排工具：

• 仍视为外部依赖，不可成为系统事实源。
• 任务编排工具只用于后台任务调度或检索链路编排，不引入通用工作流平台能力。
• 输入必须来自 Canonical 正文、正式作品知识、授权全局资料和可追溯配置快照。
• 失败模式必须明确：超时、限流、配额不足、不可用、投影落后。
• 投影失败不阻塞主事务，但必须可重试、可观察、可审计。

8. 安全边界

8.1 API Key(接口密钥)管理

• 用户密钥必须以可撤销、可轮换为前提设计。
• 任何日志与错误返回中禁止泄露密钥。
• New-API 绑定状态、分组、配额、套餐同步失败要可重试、可审计。

8.2 用户隔离

• 所有资源访问都必须绑定用户、角色、作品和授权上下文。
• 普通用户不能访问管理员接口。
• 后端必须拒绝跨作品访问，不能靠前端隐藏按钮保证安全。
• 管理员不通过后台接口替普通用户确认候选、写正文或决定作品知识取舍。

9. 关联阅读

• 系统流程：流程-02-系统处理流程(系统视角).md
• 状态机与约束：架构-04-状态机与约束清单.md
• 统一数据库 Schema(结构定义)：后端-04-统一数据库Schema-v1.md
• 统一 API(接口)契约：后端-05-统一API契约-v1.md
• Accept(接受)专题收束：专题-01-正文建议接受(Accept Suggestion)实现规范.md