oh-my-muse/design-docs/架构-03-关键决策与原则(ADR).md

架构-03：关键决策与原则（架构决策记录(ADR)）

• 版本：v6
• 更新日期：2026-05-13
• 目标读者：架构/前端/后端/产品
• 阅读时间：30-45 分钟
• 边界说明：这里只收敛架构原则和 ADR；工程结构、表结构、接口、状态机分别归属 后端-02、后端-04、后端-05 和 架构-04。本文件描述目标架构决策，不代表当前代码都已实现。

1. 架构原则（可执行）

1.1 模块化单体优先，边界先于服务拆分

• 默认采用模块化单体：清晰边界、本地事务、低部署成本、可调试。
• 只有当痛点真实且可量化时才拆服务，例如 AI 能力独立扩展、团队边界稳定或外部依赖需要隔离。
• 即使拆外部服务，Muse 的业务事实源和用户确认边界仍必须回到 Muse。

1.2 管理员控制系统能力，普通用户控制作品事实

• 管理员(Admin)通过管理员控制台(Admin Console)治理系统模板、Prompt、Agent、全局知识和权限。
• 普通用户(User)通过用户工作区(User Workspace)写作、规划、确认知识和查看用量。
• 管理员不替用户做单个作品的创作取舍；普通用户不直接操作系统后台配置。

1.3 数据主权：待审层(Shadow)先行，规范数据(Canonical)后置

• 人工智能(AI)只产出待审层(Shadow)，用户决定是否进入规范数据(Canonical)。
• 系统可以提示风险、冲突和参考来源，但不能替用户做不可逆决定。
• 来源快照(Source Snapshot)、归档层(Archive)和审计记录是用户可撤销、可追溯的基础。

1.4 数据结构优先，不按 UI 面板造模型

• 先定义模型边界、不变式和状态机，再设计页面流程。
• 作品规划台(Planning Desk)是产品入口，不是每个面板一张表。
• 规划能力应复用元结构定义(MetaSchema)、世界状态(World State)、叙事状态(Narrative State)、作品(Work)、章节(Chapter)和文本块(Block)边界。

2. ADR 索引

每条 架构决策记录(ADR)都必须包含：上下文(Context) / 决策(Decision) / 替代方案(Alternatives) / 后果(Consequences)。这里只保留决策要点，细节不要复制到各处。

ADR-001：模块化单体 vs 微服务

• 上下文(Context)：早期阶段、团队小、边界仍在探索，部署与调试成本必须低。
• 决策(Decision)：采用模块化单体，内部通过模块边界、接口隔离和事件解耦维护职责。
• 替代方案(Alternatives)：直接微服务化会放大部署、事务、观测和跨服务调试成本。
• 后果(Consequences)：开发和事务更简单；代价是必须持续维护边界，不能把模块化单体写成大泥球。
• 参考落地：后端-02-工程结构与模块职责.md

ADR-002：AI 能力通过外部 Agent 服务提供

• 上下文(Context)：文本生成、实体提取、知识校验、规划和检索等能力需要快速演进，完全放在 Java 内部会限制生态和迭代速度。
• 决策(Decision)：AI 能力通过受信任的外部 Agent 服务提供。Muse 后端负责权限、上下文组装、Agent 调用、结果消费和待审层(Shadow)写入。
• 替代方案(Alternatives)：全部写入 Muse Java 进程会降低灵活性；让 Agent 服务直接写数据库会破坏事实源和权限边界。
• 后果(Consequences)：AI 能力可独立演进；代价是新增服务信任边界，Agent 服务必须遵守同等安全和审计要求。
• 参考落地：后端-03-关键流程实现与接口契约.md

ADR-003：动态属性采用 JSONB，而不是 EAV

• 上下文(Context)：实体属性高度动态，但查询、变更追溯和投影仍必须可用。
• 决策(Decision)：用 二进制 JSON(JSONB) 当前快照 + 属性级变更日志表达动态属性。
• 替代方案(Alternatives)：实体属性值模型(EAV)会让查询和约束复杂度失控。
• 后果(Consequences)：查询与演进成本更低；代价是更依赖数据库能力和索引策略。
• 参考落地：后端-04-统一数据库Schema-v1.md

ADR-004：富文本编辑器选择以 Block 级自定义能力优先

