docs: record STEP-060A prebuild fixes

docs/50_Step记录/STEP-060A_RNTestHost编译前修正_v1.md

@@ -0,0 +1,21 @@
+# STEP-060A RN Test Host 编译前修正
+
+状态：完成（`READY_ANDROID_VALIDATION`）
+
+## 基线与目标
+
+Starting HEAD：`6a99f1a1424ce7e30c26e825251df956a46bf4c4`，分支 `particle/main`。本 Step 只修正 STEP-060 的 Codegen Kotlin override blocker 与 npm/package 文档契约；不进入 STEP-061，未改 RN ownership、MapLibre renderer、timeline 或 field contract。
+
+## 完成项
+
+- [x] 以当前 RN `0.85.2` 安装源码的 `@react-native/codegen/lib/generators/modules/GenerateModuleJavaSpec.js` 核对：必选方法生成 `public abstract`，Promise 末尾追加 `Promise promise`。
+- [x] 为 JS `NativeWeatherRuntimeBridge.ts` 的 20 个方法全部补齐 Kotlin `override`；签名逐项脚本核对，未发现额外 Spec mismatch。
+- [x] Test Host 统一为 `npm@10.9.4` 声明与 `package-lock.json`；不新增 yarn.lock。
+- [x] README/人工验收命令统一 `npm ci`；实际 `npm ci --ignore-scripts` 可通过，不需要 `--legacy-peer-deps`。
+- [x] 文档明确 Android toolchain 数值目前是验收目标；首次 Expo prebuild 后才检查实际 Gradle/AGP/Kotlin/SDK/NDK/Hermes/New Architecture。
+
+## 验证与边界
+
+执行 `npm ci --ignore-scripts --no-audit --no-fund`、throttle 下 `npx tsc --noEmit`、Node config syntax、package/lock 检查、Spec/override 一一检查、yarn 残留搜索与 `git diff --check`。未执行 Android Gradle、custom publish、Expo prebuild、APK、ADB、设备测试或 Jest。
+
+Bridge 继续按 `reactTag → Fabric UIManager → MLRNMapView → MapLibreMap → map-owned WeatherRuntime` 工作；无 Adapter/Normalizer/第二 registry，未实现 Binary Field。

docs/60_测试/STEP-060_RNTestHost_Android人工编译与验收_v1.md

@@ -2,11 +2,14 @@
 
 本说明只列出人工步骤；Codex 未执行 Android Gradle、发布、安装或 ADB。
 
