一、文档说明

本目录用于统一管理 业余无线电QSL管理系统 3.0.0 的项目文档。

文档面向项目用户、开发者、测试人员及其他协作者，覆盖系统总体架构、数据模型、客户端、Halo插件、同步机制、电台控制、数字模式、第三方服务、开放网络、安全、测试及开发维护等内容。

项目文档按照“总体说明—领域模型—具体实现—专项能力”的方式组织。不同文档分别描述对应领域的问题，避免将业务定义、系统架构和具体实现细节集中在同一文档中。

二、文档目录结构

docs/
├── architecture/          # 总体架构：系统分层、模块边界、部署模式及整体技术关系
├── data/                  # 数据设计：领域模型、QSO/QSL、Workspace、数据版本与迁移
├── sync/                  # 数据同步：客户端与Halo同步、状态管理、全量/增量同步及异常处理
├── client/                # 客户端设计：移动端、PC端及客户端公共能力
│   ├── common/            # 客户端公共能力：公共业务逻辑、本地存储及跨端接口
│   ├── mobile/            # 移动端：手机、平板等移动设备客户端设计
│   └── desktop/           # PC端：Windows、Linux、macOS等桌面客户端设计
├── halo/                  # Halo插件：插件架构、数据模型、Workspace、权限、后台及公开页面
├── api/                   # 接口规范：同步、QSO、QSL、媒体及公共开放接口
├── radio/                 # 电台控制：Radio HAL、Hamlib、rigctld、通信传输及设备兼容
├── digital/               # 数字模式：音频、DSP、SSTV、FT8/FT4、频谱及瀑布图
├── integrations/          # 外部集成：LoTW、TrustedQSL、QRZ、外部日志软件及DX Cluster
├── media/                 # 媒体管理：QSL卡片、SSTV图片、对象存储、缓存及完整性
├── network/               # 网络协议：呼号身份、签名事件、Ham Event、P2P及QSL交换
├── security/              # 安全与权限：认证、授权、凭据、密钥、隐私及公开数据控制
├── testing/               # 测试与兼容：测试策略、同步测试、电台测试、ADIF及兼容性矩阵
└── development/           # 开发维护：开发指南、编码规范、依赖、发布、迁移及协作

三、总体架构文档

目录：

docs/architecture/

用于描述整个系统的总体技术关系、组成部分及模块职责。

文档名中文名内容介绍
architecture-overview.md系统总体技术架构描述移动端、PC端、Halo插件及外部服务之间的总体关系、系统分层、主要数据流和核心模块。
module-boundaries.md模块职责与边界定义QSO、QSL、Radio、Sync、Media、Identity等模块分别负责的业务范围，以及模块之间的依赖和调用关系。
deployment-model.md系统部署与运行模式描述纯本地、移动端+Halo、PC端+Halo、多客户端+Halo以及Halo独立运行等部署方式。
technology-stack.md技术栈与基础依赖汇总移动端、PC端、Halo插件、本地数据库、Native组件、网络及第三方基础库的技术组成。

四、领域模型与数据文档

目录：

docs/data/

用于定义项目中所有客户端和服务共同使用的业务数据语义。

文档名中文名内容介绍
domain-model.md核心领域模型定义StationWorkspace、QSO、QSL、MediaAsset、Confirmation、Identity等核心业务对象及对象之间的关系。
qso-model.mdQSO数据模型定义QSO核心字段、场景扩展区段、来源信息、确认信息、媒体关联及同步相关数据。
qsl-model.mdQSL数据模型定义实体QSL、电子QSL、卡片申请、收发状态、交换方式以及QSL与QSO之间的关联关系。
station-workspace-model.md电台工作空间模型定义个人台、俱乐部台、比赛台、特设台等Station Workspace的结构、成员及业务数据归属方式。
media-model.md媒体数据模型定义QSL卡片照片、SSTV图片、活动图片及其他附件的业务数据结构和关联方式。
confirmation-model.md通联确认模型统一描述LoTW、QRZ、实体QSL、未来数字QSL及P2P QSL等不同通联确认来源。
identity-model.md呼号与身份模型定义呼号、用户身份、公钥、数字签名及外部身份凭据等相关数据结构。
data-versioning.md数据版本与迁移规范定义数据Schema版本、字段新增与废弃、兼容策略以及不同版本之间的数据迁移方式。
adif-mapping.mdADIF字段映射规范定义系统内部字段与ADIF标准字段之间的映射、转换及兼容规则。
adif-import.mdADIF导入规范定义ADIF文件解析、字段校验、重复记录识别、异常数据处理及导入结果。
adif-export.mdADIF导出规范定义标准ADIF文件生成、字段输出、字符编码及不同业务场景下的导出规则。
data-import-export.md通用数据导入导出规范定义JSON、备份文件及其他开放数据格式的导入、导出和恢复方式。

