Appearance
架构决策 ADR 模板
ADR 是 Architecture Decision Record，意思是架构决策记录。
它不是正式论文，也不是复杂设计文档。它只解决一个问题：重要技术选择为什么这么定，后面的人能不能看懂当时的理由。
上位机项目里，很多问题不是“能不能写出来”，而是后来不知道为什么选 WPF、为什么用 SQLite、为什么通信解析要独立线程、为什么日志要记录原始十六进制。ADR 用来把这些关键选择留下来。
1. 什么时候需要写 ADR
不是每个按钮、每个字段都要写 ADR。以下情况建议写：
- WPF 还是 WinForms。
- 是否使用 MVVM。
- 串口和 TCP 是否做统一通信接口。
- 协议解析放在哪里。
- 接收线程、解析线程、UI 刷新怎么分。
- 数据保存用 CSV、SQLite、MySQL 还是其他方式。
- 日志记录到 UI、文件、数据库还是多处。
- 是否引入第三方图表库。
- 是否改变已有配置文件或数据库结构。
- 是否支持多设备、多连接或长时间运行。
小改、文案、简单绑定、明显 Bug 修复通常不需要 ADR。
2. ADR 编号
建议按顺序编号：
text
ADR-001-选择WPF作为主界面框架.md
ADR-002-通信接收和协议解析分离.md
ADR-003-第一阶段使用CSV保存测试数据.md文件可以放在项目的 docs/adr/ 目录，也可以先放在需求资料里。
3. ADR 模板
text
# ADR-编号：决策标题
## 状态
提议中 / 已接受 / 已废弃 / 已替代
## 背景
为什么需要做这个决策。
当前项目遇到什么问题。
有哪些约束条件。
## 决策
最终选择什么方案。
## 备选方案
| 方案 | 优点 | 缺点 | 是否采用 |
| --- | --- | --- | --- |
| 方案 A | | | 是 / 否 |
| 方案 B | | | 是 / 否 |
## 理由
为什么选择这个方案。
为什么没有选择其他方案。
## 影响范围
这个决策会影响哪些模块、文件、数据、测试或交付。
## 风险
这个选择可能带来什么问题。
如果风险发生，怎么处理。
## 验证方式
怎么证明这个决策可行。
## 后续复查点
什么情况下需要重新评估这个决策。4. 示例：第一阶段使用 CSV 保存数据
text
# ADR-001：第一阶段使用 CSV 保存测试数据
## 状态
已接受
## 背景
第一阶段目标是尽快跑通设备连接、数据采集、显示和保存。当前只有单机使用，没有多人同时查询要求，也没有复杂报表要求。用户希望测试完成后能直接用 Excel 打开数据。
## 决策
第一阶段使用 CSV 保存测试结果，不引入 SQLite 或 MySQL。
## 备选方案
| 方案 | 优点 | 缺点 | 是否采用 |
| --- | --- | --- | --- |
| CSV | 简单、可直接打开、便于调试 | 查询能力弱，数据量大时不方便 | 是 |
| SQLite | 查询方便，结构更规范 | 第一阶段开发和迁移成本更高 | 否 |
| MySQL | 多客户端和集中管理更好 | 需要部署数据库，不适合第一阶段 | 否 |
## 理由
CSV 能满足第一阶段“保存并可检查”的目标，降低开发和部署复杂度。后续如果需要历史查询、统计和权限，再评估 SQLite。
## 影响范围
数据保存服务、导出文件格式、验收清单、用户说明。
## 风险
数据量很大时，CSV 打开和查询会变慢。字段变更时需要注意兼容旧文件。
## 验证方式
完成一次测试后生成 CSV，检查字段完整、时间正确、数值和界面一致，文件可用 Excel 打开。
## 后续复查点
当需要按时间范围查询、按设备编号筛选、长期保存大量记录时，重新评估 SQLite。5. 发给 AI 的 ADR Prompt
text
请你作为 C# WPF/WinForms 上位机架构助手。
下面这个技术选择可能影响后续维护，请帮我写一份轻量 ADR。
决策主题：
【例如：通信接收和协议解析是否分离】
项目背景：
【粘贴需求、约束、设备、通信、数据或现场情况】
备选方案：
【如果已有备选方案就粘贴；没有就让 AI 帮忙列】
请输出：
1. ADR 标题和编号建议。
2. 背景。
3. 决策。
4. 备选方案对比。
5. 选择理由。
6. 影响范围。
7. 风险。
8. 验证方式。
9. 后续复查点。