消费前服务端人员卡信息校验变更记录

• 日期：2026-09-15
• 项目：ZhctTrayBindingMachine

结论：消费首次完整读卡后已强制按读卡账号查询一卡通单人信息，并以服务端卡号、卡序号、卡状态和姓名作为后续消费权威数据；仅状态 1 可继续，状态 3、4 及其他状态均在扣款前拦截。查询失败提示“同步人员卡信息失败”，确认可对仍在位的原卡重新请求。

Compact Use Case

• Use Case ID / 状态 / DoR：UC-CONSUMPTION-CARD-VERIFY-001 / Implemented / READY
• 角色、触发与目标：消费者第一次放卡并完整读卡成功后，终端实时核对一卡通服务端人员卡信息，避免使用不可信的卡内状态继续消费。
• In Scope / Out of Scope：覆盖零元核验和正金额消费的前置查询、权威字段覆盖、状态门禁、姓名展示、人工重试、日志及 SQLite JSON 快照；不修改业务订单查询、一卡通扣款算法和既有服务端上报字段契约。
• 主流程：首次完整读卡 → 用 CustomerID 调用 GetInfoByCustID → 校验返回账号及关键字段 → 更新卡号、卡序号、状态和姓名 → 状态为 1 时继续零元核验或扣款 → 消费后复读继承已验证人员身份。
• 异常与恢复：状态 3 为挂失、4 为冻结、其他为异常，均不可消费；网络、SOAP Fault、返回失败、查无人员、账号不一致或关键字段异常统一按同步失败处理，不发送扣款指令。确认弹框可安全重试，取消后保留订单并等待移卡换卡。
• 安全边界：服务端查询和硬件交易共用串行队列；查询失败结果标记为扣款前失败，交易门禁只允许未扣款且原卡仍在位时重试，已进入扣款的结果不允许重复执行。
• 待确认项：需要在目标终端使用真实一卡通服务器、正常卡、挂失卡、冻结卡和异常状态测试卡完成真机验收。

实现

• 新增 ServerCustomerInfo、ServerCustomerInfoParser 和 OnecardCardInfoVerifier，集中完成单人字段解析、SOAP 成功校验、账号一致性校验和错误归类。
• OnecardWebServiceClient 新增无状态单人查询入口，直接调用 GetInfoByCustID，不会为单次消费额外探测 GetCustomerCount。
• CardInfo 增加 holderName 及 readerCardNumber/readerCardSerialNumber/readerStatus；业务字段使用服务端结果，读卡器原始字段只用于诊断。消费后快照保留第二次读卡余额和计数，同时继承首次已验证人员身份。
• ConsumptionCardTransactionExecutor 把服务端查询放在首次读卡和零元/扣款分支之间；查询失败、挂失、冻结和未知状态均不调用消费。
• ConsumptionCardSearchManager 保存当前在位卡的定位结果，提供受交易门禁保护的显式重试入口；确认或移卡要求跨页面停启保留，防止原卡在恢复前台时被自动重试。
• ConsumptionActivity 使用服务端姓名展示持卡人；同步失败落库、记录结构化日志并展示确认弹框，确认重试，取消后等待移卡。
• 结构化读卡日志新增姓名、权威卡字段和 reader* 原始诊断字段；现有 SQLite before_result_json/after_result_json 通过扩展后的 CardInfo 自动记录增项，无需数据库迁移。
• 状态值、SOAP 字段名和失败状态均集中定义为常量，弹框文案放入字符串资源；新增类和非显然的串行、重试及身份继承逻辑已补职责注释。
• SOAP 权威字段只从当前 operation 的 GetInfoByCustIDResult 复杂对象直接子字段读取，响应对象外同名字段不能混入，重复结果字段会被拒绝；全量人员接口的重复复杂记录结构保持兼容。

测试与验证

• 定向测试通过：单人响应解析、无状态请求、权威字段合并、状态 1/3/4/其他、查询失败禁止扣款、零元订单门禁、消费后身份继承、重试门禁、结构化日志及 SQLite JSON 快照。
• 完整单元测试：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:testDebugUnitTest --rerun-tasks，共 235 项，232 项通过、3 项失败。

3 项失败均位于既有 CustomerFullFetchServiceTest：测试断言仍按每页 1000 人，而当前未修改的 CustomerFullFetchService.SOURCE_PAGE_SIZE 已为 2000；与本次消费前单人查询链路无关，本次未扩大范围修改。

• Debug 构建：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:assembleDebug，构建成功。
• APK：app/build/outputs/apk/debug/app-debug.apk，大小 66832146 字节，SHA-256 5830468d6cfe9423d76813cca85cc52386028486f4a14b15e2292cd090672f25。
• 本次未安装 APK、未连接真实一卡通服务器、未操作现场读卡器、未触发真实订单或扣款。

Git 边界

本次未执行暂存、提交、推送、拉取、分支切换、合并、变基、重置或清理。当前分支为 order_upload_to_onecard，工作区原有修改和未跟踪文件均保留。