五、同步文档

目录：

docs/sync/

用于描述移动端、PC端与Halo之间的数据同步机制。

文档名中文名内容介绍
sync-overview.md数据同步总体设计描述本地数据、远端数据、同步关系及客户端和Halo之间的总体同步模型。
sync-state-machine.md同步状态机定义LOCAL_ONLY、REMOTE_SYNCED及同步过程中的其他状态及状态转换关系。
full-sync.md全量同步规范定义客户端由脱机切换至联机时，如何拉取Halo数据、更新远端缓存并保留本地数据。
incremental-sync.md增量同步规范定义revision、cursor、变化记录等增量同步机制及后续大规模数据同步方式。
duplicate-detection.md重复记录识别规范定义本地QSO上传前对呼号、日期、时间、频段、模式等字段进行重复记录判断的规则。
sync-error-handling.md同步异常与恢复机制定义断网、认证失败、上传失败、远端异常、重复数据及数据不一致情况下的处理流程。

六、客户端公共文档

目录：

docs/client/common/

用于描述移动端与PC端共同遵循的客户端基础能力。

文档名中文名内容介绍
client-common-architecture.md客户端公共架构描述移动端和PC端共同使用的QSO、QSL、同步、媒体、配置等基础模块。
local-storage.md客户端本地存储设计定义本地数据库、配置文件、缓存、媒体、证书及其他本地数据的存储关系。
client-sync.md客户端同步实现描述客户端如何调用同步模块、管理LOCAL_ONLY和REMOTE_SYNCED数据及切换联机状态。
client-settings.md客户端配置模型定义电台、Halo、LoTW、媒体存储、网络服务及用户偏好等客户端配置。
client-plugin-model.md客户端扩展模型描述客户端后续增加第三方设备、协议、数字模式及业务扩展模块的统一方式。

七、移动端文档

目录：

docs/client/mobile/

用于描述手机、平板等移动设备客户端。

文档名中文名内容介绍
mobile-client-architecture.md移动端技术架构描述移动端日志、QSL、同步、设备控制、音频及平台适配等模块关系。
mobile-feature-scope.md移动端功能范围描述移动端承担的日志、QSL、LoTW、媒体、轻量电台控制及数字模式能力。
mobile-storage.md移动端本地存储设计描述移动端数据库、媒体文件、缓存、配置、证书及敏感信息的本地保存方式。
mobile-platform-adapters.md移动平台适配规范描述Android、HarmonyOS、iOS等平台在USB、音频、文件、后台任务及权限方面的适配层。
mobile-radio-control.md移动端电台控制设计描述移动端通过USB、蓝牙、TCP等方式连接和控制电台的整体关系。

八、PC端文档

目录：

docs/client/desktop/

用于描述Windows、Linux、macOS等桌面系统上的固定台客户端。

文档名中文名内容介绍
desktop-client-architecture.mdPC端技术架构描述PC端日志、电台控制、数字模式、音频、同步及外部软件集成的总体关系。
desktop-feature-scope.mdPC端功能范围描述固定台、电台控制、数字模式、频谱、比赛辅助及高级日志等功能。
desktop-platform-adapters.mdPC平台适配规范描述Windows、Linux、macOS在串口、USB、音频、网络和设备发现方面的平台差异。
local-service.md本地服务与进程架构定义UI、本地后台服务、Radio Core、DSP及外部软件之间的进程和通信关系。
desktop-radio-host.mdPC端Radio Host设计描述PC作为固定台主要设备控制节点时，对其他本地或网络终端提供电台能力的方式。

九、Halo插件文档

目录：

docs/halo/

用于描述Halo插件作为Web管理、数据节点和多人协作平台的具体设计。