-1. 在当前 `particle/main` 编译并发布 custom OpenGL SDK：`cd platform/android && ./gradlew :MapLibreAndroid:publishToMavenLocal`。确认 `~/.m2/repository/org/maplibre/gl/android-sdk-opengl/13.4.1/` 是当前提交生成；建议先移走任何旧的同版本 artifact。
-2. `cd integration/react-native/MapLibreParticleRNTestHost && yarn install && npx expo prebuild --platform android --clean`。检查生成 root Gradle 有 `MapLibreParticleRNTestHost custom OpenGL SDK` 标记、`nativeVersion=13.4.1`、`nativeVariant=opengl`，并且 Maven Central 对 `org.maplibre.gl` 被排除。
-3. 用 JDK 17、AGP 8.5.0、Gradle 8.14.3、Kotlin 2.1.20、NDK 27.1.12297006、compile/targetSdk 36 编译/安装 Test Host；确认 Hermes 与 New Architecture 开启。
-4. 启动后确认单一地图正常加载。style ready 后应显示 reactTag 和 `WAITING_FOR_FIELDS`，不提交 field 时粒子/色场为空是预期。
-5. 对同一 reactTag 依次验证 Phase A：getState、enable、WeatherColor visible、particle visible、FPS 30 均得到结构化 Native result。
-6. 验证 Phase B：PLAY/PAUSE、HALF/NORMAL/DOUBLE、epoch-ms seek、stops、独立 particle/trail RGBA、count/line/length/opacity/fade/WeatherColor opacity。不得出现 JS `PLAYING/PAUSED` 第二状态机。
-7. 重载 style：旧 Runtime 必须 disposed；style ready attach 的新 Runtime 正常工作。remount Map 后，用旧 reactTag 调用必须返回 `MAP_VIEW_NOT_FOUND`，不得命中新 Map。
-8. 卸载 Host：确认 view detach dispose；无持续 Handler wake、无全局 current map。STEP-061 前不要尝试 number[]、JSON/base64 大 field。
+1. 确认当前为 `particle/main`，并记录 `git rev-parse HEAD`。
+2. 移走或清理 `~/.m2/repository/org/maplibre/gl/android-sdk-opengl/13.4.1/` 的旧 artifact，避免相同版本号造成 provenance 混淆。
+3. 手工发布当前 HEAD 的 custom OpenGL SDK：`cd platform/android && ./gradlew :MapLibreAndroid:publishToMavenLocal`。确认 Maven Local AAR/POM 是当前构建产物。
+4. `cd integration/react-native/MapLibreParticleRNTestHost && npm ci && npx expo prebuild --platform android --clean`。`package-lock.json` 已在无 `--legacy-peer-deps` 的 npm dry-run 下解析；不要改用 Yarn 或生成 `yarn.lock`。
+5. 检查生成 root Gradle 有 `MapLibreParticleRNTestHost custom OpenGL SDK` 标记、`nativeVersion=13.4.1`、`nativeVariant=opengl`，且 Maven Central 对 `org.maplibre.gl` 被排除；缺 custom AAR 时 resolution 必须失败而非 fallback。
+6. 首次 prebuild 后实际记录 Gradle wrapper、AGP、Kotlin plugin、min/compile/targetSdk、NDK、JDK、Hermes 与 New Architecture。`8.5.0/8.14.3/2.1.20/27.1.12297006/24/36/36` 在此之前只是验收目标，不是已验证值。
+7. 再按实际生成工程编译/安装 Test Host。启动后确认单一地图正常加载；style ready 后应显示 reactTag 和 `WAITING_FOR_FIELDS`，不提交 field 时粒子/色场为空是预期。
+8. 对同一 reactTag 依次验证 Phase A：getState、enable、WeatherColor visible、particle visible、FPS 30 均得到结构化 Native result。
+9. 验证 Phase B：PLAY/PAUSE、HALF/NORMAL/DOUBLE、epoch-ms seek、stops、独立 particle/trail RGBA、count/line/length/opacity/fade/WeatherColor opacity。不得出现 JS `PLAYING/PAUSED` 第二状态机。
+10. 重载 style：旧 Runtime 必须 disposed；style ready attach 的新 Runtime 正常工作。remount Map 后，用旧 reactTag 调用必须返回 `MAP_VIEW_NOT_FOUND`，不得命中新 Map。
+11. 卸载 Host：确认 view detach dispose；无持续 Handler wake、无全局 current map。STEP-061 前不要尝试 number[]、JSON/base64 大 field。

docs/报告/STEP-060A_RNTestHost编译前修正_Codex完成报告_v1.md

