2.2.2

本版本聚焦 QRZ 地址获取和卡片打印工具体验优化。

变更内容

• QRZ.COM 地址获取优先按官方 XML 字段结构化解析，避免 AI 漏掉 addr1、邮编和邮箱。
• QRZ.CN 命中“呼号不在数据库中”页面时立即返回不存在，不再等待多轮重试或调用 AI。
• 优化呼号地址获取默认 AI 提示词，明确 JSON 返回字段、字段含义和 QRZ.COM XML 字段优先级。
• 卡片打印工具字段模板新增数字上移比例，呼号中的数字可上移以区分字母和数字。
• 同步更新产品定义、API 合同和结构化文档，并补充相关测试。

升级说明

• 已保存过自定义“呼号地址获取提示词”的站点不会被自动覆盖；如需使用新版默认提示词，请在系统配置的 AI 配置中点击对应提示词的“重置”并保存。
• Release 附件由 GitHub Actions CD 自动构建上传，本 Release 不手动附加 JAR。

---

Generated from v2.2.2

2.2.1

本版本继续完善 2.2.x 的 AI 与数据维护能力，包含以下调整：

• 新增 QRZ.COM / QRZ.CN 地址获取能力，QRZ.COM 使用官方 XML 接口，QRZ.CN 通过页面抓取、主体内容抽取和图片文件名线索交给 AI 解析。
• 系统配置新增 QRZ 凭据配置与测试写入能力，密码、Cookie、AI API Key 均仅写入 Halo Secret，不进入导入导出数据包。
• QRZ 远程请求限制为官方域名，并改为测试通过后再保存配置与 Secret，降低错误配置和 SSRF 风险。
• 线上换卡导入、AI 地址整理和 QRZ 地址解析支持完整提示词配置、重置和并发控制。
• 收卡记录查询支持将未关联发卡记录的收卡记录手工关联到正式卡片。
• 通信地址新增英文姓名和英文地址展示与导入导出字段。
• 在线打印工具和标定工具新增固定辅助说明字段 fixed_text。
• 修正测试样例脱敏、收卡记录筛选显示、AI/QRZ 服务注册与插件热重载问题。

注意：本次 Release 不手动上传 JAR 附件，构建产物由 GitHub Actions CD 自动生成并上传。

---

Generated from v2.2.1

版本 2.2.0

主要变更

• 新增 AI 配置能力，支持 OpenAI 兼容接口配置、Secret 方式保存 API Key。
• 新增线上换卡导入 AI 解析，可用于单条导入和批量导入，并保留本地解析回退。
• 新增地址管理中的 AI 地址整理能力，支持勾选地址后预览并应用规范化结果。
• AI 提示词改为完整模板，可在系统配置中查看、编辑，并按项重置为内置默认值。
• 导入导出同步纳入 AI 配置与提示词字段。
• 补充对应 RBAC、接口合同、结构化文档与测试覆盖。

数据与配置提示

• AI API Key 不会写入 SystemSetting 明文字段，只写入 Halo Secret。
• 本版本新增/调整 SystemSetting AI 配置字段：aiSystemPrompt、aiOnlineImportPrompt、aiAddressCleanupPrompt 等。
• 自定义提示词必须保持系统指定 JSON 返回结构：线上换卡导入顶层字段为 rows，地址整理顶层字段为 items。

验证

• 已通过 .\gradlew.bat test。
• 已完成插件 reloadPlugin 热重载验证。

---

Generated from v2.2.0

版本说明

本版本完成 Console 表格组件化收口，并将插件版本升级为 2.1.0。

主要变化

• 新增统一表格组件 QslDataTable，收口普通列表、排序、空态、分页和行操作展示。
• 新增统一详情表组件 QslDetailTable，收口历史记录展开详情布局。
• 统一历史/批量编辑表格能力，降低各业务页面重复实现。
• 统一二次确认按钮组件，便于后续复用删除、重发、异常标记等高风险操作确认流程。
• 调整多个业务页面的表格渲染方式，保持原有业务字段和操作语义不变。

验证

• 已通过 ./gradlew.bat test。
• 已通过 ./gradlew.bat reloadPlugin，本地 Halo 插件热重载成功。
• 已使用 Chrome 对主要表格页面完成只读与可写走查；测试环境中完成新增、编辑、删除和清理测试数据；未执行邮件发送。

发布说明

Release 附件由 GitHub Actions CD 自动构建并上传，本 Release 不手动上传 JAR 附件。

---

Generated from v2.1.0

更新内容

• 数据 / 卡片异动 / 卡片重发：移除清单中的操作列，仅保留记录展示。
• 通用历史表组件新增操作列显示开关，默认保持既有页面行为不变。

验证

• pnpm --dir ui type-check
• .\gradlew.bat test
• .\gradlew.bat reloadPlugin

兼容性

• 本版本不变更数据模型、不变更公开 API、不新增权限节点。

---

Generated from v2.0.17

更新内容

• 收口卡片状态机：有收卡记录关联的正式卡片统一进入“已收卡片”状态。
• 导入完成后按卡片状态字段与 ReceiveRecord.spec.outboundCardNames 重建 flowStatus。
• 导出时按收卡关联派生 cardReceived、receivedAt 和 flowStatus，避免导出包继续携带不一致状态。
• 公开查询、审计卡片查询、统计口径统一到新的已收状态规则。
• 同步更新结构化文档与插件版本到 2.0.14。

验证

• pnpm --dir ui type-check
• ./gradlew.bat test
• git diff --check
• ./gradlew.bat reloadPlugin

---

Generated from v2.0.14

变更内容

• 创建卡片时为 CardRecord.spec.cardReceived 增加默认值 false。
• 在线打印工具在 cardReceived 为空或缺失时默认按未收卡处理，勾选“请回卡片/回复卡片/欢迎回卡”。
• cardReceived 为 true 时保持勾选“感谢来卡/感谢您的卡片/感谢您的来卡”。
• 补打眼球卡片默认设置为发出卡片并勾选请回卡片。
• 同步更新 CardPrint 说明与 docs/spec 结构化文档。

验证

• python -m pytest tools/CardPrint/tests/test_online_bridge_service.py：18 passed
• pnpm --dir ui type-check：通过
• .\gradlew.bat test：BUILD SUCCESSFUL
• .\gradlew.bat reloadPlugin：插件已就绪

---

Generated from v2.0.9

兼容性提醒

这是 2.0.x 兼容过渡版本。本版本保留旧版本字段定义，但普通业务、前端展示、统计、导入导出已不再使用旧收卡编号字段。

计划在 2.1.x 版本移除的旧字段/旧列：

• CardRecord.spec.receivedRecordCodes：旧版卡片记录内的收卡编号集合字段。
• card-record.csv 中的 receivedRecordCodes 列：2.0.7 起已不再导入/导出，旧数据迁移应以 ReceiveRecord.metadata.name 与 ReceiveRecord.spec.outboundCardNames 为准。

本次调整

• 收卡编号主数据统一为 ReceiveRecord.metadata.name。
• 发出卡片与收到卡片的关联统一为 ReceiveRecord.spec.outboundCardNames。
• 修改收卡日期时同步更新关联的 ReceiveRecord，不再重写旧字段。
• 前端卡片查询中的收卡编号改为从 ReceiveRecord 反向聚合显示。

验证

• 已执行 ./gradlew.bat test，测试通过。
• 已执行 ./gradlew.bat reloadPlugin，构建、测试、打包通过；热重载阶段因本机 http://localhost:8090 未监听而连接失败。

---

Generated from v2.0.7

重要说明

本版本仍属于 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