feat: add QBIN V3 decoder for particle.9

docs/30_设计/MapLibreParticle_QBIN_V3_Decoder与BlockGeometry实施决策_v1.md

@@ -0,0 +1,68 @@
+# MapLibreParticle QBIN V3 Decoder 与 Block Geometry 实施决策 v1
+
+## 1. 结论
+
+STEP-086 将 `QBV3` / version 3 作为新的压缩天气场容器格式接入 MapLibre Native。生产 Decoder 固定使用 **16×16 Block Geometry**，不在运行时尝试 16×16 / 32×32 双解码，也不通过启发式猜测块尺寸。
+
+既有 `QBV2` 解码链继续保留。`EncodedFieldIngress` 依据 magic 显式分流：`QBV2` → `QbinV2Decoder`，`QBV3` → `QbinV3Decoder`；version 由对应 Decoder 严格校验。解码完成后继续统一进入 `FieldProfileValidator`，不改变既有 profile contract 分层。
+
+## 2. Block Geometry 决策依据
+
+使用仓库既有 Current / Rain / Wave / Wind 四类真实 Golden 数据，共 T0/T1 8 帧，按 v2.2 冻结稿规则实现确定性的 C++ benchmark encoder/decoder，对 16×16 与 32×32 做相同输入对比。
+
+| 指标 | 16×16 | 32×32 | 结论 |
+|---|---:|---:|---|
+| 数值 payload 总字节 | 2,470,419 | 2,514,288 | 32×32 增加 43,869 字节，约 +1.7758% |
+| 总 block 数 | 22,704 | 5,984 | 32×32 block 更少 |
+| 非空 block 数 | 19,120 | 5,190 | 32×32 block 更少 |
+| C++ encode 总时间 | 218.713 ms | 200.101 ms | 32×32 约快 8.5% |
+| C++ decode 总时间 | 104.121 ms | 101.451 ms | 32×32 约快 2.6% |
+
+8 帧合计 decode 差异约 2.67 ms，平均每帧约 0.33 ms；相比之下，32×32 对 payload 尺寸有稳定负收益，Rain 两帧的增幅尤其明显。QBIN V3 的核心目标之一是降低网络、缓存和跨 RN/Native 传输成本，因此选择 **16×16**。
+
+此决定同时冻结：
+
+- `QbinV3Decoder::BlockWidth = 16`；
+- `QbinV3Decoder::BlockHeight = 16`；
+- Golden Fixture manifest 中 blockWidth/blockHeight 均为 16；
+- 后续生产 Writer 必须输出相同 ABI，不得自行改为 32×32。
+
+## 3. Decoder 责任边界
+
+`QbinV3Decoder` 只负责把已取得的 QBV3 二进制解码成现有 `DecodedFieldFrame`。它不负责 Weather provider、HTTP、下载、重试、缓存、manifest 获取、路线调度或 React 业务逻辑。
+
+实现包含：
+
+- 固定 Header / Descriptor 布局与 little-endian 读取；
+- file size、plane count、cell count、decoded bytes 等硬上限；
+- CRC32 校验；
+- canonical descriptor 排序、唯一键、16-byte packing 与 padding 校验；
+- VALIDITY 唯一性、长度、unused bits 校验；
+- Numeric dtype 约束与 all-invalid 零长度编码；
+- 16×16 block 的 Predictor + ZigZag + Rice 解码；
+- Direction 的 canonical scale、环形预测与 half-circle tie 规则；
+- 非法 Rice-K、截断、额外字节、非零 bit padding、残差越界等 fail-closed；
+- 解码后构造既有 `DecodedFieldFrame`，继续使用既有 FieldProfileValidator。
+
+## 4. Golden Fixtures
+
+正式 QBIN V3 Golden Fixture 位于：
+
+`integration/react-native/MapLibreParticleRNTestHost/assets/qbin-v3-golden/`
+
+覆盖：
+
+- current：T0 / T1，513×513；
+- rain：T0 / T1，513×513；
+- wave：T0 / T1，513×769；
+- wind：T0 / T1，513×769。
+
+`manifest.json` 固定每个文件的 bytes、SHA-256、width、height 以及 16×16 Block Geometry。校验脚本为：
+
+`integration/react-native/MapLibreParticleRNTestHost/scripts/verify-qbin-v3-golden-fixtures.py`
+
+8 个 V3 fixture 已与对应 V2 canonical raw 解码结果做逐 plane / validity byte-for-byte 对比，结果一致。
+
+## 5. 兼容性与版本
+
+本次不移除 QBV2，不改变 RN `submitEncodedField` 公共调用形态，不把 V3 压缩细节暴露给 JS/TS。Native / RN 发行版本统一升级为 `13.4.1-particle.9`。