架构决策记录 (ADR)
MRRC项目重要架构决策记录
AD-001: WebSocket实时通信协议
| 属性 | 值 |
|---|---|
| ID | AD-001 |
| 日期 | 2024-10-01 |
| 状态 | 已批准 |
| 决策者 | MRRC Team |
| 影响范围 | 整体架构 |
问题
如何在浏览器和服务器之间实现实时双向通信？
背景
- 需要实时传输控制命令（频率、模式、PTT）
- 需要实时传输音频数据（TX/RX）
- 延迟要求 < 100ms
- HTTP轮询效率低，不满足实时需求
决定
使用WebSocket作为主要通信协议，控制和音频复用同一连接。
理由
- 低延迟: 全双工通信，服务器可主动推送
- 效率高: 相比HTTP轮询，带宽节省90%+
- 浏览器原生支持: 无需额外库
- 单连接复用: 控制和音频共享连接，简化管理
替代方案
| 方案 | 描述 | 被排除原因 |
|---|---|---|
| HTTP轮询 | 定期GET请求 | 延迟高，浪费带宽 |
| Server-Sent Events | 单向推送 | 不支持双向 |
| WebRTC DataChannel | P2P | 穿透NAT困难 |
| Socket.IO | WebSocket封装 | 增加依赖 |
影响
正面影响: - 实时性大幅提升 - 架构简洁 - 调试方便
负面影响: - 需要WebSocket支持（现代浏览器均支持）
涉及模块: - 前端: controls.js - 后端: MRRC主程序
AD-002: Tornado Web框架选型
| 属性 | 值 |
|---|---|
| ID | AD-002 |
| 日期 | 2024-10-01 |
| 状态 | 已批准 |
| 决策者 | MRRC Team |
| 影响范围 | 后端架构 |
问题
选择什么作为Web服务器框架？
背景
- 需要WebSocket支持
- 需要处理静态文件
- 需要与PyAudio集成
- Python生态优先
决定
使用Tornado作为Web服务器框架。
理由
- 原生WebSocket: 内置WebSocketHandler，无额外依赖
- 异步I/O: 适合实时通信场景
- 静态文件服务: 内置支持
- 与PyAudio兼容: 同为Python生态
替代方案
| 方案 | 描述 | 被排除原因 |
|---|---|---|
| Flask-SocketIO | Flask扩展 | 需要额外依赖 |
| FastAPI | 现代异步框架 | WebSocket支持复杂 |
| aiohttp | 异步HTTP | 静态文件需另配 |
| Node.js | 完全不同栈 | 团队不熟悉 |
影响
正面影响: - 开发效率高 - 社区活跃 - 文档完善
负面影响: - 性能略低于Node.js
AD-003: Int16音频编码
| 属性 | 值 |
|---|---|
| ID | AD-003 |
| 日期 | 2024-11-01 |
| 状态 | 已批准 |
| 决策者 | MRRC Team |
| 影响范围 | 音频系统 |
问题
选择什么音频编码格式传输？
背景
- 原始PCM 48kHz/32bit每样本带宽过高
- 需要在带宽和音质间平衡
- 目标延迟 < 100ms
决定
TX/RX均使用Int16编码，采样率16kHz。
理由
- 带宽减半: 相比Float32，节省50%带宽
- 音质足够: 16kHz/16bit满足语音通信
- 编码简单: 无复杂算法，延迟低
- 兼容性: 所有浏览器支持
替代方案
| 方案 | 描述 | 被排除原因 |
|---|---|---|
| Float32 | 原始格式 | 带宽高 |
| Opus | IETF标准 | 编码延迟 |
| AAC | Apple标准 | 专利问题 |
| MP3 | 有损压缩 | 延迟高 |
影响
正面影响: - 带宽节省50% - 延迟低 - 实现简单
负面影响: - 音质不如无损格式
AD-004: WDSP NR2降噪集成
| 属性 | 值 |
|---|---|
| ID | AD-004 |
| 日期 | 2026-03-09 |
| 状态 | 已批准 |
| 决策者 | MRRC Team |
| 影响范围 | DSP模块 |
问题
选择什么作为音频降噪方案？
背景
- RNNoise降噪效果一般
- 需要专业级SSB语音降噪
- 目标15-20dB降噪深度
决定
集成WDSP库的NR2频谱降噪算法。
理由
- 专为SSB优化: OpenHPSDR项目出品
- 降噪深度: 15-20dB，远超RNNoise
- 语音保真: 频谱减法，语音失真小
- 低延迟: < 20ms处理延迟
替代方案
| 方案 | 描述 | 被排除原因 |
|---|---|---|
| RNNoise | 神经网络 | 降噪深度不足 |
| WebRTC NS | 通用语音 | 非SSB优化 |
| Audacity | 离线处理 | 不适合实时 |
影响
正面影响: - 降噪效果显著提升 - 语音清晰 - 专业级品质
负面影响: - 需要编译WDSP库 - 配置复杂度增加
AD-005: 多实例部署架构
| 属性 | 值 |
|---|---|
| ID | AD-005 |
| 日期 | 2026-03-10 |
| 状态 | 已批准 |
| 决策者 | MRRC Team |
| 影响范围 | 部署架构 |
问题
如何在单台服务器支持多台独立电台？
背景
- 单实例只能控制一台电台
- 多电台需要独立服务和端口
- 配置管理复杂
决定
采用配置文件隔离 + Unix Socket隔离架构。
理由
- 配置隔离: 每个实例独立配置文件
- 端口隔离: 每个实例独立Web端口
- Socket隔离: ATR-1000通信通过独立Socket
- 平滑扩展: 新实例只需添加配置
替代方案
| 方案 | 描述 | 被排除原因 |
|---|---|---|
| Docker容器 | 容器化部署 | 资源消耗大 |
| 进程隔离 | 多进程 | 配置复杂 |
| 数据库隔离 | 共享实例 | 不够隔离 |
影响
正面影响: - 支持多电台 - 配置清晰 - 运维简单
负面影响: - 端口占用增加
AD-006: 语音助手架构
| 属性 | 值 |
|---|---|
| ID | AD-006 |
| 日期 | 2026-03-12 |
| 状态 | 已批准 |
| 决策者 | MRRC Team |
| 影响范围 | 语音模块 |
问题
如何实现AI语音助手功能？
背景
- 需要语音识别功能
- 需要语音合成功能
- 需要本地运行保护隐私
决定
采用Whisper ASR + Qwen3-TTS本地部署架构。
理由
- 本地运行: 不依赖云服务，保护隐私
- Whisper: OpenAI开源，识别准确
- Qwen3-TTS: 阿里开源，音质好
- 低延迟: 本地推理，无需网络
替代方案
| 方案 | 描述 | 被排除原因 |
|---|---|---|
| 云语音API | 阿里/腾讯/Google | 隐私问题 |
| Whisper.cpp | C++移植 | 实现复杂 |
| Coqui TTS | 开源TTS | 效果一般 |
影响
正面影响: - 隐私保护 - 离线可用 - 定制性强
负面影响: - 本地资源需求高
AD-007: CW实时解码架构
| 属性 | 值 |
|---|---|
| ID | AD-007 |
| 日期 | 2026-03-13 |
| 状态 | 已批准 |
| 决策者 | MRRC Team |
| 影响范围 | CW模块 |
问题
如何实现CW实时解码？
背景
- CW通信需要实时解码
- 需要低延迟
- 需要离线运行
决定
采用ONNX Runtime前端推理架构。
理由
- ONNX格式: 跨平台模型格式
- Web运行: 浏览器可直接运行
- 低延迟: 实时推理
- 模型成熟: cw_decoder.onnx可用
替代方案
| 方案 | 描述 | 被排除原因 |
|---|---|---|
| Fldigi | 桌面软件 | 无法集成 |
| CWGet | Windows软件 | 闭源 |
| Cloud API | 云服务 | 延迟高 |
影响
正面影响: - 实时解码 - 浏览器集成 - 离线可用
负面影响: - 模型精度依赖
决策清单
使用此清单确保决策完整：
- [x] 问题清晰定义
- [x] 背景信息完整
- [x] 至少考虑3个替代方案
- [x] 决策理由充分
- [x] 影响分析完整
- [x] 派生需求记录
- [x] 相关团队已知会
- [x] 文档已版本化
AD-008: PTT 三层安全防护系统 (V5.6+)
| 属性 | 值 |
|---|---|
| 编号 | AD-008 |
| 标题 | PTT 三层安全防护系统 |
| 日期 | 2026-06-10 |
| 状态 | 已实现 |
| 决策 | 采用三层防护架构：L1浏览器守护 (touchmove/visibilitychange/pagehide强制释放)、L2释放ACK协议 (3次重试+冗余音频通路回退)、L3服务端保护 (120s TOT硬限制+每2s持续重试PTT释放) |
| 理由 | 远程电台操控最危险的故障是卡在发射状态，需要独立的多层冗余保护。触屏设备触摸事件不可靠，WebSocket可能半开，硬件PTT释放可能失败——每层针对不同的故障模式 |
| 影响 | tx_button_optimized.js (30s看门狗+锁泄漏检测+触摸滑动释放), ptt_manager.js (ACK协议+冗余路径), PTTSafetyMonitor线程 (120s TOT+广播) |
AD-009: FT8/ULTRON 远程控制台架构 (V5.6+)
| 属性 | 值 |
|---|---|
| 编号 | AD-009 |
| 标题 | FT8/ULTRON WebSocket 远程控制台 |
| 日期 | 2026-06-12 |
| 状态 | 已实现 |
| 决策 | 采用浏览器全功能远程控制台替代本地Python脚本：UDP→WebSocket桥接 (ft8_integration.py监听2238)，服务端QSOSequencer状态机，客户端Canvas瀑布图+6 TX消息槽+DXCC实体查询。JTDX/WSJT-X/MSHV UDP 2237 ⇄ WS桥接2238 |
| 理由 | 纯浏览器方案无需本地安装，手机/平板可操作FT8。服务端序列器使用Reply数据包可靠触发TX。WebSocket广播实现多客户端同步显示解码结果 |
| 影响 | ft8_integration.py (UDP监听+QSOSequencer+ADIF日志), ft8_ultron.js (完整UI+瀑布图+DXCC查询), ft8_ultron.html (SPA界面) |
文档信息 - 版本: 1.1 - 创建日期: 2026-06-19 - 最后更新: 2026-06-19 - 作者: MRRC Team