@@ -0,0 +1,42 @@
+# STEP-060A RN Test Host 编译前修正 — Codex 完成报告
+
+状态：`READY_ANDROID_VALIDATION`
+
+## 实际修正
+
+1. RN `0.85.2` 当前安装的 `node_modules/@react-native/codegen/lib/generators/modules/GenerateModuleJavaSpec.js` 第 36 行生成 `public abstract class`，第 526 与 536 行为必选方法生成 `@ReactMethod` 与 `abstract`。Promise 返回在同一模板中追加 `Promise promise`。这证明 STEP-060 的 Kotlin implementation 必须 override Spec 方法。
+2. `WeatherRuntimeBridgeModule.kt` 已为 attach、detach、getState、enabled/visible/target FPS、forecast、playback/speed、stops、particle/trail colors 及全部 visual controls 共 20 个 JS Spec 方法补齐 `override`。逐项脚本比较 `NativeWeatherRuntimeBridge.ts` 的 20 个方法与 Kotlin `override fun`，没有缺失。View attach listener 的两个 override 是 Android 回调，不是 Spec 方法。
+3. 未发现除 override 外的 Codegen signature mismatch；number→`Double`、boolean→`Boolean`、string enum→`String`、ColorStop list→`ReadableArray` 和 Promise 末参均保持现有最小实现，没有重构 bridge。
+4. Test Host 统一使用 npm，`packageManager` 为 `npm@10.9.4`，锁文件是现有 `package-lock.json`（lockfile v3）；没有 yarn.lock。
+5. 实际 `npm ci --ignore-scripts --no-audit --no-fund` 通过，未需要 `--legacy-peer-deps`。当前环境 npm 为 11.19.0；`packageManager` 声明保留任务指定的 npm 10.9.4 目标，人工验收以 `npm ci` 使用 lock。
+6. package/config 明确控制 package 版本、`app.json` 的 New Architecture 请求、MLRN native `13.4.1/opengl` root extras 与 Maven Local 防 fallback。AGP、Gradle、Kotlin、SDK、NDK、Hermes 和最终 New Architecture 生成值仍待首次 prebuild 后实际检查；文档不再把它们表述为已验证冻结。
+7. STEP-060 ownership/lifecycle 未改：每次 command 仍通过 Fabric UIManager 定位 concrete MLRNMapView，再到 MapLibreMap 的 map-owned WeatherRuntime。未新增 Adapter、Normalizer、global/current map 或第二 registry。
+8. 未实现 Binary Field，未加入 number[]/JSON/base64 field、JSI、NavSea、iOS、Core renderer/timeline 改动。
+
+## 文件
+
+- `integration/react-native/MapLibreParticleRNTestHost/modules/weather-runtime-bridge/android/src/main/java/org/maplibre/particle/rntesthost/weather/WeatherRuntimeBridgeModule.kt`
+- `integration/react-native/MapLibreParticleRNTestHost/package.json`
+- `integration/react-native/MapLibreParticleRNTestHost/README.md`
+- `docs/50_Step记录/STEP-060A_RNTestHost编译前修正_v1.md`
+- `docs/60_测试/STEP-060_RNTestHost_Android人工编译与验收_v1.md`
+- `docs/报告/STEP-060_RNTestHost与WeatherRuntime薄桥接_Codex完成报告_v1.md`
+- `粒子开发记录.md` 与本报告。
+
+## 实际验证
+
+- `npm install --package-lock-only --ignore-scripts --no-audit --no-fund`：PASS。
+- `npm ci --ignore-scripts --no-audit --no-fund`：PASS（530 packages）；不需 legacy peer deps。
+- throttle 下 `npx tsc --noEmit`：PASS。
+- RN Codegen generator 语义、20 个 JS Spec 与 Kotlin override 一一检查、`node --check`、package/lock 检查、yarn 残留搜索、`git diff --check`：PASS。
+
+## 未执行与人工验收
+
+未执行 Android Gradle、custom AAR publish、Expo prebuild、APK/AAB、ADB、安装、App launch、模拟器/真机、Jest。用户下一步按更新后的 STEP-060 人工验收说明：先记录 HEAD、清除旧 Maven Local 同版本 artifact、publish 当前 custom SDK、`npm ci`、Expo prebuild、核对实际工具链/Hermes/New Architecture 与 custom resolution，再进行 Phase A/B、style reload 和 remount 验收。
+
+## Git
+
+- Starting HEAD：`6a99f1a1424ce7e30c26e825251df956a46bf4c4`
+- 功能 commit：`51b58024323aeb47103ccc08e50a53ac0ab75d43`（`fix: correct RN WeatherRuntime codegen bridge`）
+- 文档 commit：待提交
+- Final HEAD / Remote HEAD / push：待提交后回填。

docs/报告/STEP-060_RNTestHost与WeatherRuntime薄桥接_Codex完成报告_v1.md

@@ -6,7 +6,7 @@ Starting HEAD：`b535d98263af58ac86845f15bb7c51bd85b59519`。
 
 ## 实际完成内容
 
-1. RN Test Host 最终目录为 `integration/react-native/MapLibreParticleRNTestHost/`。冻结 RN `0.85.2`、React `19.2.5`、Expo `56.0.4`、TypeScript `5.9.3`、MLRN `11.3.6`；New Architecture 已在 Expo config 开启。
+1. RN Test Host 最终目录为 `integration/react-native/MapLibreParticleRNTestHost/`。固定 RN `0.85.2`、React `19.2.5`、Expo `56.0.4`、TypeScript `5.9.3`、MLRN `11.3.6`；New Architecture 已由 Expo config 请求，但 Android prebuild/生成工程尚未验证。
 2. MLRN `11.3.6` 实际 Android `build.gradle` 按 root extra `org.maplibre.reactnative.nativeVersion/nativeVariant` 解析 `android-sdk-<variant>`。Test Host config plugin 固定 `13.4.1`/`opengl`。
 3. plugin 在 Android project 配置完成后清除各 project repositories，设置 Maven Local、Google 与 Maven Central（后者排除 `org.maplibre.gl`）。因此 custom `android-sdk-opengl:13.4.1` 缺失即依赖失败，不会从普通官方 SDK fallback；artifact 的字节来源仍须用户手工发布/检查。
 4. MLRN 的共享 `ReactTagResolver` 实例由 `MLRNPackage` 私有持有，不能安全注入外部模块。Bridge 没有复制其 `mViews`：使用 React Native/Fabric 的公开 `UIManagerHelper.getUIManager(...).resolveView(reactTag)`，验证结果是具体 `MLRNMapView`。

