架构决策记录(ADR)

← 开发流程规范 | ← 主页

来源:Stage4 03 架构决策记录 Architecture Decision Record(ADR)


1. 文档目的与范围

本文件用于记录智能手表/手环系统在架构层面的关键决策(Architecture Decision),包含:问题背景、备选方案、最终决策、理由、影响与验证证据。

ADR 作为“可追溯的架构记忆”,与 SyRS / SAD / RAM / SID / SSRD / SDD 等文档相互引用,用于:评审、迭代、回归与交付。

2. ADR 使用规范

  1. 每个 ADR 必须唯一编号(ADR-XXX),且不可随意重写历史;如需变更,新增一条 ADR 或将原 ADR 标记为 Superseded。
  2. 每个 ADR 必须给出可验证的验收/证据项,避免仅停留在“观点”。
  3. 每个 ADR 必须关联 SyRS 需求编号(至少 1 条),并在 RAM 中体现分配归属。
  4. 评审通过后状态从 Proposed 变更为 Accepted;废弃则为 Deprecated。

文档变更记录

版本日期修改内容作者审核
V1.02025-12-28按大厂ADR模板重构;补齐决策驱动、备选方案、影响、验证与需求追溯;新增8条核心ADR。System ArchitectPM/QA

ADR 索引

ADR ID标题状态日期Owner关联需求(SyRS)
ADR-001通信优先级:本地网优先,公网为可选增强Accepted2025-12-28System Architect / 嵌入式负责人SyRS-COMM-001, SyRS-COMM-002, SyRS-OPS-001
ADR-002低功耗策略:软硬协同(Tickless + 分域电源 + 事件驱动)Accepted2025-12-28System Architect / 嵌入式负责人SyRS-PWR-001, SyRS-PWR-002, SyRS-PERF-001
ADR-003计算与通信分工:双MCU架构(STM32负责应用/显示;nRF负责BLE/mesh)Accepted2025-12-28System ArchitectSyRS-ARCH-001, SyRS-COMM-003
ADR-004定位策略:取消内置GPS,位置由手机GPS/网关提供 + Mesh近场定位辅助Accepted2025-12-28产品经理 & System ArchitectSyRS-LOC-001, SyRS-LOC-002
ADR-005数据策略:本地缓存优先(Flash)+ 事件化上报 + 断点续传Accepted2025-12-28系统工程师SyRS-DATA-001, SyRS-DATA-002, SyRS-OPS-002
ADR-006升级策略:双链路OTA(BLE为主,USB/有线为备)+ 安全校验Accepted2025-12-28嵌入式负责人SyRS-OTA-001, SyRS-SEC-001
ADR-007消息与服务边界:应用层不直接操作驱动,采用服务层统一封装(Service Layer)Accepted2025-12-28软件架构师SyRS-MAINT-001, SyRS-TEST-001
ADR-008可观测性:统一日志 + 关键事件追踪 + 故障自愈Accepted2025-12-28测试/质量负责人SyRS-DBG-001, SyRS-REL-001

ADR-001 通信优先级:本地网优先,公网为可选增强

状态Accepted日期2025-12-28
OwnerSystem Architect / 嵌入式负责人参与者产品经理, 系统工程师, 硬件架构师, 嵌入式工程师, 测试/QA, 运维/交付
关联文档SyRS, SAD, RAM, SID, BRD关联需求SyRS-COMM-001, SyRS-COMM-002, SyRS-OPS-001

决策驱动因素

  • 目标场景“矿井/山区/海上平台”等网络受限,公网不可依赖
  • 安全合规:关键告警必须在本地就地闭环(不依赖云)
  • 功耗与成本:避免引入蜂窝模组与高功耗协议栈
  • 可交付性:一线落地需要“离线可用 + 有网增强”

背景与问题

本产品用于危险/高风险作业环境的生命体征监控与安全预警。现场可能存在:无蜂窝信号、Wi‑Fi不可用、网络受限或不允许连接公网等情况。

如果将云端作为唯一依赖,一旦断网则告警失效;如果引入4G/5G模组,会显著抬升BOM、功耗与认证成本。

因此需要明确“本地通信/本地告警/本地组网”作为主能力,公网/手机作为增强能力。

