后端权威运行时重构
仅当你能准确说明执行真相位于何处以及 UI 如何读取它时，才进行重构。
何时使用
- UI 合成后端不理解的关系图、阶段或 provider 选择。
- 重新启动或重新连接会改变可见运行时状态，因为前端缓存了权限。
- 新旧模式、启动器格式或节点类型在活跃的创作路径中并存。
- 审批、审查或下游执行依赖于仅前端重建。
不适用于
- 纯视觉清理且运行时所有权无变化。
- 后端契约已经是权威的独立组件重构。
- 在删除权限分裂的接缝之前，交付新的业务功能。
- 架构已有一个真相源的纯后端性能优化。
决策点
flowchart TD
A[工作流重构请求] --> B{UI 是否仍能发明运行时真相?}
B -->|否| C[使用更狭窄的领域或 UI 技能]
B -->|是| D[盘点命令、查询和事件的接缝]
D --> E{是否每个用户操作都能映射到命令、查询或事件?}
E -->|否| F[在特性开发前冻结契约]
E -->|是| G[将投射状态与后端拥有状态分离]
G --> H{是否还有遗留兼容路径活跃?}
H -->|是| I[将它们移到迁移边缘或删除]
H -->|否| J[添加评估器、重放安全启动查询和事件订阅]
I --> J
J --> K[验证重连、审批和下游就绪状态]
请首先使用此路由模型：
- 如果 UI 不能描述为
命令 -> 后端转移 -> 查询或事件投射，则接缝仍然是错误的。 - 如果“临时兼容”路径位于热点路径中，将其视为重构债务，而非特性。
- 如果重新启动或重新连接无法仅从后端真相重建可见状态，则重构尚未完成。
工作方法
1. 盘点分裂的“双脑”
找出所有 UI 执行以下操作的地方：
- 生成或变更执行真相
- 发明后端不知道的阶段
- 在活跃代码路径中模拟执行
- 在同一创作路径中保留新旧模式
- 混合抽象路由层级和精确 provider ID
2. 冻结契约
仅定义三类：
- 命令：启动、停止、批准、恢复、变更
- 查询：启动状态、审查负载、执行快照、provider 健康
- 事件：权威转移、评估器判定、门状态、重放标记
如果 UI 操作不能表示为其中之一，则架构仍然模糊不清。
3. 规范化状态所有权
将存储分离为：
- 契约输入状态
- 后端快照投射状态
- UI 布局状态
不要让任何存储同时拥有运行时真相和布局关注点。
4. 删除活跃的兼容接缝
优先删除，而非“暂时支持两者”。
典型删除项：
- 活跃创作中的单数和复数模式兼容性
- 活跃桌面运行时中的浏览器或演示模拟
- 主路径中的弃用节点类型
- 重复的审查摘要
- 多种启动器或导入格式
5. 在信任重构之前添加评估器
每个实现节点应有：
- 本地输出评估器，用于正确性
- 下游就绪评估器，用于契约安全性
- 重新启动或重新连接路径，从后端真相而非前端猜测中恢复
失败模式
伪装成权威的投射
症状：UI 看起来“只读”，但悄悄地在本地组合阶段、关系图或 provider 真相。
修复：将该逻辑移到后端命令或查询中，并将前端视为投射器。
兼容接缝钙化
症状：“暂时支持两者”在热点路径中停留数周，最终成为实际架构。
修复：将兼容性推至单向迁移边缘，并明确删除日期，或立即删除。
不可检查的审批
症状：人类可以批准他们无法检查的工作，因为审查负载是部分或前端合成的。
修复：后端必须发出精确的审查负载；UI 仅渲染它。
对重放敌意的启动
症状：重新启动应用会改变可见状态或丢失门位置，因为前端缓存了权限。
修复：启动必须是对后端真相的查询加上事件重放，而不是存储重建。
识别语
如果重新启动应用在没有任何新后端事件的情况下改变了可见运行时状态，则权限仍然是分裂的。
工作示例
具有前端拥有的阶段逻辑的 Tauri 工作流编辑器
问题：
- React 存储创作了关系图、推断阶段状态和归一化 provider 层级。
- 后端执行使用不同的契约，因此审查和重启流程发生漂移。
重构路径：
- 盘点每个 UI 发明执行真相的地方。
- 将运行时交互压缩为命令、查询和事件。
- 将 provider 归一层级和阶段转换移至后端命令之后。
- 从活跃创作路径中删除启动器格式联合体。
- 添加评估器门，使下游工作仅从后端验证的输出继续进行。
成功条件：
- 重新启动时，UI 从后端快照加上事件重建相同的可见状态。
- 审批屏幕渲染后端发出的审查负载，而非 React 重组。
分支指导
在工作能清晰分离时进行分支：
- 契约分支：盘点权限分裂接缝，并定义命令、查询和事件。
- 删除分支：移除兼容层、弃用节点类型和启动器格式联合体。
- 验证分支：添加评估器门、重放测试以及重新启动或重连覆盖。
保持最终所有权决策在父分支中，以便一个角色决定后端真正拥有什么。
质量门禁
- UI 无法在本地伪造关系图、阶段、provider 或门真相。
- 每个用户操作都映射到命令、查询或事件。
- 运行时状态仅凭后端真相即可在重新启动和重连后存活。
- 审查和审批负载由后端发出并由 UI 渲染。
- 兼容逻辑仅存在于迁移边缘，不在活跃路径中。
- 下游执行在上游契约失败时停止。
- 准确的 provider ID 和模型选择在契约边界可见。
- 测试覆盖重新启动、重连、审批和评估器失败路径。
参考地图
references/architecture-patterns.md— 后端拥有的工作流契约模式和状态所有权分裂。references/windags-lessons.md— 来自真实权限分裂运行时迁移的具体经验教训。