文档名中文名内容介绍
halo-plugin-architecture.mdHalo插件总体架构描述插件的数据层、服务层、API、后台管理、公开页面及同步服务。
halo-data-model.mdHalo数据模型描述核心领域对象在Halo Custom Model中的实现、字段映射及索引设计。
halo-workspace.mdHalo工作空间设计定义Station Workspace、成员关系、多呼号及多用户业务模型。
halo-permissions.mdHalo权限模型定义Owner、Manager、Editor、Viewer等业务角色及其与Halo权限体系之间的关系。
halo-public-view.mdHalo公开展示设计定义公开QSO查询、QSL申请、卡片展示、统计页面及个人电台展示方式。
halo-admin-ui.mdHalo后台管理界面设计描述日志、QSL、媒体、Workspace、用户及配置等后台管理页面。
halo-sync-service.mdHalo同步服务设计描述Halo如何向移动端和PC端提供数据拉取、上传及远端状态管理能力。
halo-standalone-mode.mdHalo独立使用模式描述用户不使用客户端时，通过浏览器完成日志、QSL、媒体和Workspace管理的业务流程。

十、API文档

目录：

docs/api/

用于定义客户端、Halo及第三方程序之间的标准接口。

文档名中文名内容介绍
api-overview.mdAPI总体规范定义API命名、版本、认证、错误格式、分页、时间格式及基础交互规范。
sync-api.md同步API规范定义客户端与Halo之间的数据拉取、上传、全量同步和增量同步接口。
qso-api.mdQSO API规范定义QSO新增、查询、修改、删除、搜索及批量处理接口。
qsl-api.mdQSL API规范定义QSL申请、收发、查询、确认及状态更新接口。
media-api.md媒体API规范定义媒体元数据、上传、下载、关联、删除及对象存储接口。
workspace-api.mdWorkspace API规范定义Station Workspace、成员、权限和Workspace相关业务接口。
public-api.md公共查询API规范定义面向第三方应用及网站访客开放的只读查询接口。

十一、电台控制文档

目录：

docs/radio/

用于描述项目统一的电台控制体系。

文档名中文名内容介绍
radio-hal.mdRadio HAL统一电台接口定义频率、模式、VFO、PTT、信号、电台状态及扩展能力的统一接口。
hamlib-adapter.mdHamlib适配设计描述Hamlib与Radio HAL之间的封装、移植和兼容关系。
rigctld-integration.mdrigctld接入规范定义客户端通过TCP连接现有rigctld服务进行远程电台控制的方法。
radio-transport.md电台通信传输层定义Serial、USB、TCP、Bluetooth及其他通信传输方式的统一抽象。
radio-device-compatibility.md电台设备兼容规范记录已支持电台型号、功能支持范围、已知限制及测试结果。
radio-state-sync.md电台实时状态同步描述频率、模式、PTT和信号状态在客户端内部及不同终端之间的实时同步。
radio-discovery.md电台设备发现机制描述串口、电台LAN服务、USB及网络设备的自动发现和识别。

十二、数字模式与音频文档

目录：

docs/digital/

用于描述音频处理、DSP以及数字模式相关能力。

文档名中文名内容介绍
audio-core.md音频核心设计定义音频输入输出、采样率、设备选择、音频流、缓冲及路由关系。
dsp-core.mdDSP核心架构定义数字信号处理模块的统一接口、数据流及扩展方式。
sstv-decoder.mdSSTV解码模块描述SSTV模式识别、音频解码、图片生成及日志关联。
ft8-decoder.mdFT8/FT4解码模块描述FT8/FT4接收、解码、消息解析、通联识别及QSO候选生成。
spectrum-waterfall.md频谱与瀑布图模块描述音频频谱、SDR频谱及瀑布图相关的数据处理和显示接口。
digital-mode-integration.md数字模式日志联动定义内部数字模式和外部数字模式软件产生的通联信息如何进入QSO Core。

十三、第三方服务与外部软件文档

目录：

docs/integrations/

用于描述项目与现有业余无线电生态及互联网服务之间的集成。

