重要说明

本版本仍属于 QSL 2.x 数据模型版本，数据格式与 1.x 旧版本不兼容。升级前请先完整备份旧版本导出数据和 Halo 数据目录。

更新内容

• 新增旧版本一键迁移能力，可在新版本安装后将旧模型中的收卡关联、线下换卡关联聚合到新数据模型。
• 新增迁移预检与执行接口，并补充导入导出页面入口。
• 迁移过程会清理旧版误写入卡片记录的本台卡片占位数据，以及旧版自动收卡临时卡片。
• 补充迁移服务测试、接口鉴权测试、RBAC 权限与文档说明。

已验证

• 已在本地 Halo 2.23.2 Docker 环境中完成 1.1.3 导入旧数据、升级 2.0.6、执行迁移的流程验证。
• 已执行 ./gradlew.bat test 并通过。

---

Generated from v2.0.6

重要：破坏性更新

本版本为 QSL 2.0 数据模型重构版本，数据格式与 1.x 旧版本不兼容。升级前必须先备份旧版本导出数据；升级后需要使用转换脚本将旧导出包转换为 2.0 数据格式，再重新导入。不要直接把旧版本导出包导入到 2.0 环境。

升级前必须执行

1. 在旧版本中完整导出并保存备份包。
2. 建议另存一份原始备份，避免转换失败后无法回退。
3. 使用仓库中的 tools/convert_legacy_export_to_qsl2.py 将旧导出包转换为 2.0 数据包。
4. 在全新或已清理的数据环境中导入转换后的数据包。
5. 导入后核对总览、统计报表、收卡记录、线下换卡记录和线上签收状态。

主要变化

• 发卡记录、收卡事实、线下换卡活动卡拆分为独立模型，减少多业务场景共用同一字段导致的耦合。
• 新增 ReceiveRecord，收卡编号以收卡记录为准，不再通过重复创建卡片来表达收卡事实。
• 新增 OfflineExchangeCard，线下换卡卡片与地址管理解耦。
• 线上换卡“送达确认”调整为“签收确认”，用于记录对方是否签收我方发出的卡片。
• 统计报表口径重构：只统计正式 C{序号} 且呼号非空的卡片，并修正已发、待发、已收统计口径。
• 审计查询按业务场景分 tab 展示，卡片记录和收卡记录分别查询。
• 在线打印工具新增补打眼球卡片能力，并优化部分拉取队列状态提示。
• 导入导出格式新增 receive-record 和 offline-exchange-card 数据集。

验证

• ./gradlew.bat test 通过。
• python -m pytest tools/CardPrint/tests tools/test_convert_legacy_export_to_qsl2.py 通过，55 项测试通过。

兼容性说明

这是破坏性版本。旧版数据需要提前备份并转换后重新导入；旧版导出格式、旧版收卡字段聚合方式和旧版线下换卡记录组织方式不再作为 2.0 的直接导入格式。

---

Generated from v2.0.4

更新内容

• 新增“导入BH6SYX卡片广场数据”菜单，支持上传 .xls/.xlsx 表格并自动识别表头行。
• 导入时按“状态”仅保留“对方已寄出，待我签收”和“待双方寄出”的记录，直接创建线上换卡场景卡片记录。
• 导入清单支持批量设置默认卡片版本，也支持逐行选择卡片版本；导入结果围绕本站卡片编号展示。
• “交换ID”和“对方备注”不写入数据；“对方备注”仅在导入清单预览显示，后续流程统一围绕卡片记录编号处理。
• 同步补充后端 API、RBAC 权限模板、结构化项目文档与导入校验测试。
• 修复 GitHub Actions 中 Gradle Wrapper 执行权限，确保 release 后 CD 可自动构建插件包。
• 插件版本递增到 1.1.3。

安装包

• plugin-qsl-management-1.1.3.jar（由 GitHub Actions 在本 release 发布后自动构建并上传）

---

Generate from v1.1.3