备选方案

  • A. 公网优先(4G/5G直连云):手表直接通过蜂窝网络上报云端,云端统一告警与管理。
  • 优点:架构简单(云做中心);跨区域统一管理方便
  • 缺点:受限网络场景不可用;功耗与BOM高;蜂窝认证/运营成本高;断网导致告警链路中断
  • B. 本地网优先(BLE Mesh/组网)+ 可选网关上云:现场设备通过BLE Mesh形成局域网;网关(手机/固定网关)在有网时再汇聚上云。
  • 优点:离线可用,告警链路就地闭环;低功耗、低成本;可渐进式上云;适配多现场环境
  • 缺点:需要设计组网、路由、网关转发与数据一致性策略;对现场部署有一定要求
  • C. LoRa/私有Sub‑GHz组网 + 可选上云:用Sub‑GHz做远距低速数据上报。
  • 优点:覆盖距离更远;穿透能力好
  • 缺点:带宽/时延受限,不适合高频数据;需要额外射频与合规认证;生态与手机协同弱
  • D. Wi‑Fi为主:依赖现场Wi‑Fi覆盖与AP。
  • 优点:带宽高,易上云
  • 缺点:现场往往无Wi‑Fi或不允许接入;功耗高;配置复杂

最终决策

采用 本地网优先(BLE Mesh) 作为默认通信与告警闭环;公网/云作为“可选增强”。

默认链路:手表↔(BLE Mesh)↔就地网关/中继(可选)→本地管理端(可选)。

增强链路:在网关具备公网(手机/固定网关)时,进行数据汇聚、断点续传与云端同步。

决策理由

  • 最小可用原则:在最差网络条件下仍满足核心安全功能(生命体征告警/紧急求救/电子围栏)。
  • 软硬成本可控:不引入蜂窝模组,降低BOM与功耗压力。
  • 演进友好:有网时可扩展云端能力(数据看板、设备管理、追溯报表)。

影响与后果

  • ✅ 核心告警链路不依赖云端,可靠性更高
  • ✅ 可按项目分层交付:离线版/联网增强版
  • ✅ 利于功耗与续航目标达成
  • ⚠️ 需要实现Mesh组网、数据路由、网关转发与异常恢复机制
  • ⚠️ 测试复杂度提高(离线/弱网/移动场景)

落地动作 / 待办

  1. 定义Mesh消息模型(心率/体温/告警/状态心跳)与版本兼容策略
  2. 制定网关职责边界:聚合、缓存、重传、上云鉴权
  3. 在SyRS中补充“离线可用”与“上云增强”两套验收标准

验证与证据

  • 弱网/断网场景:在无公网条件下,告警在本地5s内闭环(实际值按SyRS)
  • Mesh规模:X个节点下的丢包率/时延测试(按SyRS指标)
  • 网关断点续传:断网→恢复后数据一致性验证

ADR-002 低功耗策略:软硬协同(Tickless + 分域电源 + 事件驱动)

状态Accepted日期2025-12-28
OwnerSystem Architect / 嵌入式负责人参与者硬件架构师, 嵌入式工程师, 算法工程师, 测试/QA
关联文档SyRS, SAD, SSRD, SDD关联需求SyRS-PWR-001, SyRS-PWR-002, SyRS-PERF-001

决策驱动因素

  • 手环/手表续航为强约束(作业班次/巡检周期)
  • 受限环境下不能依赖频繁充电或更换电池
  • 多传感器 + 显示 + 无线组网带来持续功耗压力

背景与问题

产品包含显示、PPG/体温/IMU等传感器、BLE通信与本地存储。若采用“常亮屏 + 常采样 + 常连接”,续航无法满足业务。

需要明确“功耗预算”与“工作模式(Active/Idle/Sleep/DeepSleep)”并在软硬两侧形成可验证的策略。

备选方案

  • A. 简单策略:屏幕熄灭 + 轮询采样:通过降低屏幕亮度/熄屏来省电,其他模块基本轮询。
  • 优点:实现简单
  • 缺点:CPU唤醒频繁,整体功耗仍高;无法对无线与传感做系统级优化
  • B. 软硬协同:事件驱动 + Tickless Idle + 分域电源控制:用RTOS Tickless进入Stop/Standby;传感器按事件/窗口采样;无线按连接窗口工作;必要外设分域供电。
  • 优点:系统级省电效果明显;可量化功耗预算;模式可扩展
  • 缺点:需要严格的唤醒源设计与时钟管理;实现/验证工作量较大
  • C. 极致低功耗:硬件Always‑on协处理器:引入超低功耗协处理器负责采样与唤醒。
  • 优点:续航最优
  • 缺点:硬件复杂度与成本增加;开发周期变长

