oh-my-muse/design-docs/架构-01-系统全貌与边界上下文.md

# 架构-01：系统全貌与边界上下文

- 版本：v6
- 更新日期：2026-05-13
- 目标读者：架构/后端/前端/产品
- 阅读时间：20-30 分钟
- 边界说明：这里只定义系统边界、有界上下文(BC)和跨上下文协作规则；本文件描述目标架构，不代表当前代码都已实现。精确表结构以 `后端-04-统一数据库Schema-v1.md` 为准，精确接口(API)以 `后端-05-统一API契约-v1.md` 为准，精确状态机以 `架构-04-状态机与约束清单.md` 为准，模块职责以 `后端-02-工程结构与模块职责.md` 为准。

## 1. 系统边界（一句话）

Muse 是面向长篇小说创作的双角色人工智能(AI)创作系统：管理员(Admin)通过管理员控制台(Admin Console)治理系统能力，普通用户(User)通过用户工作区(User Workspace)管理自己的作品、写作、规划、确认知识和查看用量。

这条边界里有两个不变式：

- 管理员决定“系统能做什么、怎么做、谁能用”，不进入普通用户的单个作品替用户做创作取舍。
- 普通用户决定“我的作品写什么、哪些内容进入作品事实”，不直接操作系统 Prompt、Agent、底层元数据配置、全局知识库授权和系统审计。
- 系统任务(System Job)只能以明确服务身份执行后台任务，不复用普通用户权限绕过正文、候选或作品知识确认。

### 1.1 上层入口

| 入口 | 使用角色 | 负责什么 | 禁止混入什么 |
|---|---|---|---|
| 管理员控制台(Admin Console) | 管理员(Admin) | 元数据与创作模板、Prompt、Agent、全局知识库(Global Knowledge Base)、访问策略、模型网关(New-API)同步、上下文组装策略、任务治理、质量评估与评测集、用户与审计 | 单个作品的正文写作、候选确认、知识取舍 |
| 用户工作区(User Workspace) | 普通用户(User) | 我的作品、作品工作台、个人中心；在单个作品内完成写作台、作品规划台、知识与一致性、导入解析、导出交付、记录与用量 | 系统后台配置、全局资料授权、Prompt/Agent/Pipeline 操作 |

用户工作区(User Workspace)不是单一页面。它包含我的作品(My Works)、作品工作台(Work Workspace)和个人中心(Profile)。其中作品工作台只围绕单个作品工作，默认落在写作台(Writing Desk)，作品规划台(Planning Desk)和知识与一致性按需打开。

### 1.2 系统输入

| 来源 | 输入 | 进入的边界 |
|---|---|---|
| 管理员(Admin) | 元结构定义(MetaSchema)、字段可见性、Prompt 版本、Agent 配置、全局知识库、访问策略、New-API 同步配置、评测集 | Admin BC 和 Usage/Audit BC |
| 普通用户(User) | 正文编辑、作品规划、导入文稿、AI 辅助请求、候选处理、知识确认、导出请求 | Content BC、Knowledge BC、AI BC |
| 系统任务(System Job) | 投影消费、索引重建、同步重试、评测执行、清理任务 | 明确服务身份、任务审计上下文和受限后台能力 |
| 外部服务 | 模型调用结果、检索结果、同步结果、投影消费结果 | AI BC、Knowledge BC、Usage/Audit BC |

### 1.3 系统输出

- 规范数据(Canonical)：用户确认后的正文、作品知识、规划项和叙事状态。
- 待审层(Shadow)：AI 生成的候选文本、知识草稿、解析结果和风险标记。
- 归档层(Archive)：已接受、已拒绝、已过期或失败的候选与提案历史。
- 配置快照：管理员配置在一次生成、提取、校验或评测中使用的可追溯版本。
- 用户可见投影(User-visible Projection)：从局域知识库(Local Knowledge Base)生成、只展示元数据允许展示的实体、关系、字段和摘要。
- 使用与审计记录：普通用户可理解的生成/任务/用量记录，以及管理员可见的系统审计和同步失败记录。