文档名中文名内容介绍
lotw-integration.mdLoTW集成总体设计描述LoTW证书、QSO签名、上传、查询和确认状态同步。
trustedqsl-adapter.mdTrustedQSL适配设计描述TrustedQSL/tqsllib的封装、跨平台移植及内部接口。
qrz-integration.mdQRZ.com集成设计描述QRZ日志、呼号查询及其他可用服务的接入方式。
external-loggers.md外部日志软件兼容描述N1MM、Not1MM、TR4W、WSJT-X、JTDX等软件的数据与协议兼容方式。
dx-cluster-integration.mdDX Cluster集成设计描述传统DX Cluster、Telnet Spot及相关数据解析和接入。
external-service-adapters.md外部服务适配规范定义第三方日志、地图、奖项、呼号数据库及其他服务的统一Adapter结构。

十四、媒体与对象存储文档

目录：

docs/media/

用于描述QSL卡片、SSTV图片及其他媒体数据的管理。

文档名中文名内容介绍
media-storage.md媒体存储总体设计描述本地存储、Halo存储和外部对象存储之间的关系。
s3-adapter.mdS3兼容对象存储适配定义AWS S3、Cloudflare R2、MinIO及其他S3 Compatible服务的统一接口。
media-hash-integrity.md媒体哈希与完整性定义文件Hash、完整性检查、重复媒体判断及长期校验机制。
thumbnail-cache.md缩略图与媒体缓存定义缩略图生成、图片缓存及不同客户端的媒体加载方式。
qsl-card-media.mdQSL卡片媒体管理描述实体QSL正反面照片、扫描件及其与QSL记录、QSO记录之间的关联。

十五、安全、用户与权限文档

目录：

docs/security/

用于描述用户认证、权限、安全存储及隐私控制。

文档名中文名内容介绍
security-overview.md系统安全总体设计描述本地数据、网络通信、认证、密钥、证书和第三方凭据等总体安全模型。
authentication.md客户端认证机制定义移动端和PC端连接Halo时的Token、PAT及后续其他认证方式。
authorization.md业务授权设计定义Workspace成员、资源操作权限及业务授权逻辑。
credential-storage.md凭据与密钥存储定义LoTW证书、API Token、S3密钥、私钥等敏感信息的保存方式。
privacy-model.md隐私与公开数据模型定义Private、Members、Authenticated、Public等数据可见性。
public-data-projection.md公共数据投影规范定义内部完整数据转换为公开页面和公共API数据时的字段筛选规则。

十六、身份与开放网络文档

目录：

docs/network/

用于描述项目后期的呼号身份、签名事件、公告网络和去中心化QSL交换能力。

文档名中文名内容介绍
ham-identity.md业余无线电身份体系定义呼号、公钥、LoTW凭据及其他身份认证来源之间的关系。
signed-event.md签名事件规范定义公告、DX Spot、QSL等可签名事件的统一数据结构。
ham-event-protocol.mdHam Event网络协议定义DX Spot、QRV状态、Activation、个人公告等事件的表示与传播方式。
p2p-network.mdP2P网络总体设计描述节点发现、连接、中继、消息传播和离线交换等基础能力。
p2p-qsl.md去中心化QSL协议定义QSO声明、QSL确认、双方签名及去中心化交换流程。
telnet-gateway.mdTelnet兼容网关描述开放事件网络与传统DX Cluster及N1MM Telnet生态之间的兼容方式。

十七、测试与兼容性文档

目录：

docs/testing/

用于记录项目测试方法及软硬件兼容状态。

文档名中文名内容介绍
testing-strategy.md项目测试策略定义单元测试、模块测试、集成测试、端到端测试和硬件测试的整体方法。
sync-test-cases.md同步测试用例覆盖脱机、联机、多设备、断网、重复QSO、Halo更新及同步恢复等场景。
radio-test-cases.md电台控制测试规范定义不同电台频率、模式、PTT、状态读取等控制功能的测试方式。
adif-test-cases.mdADIF兼容测试规范验证ADIF导入导出及与不同日志软件之间的数据兼容性。
lotw-test-cases.mdLoTW测试规范定义证书导入、签名、上传及确认状态相关测试。
compatibility-matrix.md兼容性矩阵统一记录操作系统、电台、USB设备、LoTW、对象存储及外部软件的兼容状态。

十八、开发与维护文档

目录：

docs/development/

用于帮助开发者参与项目，并记录项目的长期维护规范。