最终决策

采用 方案B:软硬协同低功耗。

关键约束:

  1. FreeRTOS(或等效RTOS)启用 Tickless Idle,空闲进入低功耗模式;

  2. 以RTC/外部中断/蓝牙事件为主要唤醒源;

  3. 传感器采样采用“窗口化 + 动态频率”(如静息/运动不同策略);

  4. 显示与背光按交互驱动;

  5. 定义统一电源状态机(Power State Machine),由服务层集中管理。

决策理由

  • 在不增加硬件成本的前提下获得最显著的系统级省电收益。
  • 满足课程/项目对“可解释、可验证”的工程化目标:每个模式都有进入/退出条件、功耗指标与测试用例。

影响与后果

  • ✅ 续航目标可通过功耗预算分解到各模块
  • ✅ 模式化设计利于测试与持续优化
  • ⚠️ 需要统一管理时钟、外设状态与互斥访问,否则容易出现唤醒后外设异常
  • ⚠️ 调试手段要求提升(功耗仪、事件日志、唤醒原因统计)

落地动作 / 待办

  1. 在SSRD/SDD中定义Power Manager服务(接口、状态机、事件源)
  2. 建立功耗测试用例:Active/Idle/Stop各模式电流、唤醒时延、丢事件率
  3. 将关键唤醒源(RTC、按键、告警中断、BLE事件)写入SID接口定义

验证与证据

  • 功耗指标:按SyRS-PWR-001/002验收(不同模式电流与续航估算)
  • 唤醒原因统计:每次唤醒记录来源,保证可追溯
  • 异常场景:低电量、温度异常、无线重连下的功耗回归

ADR-003 计算与通信分工:双MCU架构(STM32负责应用/显示;nRF负责BLE/mesh)

状态Accepted日期2025-12-28
OwnerSystem Architect参与者硬件架构师, 嵌入式工程师, BLE工程师, 测试/QA
关联文档SAD, SID, SyRS, SSRD关联需求SyRS-ARCH-001, SyRS-COMM-003

决策驱动因素

  • BLE Mesh协议栈复杂且需要成熟生态(Nordic)
  • 应用侧需要显示/UI/多传感驱动与RTOS任务调度
  • 将无线与应用隔离,降低耦合与风险

背景与问题

硬件设计采用STM32F411 + nRF52840。STM32侧连接显示/传感/存储;nRF侧负责BLE与Mesh。

需要明确两颗MCU的职责边界、通信接口、升级策略与故障隔离机制。

备选方案

  • A. 单MCU完成全部(仅STM32或仅nRF):所有功能集中在一颗MCU上。
  • 优点:硬件更简单;接口更少
  • 缺点:BLE Mesh实现与维护成本高(非强项平台);资源争用导致实时性/稳定性风险;风险集中
  • B. 双MCU分工(推荐):无线栈与应用栈分离,通过UART/SPI协议连接。
  • 优点:风险隔离、职责清晰;便于并行开发与测试;无线栈可复用Nordic成熟方案
  • 缺点:需要设计MCU间协议与同步机制;调试复杂度上升

最终决策

采用双MCU分工:

  • STM32F411:传感器采集、显示交互、业务逻辑、本地存储、功耗管理主控;
  • nRF52840:BLE(含Mesh)、连接管理、安全配对、与网关/手机交互;
  • MCU间通过 UART(主链路)(可选SPI作为升级/高速通道)通信,协议定义在SID中。

同时定义“故障降级”:nRF异常时STM32仍可本地告警与记录。

决策理由

  • 无线协议栈与应用业务解耦,降低复杂度与风险。
  • 便于课程呈现:能清晰展示分层/分域/接口契约的工程方法。

影响与后果

  • ✅ 并行开发:BLE团队与应用团队可独立迭代
  • ✅ 隔离与降级能力更强
  • ⚠️ MCU间通信协议成为关键路径,需要严格版本管理与回归测试

