业余无线电管理系统3.0.0：系统总体技术架构

文件路径：docs/architecture/architecture-overview.md
文档版本：v0.1
适用版本：业余无线电QSL管理系统 3.0.0
文档状态：初稿

1. 文档目的

本文档用于说明 业余无线电QSL管理系统 3.0.0 的总体技术架构，统一移动端、PC端、Halo插件及未来第三方客户端的系统定位、模块关系、数据流向和职责边界。

本文档主要回答以下问题：

系统由哪些部分组成；
移动端、PC端和Halo插件分别承担什么职责；
本地数据、Halo共享数据和外部服务之间如何形成整体关系；
各业务模块在系统中的位置；
后续专项技术文档如何在总体架构下展开。

QSO字段、QSL字段、同步状态机、API格式、Halo Custom Model、Radio HAL接口及其他具体实现，由对应专项文档分别定义。

2. 项目技术定位

业余无线电QSL管理系统 3.0.0 是一套面向个人电台、俱乐部电台、比赛台及其他业余无线电活动场景的开放软件平台。

系统由以下三个主要终端组成：

移动端：承担随身日志、户外操作、QSL管理、媒体采集及轻量设备功能；
PC端：承担固定台日志、电台控制、音频与数字信号处理及复杂操作；
Halo插件：承担联网数据管理、多人协作、Web展示、公开查询及同步服务。

三个终端共享统一的领域模型、数据交换规范和业务语义，但可以根据各自场景提供不同的功能范围。

系统整体定位可以概括为：

移动端负责随身使用，PC端负责电台工作站，Halo插件负责自托管的联网数据节点和Web服务。

3. 总体架构目标

3.1 本地优先

移动端和PC端均以本地数据库为基础。

日志记录、QSL管理、媒体整理及其他主要操作首先在本地完成。网络和Halo服务作为同步及扩展能力，不参与本地数据写入的必要事务。

因此，用户在没有互联网、Halo服务不可用或主动切换至脱机模式时，仍可以继续完成本地工作。

3.2 Halo可选

Halo插件是用户可以自行部署的联网节点，而不是移动端和PC端运行的前置条件。

系统支持以下使用组合：

使用方式	说明
移动端独立使用	仅在移动设备上保存和管理本地数据
PC端独立使用	仅在固定台计算机上运行
移动端与PC端分别使用	各自保存本地数据，通过开放格式交换
Halo插件独立使用	通过浏览器录入、管理和展示日志
客户端连接Halo	在本地使用基础上增加同步和Web能力
多客户端连接Halo	多台移动设备和PC共同使用同一Station Workspace
第三方客户端连接Halo	通过开放API接入项目数据体系

3.3 数据开放

系统核心业务数据采用开放的数据定义和交换方式。

用户可以通过ADIF、项目备份格式、开放API及媒体原文件导出自己的数据，避免形成只能由某一个客户端或某一个在线服务读取的数据孤岛。

3.4 多端职责互补

移动端、PC端和Halo插件不追求完全相同的功能。

三端围绕统一业务对象形成互补关系：

移动端强调便携、现场使用和快速记录；
PC端强调设备连接、运算能力和复杂交互；
Halo强调联网管理、共享、协作和公开展示。

3.5 模块化和可扩展

QSO、QSL、媒体、电台、数字模式、同步及外部服务采用相对独立的模块组织。

具体电台协议、外部日志服务、对象存储和数字模式通过适配模块接入，使新增设备、服务或客户端时可以复用现有业务能力。

3.6 支持第三方实现

官方移动端、PC端和Halo插件是项目的主要实现，但不构成封闭边界。

其他开发者可以基于公开的领域模型、同步规范和API开发：

其他操作系统客户端；
卫星通信工具；
POTA、SOTA等活动工具；
比赛辅助工具；
电台控制工具；
QSL卡片应用；
数据分析和展示工具。

4. 系统总体结构

总体上，系统可以分为四个层次：

终端层：移动端、PC端和第三方客户端；
公共业务层：统一领域模型、同步、ADIF、API和设备抽象；
Halo联网节点层：共享数据、多人权限、Web管理和公开展示；
外部集成层：LoTW、电台、对象存储、日志软件及未来开放网络。

