qianbian/PROGRESS.md

进度日志 (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 测试全绿

遗留（需实机）

1. 真机功能回归（设备不在 BLE 范围内；扫到 17 台其他 BLE 设备无 NRF- 前缀）
2. SUOTA 首刷验证（建议先用仅改版本字符串的镜像，firmware-analysis §5 风险提示）
3. --mac 路径 activate --auto 的 NVDS 字节序（EFEF 路径无歧义，优先用）

会话时间线

• 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 工具链；文档终稿