STEP-052 正式数据源接入下一阶段调查 — Codex 完成报告

基线

Starting HEAD：e4ab1b9d421a4559fa3627df07ee91dcd9b680e4
branch：particle/main
origin/particle/main 起点：e4ab1b9d421a4559fa3627df07ee91dcd9b680e4
调查性质：docs-only、代码只读。

调查范围

实际检查了：

PARTICLE_BASELINE.md、docs/00_项目规范/
include/mbgl/particle/field/field_data_adapter.hpp
src/mbgl/particle/field/field_data_adapter.cpp
include/mbgl/particle/field/local_particle_field_feed.hpp
src/mbgl/particle/field/local_particle_field_feed.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
platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt
platform/android/MapLibreAndroid/src/cpp/asset_manager_file_source.cpp
platform/android/MapLibreAndroid/src/cpp/http_file_source.cpp
include/mbgl/storage/file_source.hpp
include/mbgl/storage/resource.hpp
include/mbgl/storage/response.hpp
include/mbgl/storage/database_file_source.hpp
src/mbgl/storage/file_source_manager.cpp
include/mbgl/util/lru_cache.hpp
particle-production/*、particle-fixtures/*、test/style/source.test.cpp

调查结论摘要

STEP-051 已建立 metadata + binary → Descriptor → Adapter → Snapshot → RasterArraySource → Timeline/Runtime 的 local production-like 路径，但 payload 仍是既有 canonical fixture binary，Source 仍直接编排资源请求和 candidates。当前没有 Particle Weather Service、provider contract、forecast manifest、feed coordinator、专用 retry/stale policy 或 Particle transport cache。

MapLibre 通用 FileSource/HTTP/ambient cache 可以复用为底层资源设施，但不能视为 Weather Service 已接入。Timeline cache、Runtime candidate cache、FileSource/Database cache 和 GPU T0/T1 slots 是不同层次，当前不能合并。

Recommended Next Implementation

STEP-053 Provider-neutral Field Feed / Manifest 与 Arrival Coordinator。

先以 Local/File/Mock transport 冻结 manifest、ordered arrival、metadata/payload pairing、错误分类、last-valid hold 和 initial/subsequent submit；不需要真实 network、服务器或 provider。完成 Linux/Core/OpenGL 验证后，如确需 Android 观测，再合并一次 build/install。

建议顺序：STEP-053 feed/manifest → STEP-054 HTTP Transport 与 Weather Service Adapter → STEP-055 Field Cache、Retry、Stale 与 Preload Hardening。

架构判断

不需要推翻 STEP-049/051 contract。
不建议下一步直接接 Weather Service；中间缺少 feed lifecycle、manifest、错误/重试/stale 语义和 provider-neutral transport boundary。
STEP-053 不应修改 Timeline state machine、Runtime Field Window、Renderer、WeatherColorLayer 或 Android Timeline ownership。
Validation UI MIX 滞后继续为 NON-BLOCKING observability；Rotation/Viewport 继续为独立技术债。

输出与 Git

调查报告：docs/20_调查/STEP-052_正式数据源接入下一阶段调查报告_v1.md
完成报告：本文件
是否修改功能代码：否。
是否执行 Android Gradle/APK/ADB：否。
是否执行 Jest：否。
git diff --check：PASS。
commit hash：979a1deeb4e6abe24c910c9f17248fd5c6c0aff8。
commit message：docs: investigate next production field source stage
push result：SUCCESS，已推送至 origin/particle/main。
remote branch：origin/particle/main
Final HEAD（调查文档提交）：979a1deeb4e6abe24c910c9f17248fd5c6c0aff8。
无关 untracked 文件：保持未修改、未 stage、未提交。

阻塞项：无调查阻塞；STEP-053 实现前需冻结 manifest/arrival API 与错误生命周期，避免把 Source 扩展成 Weather Service 或 cache orchestrator。

4.1 KiB Raw Permalink Blame History Unescape Escape