5. 逻辑分层

5.1 表现与交互层

表现与交互层面向不同终端的用户界面。

主要包括：

移动端界面；
PC端界面；
Halo后台管理界面；
Halo公开页面；
第三方客户端界面。

不同终端可以根据设备尺寸、输入方式和使用场景重新组织功能，但应使用统一的领域对象和业务语义。

5.2 应用服务层

应用服务层负责组织具体业务流程，例如：

新建和编辑QSO；
导入、导出ADIF；
QSL申请、收卡和发卡；
媒体与QSO关联；
本地与Halo同步；
电台状态填充日志；
LoTW签名和上传；
数字模式结果生成QSO候选。

应用服务层连接用户界面和领域核心，不直接依赖某一种数据库、操作系统或设备协议。

5.3 领域核心层

领域核心层定义系统中的主要业务对象及其关系，包括：

StationWorkspace
├── StationProfile
├── QSO
│   ├── Confirmation
│   ├── QSL
│   └── MediaAsset
├── Members
├── Identity
└── Statistics

领域核心由移动端、PC端、Halo插件及未来第三方客户端共同遵循。

5.4 数据与同步层

数据与同步层负责：

客户端本地数据库；
Halo共享数据；
本地工作数据；
远端缓存数据；
数据导入导出；
同步状态；
重复数据识别；
数据版本和迁移。

该层保证系统既能本地独立运行，也能在配置Halo后形成多端共享数据体系。

5.5 设备与信号处理层

该层主要运行于移动端和PC端，负责：

电台控制；
串口、USB、蓝牙和网络通信；
音频输入输出；
SSTV；
FT8、FT4及其他数字模式；
频谱和瀑布图；
外围设备接入。

其中，PC端通常承担更完整的设备控制和DSP能力，移动端根据平台能力提供轻量实现。

5.6 外部服务适配层

外部服务通过适配模块接入系统，主要包括：

LoTW；
QRZ及其他日志服务；
S3兼容对象存储；
Hamlib和rigctld；
N1MM、WSJT-X、JTDX等外部软件；
DX Cluster和Telnet；
未来Ham Event和P2P QSL网络。

适配模块负责将外部数据和协议转换为项目内部的统一业务对象。

6. 主要组成部分

6.1 移动端

移动端定位为随身业余无线电工具，主要适用于日常管理、户外架台、移动操作和固定台辅助场景。

主要职责

本地QSO记录和查询；
ADIF导入导出；
QSL状态管理；
卡片照片和其他媒体采集；
LoTW相关操作；
Halo数据同步；
轻量电台控制；
电台状态查看；
SSTV及轻量数字模式；
户外活动相关辅助能力。

数据特征

移动端始终保留本地数据库。

配置Halo后，本地数据库同时包含：

本地创建、尚未上传的数据；
从Halo同步到本地的共享数据副本。

平台范围

移动端不限定单一操作系统。不同平台通过公共业务模块和平台适配层实现统一功能。

6.2 PC端

PC端定位为固定电台综合操作终端，是设备控制、音频处理和复杂业务的主要承载平台。

主要职责

高级QSO日志；
QSL和媒体管理；
电台CAT、PTT和状态控制；
Hamlib、rigctld及厂商协议接入；
音频设备管理；
SSTV、FT8、FT4及其他数字模式；
频谱和瀑布图；
外部日志软件联动；
固定台自动化；
比赛和卫星通信扩展；
Halo同步；
为其他终端提供Radio Host能力。

Radio Host

PC端可以连接实际电台和音频设备，并将电台状态或控制能力提供给同一设备上的其他模块，未来也可以向局域网内其他终端提供受控访问。

6.3 Halo插件

Halo插件定位为用户自行部署的业余无线电Web Station Hub。

主要职责

共享QSO、QSL和媒体元数据；
Station Workspace管理；
多用户和成员权限；
Web日志管理；
ADIF导入导出；
QSL查询和申请；
卡片展示；
数据统计；
公开电台页面；
客户端同步接口；
第三方公共API；
对象存储和外部服务配置。

独立运行能力

Halo插件可以不依赖移动端和PC端独立使用。

用户可以直接通过浏览器：

