业余无线电 QSL 卡片管理系统

业余无线电 QSL 卡片管理系统是一个面向 Halo 2 的插件项目，用于管理 QSO 记录、QSL 收发卡、线上 EYEBALL 换卡、线下 EYEBALL 换卡、收卡编号、公开查询、邮件通知、数据备份和本地打印桥接等流程。

当前插件标识名为 qsl-management，插件显示名称为“业余无线电 QSL卡片管理系统”。

主要能力

• 通联业务：维护 QSO/SWL 记录，创建卡片，制卡签发，发信确认，送达确认。
• 
• 线上换卡业务：公开提交换卡申请，后台审核，自动创建卡片，制卡、发卡、送达流转。
• 
• 线下换卡业务：创建活动，批量创建活动卡片，线下制卡，公开确认，送达确认。
• 
• 收卡业务：通联收卡、线上换卡收卡、线下换卡收卡，支持收卡编号、收卡日期、编号迁移和已收卡片清单。
• 配置管理：系统参数、通知策略、通信地址、本台设备、本台卡片、卡片局、地址和设备库。
• 
• 公开页面：公开查询、线上换卡申请、线下换卡确认、公开签收。
• 
• 邮件通知：按业务场景配置自动或手动通知，支持测试邮件。
• 
• 数据能力：审计日志、统计报表、备份导入导出。
• 
• 本地打印工具：通过 tools/CardPrint 对接插件接口，支持卡片、信封、打包确认和二维码路径映射。

插件安装

从 GitHub Release 下载最新的插件 JAR 文件：

plugin-qsl-management-*.jar

然后在 Halo 后台进入插件管理，上传并启用该 JAR。

Release 地址：

https://github.com/bi1kbu/qsl-management/releases

后台入口

插件启用后，后台菜单入口为：

/qsl

当前菜单包含：

• 总览
• 配置
• 通联业务
• 线上换卡业务
• 线下换卡业务
• 收卡业务
• 审计
• 数据

公开页面

插件提供以下公开页面与接口能力（建议通过带参数重定向或反向代理缩短链接使用）：

公开页面也支持通过 Halo 内容短码嵌入：

[qsl-card]
[qsl-online-exchange-card]
[qsl-offline-exchange-card]
[qsl-receipt-card]

本地打印工具

本地打印工具位于：

tools/CardPrint

常用启动命令：

cd tools/CardPrint
python -m cardprint.cli ui online

打印工具需要配置站点地址、认证方式和打印预设。若使用个人访问令牌，建议在 Halo 中为令牌勾选插件提供的“卡片打印工具”权限模板。

开发环境

插件开发环境：

• Java 21+
• Node.js 18+
• pnpm
• Halo 2.23+

构建插件：

.\gradlew.bat build

构建完成后，JAR 产物位于：

build/libs

本地启动 Halo 联调：

.\gradlew.bat haloServer

前端开发：

cd ui
pnpm install
pnpm dev

项目结构

src/            Halo 插件后端、扩展模型、权限模板
ui/             Halo 控制台前端
tools/CardPrint 本地卡片打印工具
docs/spec       项目信息结构化文档

关键文档：

• docs/spec/ProductDefinition.md：产品定义与业务流程
• docs/spec/BackendApiContract.md：后台、公开 API 合同
• docs/spec/项目信息结构化清单.md：结构化项目索引

版本说明

插件版本以以下两个文件为准：

src/main/resources/plugin.yaml
gradle.properties

正式打包前需同步递增两处版本号。

许可证

本项目使用 GPL-3.0 许可证。