chore: reorganize analysis/ by SDK lineage (linux/win/android) with README index, move legacy notes to history/, refresh root README, ignore .zcode/

.gitignore

@@ -33,3 +33,6 @@ Desktop.ini
 # Python
 __pycache__/
 *.pyc
+
+# ZCode 会话目录
+.zcode/

README.md

@@ -1,64 +1,67 @@
-# MAG160C 热像仪逆向工程
+# MAG160C 热像仪统一工程
 
-MAG160C 热像仪（160×120，USB VID 0x833C）的 USB 协议、官方 SDK 逆向、纯 C SDK
+MAG160C 热像仪（160×120，15fps，USB VID `0x833C`）的逆向工程与双端实现：
-和**官方渲染管线逐像素复刻**（demo3 v5）的完整工程。
+**C 参考实现**（Linux/Windows，源自官方 PC SDK 逆向）与**安卓统一 App**
+（Kotlin + Compose，适配 Android 16，整合官方 4 个 App 的功能）。
 
-## 从这里开始
+## 从这里开始（新接手者阅读顺序）
 
-新接手者按顺序阅读：
+1. `docs/android_app/HANDOFF_DEVELOPMENT.md` — 安卓 App 总交接（必读）
-
+2. `docs/android_app/session_state.md` — 会话心跳与待办（最新进度）
-1. `analysis/reverse_20260813_full.md` — 官方管线 Ghidra 全量逆向 + 鬼影根因（最新）
+3. `analysis/README.md` — 逆向工程总目录索引（Linux/Windows/Android 三条线）
-2. `analysis/session_state.md` — 当前会话状态与恢复点（心跳锚点）
+4. `analysis/magcx_official_flow.md` — **权威 USB 协议结论**（官方源码逐行核对版）
-3. `交接_完整逆向工程说明_20260811.md` — 项目总交接（目录/环境/历史/失败路线）
+5. `analysis/protocol_spec.md` — 早期 PC 端协议逆向（硬件验证记录）
-4. `analysis/protocol_spec.md` — USB 协议/帧/命令/温度规格
+6. `csdk/README.md` — C SDK 文档（构建/API/工具/测试）
-5. `csdk/README.md` — **C SDK 完整使用文档**（构建/API/工具/测试）
-6. `csdk/tools/mag160c_demo3.c` — 主程序（官方管线复刻）
-
-## 当前状态（2026-08-13）
-
-- demo3 v5 已完整复刻官方渲染管线：DDT 校准表加载 → 快门驱动端点选择与
-  Q12 插值 → ref=FFC 窗口 4×type1 帧均值 → NUC 查表 → 盲元补偿 →
-  窗口 → LUT1024 重建 → 灰度 → 2x 升采样 → 官方调色板
-- 逐像素验证：NUC+盲元 0/19200、插值 0 误差、2x 0/76800、窗口一致
-- 同静态场景 gray 直方图与官方相关性 0.92（跨会话）
-- 原"鬼影"问题的根因已定位并复刻官方行为（见 reverse_20260813_full.md §7）
-
-## 硬件
-
-- 设备：MAG160C 热像仪，分辨率 160×120，15 fps
-- USB VID：`0x833C`，常见 PID：`0x0001`
-- 帧：19200 个小端 `uint16`；端点：命令 `0x03`/响应 `0x82`/实时帧 `0x81`
-
-## 快速入口
-
-```powershell
-# 编译 demo3（官方管线复刻）
-gcc -O2 -w -DMAG160C_STATIC -I"csdk\third_party\libusb\win64" -I"csdk\include" -I"csdk\src" `
-    -o build-artifacts\mag160c_demo3.exe csdk\tools\mag160c_demo3.c `
-    csdk\src\mag160c_display.c csdk\src\mag160c_error.c `
-    csdk\third_party\libusb\win64\libusb-1.0.x64.a -lgdi32 -luser32
-
-# 启动
-Start-Process "build-artifacts\mag160c_demo3.exe" -WorkingDirectory "build-artifacts"
-```
-
-详细用法见 `csdk/README.md`。
 
 ## 仓库结构
 
 | 路径 | 用途 |
 |---|---|
-| `csdk/` | 纯 C SDK + 工具（见 `csdk/README.md`）|
+| `android/` | **安卓统一 App**（Kotlin + Compose，Gradle 工程，package `com.mag160c.thermal`）：实时预览、拍照 MDT、录像、媒体库、离线分析、PDF 报告、任务巡检、设置 |
-| `analysis/` | 逆向证据：反编译导出（`ida/`）、协议规格、交接文档、抓帧数据 |
+| `csdk/` | 纯 C SDK（官方管线 C 复刻：渲染/温度/IR 会话/FFC 调度，见 `csdk/README.md`）|
-| `IR_Camera_SDK-1.0.1/` | 原厂 Windows/Android/Linux SDK |
+| `analysis/` | 逆向工程总目录（Linux/Windows/Android 三条 SDK 线的解包产物与结论，见 `analysis/README.md`）|
-| `build-artifacts/` | 运行目录（demo3 exe、DDT 表、官方抓帧工具）|
+| `IR_Camera_SDK-1.0.1/` | 原厂 Windows/Android/Linux SDK 原始包 |
-| `docs/` `vendor-docs/` `app/` | 历史资料与模块文档 |
+| `app/` | 官方安卓 APK 存档（普通版/专业版/ThermoScope/demo）|
-| `tools/resume_rev.ps1` | 会话恢复脚本（心跳配套）|
+| `build-artifacts/` | 构建产物（安卓 APK、PC demo3、DDT 标定数据）|
+| `docs/android_app/` | 安卓 App 交接文档（HANDOFF / session_state / 逆向功能总表）|
+| `vendor-docs/` | 厂商资料 |
+| `tools/` | 会话恢复脚本 |
 
-历史文档（早期 findings/progress/task_plan、根目录抓帧残留）已归档到
+## 快速入口
-`analysis/history/`；早期探索工具源码在 `csdk/tools/legacy/`。
+
+### 安卓 App（构建/测试）
+```powershell
+cd C:\Project\MAG160C\android
+$env:JAVA_HOME = "C:\Tools\jdk-21"
+.\gradlew.bat :app:assembleDebug test --no-daemon
+# 产物：build-artifacts\mag160c-app-debug.apk
+```
+
+### C 管线复刻 demo3
+```powershell
+gcc -O2 -w -DMAG160C_STATIC -I"csdk\third_party\libusb\win64" -I"csdk\include" -I"csdk\src" `
+    -o build-artifacts\mag160c_demo3.exe csdk\tools\mag160c_demo3.c `
+    csdk\src\mag160c_display.c csdk\src\mag160c_error.c `
+    csdk\third_party\libusb\win64\libusb-1.0.x64.a -lgdi32 -luser32
+Start-Process "build-artifacts\mag160c_demo3.exe" -WorkingDirectory "build-artifacts"
+```
+
+## 硬件
+
+- 设备：MAG160C 热像仪机芯，160×120 @15fps
+- USB：VID `0x833C` PID `0x0001`；端点 0x03 命令 / 0x82 响应 / 0x81 图像流 /
+  0x84 标定文件 / 0x05 标定上传
+- 协议细节：`analysis/magcx_official_flow.md`（权威）
+
+## 里程碑
+
+- 2026-08：官方 PC SDK（libmagcore/CoreSDKLib）逆向 + C 管线逐像素复刻（demo3）
+- 2026-09-06~09：安卓 App（纯 Kotlin，无 NDK）：渲染管线移植（逐字节验证）、
+  USB 层（官方协议 Java 源码逐行复刻）、相机式 UI、拍照/录像/媒体库/分析/PDF
+- 2026-09-10：真机联调打通（根因：USB 命令字节序反转，已修复并用单测锁死）；
+  官方 App 全量解包入库（jadx + Ghidra）
 
 ## 仓库说明
 
