12 KiB
12 KiB
后端-03：关键流程实现与接口契约
- 版本：v6
- 更新日期：2026-05-13
- 目标读者：后端/前端/架构
- 阅读时间：30-50 分钟
- 边界说明：这里只讲关键链路、事务边界、失败模式和后端职责归属；精确 API(接口)路径、请求/响应字段、错误码与异步轮询契约统一以
后端-05-统一API契约-v1.md为准。本文件描述目标后端行为，不代表当前代码都已实现。
1. 契约归属（别再两边各写一份）
后端文档分工如下：
| 文档 | 负责内容 |
|---|---|
架构-02 |
模型级不变式：双轨、Revision、Meta-driven(元结构驱动)、全局/局域知识边界、用户可见投影 |
流程-02A/02B |
系统链路、事件触发关系、同步/异步边界 |
架构-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. 关联阅读
- 管理员系统流程：
流程-02A-管理员系统处理流程(系统视角).md - 普通用户系统流程：
流程-02B-普通用户系统处理流程(系统视角).md - 状态机与约束：
架构-04-状态机与约束清单.md - 统一数据库 Schema(结构定义)：
后端-04-统一数据库Schema-v1.md - 统一 API(接口)契约：
后端-05-统一API契约-v1.md - Accept(接受)专题收束：
专题-01-正文建议接受(Accept Suggestion)实现规范.md