重要：破坏性更新

本版本为 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