手工录入QSO；
导入ADIF；
管理QSL；
上传卡片图片；
管理成员；
设置公开页面。

联网节点属性

当移动端或PC端连接Halo后，Halo负责管理已经进入共享数据域的记录，并为不同客户端提供统一的远端状态。

6.4 公共规范和基础能力

三个终端之间通过公共规范保持一致。

公共规范包括：

公共能力	主要作用
统一领域模型	保证QSO、QSL、Workspace等对象语义一致
ADIF映射	保证日志导入导出及外部兼容
同步规范	规定客户端与Halo之间的数据流转
API规范	规定客户端、Halo及第三方程序之间的接口
Radio HAL	统一不同电台和控制协议
媒体规范	统一卡片、SSTV及附件的引用方式
身份规范	为呼号、用户和未来签名能力提供基础
版本规范	保证不同客户端和Halo版本之间可以演进

7. 核心业务对象

7.1 Station Workspace

Station Workspace是系统中的主要业务数据归属单位。

一个Workspace可以表示：

个人呼号；
俱乐部电台；
比赛台；
特设台；
临时活动台；
DXpedition；
其他共同使用的电台身份。

QSO、QSL、媒体及统计信息归属于Workspace，而不是直接归属于某个软件账户。

通过这种方式，同一名用户可以管理多个电台身份，多名用户也可以共同管理同一个电台身份。

7.2 QSO

QSO是系统的核心业务记录。

QSO包括基础通联信息，并可通过不同场景区段扩展卫星、比赛、活动、数字模式等数据。

QSO可以关联：

实体QSL；
LoTW及其他确认；
卡片照片；
SSTV图片；
活动媒体；
数据来源；
操作员；
电台和天线配置。

具体字段由 qso-model.md 定义。

7.3 QSL

QSL作为独立业务对象，用于描述一次或多次QSO的确认、卡片交换及相关流程。

QSL可以表示：

实体卡片；
LoTW确认；
QRZ等电子确认；
QSL申请；
收卡和发卡；
卡片局或直邮；
未来数字QSL和P2P QSL。

QSL与QSO之间允许根据实际业务形成一对一或一对多关联。

7.4 MediaAsset

MediaAsset用于统一管理非结构化媒体内容，包括：

QSL卡片正反面照片；
扫描件；
SSTV图片；
活动照片；
通联附件；
未来其他媒体类型。

媒体文件可以保存在本地、Halo附件系统或S3兼容对象存储中，业务数据保存统一的媒体引用。

7.5 Confirmation

Confirmation用于统一表示不同来源的通联确认。

其来源可以包括：

LoTW；
QRZ；
实体QSL；
其他电子日志服务；
未来P2P QSL。

统一确认模型使不同确认渠道可以共同展示和统计，同时保留各自的原始状态和来源信息。

7.6 Identity

Identity用于描述系统中的业余无线电身份及其凭据。

早期主要用于：

用户与呼号关系；
Station Workspace成员关系；
操作员标识；
外部服务账号关联。

未来可以扩展：

呼号公钥；
LoTW证书凭据；
签名事件；
数字QSL身份；
社区认证。

8. 本地数据与Halo共享数据

客户端本地数据库从同步关系上分为两个逻辑区域。

8.1 本地工作数据

本地工作数据由客户端创建和管理，尚未进入Halo共享数据域。

其主要特点为：

可以在脱机状态创建；
可以在脱机状态修改；
可以在脱机状态删除；
可以长期只保存在本地；
联机后可由用户或同步任务上传至Halo。

8.2 远端缓存数据

远端缓存数据是Halo共享数据在客户端本地的副本。

其主要特点为：

联机状态下由Halo同步；
脱机状态下可以本地查看；
脱机状态下保持只读；
联机并刷新远端状态后可以编辑；
远端变更在下次同步时更新到本地。

8.3 联机和脱机模式

移动端和PC端均可提供：

脱机模式；
联机模式。

这里的模式表示客户端是否启用Halo共享数据能力，不等同于设备是否具有物理网络连接。

脱机模式

本地工作数据可读写；
远端缓存数据可查看；
不进行Halo数据同步；
不修改已共享到Halo的记录。

联机模式

