# 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` 明确显示：

```text
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 文件。