Web → ESP32 迁移流程
迁移采用“先冻结合同，再替换运行时”的方法。任何阶段都能通过主机测试或实板证据判断是否偏离网页，而不是等全部写完再凭肉眼猜。
M0 / 硬件冻结与可恢复环境
- 确认完整 SKU、分辨率、面板、触控、IMU、Flash/PSRAM 与官方 Demo。
- 读取实板 16 MiB 完整 Flash，保存 SHA-256 回滚点。
- 隔离安装 ESP-IDF，先构建/烧录官方 BSP 示例。
- 不开启不可逆安全特性。
本项目的原机备份为 firmware/backups/pre-migration-full-flash.bin，SHA-256 e24913…a065651，按策略不提交 Git。
M1 / 显示、触控与性能基线
- 初始化 CO5300，固定 466×466 RGB565。
- CST9217 读取 checkcode、ProjectID 与坐标范围。
- 建立全量刷新帧率、render/present 耗时、heap 与 PSRAM 基线。
- 先画测试图，再接游戏资产；避免把驱动错误误判成渲染错误。
M2 / 纯 C++ 游戏核心
把 state/economy/progression/engine 迁为不依赖 LVGL 的主机可测试 C++。浏览器生成 11 组黄金快照，C++ 对齐到 1e-10；经济逻辑通过后才进入 UI。
M3 / 静态 SEED 垂直切片
转换 PNG 与字体为打包二进制，绘制一张固定 SEED；比较浏览器与 C++ RGB565 输出。这个阶段冻结颜色字节序、字体基线、Alpha 合成和 1:1 像素。
M4 / 三页与手势事务
迁移圆屏导航、点按/长按、外缘 detent、SHOP 卡片与内环 preview/commit。所有几何逻辑在 host test 覆盖中心穿越、离环重入、取消锁与多 detent。
M5 / 全资产、动效与增量渲染
接入 111 帧资产、粒子、浮字与三组 FX。先允许全量刷新得到正确结果，再逐层加入像素 diff、语义脏区和 clipped render；每一步都与全量画面逐像素比较，防止用残影换帧率。
M6 / 设备服务与产品化
加入 QMI8658、PCF85063、NVS、AXP2101、电量、设置、ambient、音频和 PWR。把浏览器的 virtual/sim 功能明确排除或映射，避免在实体设备上保留不存在的 UI。
v7 增量迁移
v7 不是重做主程序，而是在 v6 已签字基线增加：三段 hold/burst、整数分带倾斜、设置黑场、电量作用域、ambient 显示开关、严格首输入唤醒、SHOP preview/commit、外缘 rebase、音频与 PWR 安全序列。
Definition of Done
- 玩法公式、手势阈值和存档迁移通过 host test。
- 固定状态的三页图像达到调色板像素一致。
- 动效与增量渲染多帧逐像素等同全量参考。
- 实板启动识别芯片、内存、显示、触控、IMU、RTC、音频与 NVS。
- 持续运行无 WDT、assert、brownout、coredump 或内存下降。
- 人工边界不被自动日志夸大：玻璃观感、手指手感、扬声器声压必须单独确认。