• 上下文(Context)：Muse 需要段落级文本块(Block)，并携带 id、revision、状态、实体高亮和标注。
• 决策(Decision)：选择支持结构定义(Schema)和节点扩展能力强的编辑器体系。
• 替代方案(Alternatives)：纯 Markdown 或普通富文本编辑器难以承载块级冲突、候选合并和知识标注。
• 后果(Consequences)：可实现强结构与扩展；代价是基础复杂度和学习成本更高。
• 参考落地：前端-02-编辑器与影子层交互.md

ADR-005：向量检索采用 RAGFlow，替代 pgvector

• 上下文(Context)：上下文组装需要文档管理、分块策略、混合检索和语义检索能力，简单向量相似度不足。
• 决策(Decision)：使用 检索引擎(RAGFlow)作为语义检索基座，PostgreSQL 不保存 embedding 作为主检索方案。
• 替代方案(Alternatives)：pgvector 方案部署简单，但检索能力不足；完全自建检索引擎成本过高。
• 后果(Consequences)：检索质量与灵活性提升；代价是新增外部依赖，必须有降级和重建投影路径。
• 参考落地：doc/dev/03-S1-RAGFlow集成与知识检索基座.md

ADR-006：Neo4j vs RAGFlow GraphRAG 职责分工（待 S1-B 后补完）

• 上下文(Context)：需要判断 RAGFlow GraphRAG 是否足以覆盖时间线、因果链、实体演变等查询。
• 决策(Decision)：暂不把 Neo4j 固定为必选事实；S1-B benchmark 后决定是否引入独立图查询 provider。
• 替代方案(Alternatives)：现在直接引入 Neo4j 会增加运维和同步复杂度；完全放弃图查询会削弱长篇一致性检查。
• 后果(Consequences)：保留条件交付空间；正式决策必须由 benchmark 支撑。
• 参考落地：doc/dev/03-S1-RAGFlow集成与知识检索基座.md

ADR-007：Block 使用 UUID

• 上下文(Context)：文本块(Block)需要为离线、多端、复制粘贴、候选合并和未来协作预留空间。
• 决策(Decision)：使用 唯一标识(UUID)作为 Block 的全局标识。
• 替代方案(Alternatives)：自增 ID 更省空间，但客户端生成和离线合并能力更弱。
• 后果(Consequences)：同步与合并更简单；代价是索引和存储上不如自增友好。
• 参考落地：架构-02-核心数据结构与双轨模型.md

ADR-008：管理员控制台是独立系统入口

• 上下文(Context)：新产品形态明确拆分管理员(Admin)和普通用户(User)。管理员负责系统能力治理，普通用户负责作品创作。
• 决策(Decision)：管理员控制台(Admin Console)作为独立上层入口存在，承载模板、Prompt、Agent、全局知识库、访问策略、New-API 同步、任务治理、质量评估、用户与审计。
• 替代方案(Alternatives)：把这些能力塞进普通用户作品工作台会暴露后台概念，破坏低认知负担，也会让权限边界难以验证。
• 后果(Consequences)：前端信息架构、权限模型、审计视图必须分角色；管理员配置影响普通用户生成链路时必须通过可追溯配置快照生效。
• 参考落地：架构-01-系统全貌与边界上下文.md、流程-02-系统处理流程(系统视角).md

ADR-009：模型网关 New-API 职责边界

• 上下文(Context)：New-API 已负责模型供应商、模型路由、用户分组限流、成本策略和模型消耗日志。Muse 需要和自身用户、作品、授权和配额联动。
• 决策(Decision)：New-API 继续负责模型供应商、路由、分组、限流、成本和消耗日志；Muse 只负责用户生命周期相关同步，以及必要的分组、配额、套餐和绑定状态调整入口。
• 替代方案(Alternatives)：Muse 重复实现模型网关会扩大系统复杂度；完全不记录同步状态会让失败不可恢复。
• 后果(Consequences)：New-API 同步必须幂等、可重试、可审计；Muse 的普通用户用量反馈和管理员审计可以引用同步结果，但不把 New-API 成本日志复制成新的权威来源。
• 参考落地：流程-02-系统处理流程(系统视角).md、架构-04-状态机与约束清单.md

ADR-010：全局知识库与局域知识库分层

• 上下文(Context)：管理员维护的写作方法、体裁规则、平台规范和公共资料，与单个作品沉淀的人物、关系、事件和叙事状态不是同一类资产。
• 决策(Decision)：全局知识库(Global Knowledge Base)归管理员维护和授权；局域知识库(Local Knowledge Base)归单个作品自动维护。普通用户看到的是用户可见投影(User-visible Projection)，不是系统内部完整知识。
• 替代方案(Alternatives)：混成一个知识库会导致普通用户误改系统资料，也会让全局资料未经授权进入作品生成或检索。
• 后果(Consequences)：生成、检索、导出和一致性检查必须标明来源；全局资料不自动进入作品正式知识，局域知识不跨作品共享正式事实。
• 参考落地：架构-01-系统全貌与边界上下文.md、架构-02-核心数据结构与双轨模型.md

