diff --git a/docs/报告/STEP-077_QBIN2_V4_Android_JNI_RN桥接调查_Codex完成报告_v1.md b/docs/报告/STEP-077_QBIN2_V4_Android_JNI_RN桥接调查_Codex完成报告_v1.md new file mode 100644 index 000000000..e7c6e0df8 --- /dev/null +++ b/docs/报告/STEP-077_QBIN2_V4_Android_JNI_RN桥接调查_Codex完成报告_v1.md @@ -0,0 +1,35 @@ +# STEP-077 QBIN2 V4 Android / JNI / RN 桥接调查 Codex 完成报告 v1 + +## 结果 + +已完成只读架构调查并形成 V4 桥接实施边界。推荐 V4 新建与 V3 平行的 encoded-field bridge:RN 传本地 `qbinFileUri`,Kotlin 有界读取为 `byte[]`,JNI copy 后调用 `RasterArraySource` V4 Host API;小型 contract 用受 schema 限制的 control-plane JSON,其余 binding/time/playback 使用 typed primitive。Host 不控制 T0/T1/MIX。 + +现有 V3 `submitField` 保留。V3 的 `clearFields`、`setForecastTime`、`setPlaybackState`、`setPlaybackSpeed` 直接走旧 Host-field/timeline,不能承载 V4;V4 必须有 `clearEncoded*` 与独立 forecast 命名空间,避免误操作 V3 timeline。 + +## 实际调查范围 + +- 逐层审计 `FieldRuntime.ts`、`NativeWeatherRuntimeBridge.ts`、`types.ts`、`WeatherRuntimeBridgeModule.kt`、`WeatherRuntime.java`、`MapLibreMap.java`、`NativeMapView.java`、`native_map_view.hpp/.cpp` 与 `RasterArraySource` V4 API。 +- 确认 Fabric tag 每次在 UI queue 解析到当前 `MLRNMapView -> MapLibreMap`;不新增 registry,不缓存 map/source pointer。style reload、detach 或 dispose 后应以明确 lifecycle error 拒绝,Host 重 attach 后重新提交。 +- 列出十项 `RasterArrayEncodedFieldSubmitResult` 到 RN resolved result 的一一映射,并与文件、参数、runtime、style/source 错误分层。 +- 调查 Linux 静态入口:package/Host TypeScript、TurboModule codegen config、C++/JNI 精确编译、以及现有 Mockito `WeatherRuntimeStateTest` 的 JVM facade 边界;未执行 Android Gradle/APK/ADB/实体机。 + +完整结论、API 表、参数 ABI、风险与后续三段实施建议见 [调查报告](../20_调查/STEP-077_QBIN2_V4_Android_JNI_RN桥接调查报告_v1.md)。 + +## 修改与验证 + +- production code、package version、Test Host、Renderer/GPU:均未修改。 +- 新增调查报告与 STEP 记录;将任务状态更新为完成;追加 `粒子开发记录.md`。 +- `git diff --check`:PASS(本任务文档)。 +- 没有执行 noisy build/test,因此没有 Android/Gradle、APK、ADB、真机、真实 QBIN、Jest 或 iOS/Metal 结果可报告。 + +## Git 收尾 + +- 文档调查提交:`e0088a5f0873ed95a902a9402683ffdd0dcc155c` +- 提交信息:`docs: complete STEP-077 V4 bridge investigation` +- 首次 push 结果:`0759a0610..e0088a5f0 particle/main -> particle/main` +- remote branch:`origin/particle/main` +- 本完成报告作为 Git 元数据收尾另行 scoped commit 并紧随推送;其最终 HEAD 以交付时 `git rev-parse HEAD` 为准。 + +## 未完成/阻塞 + +无调查阻塞。桥接实现、Android 编译与实体机验证都刻意不属于本 Step;按任务书在本报告提交推送后立即停止,不进入 STEP-077 实现。