软硬件全链路测试计划（设备到场后执行）
目的：验证三线逆向结论在真机上的正确性，完成 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 勾掉