-仓库包含官方 SDK、第三方依赖、二进制样本和抓帧数据。部分内容可能受原厂
+仓库包含官方 SDK、反编译产物、二进制样本和抓帧数据。部分内容可能受原厂许可
-许可限制，仅用于本项目的互操作性研究和设备调试。大型文件使用 Git LFS。
+限制，仅用于本项目的互操作性研究和设备调试。

analysis/README.md

@@ -0,0 +1,55 @@
+# analysis/ — MAG160C 逆向工程总目录
+
+> 本目录汇总了 MAG160C 相关的**全部逆向工程材料**，覆盖三条产品线：
+> ① Linux SDK（libmagcore.so）② Windows SDK（CoreSDKLib.dll / ThermalSDK.dll）
+> ③ 官方安卓 App（MAG-Cx 普通版：Java 层 + libcxsdk.so / libcoresdk.so）。
+> 阅读顺序建议：先读本 README → `magcx_official_flow.md`（权威协议结论）
+> → 按需深入各分目录。
+
+## 顶层文件（结论与工具）
+
+| 文件 | 内容 |
+|---|---|
+| `magcx_official_flow.md` | **权威协议结论**（2026-09-10，官方 Java 源码逐行核对版）：命令表、BasePara/CaliInfo 布局、连接序列、标定文件下载、FFC 逻辑 |
+| `protocol_spec.md` | 早期 PC 端逆向协议（libmagcore/CoreSDKLib，2026-08-10 硬件验证），历史参考 |
+| `gen_kotlin_tables.py` | 生成 `OfficialTables.kt`（palette256/T2E/E2T）的脚本 |
+| `render_offline.c` | PC 端参考渲染管线（gcc 编译），Kotlin 移植的逐字节差分基准 |
+| `official_render_frame.rgb` / `official_t2e_table.txt` / `t2e_table.json` / `test_ref_stats.txt` | PC 差分验证数据 |
+| `revtools.py` / `reverse_tools/` | 逆向辅助脚本 |
+
+## sdk_re/ — 按 SDK 产品线归档
+
+### `sdk_re/linux_libmagcore/` — Linux SDK（libmagcore.so.2.1.1，x86-64）
+- `magcore_disasm.txt`（全量反汇编）+ `magcore_defined.txt` / `magcore_dynsyms.txt` / `magcore_relocs.txt`
+- `disasm_*.txt`：关键函数级反汇编（LinkCameraEx / StartProcessImage / Raw2Temperature /
+  ConvertResponse2Temp / ReviseTemperature / ffc / frameParse / AccumulatorPushFrame 等）
+- `all_functions_decomp_libmagcore.so_00100000.txt`：Ghidra 全量伪代码
+
+### `sdk_re/windows_sdk/` — Windows SDK（CoreSDKLib.dll / ThermalSDK.dll）
+- `refs_CoreSDKLib.dll.txt` / `exports_decomp_CoreSDKLib.dll.txt` / `keyfuncs_decomp_CoreSDKLib.dll.txt`
+  / `callers_decomp_CoreSDKLib.dll.txt` / `coresdk_keyfuncs_disasm.txt` / `coresdk_windows_disasm.txt`
+- `exports_decomp_ThermalSDK.dll.txt` + `thermalsdk_dll/` + `thermalsdk_so/`（ThermalSDK 包装层）
+
+### `sdk_re/android_app/` — 官方安卓 App（普通版 MAG-Cx，本管线上真机跑通的代码）
+- `jadx_magcx/`：**全量 Java 源码**（jadx 1.5.1）。核心：`cn/com/magnity/magnitycx/sdk/UsbCommunication.java`
+  （USB 协议真身）、`P2DCmd.java`/`D2PCmd.java`（命令表）、`DeviceController.java`（JNI 封装）
+- `libcxsdk_decomp.txt`：Ghidra 全量伪代码（libcxsdk.so，1290 函数；Controller::StartProcess /
+  PushFrame / LoadCalibrationTable 已核对）
+- `all_functions_decomp_libcoresdk_arm64.so_00100000.txt`：libcoresdk(arm64) 全量伪代码
+  （专业版/网络路径，CNetComm 命令层）
+- `coresdk_arm64_defined.txt`：ARM64 库符号表
+
+## history/ — 过程记录（按时间）
+`task_plan_20260714` → `findings_20260810` / `progress_20260810` / `handoff_20260810..13` /
+`交接_完整逆向工程说明_20260811`（PC SDK 全流程报告）→ `reverse_20260813_full` /
+`progress_reverse`。历史参考，协议细节以 `magcx_official_flow.md` 为准。
+
+## preview/ — 渲染验证截图
+demo2_v3..v7 系列（管线复刻过程对照）、preview_*.png（安卓 UI 验证）。
+
+## 与代码库的关系
+- `csdk/src/`：依据 Linux SDK 逆向写出的 C 参考实现（渲染/温度/IR 会话/FFC 调度），
+  Kotlin 管线（android/app）与其逐字节差分验证一致。
+- `android/app/src/main/java/com/mag160c/thermal/usb/IrSession.kt`：官方
+  UsbCommunication.java 的 Kotlin 等价实现（含小端命令、800ms 超时、0x84 标定下载）。
+- `docs/android_app/HANDOFF_DEVELOPMENT.md` §4.2 指向本目录。

