docs: investigate next production field source stage

docs/20_调查/STEP-052_正式数据源接入下一阶段调查报告_v1.md

@@ -0,0 +1,225 @@
+# STEP-052 正式数据源接入下一阶段调查报告
+
+## 1. Git / 调查基线
+
+- 仓库：`MapLibreParticleLab`
+- 分支：`particle/main`
+- Starting HEAD：`e4ab1b9d421a4559fa3627df07ee91dcd9b680e4`
+- `origin/particle/main`：`e4ab1b9d421a4559fa3627df07ee91dcd9b680e4`
+- STEP-049：`CLOSED / PASS`
+- STEP-051：`CLOSED / PASS`
+- 调查性质：代码与既有文档只读；本任务不修改功能代码。
+
+## 2. 结论摘要
+
+STEP-051 已把一条真实可验证的 local production-like 链路接到 Core：
+
+`asset metadata + binary payload → LocalParticleFieldFeed → ParticleFieldDescriptor → ParticleFieldDataAdapter → ParticleFieldSnapshot → RasterArraySource → Core Timeline/Runtime Field Window → Renderer`。
+
+但它仍不是正式生产数据源。当前 local metadata 是新的 `maplibre-particle-field/v1`，payload 仍复用仓库已有的 canonical `particle-fixtures/*/field.f32`；`RasterArraySource` 直接拥有资源请求、candidate 收集、解析和 Timeline 初始化。仓库没有 Particle 专属的 feed coordinator、forecast catalog/manifest、异步 field-arrival API、retry/timeout/stale policy 或专用 transport cache。
+
+MapLibre 通用 `FileSource` 已提供 asset、filesystem、HTTP、offline database 等资源能力，但这不等于已有 Weather Service。当前最合理的下一实现阶段不是直接绑定天气供应商，而是先建立 provider-neutral feed/manifest 与低频 arrival coordinator，并用 Local/File/Mock transport 验证。之后再单独接入真实 HTTP/provider。
+
+## 3. STEP-051 后的真实数据链路
+
+### 3.1 Local feed 起点与终点
+
+入口和 contract：
+
+- `include/mbgl/particle/field/local_particle_field_feed.hpp`
+- `src/mbgl/particle/field/local_particle_field_feed.cpp`
+- metadata：`particle-production/field-00.json` 至 `field-03.json`
+- Android metadata：`platform/android/MapLibreAndroidTestApp/src/main/assets/integration/particle-production/`
+
+`LocalParticleFieldFeed::load(metadataText, payload)` 只处理 provider-neutral metadata 和内存 bytes，调用唯一正式 `ParticleFieldDataAdapter::decode()`。它不打开文件、不请求网络、不保存缓存，也不认识 Android、Timeline 或 Renderer。
+
+STEP-051 的 Android `ParticleCoreLayerValidationActivity.kt` 使用 `production-fields` style source，metadata 走 `asset://integration/particle-production/field-*.json`，binary 仍来自既有 `asset://integration/particle-fixtures/*/field.f32`。这已经脱离 fixture metadata/wrapper，但 payload 内容尚是验证用 canonical binary，而非远程生产数据。
+
+### 3.2 Provider-neutral 边界
+
+正式 neutral 边界位于：
+
+`ParticleFieldDescriptor + payload bytes → ParticleFieldDataAdapter → immutable ParticleFieldSnapshot`。
+
+`include/mbgl/particle/field/field_data_adapter.hpp` 的 Descriptor/Snapshot 不含 URL、token、HTTP client、provider name、Android object 或 GPU ownership。Descriptor/Snapshot 当前满足 WIND/GLOBAL 的 Runtime 最小输入；Ocean-only field、mask、更多物理变量尚未进入本阶段 contract。
+
+当前仍留在上游/Source 的内容是资源 URL、metadata 文本、文件请求、asset 读取和 candidate 编排。它们不应进入 `RasterParticleLayer` 或 `ParticleFieldSnapshot`。
+
+## 4. Adapter、Snapshot 与 Source 现状
+
+### 4.1 Adapter / Snapshot
+
+- `ParticleFieldDataAdapter::decode(const ParticleFieldDescriptor&, const std::vector<char>&, uint64_t)` 是唯一正式 decode API。
+- `ParticleFieldDescriptor` 已有 `fieldID`、`fieldType`、`displayDomain`、`generation`、`validTime`、dimensions、bounds、`noData`、`dataVersion`、`byteLength`、stride、layout、encoding、可选 checksum。
+- `ParticleFieldSnapshot` 自有 metadata、velocity 和 valid arrays；不拥有外部 bytes、FileSource、GPU texture 或 Timeline。
+- generation 必须由 producer/source 在 adapter 前提供，adapter 不把 0 改成 1；`fieldId` 与 `validTime` 由 producer metadata 提供。
+- `OfflineFixtureParticleAdapter` 仍存在，但只是 fixture-v1 validation wrapper，不是正式 production feed。
+
+### 4.2 RasterArraySource / submit
+
+实际文件：
+
+- `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`
+
+STEP-051 新增 `RasterArrayLocalFieldDescriptor`、local candidates 和 `submitInitialRuntimeFieldWindow(T0, T1)`。Source 对每个 metadata/field URL 使用 `FileSource::request(Resource::source(...))`，收齐后交给 `LocalParticleFieldFeed`，再由 bridge 建立 authoritative initial T0/T1。后续 Timeline 从 local candidates 构造 entries，使用 Snapshot 的 producer `validTime`。
+
+已有 `updateRuntimeFieldWindow(ParticleFieldSnapshot)` 是已有 T0/T1 之后的最短 submit 路径，继续实现 `OLD_T1 → NEW_T0`、only NEW_T1、Duplicate NOOP 和 fail-closed。它不是一个独立的外部 feed queue，也没有 feed-level arrival state、manifest index 或持久化生命周期。
+
+### 4.3 Timeline / Playback
+
+`RasterArrayTimelineRuntime` 位于 `raster_array_source.hpp/.cpp`，只消费 immutable Snapshot entries 和严格递增 timestamp，持有 Core-owned cursor/speed/paused/gap/invalid 状态；cache capacity 当前为 8。
+
+这属于 Timeline memory cache，不是 transport/download cache，也不是 persistent field cache。Timeline 已足够消费外部 Snapshot，下一阶段不应重写其 state machine 或 Playback ownership。缺口在 Source/feed producer 如何按时间目录、到达、失败和预取 Snapshot。
+
+## 5. 仓库已有 transport / network / cache 能力
+
+### 已有但属于 MapLibre 通用基础设施
+
+- `include/mbgl/storage/file_source.hpp`：异步 `request()`、`Resource`、cache-only 能力、pause/resume 和资源转发。
+- `include/mbgl/storage/resource.hpp`：`asset/file/network` 资源请求语义、loading method、storage policy、etag/expiry 等 HTTP/cache 元数据。
+- `src/mbgl/storage/file_source_manager.cpp`：按类型与配置复用 FileSource 实例。
+- `platform/android/MapLibreAndroid/src/cpp/asset_manager_file_source.cpp`：Android `asset://` 读取。
+- `platform/android/MapLibreAndroid/src/cpp/http_file_source.cpp` 与 `include/mbgl/storage/http_file_source.hpp`：Android 通用 HTTP FileSource。
+- `include/mbgl/storage/database_file_source.hpp`：MapLibre ambient cache/offline database 的 put、invalidate、clear、容量和 revalidation API。
+- `include/mbgl/util/lru_cache.hpp`：通用内存 LRU 工具。
+- `include/mbgl/storage/response.hpp`：通用成功、NotFound、Server、Connection、RateLimit、etag、expires、retryAfter 等 Response/Error 字段。
+
+这些能力可以作为 STEP-053 的底层 transport 适配点，但目前没有 Particle field 的 manifest、字段语义、时间序列目录、payload checksum policy、retry/stale policy 或 adapter 错误映射。
+
+### 当前不存在的 Particle 正式能力
+
+搜索当前 `src/`、`include/`、Android JNI/Host 和测试区域，没有发现：
+
+- Weather Service client、Open-Meteo/Windy/vendor client；
+- Particle provider abstraction、provider registry 或 provider-specific decoder；
+- GRIB/NetCDF/external weather decoder；
+- Particle remote manifest/forecast endpoint contract；
+- Particle 专用 download queue、transport coordinator、persistent field cache；
+- Particle retry、timeout、stale-data、gap inventory 或 availability state policy；
+- token/auth/config 与 Particle field service 的绑定。
+
+因此不能把 MapLibre 的通用 HTTP/FileSource 误认成 Weather Service 已接入。
+
+## 6. Cache、preload 与数据生命周期
+
+当前存在四种不同层次，不能合并：
+
+1. `RasterArrayTimelineRuntime` 的 entries/cache capacity 8：已经解码的 Snapshot memory cache，服务 Timeline cursor。
+2. `RasterArraySource` 的 local/runtime candidate vectors：Source-owned preload candidates，服务初始窗口和后续 boundary。
+3. MapLibre `FileSource`/`DatabaseFileSource` ambient/offline cache：通用资源缓存，按 Resource URL/HTTP metadata 工作，不理解 fieldId、validTime、generation 或 Snapshot。
+4. Renderer GPU slots：RasterParticleLayer/validation layer 的 T0/T1 texture 与 simulation state，不是下载缓存，不能由数据源层直接管理。
+
+STEP-051 当前是四个资源请求全部到达后构建 Timeline；没有独立的 manifest-first inventory、有限并发下载、field dedup、retry 或 stale policy。已有 MapLibre cache 可以降低资源获取成本，但不能替代 Particle feed lifecycle。
+
+建议下一阶段先定义低频 field arrival/availability 状态和 manifest 顺序，明确：manifest 可用但 payload 缺失、metadata reject、payload mismatch、gap、stale、retry exhausted 时如何保持 last valid Field。Persistent cache 不应在没有 feed key/manifest 生命周期之前先做；第一步只需要 memory/injected transport validation，是否接 DatabaseFileSource 应后置。
+
+## 7. Forecast manifest/catalog 最小模型
+
+不要把所有未来业务字段塞入 Descriptor。进入正式 feed 必要的最小分层如下。
+
+### 已属于 `ParticleFieldDescriptor/Snapshot`
+
+- field identity：`fieldID`
+- producer revision：`generation`
+- forecast `validTime`
+- `fieldType` / `displayDomain`
+- grid width/height、bounds
+- vector layout/encoding/noData
+- expected byte length、stride、data version、可选 payload checksum
+
+这些字段是解码、插值兼容性、fail-closed 和 Renderer canonical input 所必需的。
+
+### 应属于上游 manifest/catalog，而不是 Snapshot/Renderer
+
+- forecast `runTime`/cycle
+- `leadTime`（可由 runTime 与 validTime 推导，但目录可显式记录）
+- ordered snapshot list / window membership
+- grid identity、resolution、coverage version
+- metadata URL 与 payload URL/resource key
+- source revision、availability、retry hint、expiry/stale policy
+
+manifest 可以有 source/provider identity，但它不应穿过 Adapter 进入 Snapshot，也不应被 Renderer 或 Runtime Window 解释为业务 provider。
+
+### 目前不应新增
+
+不要仅为“以后可能需要”加入 level、ensemble、unit system、auth token、HTTP headers、vendor schema、download path、cache database key 或 ocean mask 字段。若未来 Wave/Tide/Current 需要这些语义，应单独设计并遵守 Ocean-only 与 mask 边界。
+
+## 8. Weather Service 直接接入判断
+
+当前不具备安全的直接接入条件。虽然 Android 有 `HTTPFileSource`，MapLibre 有通用 Response/cache/error，当前 Particle 仍缺少：
+
+- provider-specific metadata/payload decoder 与其到 neutral Descriptor 的映射；
+- forecast run/lead/valid-time inventory；
+- provider-independent feed API 和 arrival ordering；
+- retry/timeout/stale/gap policy；
+- service auth/config ownership；
+- 可在不改 Renderer/Timeline 的情况下将网络数据稳定送入 Snapshot submit。
+
+直接接入会把 HTTP/provider 选择、目录和失败策略塞进 `RasterArraySource` 或 Android Host，容易越过冻结边界。结论：先建立 provider-neutral feed/manifest coordinator，再以独立阶段接 Weather Service；真实 network 不是 STEP-052 后的立即实现目标。
+
+## 9. 候选下一阶段
+
+| 候选 | 目标 | 新架构/模块 | Network/Provider | Timeline/Renderer | Android | 主要风险 |
+|---|---|---|---|---|---|---|
+| A. 直接 Weather Service | 立即接真实远程天气接口 | 新增 client、decoder、auth、生命周期 | 需要 | 不应修改，但 Source 会膨胀 | 需要一次高成本 build/test | 缺少 manifest、retry、provider 边界，容易把业务逻辑塞入 Core/Host |
+| B. Provider-neutral Feed/Manifest Coordinator | 先定义 manifest、低频 arrival、Snapshot submit 和错误生命周期，用 Local/File/Mock transport 验证 | 一个薄跨平台 feed/coordinator；不建立 Provider Framework | 不需要；可注入 Local/Mock transport | 不改 state machine；不改 Renderer | 若只做 Core 可不需要；若补入口则合并一次 | arrival ordering、initial T0/T1 和 last-valid 语义需冻结 |
+| C. Transport Cache/Preload | 先建立持久缓存、重试、过期和预取 | 新增 cache policy/lifecycle | 可不需要 | 不改 Renderer，但会依赖未定义 feed key | 建议需要 | 过早把 MapLibre ambient cache 当 Particle cache，生命周期和 key 尚未稳定 |
+| D. Provider Decoder | 先做 GRIB/NetCDF 或某一供应商 decoder | 明显 provider-specific 模块 | 通常需要 | 输出应是 neutral Snapshot | 视入口而定 | 当前无真实 provider contract，容易锁死错误 schema |
+
+候选 B 能以最小修改面冻结真正缺口，并兼容未来 Local/File、HTTP 和 provider decoder；C 应在 B 的 manifest/key/error contract 之后做，A/D 应后置。
+
+## 10. 唯一推荐的下一实现阶段
+
+### Recommended Next Implementation: STEP-053 Provider-neutral Field Feed / Manifest 与 Arrival Coordinator
+
+目标范围：
+
+1. 定义最小 provider-neutral field manifest/catalog 与 ordered snapshot arrival contract。
+2. 将 metadata/payload transport 与 `ParticleFieldDataAdapter`、`ParticleFieldSnapshot`、现有 initial T0/T1/update submit 接口连接起来。
+3. 以 injected Local/File/Mock transport 验证 initial T0/T1、subsequent T1、strict validTime ordering、duplicate、gap、invalid、retry exhausted 和 last-valid hold。
+4. 只做低频异步 callback/future 或等价 arrival API，不做 Android per-frame JNI，不拥有 Timeline cursor/speed/pause。
+5. 建立结构化 feed availability/error 分类，明确 metadata reject、payload mismatch、not-yet-available、gap 和 stale 的边界。
+6. 保持 provider/vendor identity、URL、auth、HTTP headers 和 cache policy 在上游 feed/transport 层，不进入 Snapshot、Runtime 或 Renderer。
+
+输入：manifest/catalog entry、metadata bytes、payload bytes，或注入的 transport response。
+
+输出：已通过正式 Adapter 的 `ParticleFieldSnapshot`/arrival result；初始窗口和后续窗口仍调用现有 Core submit/update 语义。
+
+允许修改：新增薄的 Core-neutral feed/coordinator、Source 的最小接线、定向 C++ tests、local/mock transport test seam 和必要日志/文档。若增加 Android validation 入口，应与同一阶段其他功能合并一次 build/install。
+
+禁止修改：Timeline state machine、Playback、Runtime Field Window 语义、RasterParticleLayer/GPU simulation/trail、WeatherColorLayer、Adapter 合法性、Provider Framework、Weather Service、HTTP client、vendor decoder、第二套 Snapshot/Timeline/Window。
+
+STEP-053 默认不需要真实 network、服务器、真实 provider 或 Android APK；先完成 Linux/Core/OpenGL 精确验证即可。只有要验证 Android Host 的低频 feed arrival/错误可观测性时才需要一次 Android build/install。
+
+## 11. 建议的后续 2～4 阶段顺序
+
+1. **STEP-053 Provider-neutral Field Feed / Manifest 与 Arrival Coordinator**：先冻结 manifest、arrival、错误和 last-valid 生命周期，使用 Local/File/Mock transport。
+2. **STEP-054 HTTP Transport 与 Weather Service Adapter**：在不改变 neutral Snapshot/Runtime/Renderer 的前提下，把真实 HTTP/provider decoder 置于 feed 上游；此阶段才处理 auth/config 和真实服务契约。
+3. **STEP-055 Field Cache、Retry、Stale 与 Preload Hardening**：基于已冻结的 manifest key、generation、validTime 和 error policy，决定 memory/cache/database 组合、重试和容量。
+
+这三个阶段足够表达当前真实缺口，不提前规划更多 provider 或 Ocean field 变体。
+
+## 12. 平台 / Core / Renderer 责任边界
+
+- Transport/platform：负责 FileSource/HTTP/asset 的资源获取、平台凭据配置和底层 request cancellation；不生成 Timeline 状态。
+- Feed/coordinator（建议跨平台 Core-owned seam）：负责 manifest 顺序、低频 arrival、metadata/payload 配对、调用正式 Adapter、错误分类和 submit 意图；不负责 GPU。
+- `ParticleFieldDataAdapter`：只做 descriptor/payload contract validation 与 canonical Snapshot construction。
+- `RasterArraySource`：保持 Source-owned authoritative T0/T1、Timeline 接线和已有 Window update；不变成 provider client。
+- Timeline/Playback：Core-owned，消费 Snapshot 时间和 low-frequency feed 结果；不请求网络。
+- Renderer：只消费规范化 Snapshot/Window，继续执行 GPU upload/reuse/simulation/trail；不包含 provider/network/vendor/cache policy。
+- Android/Kotlin：只提供低频用户意图和可选资源配置；不拥有 Timeline、Window、feed state 或 per-frame JNI。
+
+## 13. Android 成本、技术债与风险
+
+后续实现应遵守：先 Linux/Core/OpenGL precise build 与定向测试，再由用户在 Windows 11 对 `192.168.1.146` 用一次 APK 完成综合验证；若使用 ADB，必须显式 `adb -s 192.168.1.146 ...`。不为单个 MIX 文本问题单独触发 Android 周期。
+
+Validation UI 的 auto MIX 文本滞后、WAITING/INVALID 视觉提示不足继续是 `NON-BLOCKING observability`，不阻塞正式 feed 架构，不推荐作为 STEP-053 主任务。Rotation/Viewport 自动恢复继续保留技术债；STEP-053 若不触及 lifecycle/surface/source reload，不合并修复。
+
+主要风险是把 manifest/catalog 与 Descriptor 重复建模，或让 Source 直接拥有下载/重试/缓存策略。应优先薄化并用测试锁定：Snapshot immutable、validTime strict ordering、invalid/gap fail-closed、last valid Field、Window reuse、MIX property-only 和 Renderer 分离。
+
+## 14. 调查结论
+
+当前可以进入 STEP-053 实现 MD 编写，但不能跳过 provider-neutral feed/manifest 与 arrival 生命周期直接实现 Weather Service。STEP-051 production-like local feed 作为已验证过渡层保留；STEP-052 本身不修改代码、不引入网络、不新增缓存或 Provider。

docs/报告/STEP-052_正式数据源接入下一阶段调查_Codex完成报告_v1.md

@@ -0,0 +1,72 @@
+# 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：待提交后回填。
+- commit message：`docs: investigate next production field source stage`
+- push result：待执行。
+- remote branch：`origin/particle/main`
+- Final HEAD：待 push 后回填。
+- 无关 untracked 文件：保持未修改、未 stage、未提交。
+
+阻塞项：无调查阻塞；STEP-053 实现前需冻结 manifest/arrival API 与错误生命周期，避免把 Source 扩展成 Weather Service 或 cache orchestrator。