落地动作 / 待办

  1. 在SID中定义UART帧格式、命令集、超时/重传、版本协商
  2. 在RAM中明确需求分配到STM32或nRF侧
  3. 定义联调测试:丢包/重传/断电恢复/固件版本不一致场景

验证与证据

  • 接口一致性测试:SID命令覆盖率≥X%(按SyRS)
  • 降级验证:nRF失联时本地告警仍可触发并记录

ADR-004 定位策略:取消内置GPS,位置由手机GPS/网关提供 + Mesh近场定位辅助

状态Accepted日期2025-12-28
Owner产品经理 & System Architect参与者产品经理, 系统工程师, 硬件架构师, BLE工程师
关联文档BRD, SyRS, SAD关联需求SyRS-LOC-001, SyRS-LOC-002

决策驱动因素

  • 体积/功耗/BOM约束:内置GNSS成本与功耗高
  • 受限网络场景下定位更依赖现场管理与近场范围判定
  • 产品已明确:GPS通过BLE从手机端获取

背景与问题

需求包含“人员位置/电子围栏/轨迹回放”等能力。但在矿井等室内/地下环境,GNSS本身也不可用。

因此定位应分层:室外用手机/网关GPS;室内/地下用Mesh近场(RSSI、锚点)实现区域级定位与围栏。

备选方案

  • A. 手表内置GNSS:手表自带GNSS模块获取位置。
  • 优点:不依赖手机
  • 缺点:功耗高,室内不可用,成本高,天线设计复杂
  • B. 手机/网关提供GPS(BLE同步)+ 室内用Mesh近场:手表在连接手机/网关时同步GPS;无GPS时使用Mesh锚点判定区域/距离。
  • 优点:满足室外定位需求;成本/功耗可控;更符合地下/室内的实际
  • 缺点:需要手机/网关App配合;室内定位精度为“区域级”而非米级

最终决策

取消内置GPS模块;位置来源优先级:

  1. 手机/网关提供GPS(BLE同步,带时间戳);

  2. Mesh锚点近场定位(区域级)用于电子围栏与人员分布。

对外承诺:定位精度按SyRS-LOC指标定义(区分室外/室内)。

决策理由

  • 真实场景驱动:地下/室内GNSS无意义,做“区域围栏/就地告警”更落地。
  • 满足需求同时控制成本与功耗。

影响与后果

  • ✅ 硬件更简洁,续航更好
  • ✅ 定位能力与场景匹配度更高
  • ⚠️ 依赖手机/网关提供室外定位与上报
  • ⚠️ 需要解释定位精度与使用边界(培训/文档)

落地动作 / 待办

  1. 在SyRS中区分室内/室外定位需求与验收标准
  2. 在SID中定义GPS同步数据结构(经纬度、精度、时间戳、来源)
  3. 在BRD中补充“室内区域定位”对电子围栏的价值说明

验证与证据

  • 室外:手机GPS同步成功率/时延/丢包率测试
  • 室内:锚点覆盖下的区域判定准确率测试

ADR-005 数据策略:本地缓存优先(Flash)+ 事件化上报 + 断点续传

状态Accepted日期2025-12-28
Owner系统工程师参与者嵌入式工程师, 测试/QA, 运维/交付
关联文档SyRS, SAD, SSRD, SID关联需求SyRS-DATA-001, SyRS-DATA-002, SyRS-OPS-002

决策驱动因素

  • 现场可能长时间离线,数据必须可追溯
  • 告警信息需要可复盘(事故分析)
  • 存储空间与写入寿命需要工程化管理

背景与问题

生命体征数据(心率/体温/血氧等)包含连续数据与事件数据。连续数据量大,不适合全部实时上云;但关键告警必须可靠保存与上传。

需要在设备侧定义:采样频率、存储格式、保留策略、上传策略与一致性。

备选方案

  • A. 全量实时上报:所有数据实时通过无线发送。
  • 优点:云端最完整
  • 缺点:离线不可用、功耗高、链路压力大
  • B. 本地缓存 + 事件化上报(推荐):设备侧保存时间序列;关键事件实时上报;网络恢复后批量同步。
  • 优点:离线可用;功耗可控;事故可追溯
  • 缺点:需要存储管理、索引、上传队列与一致性机制

最终决策

