STEP-113 — NavSea FZG1 PBF/Layer 等价测试 App 与逐帧 Fast Gate 诊断

授权与范围

用户明确授权：在 Particle Android 测试 App 接入与 NavSea 相同的正式 PBF 与图层分段，找到每帧阻止 Particle Fast Path 的所有 Gate；RDC 可以编译 APK、使用已连接 FZG1-2 的 ADB 测试。使用 Codex GPT-6.1-Sol High 实施源码，RDC 独立编译/设备验收。不得把调研中的假设冒充真机结果。

项目与协作

Particle repo: /Users/tei/dev/MapLibreParticleLab, particle/main; NavSea 只读: /Users/tei/dev/NavSea-Build。Integration 只读: /Users/tei/dev/navsea-particle-integration；已 fetch 核实 Integration main 80667d6c。
先完整阅读 Particle AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范/、docs/00_项目总则/README.md 和其四份有效总则，以及 STEP-112 源码调查、上一步报告。
Native/Shared Core 仅增加诊断，Android Test App 增加测试 UI/场景。禁止改变现有 Fast Path Gate 准入逻辑、Placement/Fade、安全回退、公开 RN API、NavSea 源码、Cache 等价安全判定。Common Core 诊断数据不能含 Android 专有语义。
仓库中两个已有未跟踪 STEP-110/111 任务 MD 必须原样保留，不得 add/reset/clean；禁止新分支或工作树。
Codex 不编译、不执行 Android Gradle/ADB、不执行 Jest（用户没有要求），不做正式发行、Git commit/push；由 RDC 负责这些步骤。

目标 A：准确复制生产 Style、场景与真实 R/C 分层

现有测试 App 已支持 NAVSEA PBF，使用生产 URL https://pbf.jpcn.ccwu.cc/style/style.navsea-delivery-full-semantic-extentfix.json，但仅有 63 个基础图层；它与 NavSea FZG1 实测 113 个最终渲染图层尚未等价。NavSea 源码 src/config/builtinRuntimeUrlConfig.ts 是 URL 事实源；src/map/particle/RenderSegmentHost.tsx 是宿主分段控制。STEP-112 用户 FZG1 的 RCRR_PREFIX 诊断：R0 [0,13), C1 [13,33), R2 [33,107), R3 [107,113)。注意 NavSea 当前源码 R/C 初始 plan 可能与运行诊断不一致，必须记录版本/选择器，不得当作同一事实。

基于现有 platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt/fixture 增加独立 STEP-113 FZG1-PBF Gate 测试场景。真正加载生产 Style、Sprite、Glyph、VectorTile URI；原有场景全部保留，且不得改为假矢量地图。
与 NavSea 对齐层顺序、类型、Source ID 和显隐规则：优先从 NavSea 实际源码、已有 FZG1 快照/资料得到完整清单，至少能证明原始63层一致；对于 RN 额外动态层，若没有真实 Source/图层定义，不得将同名假图层宣称为“同等画面”，应分别标注原样/结构仿真/缺失。严格实现全113层和所述四分段如能力允许；若其余层无法准确复制，仍完成可运行的 真实 PBF 63 层模式 + 明示的部分等价模式，并记录阻塞原因，不要卡死整个任务。
每个场景导出/Logcat：实际 styleLayers (index/id/type/source/visibility)、总层数、每段 [begin,end)/类型与层名、分段配置接受/拒绝原因、当前 Style URL/版本/fingerprint、预报时间和 Particle Tick 状态；严格用实际 Layer ID 定义分段，不假定第13/33/107的 ID 永远不变。
支持至少静态30fps粒子且 camera/forecast fixed、粒子关闭、Source 变化、场景对照。静态场景不可每500ms自行修改 Symbol；原 STEP-102 的动态 fixture 保持原样。

目标 B：逐帧 24 Gate 完整诊断

阅读 src/mln/renderer/particle_fast_path.hpp 的 ParticleFastPathGateInput (24 条固定顺序) 与 src/mln/renderer/renderer_impl.cpp::tryRenderParticleFastFrame；每次真实 Fast 尝试，记录统一 frame/sequence、所有 24 条 Gate 的 PASS/FAIL 或明确不可观测的 UNKNOWN，并保存首个实际短路 Gate 与同帧失败全集。不得通过二次调用有副作用的函数来获取字段；优先使用现成的已计算 ParticleFastPathGateInput 在单次调用无副作用完成独立掩码计算，并确保首错与 evaluateParticleFastPath 决定一致。
对于 CacheInvalid 等早期阻断，也能看出后面的 unsupported-continuous-layer / unsupported-scene 是否同帧成立。记录 per-R cache state/build/reuse/invalidation/fallback, Placement changed/transition/fade、原因分类、FullFrame count。不要把 Full 绘制导致的 post frame Placement 数据冒充 pre-fast 原子时刻；必要时为 pre/post 两种 phase 分离记录。
诊断必须为有界环形缓冲/低开销低频导出（例如保留最近120或256帧，另聚合失败计数），不得每 33ms 从 JS/Android UI Logcat 输出大 JSON。沿用已存在的 Android getRenderSegmentDiagnostics Native JSON 出口，新增 fastGateTrace 可选诊断字段，避免新 RN API/ABI；必要时增加手动/低频截图/Logcat 导出入口。控制每分钟几条摘要而非每帧 log。
同一渲染生命周期 reset 要有清晰逻辑；不引入 data race，遵循现有 shared snapshot/atomic/锁语义，避免在 map UI 线程操作 Native mutable renderer state。

目标 C：可验收性

Test App UI 能切换 STEP-113 场景、查看 Gate 首错/失败排名与各段状态；可用 Logcat 定向标签稳定抽取机器可读 JSON (包含 schema/version, style parity summary, frame window计数, gate-failure聚合, R状态摘要)。不要让 UI 实时多次 Native 查询产生额外帧，使用约2至5秒刷新。
提供实际验证步骤（Mac PowerShell不要，macOS shell可用），基于标准 tools/particle_android_validation/build_validation_apk.sh 构建，确认设备 ABI 与脚本默认 ABI一致后交 RDC 运行。ADB 必须明确 -s 192.168.200.139:5555（这个设备本轮是 FZG1-2），不可无参数误操作其他设备。
文字报告区分：SOURCE-PROVEN / TEST-APP-STRUCTURAL / DEVICE-MEASURED / NOT-VERIFIED。成功构建 APK 不表示真机性能验证通过。

必做输出与收尾

所需 Shared Core / Android Test App 源码实现（尽量只局部变更）。
docs/50_Step记录/STEP-113_FZG1_PBF_Layer与FastGate诊断_v1.md：实际状态、设备验收填写栏、剩余风险。
docs/报告/STEP-113_FZG1_PBF_Layer与FastGate诊断_Codex完成报告_v1.md：改动文件列表、与 NavSea 样式/层等价度证据、24 Gate 定义、精确构建/ADB/场景命令、产物/日志预期、静态检查事实、未做项。
粒子开发记录.md 中文末尾追加少量本次进展（append-only）。
Codex 最终回报真实 model=GPT-6.1-Sol / high，以及剩余需要 RDC 独立验证事项。
文件变更仅 scoped；git diff --check，不提交不 push；避免 Jest 和 Native/Android 长时编译。任何公共跨项目 API 变更先停、写明需要 Integration RFC。

优先次序

优先先完成 B 24Gate真正可靠同帧采集，再实现已有 PBF Mode 的专项布局与 UI；不允许因为“113层不能精确复刻”就省略实际可交付的完整 Gate 诊断。

7.0 KiB Raw Blame History Unescape Escape