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. 当前状态与待办
 

docs/android_app/session_state.md

@@ -350,6 +350,32 @@
 - 预期日志：GetParameter1 resp=0x5BB5B55B len=60 → GetParameter2 → GetCaliInfo
   （cali size=…date=…）→ 下载（首次）或 cache hit → frames 递增。
 
+## 用户反馈修复 第十七轮（2026-09-10，根因确认：命令字节序反转）
+
+- [x] **第 16 轮日志**：官方序列下 GetParameter1 仍唯一有响应（60B BasePara1 完整
+  解析成功：serial=160043865 devType=3=core160 160x120@15fps），66c/66f/673 全部
+  800ms 超时 → 与"字节内容"相关而非流程顺序。
+- [x] **根因**：`MagProtocol.cmd4/cmd8` 用 `ByteBuffer.putInt` —— **默认大端**！
+  官方 `GlobalFunc.intToByteArray` 是小端。66b=0x6BB6B66B 是回文数，大小端
+  字节相同，所以 16 轮调试里它是唯一能被相机识别的命令，完美掩盖了 bug；
+  其余命令（66c/66f/670/672/673/674）发出去的字节全是反的 → 相机不应答、
+  收到垃圾触发看门狗重启。PC 的 C 参考（mag160c_ir.c）是手工小端打包，所以
+  PC 上一直正常。
+- [x] **修复**：cmd4 改手工小端打包（与官方 intToByteArray 逐字节一致）；
+  cmd8 = cmd4(magic)+cmd4(param)。新增 MagProtocolTest 锁死
+  GetParameter2/StartTransferImg/SetShutterState 的线缆字节序。
+- [x] 构建+单测全过；APK 已更新。提交 623d62b。
+- [x] **按用户要求完成全量解包复核**（产物入库 analysis/）：
+  - `analysis/jadx_magcx/`：官方普通版全量 Java 源码（64 文件）；
+  - `analysis/ida/export/ghidra_dump/libcxsdk_decomp.txt`：Ghidra 11.3.2 全量
+    反编译 libcxsdk.so（1290 函数）；
+  - `analysis/magcx_official_flow.md`：权威协议结论（命令表/BasePara/CaliInfo/
+    连接序列/FFC 逻辑/工具重跑命令）。
+  - native 复核：`Controller::StartProcess` 必须 `LoadCalibrationTable(caliPath)`
+    （官方 startProcess 失败会删缓存文件重下）→ 我们的 loadDdt 等价正确；
+    `Controller::PushFrame` 输入=整帧缓冲（28B头+像素+28B尾），与本管线一致。
+- 预期：66b/66c/66f 全部有响应 → cali 下载（首次）→ 流出帧。
+
 ## 待办
 
 - 真机USB实测（温度绝对值标定、FFC/录像/MDT保存端到端）——进行中：