连接并认证Halo；
拉取Workspace中的共享数据；
更新本地远端缓存；
保留本地工作数据；
上传用户选择同步的本地数据；
允许对共享数据进行在线修改。

9. 同步总体流程

客户端由脱机模式切换至联机模式时，采用以下总体流程：

同步过程遵循以下总体语义：

Halo共享数据用于更新本地远端缓存，本地工作数据在拉取过程中保持不变。

上传成功的本地工作数据进入Halo共享数据域，并在客户端中转换为远端同步数据。

具体同步状态、重复数据判断、失败重试和后期增量同步机制，由同步专项文档定义。

10. 典型部署模式

10.1 纯本地模式

移动端或PC端
└── 本地数据库

适用于：

不准备部署服务器的个人用户；
完全离线使用；
户外和临时操作；
仅通过ADIF交换数据。

主要能力包括本地日志、QSL管理、媒体管理、电台控制和数字模式。

10.2 单客户端与Halo模式

移动端或PC端
        │
        ▼
      Halo

适用于：

个人电台；
需要Web查询和公开页面；
需要远端备份和管理；
需要通过浏览器补录数据。

10.3 多客户端与Halo模式

移动端A ───┐
移动端B ───┼── Halo Workspace
PC端A ─────┤
PC端B ─────┘

适用于：

同一用户的多设备；
固定台与随身设备组合；
多名操作员共同管理电台；
俱乐部台和比赛台。

Halo负责共享数据和权限管理，各客户端保留自己的本地数据和远端缓存。

10.4 Halo独立模式

浏览器
  │
  ▼
Halo插件

适用于：

不安装移动端或PC端的用户；
只需要Web日志和QSL管理；
现有Android、iOS或其他平台用户；
俱乐部公共数据管理。

10.5 Halo与对象存储模式

客户端 ──────── Halo
   │              │
   └────── S3兼容对象存储

结构化业务数据保存在本地数据库和Halo中，大型媒体文件保存到用户配置的对象存储。

该模式适用于：

大量QSL卡片扫描件；
SSTV图片；
活动照片；
多客户端共同访问媒体。

11. 典型业务数据流

11.1 脱机记录QSO

用户录入QSO
    ↓
保存到客户端本地数据库
    ↓
标记为本地工作数据
    ↓
继续脱机编辑和管理

该流程不依赖Halo和互联网。

11.2 联机上传本地QSO

客户端连接Halo
    ↓
拉取Halo共享数据
    ↓
更新远端缓存
    ↓
检查本地QSO是否与Halo记录重复
    ↓
上传本地QSO
    ↓
Halo保存至Workspace
    ↓
客户端更新同步状态

11.3 Halo网页录入QSO

用户通过浏览器录入
    ↓
Halo保存至Workspace
    ↓
客户端下次联机拉取
    ↓
进入客户端远端缓存

因此，Halo可以独立作为日志录入端，也可以与客户端共同使用。

11.4 电台状态填充日志

电台
 ↓
Hamlib、rigctld或厂商协议
 ↓
Radio HAL
 ↓
客户端日志模块
 ↓
自动填充频率、模式等信息

电台控制主要运行于客户端，不依赖Halo。

Halo可以保存最终日志和设备资料，但不承担实际电台实时控制。

11.5 QSL卡片媒体处理

拍照或扫描QSL卡片
    ↓
客户端或Halo创建MediaAsset
    ↓
保存至本地、Halo附件或S3对象存储
    ↓
关联QSL记录
    ↓
关联对应QSO
    ↓
根据权限公开展示

11.6 数字模式生成日志

音频输入
  ↓
SSTV或FT8等解码模块
  ↓
生成解码结果或QSO候选
  ↓
用户确认
  ↓
进入QSO Core
  ↓
本地保存并按需同步

数字模式模块不建立独立于QSO Core之外的日志体系。

12. 电台控制体系

电台控制能力通过统一的Radio HAL向上层提供。

Radio HAL用于统一表示：

频率；
模式；
VFO；
PTT；
功率；
信号；
SWR；
滤波器；
设备能力；
状态订阅。

Hamlib是重要的兼容实现之一，但上层业务只依赖Radio HAL。