采用本地缓存 + 事件化上报:

  • 连续数据按窗口聚合存储(例如每N秒一包,含校验与时间戳);
  • 告警/求救为高优先级事件,优先广播与上报;
  • 网络恢复后按序断点续传,上传完成后可按策略清理。

存储介质优先使用外部SPI Flash(如W25Q系列),并实现写入寿命管理。

决策理由

  • 兼顾离线可用、功耗与数据价值密度。
  • 将数据流从“连续洪水”转为“事件驱动”,更利于业务闭环。

影响与后果

  • ✅ 离线情况下数据不丢失,满足事故追溯
  • ✅ 无线带宽与功耗更可控
  • ⚠️ 需要实现Flash磨损均衡/文件系统/日志结构存储等方案
  • ⚠️ 需要定义数据治理策略(保留周期、导出方式)

落地动作 / 待办

  1. 在SSRD中定义Data Logger服务(数据包格式、索引、清理策略)
  2. 在SID中定义上传协议(批量、校验、断点续传)
  3. 在测试计划中加入Flash寿命与掉电恢复测试

验证与证据

  • 掉电恢复:写入中断后数据可恢复且不破坏索引
  • 断点续传:中途断链后可从最后确认点继续
  • 寿命评估:按写入频率估算并验证擦写次数

ADR-006 升级策略:双链路OTA(BLE为主,USB/有线为备)+ 安全校验

状态Accepted日期2025-12-28
Owner嵌入式负责人参与者BLE工程师, 嵌入式工程师, 测试/QA
关联文档SyRS, SAD, SSRD, SDD关联需求SyRS-OTA-001, SyRS-SEC-001

决策驱动因素

  • 现场设备分散,必须支持无线升级
  • 弱网/断网常见,升级需要可恢复
  • 固件安全与防篡改是基本要求

背景与问题

产品包含两颗MCU与多模块软件,升级需要考虑:包管理、版本兼容、失败回滚、以及安全校验。

受限网络场景下,升级包更可能通过手机/网关下发,而非设备直接下载。

备选方案

  • A. 仅BLE升级:所有固件通过BLE下发。
  • 优点:使用方便;无需额外接口
  • 缺点:需要处理弱网、重传、回滚;对大包耗时较长
  • B. BLE为主 + 有线兜底(推荐):日常BLE OTA;异常/返修可USB/有线升级。
  • 优点:现场可用性高;故障恢复路径明确
  • 缺点:需要同时维护两套升级链路

最终决策

采用BLE为主的OTA方案:

  • nRF侧采用成熟DFU机制升级自身固件;
  • STM32侧固件通过nRF转发下发到外部Flash,再由Bootloader完成切换(支持回滚/失败保护);
  • USB/有线作为生产/返修兜底。

安全:升级包需做完整性校验(CRC/Hash)与签名/密钥校验(按SyRS-SEC定义)。

决策理由

  • BLE链路与手机生态匹配,适合现场分发升级包。
  • 有线兜底保证交付可控与售后可修复。

影响与后果

  • ✅ 升级路径清晰,覆盖日常与极端场景
  • ✅ 安全校验降低被篡改风险
  • ⚠️ Bootloader与升级协议需要较严格测试(掉电、断链、版本不匹配)

落地动作 / 待办

  1. 在SID中定义升级命令集与状态机(开始/分包/校验/提交/回滚)
  2. 在SSRD中定义Bootloader接口与镜像布局(A/B或主备)
  3. 制定升级测试矩阵:断电点、丢包率、跨版本升级、回滚验证

验证与证据

  • 断链/掉电恢复:升级中断后可重试或回滚到旧版本
  • 安全验证:非法包/旧包重放被拒绝
  • 量产测试:生产线升级耗时与成功率统计

ADR-007 消息与服务边界:应用层不直接操作驱动,采用服务层统一封装(Service Layer)

状态Accepted日期2025-12-28
Owner软件架构师参与者嵌入式工程师, 测试/QA
关联文档SAD, SSRD, SDD关联需求SyRS-MAINT-001, SyRS-TEST-001

决策驱动因素

  • 降低耦合,提高可测试性与可演进性
  • 避免多任务/多模块抢占外设造成不稳定
  • 便于将来平台化迁移与模块复用

背景与问题

