# 84 采集采购前检查 Android 设备连接状态

- 类型：缺陷
- 父级大工单：#1
- 所属 MVP / 版本：#2 Client 可运行任务闭环（MVP）
- 状态：已完成，用户验收通过
- 日期：2026-08-10
- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/84>

## 背景与目标

原流程只确认本地保存了 Android 设备号，没有在任务开始前确认对应 USB 或 Wi-Fi 设备仍处于 ADB 可用状态。设备断开时，Client 可能先领取任务或重置重新采集任务，直到 uiautomator2 连接时才发现失败。

本任务要求在采集、采购演练和重新采集开始前检查设备连接。检查失败时中断操作，不领取新任务，也不改变重新采集任务的原有数据。

## 最终方案

- Android 设备服务增加精确设备号检查，只接受 `adb devices -l` 返回的 `device` 状态，并区分未连接、`offline` 和 `unauthorized`。
- 自动获取仍优先补交 Outbox；没有待提交结果时，先在工作线程检查设备，再执行本地任务或领取 Admin 新任务。
- 重新采集在用户确认后进入工作线程，先检查设备，再重置任务和创建新执行记录。
- 设备不可用时停止本轮操作。采集、采购、重新采集和设备错误使用较大的提示，提供明显的“关闭提示”按钮，5 秒后自动关闭；设备错误另有“打开设置”，重复提示不会堆叠。底部状态区继续保留完整错误。
- 保留运行过程中 uiautomator2 的断线检查。未修改 Admin 接口、数据库结构、`pdd_data` 和采购安全开关。

验收时用户补充指出，错误提示不能只依赖右上角的小关闭图标。最终方案将原来的持久小提示调整为较大的提示、明显的关闭按钮和 5 秒自动关闭；这是与建单方案的差异。

## 改了哪些

- `client/src/android_device_service.py`：增加指定设备连接状态检查。
- `client/src/task_dispatcher.py`：在任务执行和领取前接入检查，同时保留离线 Outbox 补交。
- `client/src/pdd_ui_event.py`：在后台线程执行检查，并处理中断状态和提示。
- `client/src/pdd_ui.py`、`client/src/ui_main.py`：增加从设备提示进入设置页的信号和导航。
- `client/test/`：覆盖 USB、Wi-Fi、离线状态、Outbox、重新采集数据保护、线程和提示交互。
- `docs/client/02-architecture.md`、`docs/client/05-ui-specification.md`：记录任务顺序和界面规则。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 设备不在 ADB 列表时不领取新任务、不创建执行记录 | 通过 |
| `offline` 或 `unauthorized` 时明确提示并中断 | 通过 |
| USB 或 Wi-Fi 设备处于 `device` 状态时允许继续 | 通过 |
| 设备断开时仍可补交 Outbox | 通过 |
| 重新采集检查失败时保留原任务状态和数据 | 通过 |
| ADB 检查不阻塞 Qt 主线程 | 通过 |
| 提示可打开设置、可关闭且不堆叠 | 通过 |
| 采集、采购和重新采集错误提示尺寸增大并在 5 秒后自动关闭 | 通过（自动化配置） |
| 运行期间断线仍由原有设备错误安全停止 | 通过（代码回归） |
| Client 专项测试和全量回归通过 | 通过 |

## 测试

- 执行的命令：`cd client; python -m py_compile src/android_device_service.py src/task_dispatcher.py src/pdd_ui.py src/ui_main.py src/pdd_ui_event.py test/test_android_device_service.py test/test_task_dispatcher.py test/test_purchase_recovery.py test/test_pdd_ui_event.py`
- 执行的命令：`cd client; python -m unittest discover -s test -v`
- 结果：语法检查通过；Client 224 项自动化测试全部通过。
- **没验证到的部分**：未使用真机人工验证 USB/Wi-Fi 拔线提示、进入设置以及重新连接后再次执行；未执行真实采购、下单或付款。

## 相关提交

- `e7fb06d` 任务执行前检查 Android 设备连接
- `74198bd` 根据验收反馈放大任务错误提示并设置 5 秒自动关闭