ADR-011：作品规划台复用已有模型边界

• 上下文(Context)：作品规划台需要支持作品方向、作品结构、世界实体、事件时间线、角色弧光、剧情结构、章节叙事规划、张力节奏、叙事策略、文风与质量检查。
• 决策(Decision)：这些规划维度映射到元结构定义(MetaSchema)、世界状态(World State)、叙事状态(Narrative State)、作品(Work)、章节(Chapter)和文本块(Block)，不为每个 UI 面板新建孤立模型。
• 替代方案(Alternatives)：按 UI 面板建模会形成重复事实源，导致规划、正文、知识和生成上下文互相打架。
• 后果(Consequences)：前端可以按创作语言组织入口，但后端和架构文档必须保持模型归属；新增规划维度先判断落点，而不是先建表。
• 参考落地：架构-02-核心数据结构与双轨模型.md

ADR-012：小说场景(Scene)暂不作为独立一级模型

• 上下文(Context)：产品可以使用情节节拍、场景推进、章节目标等作者语言，但当前正式模型更稳定的骨架是作品、章节、文本块、世界状态和叙事状态。
• 决策(Decision)：当前阶段不引入小说场景(Scene)作为独立一级模型，也不采用 Outline / Scene 作为并列一级模型。近程叙事控制归入章节叙事规划，并由 Chapter、Block 上下文和 Narrative State(chapter)承载。
• 替代方案(Alternatives)：直接引入 Scene 会带来章节顺序、文本块归属、解析确认、导出和知识追溯的连锁改造；继续使用章节叙事规划可以先满足产品语言和生成约束。
• 后果(Consequences)：所有文档可以写“情节节拍 / 场景推进”，但不能假定已有 Scene 表、Scene API 或 Scene 状态机。未来若需要独立模型，必须新增 ADR 并同步后端、前端和状态机。
• 参考落地：架构-02-核心数据结构与双轨模型.md

ADR-013：Sa-Token 作为认证授权基座

• 上下文(Context)：管理员控制台需要稳定的登录认证、角色权限、接口鉴权、会话与 Token 生命周期、当前用户上下文和基础审计上下文。现有自研 Bearer Token 能力已经能支撑局部 current user，但继续扩展会导致认证、权限和当前用户解析散落在多处。
• 决策(Decision)：引入 Sa-Token 作为 Muse 的认证授权基座；现有自研 Bearer Token 能力逐步收敛为 Sa-Token 适配层。Sa-Token 负责 Authentication(登录认证)、RBAC(角色权限)、接口鉴权、会话、Token 生命周期、管理员接口保护、当前用户上下文和基础审计上下文。
• 替代方案(Alternatives)：继续扩展自研 Token 会重复造轮子；引入 Yudao / RuoYi 完整后台系统会把通用平台能力带进 Muse，扩大边界并冲击现有产品架构。
• 后果(Consequences)：Muse 需要补最小 RBAC 数据模型、默认超级管理员初始化、登录/登出/刷新/me API、前端登录状态管理和权限测试；但 Sa-Token 不决定作品正文、知识草稿或 AI 候选是否进入 Canonical(规范数据)，这些仍由 Muse 的 Shadow -> Canonical 业务规则控制。系统任务必须用明确服务身份，不复用普通用户权限绕过确认。
• 参考落地：后端-04-统一数据库Schema-v1.md、后端-05-统一API契约-v1.md、前端-01-工程结构与核心依赖.md

3. 本次是否需要新增 ADR 的结论

需要。双角色入口、New-API 职责边界、全局/局域知识库分层、作品规划台模型复用、小说场景(Scene)暂不升一级模型、Sa-Token 认证授权基座，都会影响跨文档边界和后续实现，因此已补 ADR-008 到 ADR-013。

4. 关联阅读

• 系统边界与 BC：架构-01-系统全貌与边界上下文.md
• 数据结构与模型规则：架构-02-核心数据结构与双轨模型.md
• 状态机与约束：架构-04-状态机与约束清单.md
• 系统处理流程：流程-02-系统处理流程(系统视角).md