analysis/magcx_official_flow.md

@@ -1,10 +1,10 @@
 # MAG160C 官方 MAG-Cx 完整逆向结论（2026-09-10，jadx + Ghidra 全量解包）
 
 > 产物来源：
-> - Java 层：`analysis/jadx_magcx/`（jadx 1.5.1 反编译官方普通版 MAG-Cx.apk 全量源码）
+> - Java 层：`analysis/sdk_re/android_app/jadx_magcx/`（jadx 1.5.1 反编译官方普通版 MAG-Cx.apk 全量源码）
-> - Native 层：`analysis/ida/export/ghidra_dump/libcxsdk_decomp.txt`
+> - Native 层：`analysis/sdk_re/android_app/libcxsdk_decomp.txt`
 >   （Ghidra 11.3.2 headless 全量反编译 lib/armeabi/libcxsdk.so，1290 函数）
-> - libcoresdk(arm64) 反编译已在 `analysis/ida/export/ghidra_dump/`（专业版/网络路径）
+> - libcoresdk(arm64) 反编译已在 `analysis/sdk_re/android_app/`（专业版/网络路径）
 > - 本文结论全部来自以上反编译源码，与真机日志交叉验证（vivo V2509A, Android 16）。
 
 ## 1. USB 协议权威版（以官方 Java UsbCommunication.java 为准）
@@ -96,7 +96,7 @@ fpaTemp 在尾 +8（devType0/5/6/3），camTemp=fpaTemp-500。
 
 ## 3. 工具与环境（2026-09-10 本机）
 - jadx 1.5.1：C:\Tools\jadx-1.5.1（反编译产物 C:\Tools\jadx-out，已拷贝入库
-  analysis/jadx_magcx/）
+  analysis/sdk_re/android_app/jadx_magcx/）
 - Ghidra 11.3.2：C:\Tools\ghidra_11.3.2_PUBLIC；工程 C:\Tools\ghidra_proj\MagCX；
   全量反编译脚本 C:\Tools\ghidra_scripts_user\DumpAllDecomp.java
 - 重跑命令（PowerShell/cmd）：