STEP-063 MapLibre 粒子 Android v1 发布工程化 — 完成报告 v2

结论：CLOSED / PASS。日期：2026-09-09。

1. 最终发布契约

MapLibre Native upstream：13.4.1。
Core commit：18545ca10d296704b2cba675b182ff2c8da24588。
renderer：OpenGL。
npm package：@navsea/maplibre-particle-rn@13.4.1-particle.1。
Maven：cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1。
Maven repository：https://pbf.jpcn.ccwu.cc/maven。
release manifest：release/maplibre-particle/release-manifest.json。
Consumer：integration/react-native/MapLibreParticlePackageConsumerTestHost/。

正式 package 的职责是提供 React Native facade、WeatherRuntime bridge、Expo/Gradle 接线并复用唯一 MLRN peer dependency；正式 Android Native 来自 Maven AAR，不通过源码路径或 Maven Local 消费。

2. 正式制品与哈希

Android AAR：166,304,929 bytes，SHA-256：

63c976c5a73fe8f132f428afecca40b09fa2dbdedaa13721586c472ea7eb279d

npm tarball：navsea-maplibre-particle-rn-13.4.1-particle.1.tgz，9,100 bytes；SHA-1 247e2db901f6588c9e48bc3156a448b97d203d0d；SHA-256 31335791a5a6e553a538f84816322e8cd119f16d7c2b15436ce785aa497da6a8。

3. Consumer 依赖问题与最终修正

首次 Windows Consumer APK 编译失败原因不是 Particle AAR，而是正式 npm 包把 MLRN 作为普通 dependency，导致 native module 嵌套在 @navsea/.../node_modules/@maplibre/...，RN codegen/CMake 路径超过 Windows 260 字符限制。

修正提交：fa431ba6fd1f182b8b77345b50a9d74e225f17d4，将 @maplibre/maplibre-react-native@11.3.6 调整为 peer dependency，并仅保留 devDependency 支撑包自身开发。

修正后实际安装验证：根层 MLRN 存在，NavSea package 内嵌 MLRN 不存在；npm ls 只形成一份 MLRN native module。Gradle dependencyInsight 明确显示：

org.maplibre.gl:android-sdk-opengl:13.4.1
→ cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1

因此正式 Consumer APK 中使用的是正式 Particle AAR，而不是 step061、官方 OpenGL AAR、Maven Local 或 MapLibre Native 源码构建。

4. 真实 WeatherV2 验收 Host

为了让 Package Consumer 真正模拟未来 NavSea 升级包后的使用方式，Consumer 从原 2×2 smoke fixture 升级为真实 WeatherV2 T0–T3。实现提交：3ac678a3c8164082452bd77e61989ccc928ed8bd，message：test: validate release package with real WeatherV2，已 push 到 origin/particle/main。

Consumer 仍只从 @navsea/maplibre-particle-rn 导入 Map、Camera、WeatherRuntime；没有重新引入旧 weather-runtime-bridge 或 direct MLRN import。

真实数据为 ECMWF HRES 2026-08-07 00/06/12/18 四帧。每帧 513×769、3,155,976 bytes，canonical contract 为 maplibre-particle-field/v1、float32-le、interleaved-uv，U eastward、V northward；React transport 为 metadataJson + local file:// payload。

Linux 已通过：

Consumer TypeScript typecheck；
package peer/hoist 结构检查；
禁止 direct MLRN / 旧 bridge 依赖审计；
Metro .f32 asset 配置；
npx expo export --platform android，实际导出四个 3.2MB .f32；
git diff --check。

没有执行 Jest。

5. Windows / Android 最终人工验收

Win11 Consumer Android 环境按 NavSea 当前编译基线对齐：Gradle 8.14.3、buildTools 36.0.0、minSdk 24、compileSdk/targetSdk 36、NDK 27.1.12297006、Kotlin Plugin 2.1.20、JDK 17、RN 0.85.2、New Architecture 与 Hermes 开启。

用户手工完成正式 Package Consumer 的 Android 编译和安装，并在实体设备运行；2026-09-09 用户明确确认：这个APK确认正常了。该 APK 对应已经升级为真实 WeatherV2 T0–T3 的 Package Consumer，因此 STEP-063 要求的正式 package / Maven AAR / Runtime / WeatherColor / Particle 消费链人工门槛判定 PASS。

本报告不把未单独提供的 PID logcat 全量 hard-gate 扫描写成已执行；PASS 依据正式依赖解析、成功 APK 编译安装、真实 Consumer 运行以及用户最终确认。

6. 关闭边界

未修改 Particle GPU、WeatherColor 算法、Timeline、HostField canonical contract、JNI/Core 业务功能。
未接入 NavSea 仓库。
未执行 Jest。
npm registry 仍为 null。
release tag 仍为 null。

因此 STEP-063 的 CLOSED / PASS 只表示发布工程化、正式制品和 Package Consumer Android 验收完成；不等于 npm 已正式上传，也不等于 release tag 已创建。下一步应单独执行 Release Freeze / Tag。

7. React 使用说明

新增：

docs/30_设计/MapLibre粒子ReactNative使用说明_v1.md

该说明从 React Native 使用角度记录：正式包安装模型、Expo plugin、Map attach/detach、WeatherRuntime API、真实 T0–T3 提交方式、NavSea/Core 边界，以及最重要的 canonical 显示数据结构。

数据结构明确为规则二维 NW-origin row-major Grid；payload 是 contiguous float32-le / interleaved-uv，每 cell 8 bytes，cell=y*width+x，U eastward-positive、V northward-positive；metadata 包含 schema、field identity、generation、validTime、bounds、grid、noData 和 byteLength。文档同时区分当前 Native 强制校验字段与仅用于审计的额外 metadata。

8. Git 基线

本轮最终人工验收前的主线实现 HEAD：3ac678a3c8164082452bd77e61989ccc928ed8bd，已与 origin/particle/main 一致。本文档收尾只允许精确提交本轮新增/更新文档与 release manifest，不提交历史无关 untracked 文件。

5.5 KiB Raw Permalink Blame History Unescape Escape