STEP-050 正式数据链路下一阶段调查 — Codex 完成报告

基线

Starting HEAD：1572b6c3b1bcc2ab0007181bad0609e7d0134575
origin/particle/main 起始 HEAD：1572b6c3b1bcc2ab0007181bad0609e7d0134575
当前分支：particle/main
调查性质：代码只读、文档新增

调查结论

STEP-049 的 Adapter 已停在“canonical descriptor + bytes → immutable Snapshot”层。当前真实业务入口仍是 RasterArraySource 的 fixture style schema 和 OfflineFixtureParticleAdapter；没有 Particle Weather Service、provider abstraction、生产网络下载、GRIB/NetCDF decoder、production cache 或外部生产 field source。

推荐下一实现阶段：STEP-051 Local Production-like Field Feed 与 Core Snapshot Submit Bridge。先以离线 local/asset binary 验证正式 neutral producer → Adapter → Snapshot → Timeline/Runtime 链路，再决定是否进入真实 provider/network 阶段。

实际检查的核心文件

include/mbgl/particle/field/field_data_adapter.hpp
src/mbgl/particle/field/field_data_adapter.cpp
src/mbgl/particle/field/offline_fixture_particle_adapter.hpp/.cpp
include/mbgl/style/sources/raster_array_source.hpp
src/mbgl/style/sources/raster_array_source.cpp
src/mbgl/style/sources/raster_array_source_impl.hpp
src/mbgl/style/conversion/source.cpp
src/mbgl/renderer/layers/render_particle_validation_layer.cpp
src/mbgl/renderer/layers/render_raster_particle_layer.hpp
test/style/source.test.cpp
platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt
particle-fixtures/README.md 与 particle-fixtures/*
MapLibre 通用 FileSource/Resource/offline storage 与 src/mbgl/util/io.cpp

设计判断

不需要新 Provider Framework 或复杂新架构；STEP-051 可新增一个小型 local feed/submit 模块。
不需要 network；不需要 vendor-specific code。
原则上不修改 Timeline state machine、Runtime Field Window 或 Renderer；只在 Source/producer 边界做最小接线。
Snapshot ownership 已足够承载当前生产-like 输入；generation 由 Core Source/Runtime 分配，identity/validTime 由 producer descriptor 提供。
当前 Timeline 已能消费外部 Snapshot，但 Source builder、style schema 和 candidate preload 仍 fixture-specific；Timeline timestamp 还使用固定逻辑时间。

候选与推荐

已比较四个候选：Core Snapshot Feed API、Local Binary/File-backed Production-like Source、Weather Service/Network Provider 骨架、Timeline/Preload 通用化。推荐合并前两者形成 STEP-051；不推荐现在引入网络 provider，也不建议在缺少真实 producer 时单独抽象 Timeline/cache。

Rotation/Viewport 与 MIX

当前 Android Activity 有标准 MapView lifecycle 转发和控件状态保存，但没有独立 Particle viewport recovery state machine；历史 Rotation/Viewport 议题不应并入不触及 Android host 的 STEP-051，也不应单独触发 APK。MIX UI 百分比文本滞后继续记录为 NON-BLOCKING observability；只有 STEP-051 本来修改 UI 时才顺带处理。

输出与验证

调查报告：docs/20_调查/STEP-050_正式数据链路下一阶段调查报告_v1.md
完成报告：本文件
未修改功能代码、Renderer、Android、Tests、Gradle、CMake、iOS 或既有 Step 文档。
未执行 Android Gradle/APK/ADB/App/实机测试。
未执行 Jest。
git diff --check：PASS。
commit hash：0dacb72b5725e0f2e539630f1269e7fde62a1ab1
commit message：docs: investigate production particle data pipeline
push result：SUCCESS
remote branch：origin/particle/main
Final HEAD（调查文档提交推送时）：0dacb72b5725e0f2e539630f1269e7fde62a1ab1
阻塞项：无调查阻塞；STEP-051 需在实现前冻结 local feed metadata/timestamp/generation ownership。

3.9 KiB Raw Permalink Blame History Unescape Escape