OnecardDemo 读卡器全链路本地日志与查看功能设计

目标

为连接、初始化、寻卡、读卡、自动读卡、异常和关闭建立统一、可导出的本地日志，并在应用中直接查看。每条记录使用 yyyy-MM-dd HH:mm:ss.SSS 绝对时间，耗时字段使用单调时钟计算到毫秒。

日志边界

• 业务层：连接、手动寻卡、手动读卡、一键寻卡读卡、自动会话、关闭和 USB 插拔。
• 读卡器层：设备查找、权限、HID 接口/端点、打开、占用、释放。
• 协议层：初始化开/关、激活、寻卡、基础信息、主钱包、补助钱包、APDU、通道关闭。
• HID 层：opcode、channel、请求/响应长度、分片数、步骤耗时和错误；正常场景不写整段 64 字节补零报告，协议异常保留必要原始逻辑响应。

文件策略

• 目录：应用私有目录 files/reader_logs/，不申请外部存储权限。
• 文件：reader-YYYY-MM-DD.log；达到 5MB 后滚动为带序号文件。
• 保留：只保留最近 7 个自然日的日志，初始化和写入时清理过期文件。
• 并发：日志写入串行同步，单条记录一次性追加，避免 UI、USB I/O 和自动轮询交叉破坏行结构。
• 降级：日志文件写入失败不能打断读卡业务，仍输出到 Logcat，并记录一次写入失败。

日志格式

2026-08-23 14:32:18.126 | session=7 | level=INFO | event=FIND_CARD_START | uid=- | details=-
2026-08-23 14:32:18.171 | session=7 | level=INFO | event=HID_EXCHANGE_SUCCESS | opcode=62 channel=1 responseLen=9 elapsedMs=32

动态文本中的换行和竖线统一转义，确保一条事件固定占一行。UID、卡号、余额等沿用当前诊断日志口径；不新增密钥、注册码或完整安全参数记录。

页面设计

主页面增加“查看读卡日志”按钮。独立日志页面包含日志文件选择、刷新按钮、当前文件说明和可横向/纵向滚动且可选择复制的等宽文本区；默认打开最新日志。没有日志时显示明确空状态，读取失败时显示错误，不影响主读卡页面。

验证

• 单元测试验证毫秒格式、字段转义、5MB 滚动、7天清理、最新文件读取和写入失败不抛出。
• 协议测试验证 HID 请求成功与异常均产生日志事件。
• Android 仪器测试验证主页面入口和日志查看页面控件。
• 真机验证安装、页面启动、本地文件生成，并由用户执行连接至关闭的完整读卡验收。

边界

本次不实现联网上传、外部存储写入、分享 FileProvider、日志加密或完整 Bus Hound 替代抓包。