# 进度日志 (PROGRESS)

## 2026-07-24（最终状态）

### 已完成（对照门禁）

| 门禁 | 状态 | 证据 |
|------|------|------|
| G1 架构摸清 | ✅ | docs/architecture.md + docs/protocol.md + docs/firmware-analysis.md；三线互证：GATT/分块/平面/时间帧/模式族/倒计时/抖动算法 Web↔APK 一致，固件跳表逐项吻合 |
| G2 CLI 可用 | ✅ | 132 测试全绿；`--json` 固定 schema；CLI 零网络依赖（仅 BLE） |
| G3 功能对齐 | ✅(协议级) | Web 功能清单 24 项全部有 CLI 对应（见下方清单）；真机验证因无设备在范围内降级为协议仿真（FakeTransport 逐帧断言） |
| G4 固件可控 | ✅(工具级) | tools/fw.py 解析/修改/重打包字节级往返 + CRC32 验证；SUOTA 全流程文档化（firmware-analysis §5）+ `ppclock ota` 实现；实机首刷待硬件 |
| G5 离线交付 | ✅ | 激活本地 keygen（activate --auto）；模板本地渲染（wqy 字体）；qrcode 本地库；无任何 CDN/服务器调用 |

### 三线逆向关键结论

1. **协议**：双通道 GATT（EPD 图像+RXTX 命令），全部 opcode 见 docs/protocol.md §4。
2. **激活可离线绕过**（firmware-analysis §4.3）：激活码 = `ror2(((MAC[i]<<1)&0xFF)^0xEF)%101`（i=0..5），EFEF 设备 ID 可无损反解 MAC；EF 不门禁任何命令。
3. **SUOTA 可用**（§5）：藏在 0x221F 服务，任务 0xFC 四消息，接收方校验 pQ 头+长度+XOR 写 Flash 0x38000 备 bank。
4. **固件 no-op 命令**：E9/EA/WIFI 在本固件版本被忽略（§3.3）。
5. **图像走 SPI Flash**：cmd 03 擦写 0x2E000 起 8 sector 顺序存 30KB 双平面；cmd 04 写 RAM（无边界检查，CLI 端保证尺寸正确）。
6. **驱动 IC**：SSD1683 兼容（400x300 三色）+ UC8151 备选；OTP 波形无 LUT 表；E6=红黑平面校准字节。

### 交付物清单

- `src/ppclock/`：CLI（protocol/image_pipeline/commands/transport/cli/templates/textbitmap/ota/keygen）
- `tools/`：fw.py / fw_info.py / fw_pack.py / check_env.py
- `docs/`：protocol.md / architecture.md / firmware-analysis.md
- `analysis/`：web 抓取与协议原始报告、apk 反编译报告与中间产物、firmware 反汇编产物
- `tests/`：132 测试全绿

### 遗留（需实机）→ 已备好执行器

**执行入口：`.venv/bin/python tools/field_test.py`（计划 docs/field-test-plan.md，结果自动写 docs/field-test-result.md）**

1. 真机功能回归（设备不在 BLE 范围内；扫到 17 台其他 BLE 设备无 NRF- 前缀）→ 阶段 1–8
2. SUOTA 首刷验证（建议先用仅改版本字符串的镜像）→ 阶段 9（`--ota` 才执行，脚本自动制作等长测试镜像+回滚）
3. `--mac` 路径 activate --auto 的 NVDS 字节序（EFEF 路径无歧义，优先用）→ 阶段 1.2 自动反解对比

### 2026-07-25：workspace 整理清理

- 清理：删除可再生产物（apk/native/*.so 5.2MB、firmware/fw.asm 1.2MB、decomp 日志 5 个）与 __pycache__/.pytest_cache；再生方法写入 analysis/README.md
- 新增：docs/field-test-plan.md（10 阶段验收表）、tools/field_test.py（引导执行器）、examples/field_test.jsonl（batch 冒烟序列）
- 冒烟验证：field_test.py --help / jsonl 10 行可解析 / 测试镜像制作+CRC 均通过

### 会话时间线

- 08:14 目标设定（治理+规划+执行）
- 治理：GOVERNANCE.md / PLAN.md / DECISIONS.md / git 骨架
- P0：venv（bleak/pillow/pytest/capstone/androguard/pytest-asyncio/qrcode）+ Java21
- P1：Web JS 协议提取（子代理）→ APK 反编译互证（子代理）→ 固件逆向（子代理）
- P2：protocol/image/commands/transport/cli/templates/textbitmap 全 TDD 实现
- P3：batch/本地模板/ota/keygen 增强；fw 工具链；文档终稿