13. 音频与数字模式体系

数字模式模块由音频核心、DSP核心和具体模式模块组成。

音频设备
   ↓
Audio Core
   ↓
DSP Core
   ├── SSTV
   ├── FT8 / FT4
   ├── 音频频谱
   └── 其他模式
          ↓
       QSO Core

PC端承担完整音频设备管理、频谱和复杂DSP能力。

移动端可以根据平台性能和接口条件提供：

SSTV接收；
FT8接收；
音频频谱；
轻量数字模式；
外部音频设备接入。

14. 外部服务集成

14.1 LoTW

LoTW适配模块用于：

呼号证书管理；
Station Location管理；
QSO签名；
日志上传；
上传结果处理；
确认状态同步。

LoTW是外部确认服务，不参与项目自身的本地存储和Halo同步基础。

14.2 ADIF

ADIF是系统与现有业余无线电日志生态交换数据的主要标准格式。

移动端、PC端和Halo均应支持基本ADIF导入导出，并遵循统一的字段映射规范。

14.3 外部日志软件

PC端重点承担与现有软件互操作的职责，包括：

N1MM Logger+；
Not1MM；
TR4W；
WSJT-X；
JTDX；
其他支持ADIF、UDP、TCP或Telnet的软件。

外部软件产生的数据经过适配后进入QSO Core。

14.4 对象存储

媒体存储通过统一对象存储适配层连接：

AWS S3；
Cloudflare R2；
MinIO；
其他S3兼容服务；
用户自建对象存储。

业务对象保存媒体引用、哈希及元数据，存储服务负责保存实际文件。

14.5 未来开放网络

未来的个人公告、DX Spot、QRV状态和去中心化QSL计划建立在统一的身份与签名事件体系上。

该能力作为独立网络模块接入，不改变基础QSO、QSL、本地存储和Halo同步架构。

15. 多用户和权限

多用户能力主要由Halo提供。

用户通过成员关系加入Station Workspace，并根据角色访问相应数据。

总体角色包括：

角色	总体职责
Owner	Workspace所有者、成员和总体配置管理
Manager	业务管理和主要数据维护
Editor	QSO、QSL及媒体编辑
Viewer	只读访问

具体权限由 halo-permissions.md 和 authorization.md 定义。

客户端连接Halo后，同时受到以下因素约束：

Halo身份认证；
Workspace成员关系；
业务角色；
数据可见性；
当前联机或脱机状态。

16. 公开展示和隐私

系统内部完整数据与公开数据相互分离。

Halo公开页面和公共API通过公共数据投影生成可展示内容。

内部完整数据
     ↓
可见性与公开字段规则
     ↓
公共数据投影
     ├── 公开日志查询
     ├── QSL申请页面
     ├── 卡片展示
     └── 统计页面

公开数据可以包括：

呼号；
通联日期；
Band；
Mode；
网格；
QSL状态；
公开媒体。

内部数据可以继续保存：

私人备注；
联系方式；
邮寄信息；
操作员内部信息；
对象存储内部地址；
其他不公开字段。

用户或Workspace管理员决定数据的公开范围。

17. 扩展体系

项目通过以下方式支持长期扩展：

17.1 客户端平台适配

同一业务模块可以通过平台适配层连接不同操作系统的：

本地数据库；
USB；
串口；
音频；
文件系统；
后台任务；
安全凭据存储。

17.2 外部服务适配

第三方服务通过Adapter接入统一业务接口，例如：

LoTW Adapter
QRZ Adapter
S3 Adapter
Hamlib Adapter
DX Cluster Adapter
External Logger Adapter

17.3 业务模块扩展

未来可以在现有领域核心上增加：

卫星通信；
POTA和SOTA；
Contest；
Award；
天线和云台控制；
SDR；
活动和团队协作；
其他数字模式。

17.4 第三方客户端

第三方客户端通过公开领域模型、API和同步规范接入Halo或处理本地数据，不要求使用官方客户端的界面和技术栈。

18. 架构质量要求