### 1.4 系统组件与外部依赖

Muse 后端以模块化单体为编排层。外部模型、检索和图查询能力可以参与链路，但不能成为业务事实源。

| 组件 | 角色 | 边界 |
|---|---|---|
| Muse Backend | 权限、配置快照、上下文组装、任务编排、Shadow 写入、Canonical 写入、投影事件 | 业务编排与事实写入归属 Muse |
| Sa-Token | 登录认证(Authentication)、角色权限(RBAC)、接口鉴权、会话与 Token 生命周期、当前用户上下文 | 只作为认证授权基座；作品级权限、全局知识库授权和 Shadow -> Canonical 仍由 Muse 业务规则判断 |
| Admin Console | 管理员配置系统能力和授权边界 | 不承载单作品创作取舍 |
| User Workspace | 普通用户创作、规划、确认、检索、导出和查看用量 | 不暴露后台配置 |
| Agent 服务 | 生成、提取、校验、规划、检索等 AI 能力执行 | 受信任后端；不得绕过 Muse 写 Canonical |
| 模型网关(New-API) | 模型供应商、模型路由、用户分组限流、成本策略和消耗日志 | Muse 只做用户、分组、配额、套餐和绑定状态同步 |
| RAGFlow | 语义检索与 GraphRAG 基座 | 读取 PostgreSQL 投影，不是事实源 |
| Neo4j | 实体演变、关系网络、事件因果的条件能力 | 是否引入以 ADR 和后续 benchmark 为准 |
| PostgreSQL | 唯一事实源 | Canonical、Shadow、Archive、配置、审计的权威存储 |

## 2. 有界上下文(BC)划分

有界上下文(BC)按数据所有权和写入边界划分，不按 UI 面板划分。界面入口可以变多，但不能因此给每个面板新造孤立模型。

| BC | 核心职责 | 主写入边界 | 对外输出 |
|---|---|---|---|
| Admin BC | 系统模板、元数据、Prompt、Agent、用户、权限、New-API 同步、全局知识库、访问策略、评测集 | 系统级配置、授权策略、配置版本与启停状态 | 配置快照、权限结果、授权范围 |
| Content BC | 作品、章节、文本块和正文版本 | Work / Chapter / Block 的 Canonical 正文 | 正文、章节结构、版本信息、导入状态 |
| Knowledge BC | 全局知识库、局域知识库、正式作品知识、用户可见投影、来源追溯 | 全局资料授权边界、作品级知识事实、投影事件 | 作品知识、授权资料、投影读模型、一致性检查输入 |
| AI BC | 生成、提取、校验、规划、检索编排、任务和候选 | Generation Job、Extraction Job、Suggestion、Knowledge Draft、风险标记 | 待审对象、任务状态、候选解释 |
| Usage/Audit BC | Token 使用、生成记录、任务记录、系统日志、审计、同步失败 | 使用记录、业务审计、失败记录、配置变更记录 | 普通用户用量反馈、管理员审计视图、可重试失败 |

### 2.1 认证授权边界

Sa-Token 负责 Muse 的登录认证(Authentication)、角色权限(RBAC)、接口鉴权、会话与 Token 生命周期、管理员接口保护、当前用户上下文和基础审计上下文。

Sa-Token 不决定作品事实：

- 管理员(Admin)有管理员权限，不代表可以替普通用户确认正文、规划项、知识草稿或 AI 候选。
- 普通用户(User)有登录态，不代表可以访问其他用户作品或未授权全局知识库。
- 系统任务(System Job)有服务身份，不代表可以绕过 Shadow -> Canonical 确认规则。
- 前端隐藏按钮只是体验优化，后端接口和 Muse 业务权限必须强制校验。

### 2.2 知识库边界

全局知识库(Global Knowledge Base)和局域知识库(Local Knowledge Base)不能混成一个概念：