文档名中文名内容介绍
development-guide.md开发环境与参与指南描述代码仓库、开发环境、构建、调试、运行及开发工作流程。
coding-guidelines.md编码规范定义代码命名、模块组织、异常处理、日志、注释及代码风格。
dependency-management.md第三方依赖管理记录Hamlib、TrustedQSL、DSP库等第三方依赖的来源、版本、许可证及维护状态。
release-process.md版本发布流程定义版本号、Alpha、Beta、RC、正式版及Release Note等发布规则。
migration-guide.md数据与版本升级指南描述2.x到3.x以及后续版本之间的数据迁移、升级和兼容方式。
contributing.md项目协作指南面向开发者、测试人员和其他协作者说明Issue、PR、测试、文档及设备适配参与流程。
roadmap.md项目技术路线图记录各模块开发阶段、版本目标及当前进展。
license-and-third-party.md开源许可与第三方组件说明汇总项目自身许可证及Hamlib、TrustedQSL等第三方组件的许可要求。

十九、文档之间的关系

整个文档体系可以按以下层次理解：

项目章程
   │
   ▼
architecture/
系统总体架构
   │
   ├─────────────┐
   ▼             ▼
data/           sync/
领域模型         数据同步
   │             │
   ├──────┬──────┴─────────┐
   ▼      ▼                ▼
client/  halo/            api/
客户端    Web节点           接口
   │
   ├───────────────┐
   ▼               ▼
radio/           digital/
电台控制          数字模式
   │               │
   └───────┬───────┘
           ▼
     integrations/
       外部生态

media/      security/      network/
媒体         安全            开放网络

              │
              ▼
          testing/
              │
              ▼
        development/

其中：

  • architecture/ 描述系统整体；
  • data/ 定义业务对象；
  • sync/ 定义数据如何在不同节点之间流转；
  • client/ 描述移动端和PC端；
  • halo/ 描述Web数据节点和管理端；
  • api/ 定义不同组件之间的接口；
  • radio/ 和 digital/ 描述业余无线电设备和信号处理能力；
  • integrations/ 负责现有业余无线电生态兼容；
  • media/ 负责卡片和图片等非结构化数据；
  • security/ 负责身份、权限和隐私；
  • network/ 负责后续开放网络和去中心化协议；
  • testing/ 负责质量与兼容性；
  • development/ 负责项目开发和长期维护。

二十、文档命名规则

项目技术文档统一使用：

小写英文
+
短横线分隔
+
.md

例如：

architecture-overview.md
qso-model.md
radio-hal.md
lotw-integration.md
p2p-qsl.md

文档文件名用于代码仓库和内部引用，文档一级标题使用对应中文名称。

所有跨文档引用应尽量使用相对路径，保证Git仓库、离线文档和静态文档站点均可正常访问。

二十一、文档版本关系

项目整体版本为：

业余无线电QSL管理系统 3.0.0

技术文档可根据内容独立维护修订记录。

涉及以下内容发生重大变化时，应同步检查相关文档：

  • 核心领域模型；
  • ADIF字段映射；
  • 同步协议；
  • API；
  • Radio HAL；
  • Halo数据结构；
  • 权限模型；
  • 身份及开放网络协议。

技术实现文档与具体客户端版本可以独立迭代，但应保持与当前公开领域模型和接口规范的一致性。

二十二、文档索引目标

本索引用于形成统一的项目技术知识结构，使不同参与者能够根据自身工作快速定位相关文档。

对于普通用户，主要涉及：

architecture-overview.md
deployment-model.md
mobile-feature-scope.md
desktop-feature-scope.md
halo-public-view.md
compatibility-matrix.md

对于客户端开发者，主要涉及：

domain-model.md
qso-model.md
qsl-model.md
sync-overview.md
api-overview.md
client/
radio/
digital/

对于Halo插件开发者，主要涉及：

domain-model.md
station-workspace-model.md
sync-overview.md
halo/
api/
security/

对于设备和数字模式开发者，主要涉及：

radio/
digital/
integrations/
testing/

对于开放协议和社区网络开发者，主要涉及：

identity-model.md
network/
security/
api/

通过统一的文档体系，使移动端、PC端、Halo插件及未来第三方客户端能够基于相同的业务语义和开放规范持续发展。

许可协议

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

分享文章