MapLibreParticleLab/docs/50_Step记录/STEP-064_RN纯FieldRenderer接口V2_v1.md

STEP-064 RN 纯 Field Renderer 接口 V2

状态：冻结（13.4.1-particle.2 正式发布完成）

目标

将 @navsea/maplibre-particle-rn 升级为 13.4.1-particle.2 纯 Field Renderer 公共 API。React/宿主负责业务、WeatherV2、provider、网络、数据选择和文件管理；SDK 只向既有 Native ingress 提交 canonical Field 并控制图场/粒子渲染。

已完成

• 新增根入口 FieldRuntime，以薄映射保留既有 Native bridge ABI，未保留旧 API wrapper。
• 公共类型使用 FieldColorStop.value；保留无业务含义的 Runtime、Playback、FPS 与结果类型。
• 移除 package 内 src/weatherV2/ 与根导出；不再转导出 MLRN。
• 新增不含底图的 particleFieldIds 和 createParticleFieldStyleFragment()。
• TurboModuleRegistry.get() 使无 Native module 的 import 安全；实际调用时给出明确错误。
• Consumer Host 直接从官方 MLRN 导入 Map/Camera，仅从 NavSea 包导入 Field Renderer API；本地真实 fixture 仍由宿主提交 canonical metadata 与 file URI。
• release manifest 明确 RN .2 对应冻结 Native .1。

验证

• package TypeScript typecheck：通过。
• Consumer TypeScript typecheck：通过（使用临时类型解析配置，仅用于检查，不进入 Consumer 产品依赖）。
• npm pack：通过，.2 tarball 仅生成在 /tmp/step064-pack/，未触碰仓库既有未跟踪 .1 tarball。
• tarball 内容审计：通过；不含 src/weatherV2/、WeatherV2 HTTP/decoder/loader、Test Host、node_modules 或构建缓存。
• 根导出与业务语义审计、git diff --check：通过；旧名称仅存在于内部 Native ABI/codegen 接缝，未由根入口公开。
• Android Gradle、AAR、APK、ADB、Jest：按边界未执行。
• RN 0.85.2 Codegen parser 已核对支持 TurboModuleRegistry.get() 与 getEnforcing()；当前 import-safe get() 方案保留。
• 收尾复审修正：.2 Consumer validation 明确为 pending，.1 PASS 仅作为 previous baseline；FieldColorStop 文档示例改为满足至少 2 个 stop 的既有 Native 契约。

待办与边界

• 待 Consumer 安装最终 .2 tarball 并实际运行验证；此项完成前不得标记 RELEASED 或 CLOSED/PASS。
• 未修改 Native/Core/JNI/shader/Android AAR，Native artifact 继续 13.4.1-particle.1。
• 未进入 NavSea。

2026-09-10 Consumer 正式验证

• Win11 固定 Consumer 安装 13.4.1-particle.2 tgz，MLRN 唯一解析为 11.3.6，TypeScript 通过。
• 首轮实测暴露 RN helper 无效属性 raster-particle-opacity，导致 rn-weather-particles 缺失；仅在 RN helper 改为 Native .1 已验证的 raster-particle-active，未改 Native。
• 修正后 FieldRuntime attached; style ready；T0–T3 依次返回 Pending / InitialWindowReady / NextSnapshot / NextSnapshot，Runtime READY。
• Field OFF + Particle ON 与 Field ON + Particle OFF 均实测通过，并恢复两者 ON。
• hard gate 未见 WEATHER_OBJECTS_NOT_READY、FATAL、SIGSEGV、JNI DETECTED ERROR、NoSuchMethodError、UnsatisfiedLinkError 或非法 layer property。

正式发布关闭

• Release source commit：e43b58707cfd0f87965424477ed3f95625b3f724。
• Release tag：maplibre-particle/rn/13.4.1-particle.2，已 push。
• 正式 HTTPS：https://pbf.jpcn.ccwu.cc/npm/navsea-maplibre-particle-rn-13.4.1-particle.2.tgz。
• 正式 tgz：10,660 bytes；SHA256 ace9e0401824839d18a93cc4201c1f5d4cccbff0636570cfde82fd80b60779b5；公网 HTTP 200 且下载字节完全一致。
• Win11 Consumer 已从正式 HTTPS URL 安装 .2，TypeScript 通过，MLRN 11.3.6 单份 dedupe。
• STEP-064 正式冻结；后续修改必须升 13.4.1-particle.3，不得覆盖 .2 tgz 或移动 release tag。