质量属性	总体要求
可用性	无网络和无Halo环境下仍可完成主要本地业务
数据可控性	用户可以导入、导出、备份和迁移自己的数据
一致性	三端使用统一领域模型和同步语义
兼容性	保持与ADIF、Hamlib、LoTW及现有日志软件的互操作
可扩展性	设备、服务和数字模式通过适配模块增加
可维护性	领域、同步、客户端、Halo和外部集成保持清晰边界
隐私性	内部数据与公开数据分别管理
可移植性	移动端和PC端不绑定单一操作系统
可部署性	Halo支持用户自托管，客户端支持独立运行
可验证性	核心模块具有明确接口，并可进行独立测试

19. 系统演进方向

第一阶段：统一数据基础

建立：

核心领域模型；
QSO和QSL模型；
Station Workspace；
ADIF映射；
基础同步语义；
三端基础架构。

第二阶段：基础应用和Halo重构

形成：

移动端基础日志；
PC端基础日志；
Halo插件3.0；
基础Web管理；
基础同步。

第三阶段：设备和外部服务

完善：

Radio HAL；
Hamlib和rigctld；
LoTW；
对象存储；
外部日志软件兼容。

第四阶段：数字模式和媒体

完善：

SSTV；
FT8、FT4；
音频频谱；
QSL卡片媒体工作流。

第五阶段：多人和开放生态

完善：

多用户Workspace；
俱乐部和比赛台；
第三方客户端；
开放API；
插件与扩展模块。

第六阶段：身份和开放网络

逐步建立：

Ham Identity；
签名事件；
Ham Event；
去中心化QSL；
P2P通信。

20. 核心架构约束

后续技术设计和实现应遵循以下总体约束：

移动端和PC端以本地数据为基础；
Halo作为可选的自托管联网节点；
移动端、PC端和Halo共享统一领域模型；
QSO、QSL和媒体归属于Station Workspace；
本地工作数据与Halo远端缓存数据保持明确区分；
脱机状态下，Halo远端缓存数据保持只读；
切换联机状态时，先更新远端缓存，再上传本地工作数据；
Halo数据更新远端缓存时，不覆盖本地工作数据；
Halo可以独立完成日志、QSL和媒体管理；
移动端、PC端和Halo允许功能不对称；
电台控制通过Radio HAL与上层业务隔离；
外部服务和设备协议通过Adapter接入；
数字模式结果统一进入QSO Core；
媒体文件与结构化业务数据分离管理；
内部完整数据与公共展示数据分别建模；
核心数据支持开放导入、导出和迁移；
官方客户端与第三方客户端遵循相同开放规范；
具体技术实现可以演进，但不得破坏已公开的核心业务语义和数据可移植性。

21. 与其他技术文档的关系

本文档定义系统总体结构，后续专项文档在此基础上展开。

文档	与本文档的关系
`module-boundaries.md`	细化各模块职责、依赖和调用边界
`domain-model.md`	详细定义核心业务对象及关系
`qso-model.md`	详细定义QSO结构
`qsl-model.md`	详细定义QSL结构
`station-workspace-model.md`	详细定义Workspace、多用户和数据归属
`adif-mapping.md`	详细定义内部字段与ADIF之间的映射
`sync-overview.md`	详细定义客户端与Halo的同步模型
`radio-hal.md`	详细定义统一电台控制接口
`halo-plugin-architecture.md`	细化Halo插件内部架构
`mobile-client-architecture.md`	细化移动端架构
`desktop-client-architecture.md`	细化PC端架构
`api-overview.md`	定义系统API的公共规范

22. 总体架构定义

业余无线电QSL管理系统 3.0.0 的总体架构可以概括为：

以统一领域模型为基础，以移动端和PC端作为本地优先的操作终端，以Halo插件作为可选的自托管共享节点，通过开放API、ADIF、Radio HAL和适配模块连接现有业余无线电设备及服务，并为未来第三方客户端、数字模式、身份体系和开放网络提供扩展基础。

在这一架构下：

本地客户端解决个人使用和实际电台操作问题；
Halo解决联网管理、多人协作和Web展示问题；
开放规范解决跨平台、跨客户端和长期演进问题；
外部适配层解决与现有业余无线电生态的兼容问题。

三个部分可以分别独立运行，也可以组合形成完整的个人或团队业余无线电软件环境。

本文由王绍铭原创，采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。