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

For agentic workers: REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 从连接开始到关闭结束记录毫秒级全链路日志，并提供应用内日志查看页面。

Architecture: 使用纯 Java ReaderLogStore 负责格式化、追加、滚动、保留和读取；Android ReaderLog 同时输出 Logcat 与本地文件。业务层、读卡器层和协议层共享同一日志入口，日志失败与读卡业务隔离。

Tech Stack: Java 8、Android app-private files、JUnit 4、AndroidX ActivityScenario。

Task 1: 日志存储核心

Files:

• Create: app/src/main/java/com/cpt/onecarddemo/log/ReaderLogStore.java

• Create: app/src/test/java/com/cpt/onecarddemo/log/ReaderLogStoreTest.java

• 先写失败测试，覆盖 yyyy-MM-dd HH:mm:ss.SSS、单行转义、按日文件、5MB滚动、7天清理、最新日志读取。

• 运行 ./gradlew testDebugUnitTest --tests com.cpt.onecarddemo.log.ReaderLogStoreTest，确认缺少实现而失败。

• 使用 java.io 和注入的时间源实现最小存储核心；任何写入异常由调用方降级处理。

• 重跑目标测试并确认全部通过。

Task 2: Android 日志入口与全链路埋点

Files:

• Create: app/src/main/java/com/cpt/onecarddemo/log/ReaderLog.java

• Modify: app/src/main/java/com/cpt/onecarddemo/MainActivity.java

• Modify: app/src/main/java/com/cpt/onecarddemo/reader/AndroidUsbHidTransport.java

• Modify: app/src/main/java/com/cpt/onecarddemo/reader/NewcapecUsbCardReader.java

• Modify: app/src/main/java/com/cpt/onecarddemo/reader/NewcapecProtocol.java

• Modify: app/src/test/java/com/cpt/onecarddemo/reader/NewcapecProtocolTest.java

• 以日志存储失败测试和现有协议响应测试约束日志核心及协议兼容行为。

• 实现 ReaderLog.initialize(context)、info/error、会话编号和 Logcat/文件双写。

• 在 USB 连接、协议初始化、寻卡、基础读取、钱包读取、APDU、通道关闭和业务自动事件处埋点。

• 保证等待放卡产生的周期性 NO_CARD 有可诊断记录，但不写完整64字节补零报告。

• 运行协议测试和全部单元测试。

Task 3: 应用内日志查看页面

Files:

• Create: app/src/main/java/com/cpt/onecarddemo/LogViewerActivity.java

• Create: app/src/main/res/layout/activity_log_viewer.xml

• Modify: app/src/main/res/layout/activity_main.xml

• Modify: app/src/main/res/values/strings.xml

• Modify: app/src/main/AndroidManifest.xml

• Modify: app/src/androidTest/java/com/cpt/onecarddemo/MainActivityQuickReadUiTest.java

• 先扩展仪器测试，要求主页面存在“查看读卡日志”入口。

• 新增主页面按钮并启动非导出的 LogViewerActivity。

• 日志页默认选择最新文件，支持历史文件选择和刷新；文本可选择、可横向纵向滚动。

• 编译 AndroidTest 并在 F700_HW 上运行页面测试。

Task 4: 文档与交付验证

Files:

• Modify: zhctprompt/work_android/OnecardDemo/protocols/新开普HID读卡器通讯协议.md/.html

• Modify: zhctprompt/work_android/OnecardDemo/change_records/CHANGELOG.md/.html

• 更新通讯协议日志章节，记录日志格式、覆盖范围、文件策略与隐私边界。

• 更新独立变更记录并同步 Markdown/HTML。

• 执行 ./gradlew testDebugUnitTest assembleDebug assembleDebugAndroidTest lintDebug --rerun-tasks。

• 安装 Debug APK，启动 MainActivity 与日志查看页，确认日志目录和最新文件可读取。

• 不执行 Git 暂存、提交、推送、分支切换或其他写操作。