版本：Draft v0.3

状态：架构方向定义阶段

1. 文档定位

本文档是 QSL Management 重构项目的总纲文档（Architecture
Overview，架构总览）。

本文档用于定义：

• 项目定位；
• 核心设计思想；
• 总体架构路线；
• 子文档组织入口。

本文档不包含：

• 具体字段定义；
• 数据库结构；
• 权限细节；
• Halo Extension实现细节；
• 数据迁移步骤。

具体设计请参考对应子文档。

2. 项目定位

QSL Management 不再定位为单纯的 QSL 卡片管理工具。

项目目标：

建立面向业余无线电活动的通信档案管理系统。

系统围绕以下核心对象建立：

• Callsign（呼号身份）
• Activity（无线电活动）
• QSO（通联事件）
• QSL（卡片交换）
• Equipment（设备资源）

3. 核心设计思想

3.1 身份与事件分离原则

无线电世界中的客观实体独立存在，用户通过权限关系参与维护。

核心关系：

原则：

• Callsign 是无线电身份；
• QSO 是通信事件；
• QSL 是通信事件后的业务记录；
• User 是系统参与者，通过权限管理业务对象。

详细设计：

• domain-model.md

3.2 呼号公共身份档案原则

Callsign 可以独立存在。

即使没有任何用户认领，系统仍可以保存该呼号的基础档案。

数据来源包括：

• QSO记录；
• ADIF导入；
• 公开数据源；
• 用户贡献。

用户参与方式分为：

• Contribution（数据贡献）
• Claim（管理认领）
• Permission Grant（权限授权）

详细设计：

• domain-model.md
• permission-model.md
• data-model-reference.md

3.3 长期权限与活动权限并存原则

用户对呼号的管理关系可能具有不同生命周期。

系统支持：

• DIRECT（长期权限）
• ACTIVITY（活动权限）

因此同时支持：

• 个人呼号长期使用；
• 集体台多人管理；
• 特设台临时管理；
• 比赛团队协作。

详细设计：

• permission-model.md

4. 领域划分

Identity（身份领域）

负责：

• User（用户）
• Callsign（呼号）
• Permission Grant（权限授权）

Activity（活动领域）

负责：

• 比赛；
• 特设台；
• POTA；
• 卫星活动；
• 野外架台。

Activity 描述：

某个呼号在特定时间和目的下的使用过程。

Logbook（通联日志领域）

负责：

• QSO记录；
• 通联查询；
• 数据统计。

QSL（卡片领域）

负责：

• 卡片交换；
• 地址匹配；
• 卡片状态管理。

Resource（资源领域）

负责：

• 设备库；
• 卡片模板；
• 辅助资源。

5. 文档结构入口

docs/

├── qsl-management-rebuild-direction.md
│   总纲：项目思想与架构路线
│
├── domain-model.md
│   领域模型：核心对象与关系
│
├── permission-model.md
│   权限模型：用户、呼号、活动权限
│
├── data-model-reference.md
│   数据字段定义
│
├── qso-adif-mapping.md
│   ADIF字段映射
│
├── database-design.md
│   数据库设计
│
├── halo-extension-design.md
│   Halo 2插件实现
│
└── migration-plan.md
    数据迁移方案

6. Halo 2实现方向

总体原则：

业务对象使用 Extension（扩展资源）表达。

适合作为 Extension：

• Callsign Profile
• Activity
• QSO Record
• QSL Record
• Equipment
• Card Template

不作为核心 Extension：

• Grid；
• Band；
• Mode；
• DXCC等基础枚举数据。

详细实现：

参考：

• halo-extension-design.md

7. 后续设计顺序

1. domain-model.md
2. permission-model.md
3. data-model-reference.md
4. qso-adif-mapping.md
5. database-design.md
6. halo-extension-design.md
7. migration-plan.md