业余无线电 QSL 卡片管理系统
业余无线电 QSL 卡片管理系统是一个面向 Halo 2 的插件项目，用于管理 QSO 记录、QSL 收发卡、线上 EYEBALL 换卡、线下 EYEBALL 换卡、收卡编号、公开查询、邮件通知、数据备份和本地打印桥接等流程。
当前插件标识名为 qsl-management，插件显示名称为“业余无线电 QSL卡片管理系统”。
主要能力
插件安装
在线安装
通过HALO应用市场一键安装
https://www.halo.run/store/apps/app-z7ouhnfn
离线安装
从 GitHub Release 下载最新的插件 JAR 文件，然后在 Halo 后台进入插件管理，上传并启用该 JAR。
Release 地址：
https://github.com/bi1kbu/qsl-management/releases
公开页面
插件提供以下公开页面与接口能力（建议通过带参数重定向或反向代理缩短链接使用）：
| 能力 | 默认路径 |
|---|---|
| 公开查询 | /apis/api.qsl-management.bi1kbu.com/v1alpha1/cards/page |
| 线上换卡申请 | /apis/api.qsl-management.bi1kbu.com/v1alpha1/ONLINE_EYEBALL |
| 线下换卡确认 | /apis/api.qsl-management.bi1kbu.com/v1alpha1/EYEBALL |
| 公开签收 | /apis/api.qsl-management.bi1kbu.com/v1alpha1/receipt-public |
公开页面也支持通过 Halo 内容短码嵌入：
[qsl-card]
[qsl-online-exchange-card]
[qsl-offline-exchange-card]
[qsl-receipt-card]
本地打印工具
本地打印工具用于连接打印机打印卡片、信封封面。推荐使用针式打印机，例如南天PR2E（本项目的测试环境已实测）
本地打印工具位于：
tools/CardPrint
常用启动命令：
cd tools/CardPrint
python -m cardprint.cli ui calibrator （标定）
python -m cardprint.cli ui online （在线打印）
打印工具需要配置站点地址、认证方式和打印预设。使用个人访问令牌时，需要在 Halo 中为令牌勾选插件提供的“卡片打印工具”权限模板。
项目结构
src/ Halo 插件后端、扩展模型、权限模板
ui/ Halo 控制台前端
tools/CardPrint 本地卡片打印工具
docs/spec 项目信息结构化文档
关键文档：
docs/spec/ProductDefinition.md：产品定义与业务流程docs/spec/BackendApiContract.md：后台、公开 API 合同docs/spec/项目信息结构化清单.md：结构化项目索引
版本说明
版本号分为三部分，以“.”作为分隔符
大版本.小版本.修复迭代版本
其中：
大版本 指的是存在破坏性更新，例如字段的移除、废弃、接口合同变更等，一般需要通过迁移程序将数据做一定的转化。
小版本 指的是存在关键功能更新，例如新增字段、新增功能、新增接口等，一般可以正常更新而无需额外处理。
修复迭代版本 指的是日常修复bug产生的版本，可以完全的无损更新。
插件版本以 src/main/resources/plugin.yaml 与 gradle.properties 为准，正式打包前需同步递增两处版本号。
许可证
本项目使用 GPL-3.0 许可证。