integration/react-native/MapLibreParticleRNTestHost/README.md

@@ -2,10 +2,11 @@
 
 这是 MapLibreParticleLab 内的独立 React Native 开发宿主，不是 NavSea 业务应用。它只有一个 `MLRNMapView` 与 WeatherRuntime 控制页，用于证明低频控制面：React 的 `reactTag` 经薄 Android 模块定位该 View，再定位该 View 的 `MapLibreMap` 与 map-owned `WeatherRuntime`。
 
-## 冻结版本
+## 版本与首次 prebuild 边界
 
-- React Native `0.85.2`、React `19.2.5`、Expo `56.0.4`、TypeScript `5.9.3`；Hermes 与 New Architecture 由 Expo Android prebuild 保持开启。
-- `@maplibre/maplibre-react-native` `11.3.6`；Android AGP `8.5.0`、Gradle `8.14.3`、Kotlin `2.1.20`、NDK `27.1.12297006`、JDK 17、minSdk 24、compile/targetSdk 36 是手工 Android 工程的冻结目标。
+- package manager 为 npm（`packageManager: npm@10.9.4`），锁文件为 `package-lock.json`；当前环境的 `npm ci --dry-run --ignore-scripts` 无须 `--legacy-peer-deps` 即可解析。
+- package 明确固定 React Native `0.85.2`、React `19.2.5`、Expo `56.0.4`、TypeScript `5.9.3`、MLRN `11.3.6`；`app.json` 明确请求 New Architecture。Hermes 的最终启用状态必须在首次 Android prebuild 后检查生成工程。
+- AGP `8.5.0`、Gradle `8.14.3`、Kotlin `2.1.20`、NDK `27.1.12297006`、JDK 17、minSdk 24、compile/targetSdk 36 是本 Test Host 的**人工验收配置目标**，不是尚未生成 Android 工程的已验证结果。首次 prebuild 后必须以实际 Gradle wrapper、AGP/Kotlin plugin、SDK/NDK 与 Hermes/New Architecture 配置为准核对。
 - MLRN 的 root Gradle extras 固定 `org.maplibre.reactnative.nativeVersion=13.4.1` 与 `nativeVariant=opengl`。
 
 ## Custom SDK 来源（手工执行）
@@ -16,7 +17,7 @@ Test Host 的 Expo plugin 会把 `org.maplibre.gl` 从 Maven Central 排除，
 cd /mnt/sda1/MapLibreParticleLab/platform/android
 ./gradlew :MapLibreAndroid:publishToMavenLocal
 cd /mnt/sda1/MapLibreParticleLab/integration/react-native/MapLibreParticleRNTestHost
-yarn install
+npm ci
 npx expo prebuild --platform android --clean
 npx expo run:android
 ```

粒子开发记录.md

@@ -504,3 +504,8 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 `
 - MLRN 11.3.6 的共享 ReactTagResolver 实例由 `MLRNPackage` 私有持有；Test Host 改用 RN/Fabric 的公开 UIManager view resolver，即时收窄到 MLRNMapView 并读取其公开 MapLibreMap，不复制私有 mViews 或建立 current-map registry。
 - MapLibreMap 新增 map-owned WeatherRuntime attach/detach seam；style replacement、view detach 与 React unmount dispose 旧 facade。Android custom SDK 必须先手工发布 Maven Local，Host 配置会排除 Maven Central 中 org.maplibre.gl fallback。
 - 非 Android 验证：冻结 package-lock/config、Node config plugin 语法、禁止 Binary Field/global map/private registry 搜索与 throttle 下 `tsc --noEmit` 均通过；Android Gradle/设备/Jest 未执行。
+
+# 2026-09-07 — STEP-060A RN Test Host 编译前修正
+
+- 按 RN 0.85.2 当前 Codegen 模板为 TurboModule 的 20 个必选 Kotlin Spec 方法补齐 `override`，消除首次 Android 编译的确定 blocker。
+- Test Host package manager 统一为 npm/package-lock；实际 `npm ci --ignore-scripts` 不需 legacy peer deps。文档将 Android toolchain 数值改为首次 prebuild 前的验收目标，待生成工程实测。