analysis: full official-app reverse artifacts (jadx sources, ghidra libcxsdk decomp, authoritative protocol conclusions) + docs

docs/android_app/HANDOFF_DEVELOPMENT.md

@@ -101,11 +101,16 @@ res/drawable/*.xml          自绘矢量图标（双弧圆等可靠几何图形
   4. 暖机窗口检查在 ffc_step **之前**（顺序不能改）。
 - 验证方式：`android/app/src/test/.../RenderPipelineTest.kt`（JVM 差分测试，参照 `analysis/render_offline.c` 的 C 输出，60帧序列与官方DDT）。
 
-### 4.2 USB 协议（analysis/protocol_spec.md 全文）
-- 命令：普通 4 字节 magic；FFC 8 字节 {magic, param}。
-- 初始化：66b→66c→66f（4B）→FFC(0)×2→300ms→START(73)；停止 STOP(74)。
-- 帧流：EP 0x81 bulk，0x1BB1B11B 头 + 0x1C 起像素 + 尾部 shutter 于 +0x24。
-- 相机信息块 0x5BB5B55B：+0x00 pid、+0x08 序列号、+0x10 宽、+0x14 高、+0x18 fps。
+### 4.2 USB 协议（权威版：analysis/magcx_official_flow.md）
+- **2026-09-10 已反编译官方普通版全量源码**（jadx：`analysis/jadx_magcx/`，
+  UsbCommunication.java 是 USB 层真身；Ghidra：libcxsdk 全量伪代码
+  `analysis/ida/export/ghidra_dump/libcxsdk_decomp.txt`，1290 函数）。
+- 协议要点：命令 4 字节**小端**；超时全线 800ms；序列
+  GetParameter1(66b)→GetParameter2(66c)→GetCaliInfo(66f)→[缓存缺失]
+  GetCaliFile(670)+EP 0x84 拉 16KB 块→StartTransferImg(673)；FFC=672（帧驱动）。
+- 官方响应格式：0x5BB5B55B BasePara1（60B，含 serial/devType/宽/高/fps）。
+- 旧 analysis/protocol_spec.md 的 66f/670 描述（"prepare/version query"）不准，
+  以 magcx_official_flow.md 为准。
 
 ### 4.3 实时画面渲染（最终约定：构图钉死竖屏框架）
 - **Activity 锁定竖屏**（manifest `screenOrientation="portrait"`）：屏幕相对手机框架
@@ -166,6 +171,11 @@ git -C C:\Project\MAG160C commit -m "android: ..."
 3. **SurfaceView 与旋转**：不要在横竖屏间切换不同布局分支（SurfaceView 会被销毁且 surface 不重建）。
    用"稳定单分支 + 覆盖层"布局（当前实现即如此）。
 4. **写代码要谨慎**：本会话多次因急于成稿写出语法错误/残留死代码。每写一个文件后立即编译。
+5. **ByteBuffer.putInt 默认大端**：USB 命令必须小端（官方 intToByteArray）。
+   16 轮黑屏调试的根因就是它（66b 回文数掩盖了字节反转），MagProtocolTest 已锁死。
+6. **官方 App 源码已入库，先读它再写协议代码**：analysis/jadx_magcx/（Java）、
+   analysis/ida/export/ghidra_dump/libcxsdk_decomp.txt（native）、
+   analysis/magcx_official_flow.md（权威结论）。不要凭旧文档猜协议。
 
 ## 7. 当前状态与待办