From 0e117a9255f708f3f74a39d022ff740976a28ba4 Mon Sep 17 00:00:00 2001 From: OpenAI Codex Date: Mon, 7 Sep 2026 14:10:33 +0800 Subject: [PATCH] docs: record STEP-057D WeatherRuntime API freeze --- ...D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md | 31 ++++++++++++ ...me接口收尾与RN桥接前冻结_Codex完成报告_v1.md | 50 +++++++++++++++++++ 粒子开发记录.md | 6 +++ 3 files changed, 87 insertions(+) create mode 100644 docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md create mode 100644 docs/报告/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_Codex完成报告_v1.md diff --git a/docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md b/docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md new file mode 100644 index 000000000..45a400987 --- /dev/null +++ b/docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md @@ -0,0 +1,31 @@ +# STEP-057D WeatherRuntime 接口收尾与 RN 桥接前冻结 + +状态：`IMPLEMENTED / READY_ANDROID_COMPILE_CHECK` + +基线：`01295df4b814562f569375e7e7cf1f48ce35388f`，分支 `particle/main`。 + +## 目标与范围 + +本 Step 只收紧 Android Host `WeatherRuntime` 公共接口，为后续 RN 薄桥接冻结边界；不实现 RN/TurboModule/JSI，不修改 provider、Timeline、Runtime Field Window、canonical field、shader、UBO 或 renderer 架构。 + +## 已完成 + +- 新增 `WeatherRuntime.setParticleColor(r,g,b,a)` 与 `setTrailColor(r,g,b,a)`，分别通过 JNI 进入 Core 的独立 `RasterParticleLayer::setParticleColor` / `setTrailColor`。两者不提交 field、不影响 WeatherColor ramp、不重置 Timeline 或粒子模拟。 +- 保留 `setParticleColors(...)` 作为兼容 helper，继续使用原子成对底层提交；新 Host/RN 契约使用两个独立 typed 方法。Core 既有 `particleColor=(0.08,0.55,1,1)`、`trailColor=(1,1,1,1)` 默认值不在 facade 重建或猜测。 +- REAL WEATHER 数据提交改用 `WeatherRuntime.FieldSubmitResult` 与 `accepted()`/enum 名称，不再用 `getCode()` 或整数比较组织正常 Host 路径。 +- REAL WEATHER playback/visual 正常路径遇到不支持命令或 property 时不再回退到 `MapLibreMap` 低层调用。旧 fixture、HOST、diagnostic time-mix/field-window 入口保留为 legacy/diagnostic 路径。 +- 增加独立颜色 API 的现有 JUnit/Mockito 定向源码覆盖，包含独立调用、参数隔离和 native rejection fail-closed。 + +## 低层入口审计 + +- A 类（REAL WEATHER）：field submit、play/pause/speed、已支持粒子视觉属性均经 `WeatherRuntime`；独立 particle/trail color 也经 `WeatherRuntime`。 +- B 类（legacy/diagnostic）：fixture/HOST INVALID/DUPLICATE、ADVANCE WINDOW、time-mix 及旧诊断 property 仍可直接使用 `MapLibreMap`，仅供既有验证工具，不构成未来 RN contract。 + +## 验证与未执行 + +- 已执行 `git diff --check` 与源码静态审计（typed API、`getCode()` 使用、REAL WEATHER fallback 边界）。 +- 未执行 Android Gradle/APK、ADB、设备/虚拟机测试或 Jest；Android compile check 留待后续统一授权。 + +## 剩余风险与下一步 + +JNI/Android Java 编译及 Mockito 配置仍需 Android compile check；设备上的独立颜色视觉效果和 style reload/资源生命周期需后续人工验收。代码边界已冻结，可进入 RN 薄桥接前独立审计。 diff --git a/docs/报告/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_Codex完成报告_v1.md b/docs/报告/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_Codex完成报告_v1.md new file mode 100644 index 000000000..408a81606 --- /dev/null +++ b/docs/报告/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_Codex完成报告_v1.md @@ -0,0 +1,50 @@ +# STEP-057D WeatherRuntime 接口收尾与 RN 桥接前冻结 — Codex 完成报告 + +状态：`IMPLEMENTED / READY_ANDROID_COMPILE_CHECK` + +## 实际完成内容 + +本轮基于 `01295df4b814562f569375e7e7cf1f48ce35388f`，完成 Host facade 收尾，不进入 STEP-058，不实现 RN/JSI/TurboModule。 + +- 新增 `WeatherRuntime.setParticleColor(float,float,float,float)` 与 `setTrailColor(float,float,float,float)`，经独立 JNI setter 进入 Core。两者互不提交另一颜色，不影响 WeatherColor ramp、field、Timeline、Runtime Field Window 或粒子模拟。 +- 保留 `setParticleColors(...)` 兼容 helper，继续使用原子成对底层 setter；不在 facade 猜测默认值。Core 默认值仍由 `RasterParticleLayer::Impl` 所有。 +- REAL WEATHER submit 改用 `FieldSubmitResult` 与 `accepted()`/enum 日志，不再使用 `getCode()` 或整数结果做正常 Host 业务判断。 +- REAL WEATHER 的 playback 和 typed visual 属性不再回退到 `MapLibreMap` 低层接口；旧 fixture、HOST、time-mix、field-window 与 diagnostics 入口保留并明确属于 legacy/diagnostic。 +- 增加独立颜色 API、隔离性及 native rejection fail-closed 的既有 JUnit/Mockito 测试源码。 + +## 修改文件 + +- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java` +- `platform/android/MapLibreAndroid/src/main/java/org/libre/android/maps/MapLibreMap.java` +- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java` +- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java` +- `platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp` +- `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp` +- `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt` +- `platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java` +- `docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md` +- `粒子开发记录.md` + +## API 与旁路边界 + +正式 Host/RN API 使用独立 `setParticleColor`/`setTrailColor`、typed field result、typed playback 与 typed visual 方法。A 类 REAL WEATHER 正常控制均经 `WeatherRuntime`。B 类 legacy/diagnostic 仍可直接调用 `MapLibreMap`，仅服务 fixture、HOST INVALID/DUPLICATE、ADVANCE WINDOW、time-mix 和旧诊断，不构成 RN contract。 + +## 验证 + +- `git diff --check`：PASS（功能提交前及文档收尾前均执行）。 +- `rg` 源码审计：确认 REAL WEATHER 不再使用 `submitWindField(...).getCode()`，且 REAL WEATHER 不走 timeline/property 低层 fallback。 +- 未执行 Android Gradle、APK build、ADB、设备/虚拟机测试或 Jest。 +- 未执行 noisy compile/test；Android compile check 留待后续统一授权。 + +## 已知剩余风险 + +Android Java/JNI 编译、Mockito final-class 配置和设备上的独立颜色视觉效果尚未运行验证；需后续 Android compile check 与人工验收。未改变 Core/render 生命周期，未引入 RN bridge。 + +## Git + +- 功能 commit：`544e4aee3`（完整 SHA 在下方最终交付信息中列出） +- commit message：`fix: finalize WeatherRuntime host API boundary` +- 文档提交：待文档收尾提交后记录 +- Push：待文档收尾提交后记录 +- Remote branch：`origin/particle/main` +- Final HEAD：待文档收尾提交后记录 diff --git a/粒子开发记录.md b/粒子开发记录.md index 7b35fb72a..1145c606a 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -475,3 +475,9 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 ` - Android x86_64 CMake 编译发现 `jni::Array` 误用底层 5 参数 `jni::GetArrayRegion`，导致 `native_map_view.cpp` 四处编译失败。 - 已改为 `jni::Array::GetRegion()`，只修正 particle/trail 与 WeatherColor stops 的数组读取，不改变业务语义或渲染生命周期。 - 功能提交：`4f76245533817751f4e24f76e47e856c35fb23c7`；Android Gradle/设备验证由用户重新执行。 + +## 2026-09-07 — STEP-057D WeatherRuntime 接口收尾与 RN 桥接前冻结 + +- `WeatherRuntime` 新增独立 typed `setParticleColor()` / `setTrailColor()`，分别委托 Core 独立颜色 setter；保留原 `setParticleColors()` 作为兼容成对提交 helper，不猜测或复制 Core 默认色值。 +- REAL WEATHER submit 使用 `FieldSubmitResult`/`accepted()` 与 enum 日志，不再依赖 `getCode()`；REAL WEATHER 的 playback/visual 不再回退到 MapLibreMap 低层入口，旧 fixture/diagnostic 路径继续保留。 +- 本轮仅执行 `git diff --check` 与源码静态审计；未执行 Android Gradle、APK、ADB、设备测试或 Jest，状态为 `IMPLEMENTED / READY_ANDROID_COMPILE_CHECK`。