- 全局知识库(Global Knowledge Base)：管理员(Admin)维护和授权的系统级资料集，用于写作方法、体裁规则、平台规范和公共资料。它可以被授权为可见、可检索或可用于生成，但不会自动变成某个作品的正式知识。
- 局域知识库(Local Knowledge Base)：单个作品自动维护的作品级知识空间，来自正文、导入解析、作品规划和用户确认。它只归属当前作品，不跨作品共享正式事实。
- 用户可见投影(User-visible Projection)：局域知识库面向普通用户的读模型，只展示元数据允许展示、允许编辑、允许检索或允许导出的内容。系统内部完整知识可以参与生成、检查和审计，但不等于全部对用户可见。

### 2.3 写入边界

- Content BC 只能写规范数据(Canonical)正文；AI BC 禁止直接写 Canonical。
- Knowledge BC 的正式知识写入必须来自用户确认、章节级确认或用户手动修正，并保留来源追溯。
- Admin BC 变更影响生成与校验时，运行链路必须读取可追溯的配置快照。
- Usage/Audit BC 可以记录行为和失败，但不能替业务上下文做事实写入。

## 3. 跨上下文协作规则

### 3.1 依赖方向

`Admin` 提供配置与授权；`Content` 提供正文事实；`Knowledge` 依赖 `Content` 的来源与作品边界；`AI` 依赖 `Admin + Content + Knowledge` 组装上下文；`Usage/Audit` 订阅各上下文的事件和结果。

反向依赖禁止：

- 普通用户工作区不能直接写 Admin BC 的系统配置。
- AI BC 不能绕过 Content BC 或 Knowledge BC 写正式事实。
- 投影层不能反向覆盖 PostgreSQL 中的事实源。

### 3.2 协作方式

- 同步路径：权限校验、配置快照、正文写入、候选处理和知识确认走明确 API；接口细节只在 `后端-05` 定义。
- 异步路径：正式写入后通过投影事件盒(outbox)或等价机制分发投影事件，RAGFlow、图查询 provider 和用户可见投影异步消费。
- 一致性路径：投影未追平时，上下文组装使用水位标记(watermark)和覆盖层(overlay)或等价策略保证写后读；具体实现不在本文件展开。

## 4. 核心链路（系统视角）

### 4.1 管理员配置链路

管理员(Admin)在管理员控制台(Admin Console)修改系统模板、Prompt、Agent、全局知识库、访问策略、New-API 同步配置、上下文策略或评测集。系统写入配置版本和变更记录，普通用户运行链路读取配置快照。

### 4.2 普通用户写作链路

普通用户(User)在用户工作区(User Workspace)保存文本块(Block)时，Content BC 以修订号保护写入规范数据(Canonical)。后续提取、校验和投影可以异步发生，但失败不得回滚已保存正文。

### 4.3 AI 生成链路

普通用户触发续写、改写、描写、规划或检查时，AI BC 读取权限、配置快照、当前正文、正式作品知识、规划项和授权全局知识，生成候选文本、知识草稿与风险标记，并写入待审层(Shadow)。

### 4.4 审核合并链路

普通用户确认候选或知识草稿后，系统按规范数据(Canonical)写入规则合并正文或作品知识，待审对象迁入归档层(Archive)。修改后合并必须让旧知识草稿失效，并基于最终正文重新提取。

### 4.5 知识与投影链路

正式作品知识进入局域知识库(Local Knowledge Base)后，Knowledge BC 生成投影事件。用户可见投影(User-visible Projection)只暴露元数据允许展示的实体、关系、字段和摘要；正式检索只接收 Canonical 正文、已确认作品知识和被授权的全局资料。

## 5. 关联阅读

- 数据结构与模型规则：`架构-02-核心数据结构与双轨模型.md`
- 生命周期与约束：`架构-04-状态机与约束清单.md`
- ADR：`架构-03-关键决策与原则(ADR).md`
- 系统处理流程：`流程-02-系统处理流程(系统视角).md`
- 统一数据库 Schema：`后端-04-统一数据库Schema-v1.md`
- 统一 API 契约：`后端-05-统一API契约-v1.md`