项目包含显示、传感、无线、存储、功耗等多个模块,且在RTOS下并发运行。若应用层直接调用驱动,容易出现资源争用与跨层耦合。

需要明确“服务层”作为统一入口:管理资源、缓存数据、提供稳定API。

备选方案

  • A. 应用层直连驱动:App任务直接调用I2C/SPI/Flash/LCD驱动。
  • 优点:初期开发快
  • 缺点:耦合高、难测试;资源争用频繁;后期维护成本高
  • B. 引入服务层(推荐):App只调用服务层接口;服务层内部管理驱动与任务交互。
  • 优点:高内聚低耦合;便于Mock与单元测试;线程安全更集中
  • 缺点:需要先做接口与边界设计

最终决策

采用服务层封装:

  • 传感服务(Sensor Service):采样调度、滤波/算法入口、数据缓存;
  • 通信服务(Comms Service):与nRF命令交互、重传、状态机;
  • 存储服务(Storage Service):日志/数据落盘、索引、导出;
  • 功耗服务(Power Service):模式切换与唤醒源管理;

服务层对外提供线程安全API;应用层以“事件/消息”驱动业务流程。

决策理由

  • 把复杂性关进笼子:资源互斥、时序约束、错误恢复都在服务层处理。
  • 服务层天然适配需求到实现的追溯(SSRD→SDD→代码)。

影响与后果

  • ✅ 并发稳定性提升,接口更清晰
  • ✅ 测试可控:服务层可Mock驱动做单元测试
  • ⚠️ 初期需要投入接口设计与基础设施(消息队列、事件总线)

落地动作 / 待办

  1. 在SSRD中为每个服务层定义职责、接口、线程模型与错误码
  2. 在SDD中补充服务层状态机与模块交互图
  3. 建立驱动访问规则:统一从服务层进入(禁止App直接访问)

验证与证据

  • 并发测试:LCD/I2C/Flash在高负载下无死锁/无丢数据
  • 接口回归:服务层API变更需更新SID/SSRD并跑回归

ADR-008 可观测性:统一日志 + 关键事件追踪 + 故障自愈

状态Accepted日期2025-12-28
Owner测试/质量负责人参与者嵌入式工程师, 系统工程师, 交付/运维
关联文档SyRS, SSRD, SDD关联需求SyRS-DBG-001, SyRS-REL-001

决策驱动因素

  • 现场问题难复现,需要可追溯证据链
  • 弱网环境下远程调试能力受限
  • 医疗/安全类产品对可靠性要求更高

背景与问题

设备在复杂电磁/温湿环境下运行,可能出现偶发重启、无线异常、传感器失联等问题。

必须在系统层设计可观测性:日志、事件、计数器与故障恢复策略。

备选方案

  • A. 仅串口日志:开发阶段使用串口打印。
  • 优点:简单
  • 缺点:现场不可用、影响功耗、数据不持久
  • B. 统一日志 + 持久化事件(推荐):关键事件写入Flash环形缓冲,必要时导出或通过网关上传。
  • 优点:可追溯;对现场友好;可做可靠性统计
  • 缺点:需要存储空间与格式管理

最终决策

实现统一可观测性框架:

  • 运行日志:分级(INFO/WARN/ERROR),可按需开启;
  • 关键事件:告警、重启原因、连接状态、升级状态等写入持久化环形缓冲;
  • 故障自愈:关键模块心跳与看门狗策略,异常自动重连/重初始化;
  • 导出:USB/有线导出 + 网关上传两种方式。

决策理由

  • 把“不可复现”变成“可定位”:面向交付的工程能力。
  • 同时服务研发与量产阶段的可靠性统计。

影响与后果

  • ✅ 现场问题定位效率大幅提升
  • ✅ 形成可靠性数据闭环(MTBF、重启分布、告警统计)
  • ⚠️ 需要额外Flash空间与写入寿命管理
  • ⚠️ 日志开关与隐私合规需要明确

落地动作 / 待办

  1. 定义事件码表与日志格式(含版本、时间戳、上下文)
  2. 在SyRS中增加可观测性验收项(导出、上传、容量、保留周期)
  3. 在测试中加入长稳(72h/168h)与故障注入测试

验证与证据

  • 长稳测试:日志不爆、写入不异常、无内存泄漏
  • 故障注入:传感器断开/无线干扰/低电压下可记录并恢复