# 软硬件全链路测试计划（设备到场后执行）

> 目的：验证三线逆向结论在真机上的正确性，完成 G3/G4 的实机门禁。
> 前置：设备充电开机；本机蓝牙可用；`tools/check_env.py` 通过。
> 执行方式：`.venv/bin/python tools/field_test.py [--mac AA:BB:..]`（引导式，自动+目视确认）。
> 危险操作仅 `--ota` 分支，默认跳过。

## 阶段 0 · 预检（自动）

| # | 检查 | 通过标准 |
|---|------|----------|
| 0.1 | check_env.py | 全 OK |
| 0.2 | 蓝牙适配器 | `ppclock scan` 返回 ≥0 设备不报错 |
| 0.3 | 固件样本 | `ppclock ota app/firmware-PP_da14585_4.2_CH.img` 预检 ok（**不烧录**） |

## 阶段 1 · 发现与识别（自动）

| # | 检查 | 通过标准 |
|---|------|----------|
| 1.1 | `scan` | 发现 `NRF-XXXXXX` 设备，记录 MAC |
| 1.2 | `activate --show-id` | 收到 14 hex 设备 ID；本地反解 MAC 与 1.1 的 MAC 对比（字节序验证 → 回填 DECISIONS.md） |
| 1.3 | 断线重连 | CLI 连续两次命令均成功 |

## 阶段 2 · 激活（自动+目视）

| # | 检查 | 通过标准 |
|---|------|----------|
| 2.1 | `activate --auto` | ok=true，code 与 keygen 一致；屏上激活提示（若有）消失 |
| 2.2 | 错误码激活 | 发 6 字节全 0 码：无惩罚、后续命令仍可用（验证固件不门禁结论 §4.3） |

## 阶段 3 · 时钟/模式族（目视）

| # | 命令 | 屏显预期 |
|---|------|----------|
| 3.1 | `time` | 屏显时间与手机/电脑一致 |
| 3.2 | `mode clock1/2/3` | 三种时钟版式切换 |
| 3.3 | `mode calendar1/2/3` | 三种日历版式切换 |
| 3.4 | `toggle hour_format` | 12/24h 切换 |
| 3.5 | `toggle clock_color` | 时钟颜色变化 |
| 3.6 | `toggle invert` | 反色 |
| 3.7 | `toggle font` | 字体变化 |
| 3.8 | `toggle rotate180` | 旋转 180°（恢复再按一次） |
| 3.9 | `mode tricolor` / `mode mono` | 三色/黑白切换 |
| 3.10 | `clear` | 全屏刷新 |

## 阶段 4 · 图像（目视）

| # | 命令 | 屏显预期 |
|---|------|----------|
| 4.1 | `image <棋盘+红块测试图> --slot 0` → `mode image0` | 棋盘清晰、红块为红 |
| 4.2 | 六算法各传一张 | 抖动风格差异可见（Floyd/Atkinson/Bayer/Stucki/Jarvis/none） |
| 4.3 | `image --mono` | 无红色通道 |
| 4.4 | `image --size 400x180`（小图 cod=04 路径） | 小图正常 |
| 4.5 | 亮度/对比度/饱和度/旋转参数 | 效果可见 |
| 4.6 | `image --slot 1..3` + `mode image1..3` | 多槽位（注意：固件 EA0x 为 no-op 风险 → 记录实际行为） |

## 阶段 5 · 模板（目视）

6 模板（schedule/businesscard/memo/course/qrcode/custom）各传一次：版式正确、中文无方块、`【…】` 字段为红。

## 阶段 6 · 倒计时（目视）

| # | 命令 | 预期 |
|---|------|------|
| 6.1 | `countdown 2026-12-31 --prefix 目标` | 时钟界面显示前缀+天数 |
| 6.2 | `countdown --mode calendar 2026-12-31 --prefix 中考` | 日历界面 |
| 6.3 | `countdown --show-calendar --prefix test` | upload_rili 序列 |
| 6.4 | `countdown --off` | 倒计时关闭 |

## 阶段 7 · 其他命令（含固件 no-op 验证）

| # | 命令 | 预期 |
|---|------|------|
| 7.1 | `sleep --on --start 23 --end 7` | 时段内不刷新（次晨验证）；`sleep --off` 恢复 |
| 7.2 | `parking 13800138000` | 停车牌显示 |
| 7.3 | `lut 0x05` / `lut 0x15` | 红/黑深度变化 |
| 7.4 | `rotation --count 4`、`rotation --interval 5` | **验证固件 no-op 结论**：预期无效果（firmware-analysis §3.3） |
| 7.5 | `wifi SSID PASS` | **验证 no-op**：预期无效果 |
| 7.6 | `raw e2` / `raw 01 --channel epd` | 提交/刷新 |

## 阶段 8 · 异常与契约（自动）

| # | 检查 | 通过标准 |
|---|------|----------|
| 8.1 | 错误参数 | `--json` 输出 `{"ok":false,...}`，退出码 1 |
| 8.2 | 设备关机中途执行 | 退出码 2，error 含连接失败 |
| 8.3 | `batch examples/field_test.jsonl` | 单连接全序执行，results 逐行 ok |

## 阶段 9 · 固件可控（高危，默认跳过，`--ota` 才执行）

| # | 步骤 | 预案 |
|---|------|------|
| 9.1 | field_test.py 自动制作仅改版本串镜像（`V:PP_da14585_4.2`→`V:PP_da14585_TST`，等长），fw_pack 重打包，CRC 验证 | 本地完成，不触机 |
| 9.2 | `ppclock --mac X ota /tmp/fw_tst.img --yes` | 观察块进度 302 块全 ok |
| 9.3 | 设备重启后 `scan` + `time` | 设备复活且可用 |
| 9.4 | 回滚 | `ota 原镜像 --yes` 刷回 |
| 9.5 | 若 9.2 失败/变砖 | 记录 SERV_STATUS 错误码；设备有备 bank（0x38000 产品头机制，firmware-analysis §5），断电重连试刷原镜像 |

## 结果回填

- 每步实际结果记于本文件"实测"列（执行时生成 field-test-result.md）
- 与协议不符处 → 改 docs/protocol.md + 测试向量 + DECISIONS.md
- 全过 → PROGRESS.md 将 G3/G4 从"协议级/工具级"升级为"实机验证"，Plan Task 9 勾掉