一键寻卡并读卡功能 Implementation Plan

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

Goal: 在现有结果区下方增加“一键寻卡并读卡”按钮和独立结果区，并复用已连接读卡器串行执行寻卡与完整读卡。

Architecture: 只修改布局、字符串和 MainActivity。组合操作留在页面层，通过现有单线程执行器调用 findCard() 与 readCard()；底层协议保持不变。

Tech Stack: Java 8、Android XML、AppCompat、AndroidX Test、JUnit 4、Espresso。

Task 1: 用 UI 测试锁定控件位置与初始状态

Files:

Create: app/src/androidTest/java/com/cpt/onecarddemo/MainActivityQuickReadUiTest.java
Step 1: 写入失败测试

测试通过 ActivityScenario.launch(MainActivity.class) 获取根布局，断言：

assertTrue(parent.indexOfChild(quickButton) > parent.indexOfChild(existingResult));
assertTrue(parent.indexOfChild(quickResult) > parent.indexOfChild(quickButton));
assertFalse(quickButton.isEnabled());
assertEquals(activity.getString(R.string.result_find_and_read_empty),
        quickResult.getText().toString());

Step 2: 验证 RED

运行：

./gradlew compileDebugAndroidTestJavaWithJavac

预期：因 button_find_and_read、text_find_and_read_result 和新字符串尚不存在而编译失败。

Task 2: 增加布局与字符串

Files:

Modify: app/src/main/res/layout/activity_main.xml
Modify: app/src/main/res/values/strings.xml
Step 1: 在 text_result 后添加按钮

<Button
    android:id="@+id/button_find_and_read"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginTop="16dp"
    android:text="@string/action_find_and_read" />

Step 2: 在按钮后添加独立结果区

<TextView
    android:id="@+id/text_find_and_read_result"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginTop="6dp"
    android:background="#12000000"
    android:minHeight="220dp"
    android:padding="12dp"
    android:text="@string/result_find_and_read_empty"
    android:textIsSelectable="true" />

Step 3: 增加按钮、进度、成功、空结果和失败字符串

字符串必须覆盖“一键寻卡并读卡”“正在寻卡并读取卡片”“寻卡并读卡成功”“暂无一键操作数据”“寻卡结果 UID + 读卡结果”和错误结果。

Task 3: 实现页面级组合操作

Files:

Modify: app/src/main/java/com/cpt/onecarddemo/MainActivity.java
Step 1: 绑定新控件与点击事件

新增 findAndReadButton、findAndReadResultView，在 onCreate 中绑定并调用 findAndReadCard()。

Step 2: 串行执行寻卡和读卡

CardUid uid = cardReader.findCard();
CardInfo info = cardReader.readCard();

成功后在主线程更新状态和独立结果区。

Step 3: 显示独立错误结果

为 runOperation 增加可选的错误结果 TextView；现有调用继续使用无结果目标的重载，新组合操作传入 findAndReadResultView。

Step 4: 同步按钮状态和关闭清理

refreshButtons() 中仅在 !busy && connected 时启用新按钮；disconnectReader() 清空新结果区。

Task 4: 验证 GREEN 与完整构建

Files:

Test: app/src/androidTest/java/com/cpt/onecarddemo/MainActivityQuickReadUiTest.java
Step 1: 运行目标 UI 测试编译

./gradlew compileDebugAndroidTestJavaWithJavac

预期：成功。

Step 2: 运行完整静态验证

./gradlew testDebugUnitTest assembleDebug assembleDebugAndroidTest lintDebug

预期：BUILD SUCCESSFUL，Lint 0 error。

Step 3: 安装并真机验证

安装 Debug APK 和 AndroidTest APK；先运行 UI 仪器测试，再启动应用。连接读卡器后确认新按钮启用，点击后确认独立结果区显示寻卡 UID 与完整卡片信息，或显示真实 ReaderException。

Task 5: 同步项目记录

Files:

Modify: change_records/CHANGELOG.md
Modify: change_records/CHANGELOG.html
Step 1: 记录改动文件、行为和验证结果

明确生产协议未修改，新功能只组合现有 API。

Step 2: 生成匹配 HTML 并核对结论

Markdown 为可编辑真源，HTML 为浏览版。按照当前工作约束不执行 Git 暂存、提交或推送。