docs: add STEP-073 completion report
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
This commit is contained in:
OpenAI Codex
@@ -0,0 +1,79 @@
|
||||
# STEP-073 QBIN2 V4 Core 与通用 Field Profile Validator 完成报告
|
||||
|
||||
## 结论
|
||||
|
||||
**已完成 / PASS。** 本 STEP 只建立 QBIN2 V4.4 的 provider-neutral C++ Core primitive 与 Contract Schema v1 的通用 Validator。没有实现 QBIN 二进制 Decoder，未接入 Android/JNI/RN，未修改 Renderer，也未切换现有 V3 `submitField(...)` 生产路径。
|
||||
|
||||
## Git 记录
|
||||
|
||||
- 任务开始 HEAD：`a0aa367f302ad0e3518931c311ae8764efd2d566`。
|
||||
- 实现 Final HEAD：`0a190adff3a24af59647af4977f1c1e7e107ec28`。
|
||||
- 实现提交：`0a190adff3a24af59647af4977f1c1e7e107ec28`，`feat: add QBIN2 V4 generic field profile validation`。
|
||||
- 远端分支：`origin/particle/main`。
|
||||
- push 结果：已成功从 `a0aa367f3` 推送至 `0a190adff`。
|
||||
- 任务开始前的既有 modified/untracked 文件未暂存、未提交、未删除或格式化。
|
||||
|
||||
## 实际修改文件
|
||||
|
||||
- `CMakeLists.txt`、`test/CMakeLists.txt`：注册 V4 Core、Validator 与测试。
|
||||
- `include/mbgl/particle/field/field_profile_contract.hpp`：Contract Schema v1、value class/component/time relation 与 Core 单位常量。
|
||||
- `include/mbgl/particle/field/field_runtime.hpp`、`src/mbgl/particle/field/field_runtime.cpp`：provider-neutral frame/grid/plane、Series/store、ForecastClock 与 revision 处理。
|
||||
- `include/mbgl/particle/field/field_profile_validator.hpp`、`src/mbgl/particle/field/field_profile_validator.cpp`：独立通用 Validator。
|
||||
- `test/particle/field_runtime.test.cpp`：Validator、revision、独立 cadence 与 clock 自动化测试。
|
||||
- `docs/50_Step记录/STEP-073_QBIN2_V4_Core与通用FieldProfileValidator_v1.md`、`粒子开发记录.md`：正式阶段与开发记录。
|
||||
|
||||
## V4 Core 草稿审查与修正
|
||||
|
||||
已保留草稿的 `FrameContentIdentity`、`FieldSeries`、每 fieldKey 独立 store/window 与 `ForecastClock` 边界。修正点是增加 `DecodedFieldPlane::requiredFlag`，并在 `DecodedFieldFrame` 中加入独立 `validityPlane` descriptor。Runtime 仍没有 QBIN header、byte offset、CRC、网络或 provider 字段。
|
||||
|
||||
`ForecastClock` 仅拥有 requested time、播放状态和速度；未接管 `RasterArrayTimelineRuntime`。旧 `ParticleFieldDescriptor`、`ParticleFieldSnapshot`、`ParticleFieldDataAdapter`、`LocalParticleFieldFeed` 和 `RasterArrayTimelineRuntime` 均未删除或迁移。
|
||||
|
||||
## Validator API 与结果映射
|
||||
|
||||
最终入口为 `FieldProfileValidator::validate(const ResolvedFieldProfileContract&, const DecodedFieldFrame&)`，返回 `FieldProfileValidationResult { code, detail }`。
|
||||
|
||||
| 结果枚举 | 含义 |
|
||||
| --- | --- |
|
||||
| `Accepted` | 已接受 |
|
||||
| `UnsupportedContractSchema` | 不支持的 schema version |
|
||||
| `InvalidContract` | Contract 结构非法 |
|
||||
| `InvalidFrame` | Frame/dtype/结构非法 |
|
||||
| `MissingRequiredPlane` | 缺少 Contract required plane |
|
||||
| `PlaneDescriptorMismatch` | required descriptor 或 REQUIRED flag 不一致 |
|
||||
| `UndeclaredRequiredPlane` | 实际 REQUIRED plane 未被 Contract 声明 |
|
||||
| `AdditionalPlaneNotAllowed` | 禁止额外的非 REQUIRED plane |
|
||||
| `InvalidVelocityGroup` | 速度 group 缺分量、重复分量或 group=0 |
|
||||
| `InvalidCoreUnit` | Velocity/Direction/Validity 的 Core 单位或 dtype 违规 |
|
||||
| `UnsupportedSharedValidityMode` | Schema v1 当前 frame 能力无法表达 `sharedValidityRequired=false` |
|
||||
| `TimeRelationMismatch` | Contract 要求的 valid/reference 时间关系不成立 |
|
||||
|
||||
验证仅使用 Contract descriptor，不基于 `profileID` 做产品分支。普通 Scalar semanticID 与 unitID 保持 opaque；测试中的未知 semantic `777` 和 unit `65432` 在 Contract/Frame 一致时已接受。
|
||||
|
||||
## Validity、REQUIRED 与 Core 规则
|
||||
|
||||
Validity 采用“独立 descriptor + `validityBits` payload”：`validityPlane.storage` 与 `validityBits` 是同一共享只读引用，因此不复制 payload，且后续 projection 可复用同一 validity domain。Validator 检查 Validity semantic/valueClass/unit/group/component/dtype/REQUIRED/count；要求 `BITSET`、`NONE`、group `0`、component `None`。
|
||||
|
||||
REQUIRED 为双向 fail-closed：Contract 每项必须在 Frame 中存在、完整 descriptor 匹配且实际 REQUIRED=true；任一实际 REQUIRED=true plane 必须被 Contract 完整声明。`allowAdditionalPlanes=true` 只允许额外的非 REQUIRED plane。
|
||||
|
||||
Velocity 的通用检查要求非零 group、唯一 U_EAST/V_NORTH、两者 count/unit 一致且单位为 MPS；Direction Angle 要求 DEGREE。上述规则均没有 profile 名称逻辑。
|
||||
|
||||
## Frame identity、cadence 与时钟
|
||||
|
||||
自动化测试确认：同 fieldKey + validTime + identity + content 返回 `Duplicate`；同 identity 不同 content 返回 `RejectedIdentityConflict`；generation/dataVersion 更新返回 `ReplacedRevision`，且 replacement 继续检查相邻 frame interpolation compatibility。不同 fieldKey 在同一 requested time 各自计算不同 cadence 的 T0/T1/mix。ForecastClock 的 pause/play/速度与 Runtime window 独立。
|
||||
|
||||
## 实际 Linux 验证
|
||||
|
||||
所有构建/测试通过输出节流脚本执行：
|
||||
|
||||
- `cmake --build build-linux-opengl --target mbgl-test -j3`：PASS。
|
||||
- `build-linux-opengl/mbgl-test-runner --gtest_filter='ParticleFieldRuntime.*:ParticleFieldProfileValidator.*'`：PASS。
|
||||
- `build-linux-opengl/mbgl-test-runner --gtest_filter='Source.ParticleFieldDataAdapter*:Source.RasterArrayTimeline*:Source.HostField*'`：PASS。
|
||||
- `git diff --check`：PASS。
|
||||
|
||||
未执行 Android Gradle、APK 编译、ADB 或真机操作；这符合本 STEP 禁止范围。未执行 iOS/Metal 验证，也不声明其通过。
|
||||
|
||||
## 未完成 / 无法验证
|
||||
|
||||
- 未完成：QBIN2 Encoded Ingress / `QbinV2Decoder`，按任务边界留给后续审计批准后的 STEP。
|
||||
- 未完成：Android/JNI/RN、Renderer、GPU 与 iOS/Metal 验证；本 STEP 明确禁止或不要求这些工作。
|
||||
- 无法验证项：无阻塞的本 STEP 必做 C++ 项。
|
||||
Reference in New Issue
Block a user