docs: record STEP-053 host validation handoff
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled

This commit is contained in:
OpenAI Codex
2026-09-04 19:10:21 +08:00
parent 4b453a109b
commit c188d6b590

View File

@@ -0,0 +1,57 @@
# STEP-053 Android Validation Host 接线补充 Codex 完成报告
## 基线与问题确认
- Starting HEAD:`b31f80c72d46a160f576b312f5d9aeebfa225a5e`
- 分支:`particle/main`
- 当前状态:`IMPLEMENTED / WAITING_ANDROID_VALIDATION`
- 本任务只补充 Android Validation Host 的可见性与低频观测,不重新实现 STEP-053 Core。
STEP-053 的 `RasterArraySource::submitHostField()`、Android `MapLibreMap.submitRasterArraySourceHostField()`、JNI forwarder 和三个隐藏 Validation controls 已在起点存在。MORE 菜单却把主入口显示为 `HOST FIELD SUBMIT`、不紧邻 `PRODUCTION FEED`,并且 Kotlin 在读取 local canonical dataset 后没有独立 dataset-load 日志。因此用户当前只能确认 STEP-051 `PRODUCTION FEED`,难以明确选择并观察 STEP-053 Host submission 路径。
## 实际修改
- `ParticleCoreLayerValidationActivity.kt`
- MORE 相关顺序调整为 `PRODUCTION FEED → HOST FIELD → INVALID PROD → HOST DUPLICATE → HOST INVALID`;STEP-051 的 `PRODUCTION FEED` 与 `INVALID PROD` 行为保持不变。
- 主入口名称改为 `HOST FIELD`;duplicate/invalid 名称明确为 `HOST DUPLICATE`、`HOST INVALID`。
- 每次读取 T0~T3 resource 后输出低频 `HOST_FIELD_DATASET_LOAD`,含 metadata resource、payload resource 与 payloadBytes。既有 Native `HOST_FIELD_SNAPSHOT_READY`、`HOST_FIELD_INITIAL_WINDOW_READY`、`HOST_FIELD_NEXT_SUBMIT` 继续提供 fieldId、generation、validTime 与 result。
- `docs/50_Step记录/STEP-053_Windy-style_Canonical_Field与Host_MapLibre_Submission_Contract_v1.md`
- `粒子开发记录.md`
实际调用路径未变:
`HOST FIELD → host-field-submission raster-array source → Kotlin local metadata + binary bytes → MapLibreMap.submitRasterArraySourceHostField() → NativeMapView JNI → RasterArraySource::submitHostField() → ParticleFieldDataAdapter → ParticleFieldSnapshot → existing Timeline / Runtime Field Window / Renderer`。
没有新增 JNI forwarding,也没有修改 Core、Adapter、Timeline、Playback、Runtime Field Window、Renderer、GPU simulation、Trail、WeatherColorLayer、network 或 provider 逻辑。
`HOST DUPLICATE` 重交当前 Host dataset 的 T3,走同一 submit API,预期 `DUPLICATE_NOOP`。`HOST INVALID` 在有效 Host window 存在时提交既有 `field-invalid.json` 和 bytes,走同一 API 的 Adapter reject/fail-closed 分支,不通过 style reload 冒充 invalid Host submission。
## Linux 与静态验证
- `cmake --build build-linux-opengl --target mbgl-test-runner mbgl-render mbgl-render-test-runner -j3`:PASS(无 C++ 变更,targets 已最新)。
- `./build-linux-opengl/mbgl-test-runner --gtest_filter='Source.*:Layer.RasterParticleCountProperties:Layer.RasterParticleVisualProperties'`:PASS,46/46。
- Host API/JNI declaration、registration、Activity action/resource ID 与两个 Host submit 调用静态检查:PASS。
- `git diff --check`:PASS。
- Android Gradle、APK build/install、ADB、App 启动和设备测试:未执行。
- Jest:未新增、未修改、未执行。
## 用户 Android 验收
用户在 Windows 11 构建并安装一次新 APK 后:
1. 打开 `Particle Core Layer Validation → MORE → HOST FIELD`。
2. 确认 `HOST_FIELD_DATASET_LOAD`、`HOST_FIELD_SUBMIT_REQUEST`、`HOST_FIELD_SNAPSHOT_READY`、`HOST_FIELD_INITIAL_WINDOW_READY`、`HOST_FIELD_NEXT_SUBMIT` 及 `ParticleTimeline: event=READY`。
3. 执行 `TIME → PLAY / RESTART`,验证 MIX、至少两次 boundary、`OLD_T1 → NEW_T0` reuse、only NEW_T1 upload、`simulationRebuild=false` 和 `trailCleared=false`。
4. 依次执行 `HOST DUPLICATE`、`HOST INVALID`,确认 NOOP 以及 Adapter reject/fail-closed、last valid Field/Renderer continuity、无黑屏、无 crash。
如采集日志,设备命令必须显式指定:`adb -s 192.168.1.146 logcat`。
## Git 与范围保护
- 功能与 Step 文档 commit:`4b453a109b6c861996b9970b03f6582a4c083b0e`
- commit message:`fix: expose STEP-053 host field validation path`
- 本报告提交及 push result 在 Git 收尾后记录于交付结果;remote branch:`origin/particle/main`。
- Final HEAD(功能与 Step 文档提交):`4b453a109b6c861996b9970b03f6582a4c083b0e`
- 无关 untracked 文件未修改、未 stage、未提交;包括 `STEP-046-e48fa087-review.diff` 与既有任务文档。
阻塞项:无 Linux/代码阻塞。STEP-053 仍须用户完成 Android 综合验收,不能写为 `CLOSED / PASS`。