Appearance
总体设计与架构方案（V10）
总体设计回答的是：当需求已经足够明确，并且这次工作真的会影响系统边界时，软件整体应该怎样组织。
它不是所有任务的固定步骤。V10 的 Fast / Execution 小改不应因为“工程化”而重新做一份总体设计。
1. 什么时候需要总体设计
适合：
- 新项目；
- 新设备子系统；
- 新的主试验流程；
- 新的通信/数据/状态机边界；
- 多模块职责需要重新划分；
- 技术选择会长期影响多个模块。
通常不需要：
- 文案、样式、列宽、普通 XAML；
- 已明确的阈值/告警规则修改；
- 单一 Bug 修复；
- Temporal Regression；
- 临时 ExperimentalChange；
- 单个现有模块内的小功能。
这些直接走 Fast / Execution。
2. 总体设计的输入不是“所有资料都填满”
至少需要：
| 输入 | 需要达到的程度 |
|---|---|
| 目标与 NonGoals | 当前版本做什么、不做什么清楚 |
| Blocking business decisions | 会改变架构结果的关键选择已确认 |
| 现有代码事实 | 有旧项目时，已看清相关 owner 和稳定边界 |
| 设备/协议事实 | 能从文档、代码、日志确认的先确认 |
| 运行环境 | Windows、权限、网络、DLP/E-SafeNet 等重要限制 |
| 风险 | 高压、运动、长稳、兼容、历史数据等 |
不要求把所有未来细节提前讨论完。非阻塞问题可以 Deferred。
3. 系统边界：先写“谁负责什么”
| 边界对象 | 负责内容 | 不负责内容 |
|---|---|---|
| 上位机软件 | 交互、流程协调、状态展示、设备命令、数据与日志 | 替代现场安全判断或设备内部保护 |
| 外部设备 | 实际采集/执行动作/返回状态 | 保证上位机 UI 与业务状态一致 |
| 操作员 | 业务决策、授权、现场确认 | 记住软件应该自动保证的隐藏联锁 |
| 外部系统 | 下发任务、读取结果、交换数据 | 决定上位机内部线程/会话实现 |
真实设备动作的安全边界必须明确；界面“按钮禁用”不能替代后端联锁。
4. 分层只是讨论起点，不是模板强制
常见起点：
text
View / UI
↓
Application / Workflow
↓
Domain Rules / State
↓
Infrastructure / Device / Storage
↓
External Equipment目标不是增加层数，而是让关键行为有稳定 owner：
- UI 不直接拥有设备会话；
- 通信回调不直接决定所有业务后果；
- 数据保存不阻塞采集；
- 状态机/联锁不散落在多个按钮事件里。
如果现有项目已经有有效的稳定 seam，优先复用，不为了“标准架构”强行重构。
5. 模块设计看职责和稳定边界
每个关键模块回答：
text
Responsibility
Inputs
Outputs
StateOwner
SideEffects
Dependencies
Lifetime
StablePublicSeam比列几十个类名更重要。
特别关注：
- 谁拥有试验状态；
- 谁拥有设备 Session；
- 谁负责 Raw→工程量转换；
- 谁决定 AlarmOnly / InterlockFault；
- 谁负责最终持久化；
- 谁负责停止/释放。
6. 数据流和控制流都要能追踪
数据流
text
Device Raw
→ Receive
→ Parse
→ Measurement / Domain
→ Workflow State
→ UI / Storage / MES每一步说明单位、时间戳、owner 和是否保留证据。
控制流
text
Operator Action
→ Command
→ Workflow / Interlock
→ Device Service
→ Device Session
→ Response
→ State / Log / UI如果一个按钮能触发高压、运动、加热、气路等真实动作，后端必须有独立安全条件，不依赖 UI 外观。
7. 线程和资源只设计到“能说明生命周期”
总体设计阶段至少说明：
- UI thread；
- device/session task；
- receive/parse task；
- storage task；
- Timer/heartbeat；
- cancellation/stop path。
不需要提前规定每个 Task、锁或类名。
详细见 线程与资源生命周期。
8. ADR 不是“重要选择都写”
V10 只在同时满足以下三项时创建/更新 ADR：
- Hard to reverse：以后反悔代价高；
- Surprising without context：不记录原因，后来的人会觉得奇怪；
- Real trade-off：确实比较过至少两个合理方向。
适合 ADR：
- 为什么试验窗口内高压健康查询只能读缓存；
- 为什么某设备必须全局单 Session；
- 为什么历史数据格式暂时不迁移。
通常不需要 ADR：
- 普通 NuGet 版本小升级；
- UI 样式选择；
- 一次 Bug 修复；
- 常规日志字段；
- 易回退的局部实现。
ADR 不是 Changelog。
9. 总体设计和 Architecture Hotspot Review 不是一回事
总体设计：
text
我要建设/改变一个系统边界
→ 设计未来结构Architecture Hotspot Review：
text
现有项目为什么长期总返工？
→ 看 Git hot spots / coupling / stable seams
→ 找结构摩擦后者只在用户显式要求架构体检时运行，不随普通功能修改自动触发。
10. 风险优先检查
- 设备 Session 多 owner；
- UI 与设备动作耦合；
- 状态与副作用分散；
- Raw/工程值混用；
- 异常后果没有统一分类；
- 后台任务无法取消；
- 保存/日志阻塞采集；
- 历史配置/数据兼容不明确；
- 真实设备危险动作无后端联锁；
- 现场问题无法 Replay。
11. 总体设计输出按需要缩放
完整新项目可以有：
- 系统边界；
- 模块职责；
- 数据流/控制流；
- 生命周期；
- 关键状态；
- 重要 ADR；
- 风险与验证策略。
现有项目新增一个子系统时，只输出受影响部分，不重写全项目架构文档。
12. 进入详细设计前的 Ready 条件
只检查当前范围是否 ready：
- Blocking Frontier 是否清零；
- 系统边界是否清楚；
- 关键状态和副作用是否有 owner；
- 高风险设备动作是否有安全边界；
- 数据/通信/生命周期中需要专项设计的地方是否已识别；
- NonGoals 是否明确。
不要求把未来所有细节都提前确认。
对应能力
| 项目 | 内容 |
|---|---|
| 推荐 Skill | 02-system-designer |
| 需求发现 | 上位机项目需求拆解表 |
| 详细设计 | 详细设计总览 |
| Context / ADR | 项目 Context、Memory 与 ADR |
| 架构体检 | 代码审查与重构 |
一句话原则
只有系统边界真的需要设计时才做总体设计；少而稳定的职责和 seam，比为了“架构完整”增加更多层和文档更重要。