263 lines
10 KiB
Markdown
263 lines
10 KiB
Markdown
# STEP-102 RenderSegment 无 Placement 段局部复用 Codex 任务 v1
|
||
|
||
## 1. Step 编号和目的
|
||
|
||
STEP-102：修复 full CPU 多 Retained Segment 下 placement aggregate gate 的不必要扩散，使**结构上不具备 placement 能力**的 Retained Segment 能在其他 placement-bearing Segment fallback/live 时继续独立 composite/reuse。
|
||
|
||
本 Step 的设计依据：
|
||
`docs/20_调查/RenderSegment多Retained段全局Placement门槛_粒子管理员审查说明_v3.md`。
|
||
|
||
## 2. 当前已冻结基线
|
||
|
||
- 仓库：`/Users/tei/dev/MapLibreParticleLab-step102`
|
||
- branch：`step102-placement-free-retained-locality`
|
||
- start HEAD：`6df21dac38f072c5ad35b8dfc7ec5217509602bc`
|
||
- upstream base：MapLibre Native core 既有冻结基线，不升级
|
||
- V19/V20 release worktree：冻结，只读，不修改
|
||
- STEP-100 source-scoped locality：必须保持
|
||
- STEP-101 teardown 修复：必须保持
|
||
- Fast Path：本 Step 不修改
|
||
- C-001：不升级
|
||
|
||
## 3. 本 Step 目标
|
||
|
||
必须实现：
|
||
1. 增加结构性 placement-capable range 查询；
|
||
2. full CPU 每个 Retained Segment 独立计算 placement gate；
|
||
3. placement-free Retained 不再被其他 Segment 的 placementChanged/symbolFadeChange 纯 aggregate gate 拖入 fallback；
|
||
4. placement-bearing Retained 继续使用现有保守 placement gate；
|
||
5. 从 full CPU `globalLiveFallback` 移除纯 aggregate placement 条件；
|
||
6. 保持真正全局 fail-closed 条件；
|
||
7. diagnostics 增加结构 placement、per-segment gate、实际 composite/live 与全局 main-buffer execution 信息；
|
||
8. RN diagnostics TS 类型做 additive 扩展；
|
||
9. 增加对应 C++ 测试源码与 Android Validation 场景源码；
|
||
10. 不改变 Style Z-order、mixed executor、C-001 和 RN method surface。
|
||
|
||
## 4. 非目标 / 禁止事项
|
||
|
||
禁止：
|
||
- placement-bearing Segment 之间的局部碰撞缓存；
|
||
- per-segment collision graph / symbol fade / placement fingerprint；
|
||
- Fast Path 改造；
|
||
- multi-continuous Fast Path；
|
||
- 重写 `visitRenderSegmentExecution()`；
|
||
- 修改 NavSea；
|
||
- 新增 NavSea 私有 Native API；
|
||
- 修改 C-001；
|
||
- 修改 V19/V20 release worktree/tag；
|
||
- 升级 MapLibre、NDK、Gradle、AGP、Java、Node 或其他工具链；
|
||
- 为通过测试降低 fail-closed 门槛；
|
||
- Android Gradle/build、APK/AAR build、ADB、设备操作；
|
||
- Jest。用户未要求 Jest，本任务不得新增或执行 Jest。
|
||
|
||
## 5. 允许修改范围
|
||
|
||
生产代码优先限制在：
|
||
- `src/mbgl/renderer/render_orchestrator.hpp`
|
||
- `src/mbgl/renderer/render_orchestrator.cpp`
|
||
- `src/mbgl/renderer/renderer_impl.cpp`
|
||
- `include/mbgl/renderer/render_segment.hpp`
|
||
- `src/mbgl/renderer/retained_underlay_runtime_state.hpp`
|
||
- `src/mbgl/renderer/render_segment_json.hpp`
|
||
- `packages/maplibre-particle-rn/src/types.ts`
|
||
|
||
测试/Validation 允许：
|
||
- `test/renderer/retained_underlay_cache.test.cpp`
|
||
- 与现有 Particle Validation 场景直接相关的最小 Android Test App 文件
|
||
|
||
文档允许：
|
||
- 本任务书
|
||
- `docs/50_Step记录/STEP-102_RenderSegment无Placement段局部复用_v1.md`
|
||
- `docs/报告/STEP-102_RenderSegment无Placement段局部复用_Codex完成报告_v1.md`
|
||
- `粒子开发记录.md`
|
||
- v3 审查说明只读，除非发现明确事实错误；若需改，停止并先报告
|
||
|
||
如果实现必须扩大生产代码范围，先停止并报告原因，不得自行扩张架构。
|
||
|
||
## 6. 禁止修改范围
|
||
|
||
- NavSea 仓库
|
||
- `navsea-particle-integration` contract/RFC/ADR
|
||
- Fast Path 逻辑、`tryRenderParticleFastFrame()`、`singleContinuousSegment()` 语义
|
||
- `retainedRangeUsesPlacement()` 现有动态语义
|
||
- mixed executor 算法
|
||
- Source `isLoaded()` 定义
|
||
- STEP-100 source revision/locality 语义
|
||
- STEP-101 teardown 生命周期语义
|
||
- renderer/backend 架构
|
||
- release/version/tag/publish 坐标
|
||
|
||
## 7. 实施要求
|
||
|
||
### 7.1 结构性 placement-capable 查询
|
||
|
||
新增 full CPU retained 专用查询，必须基于 layer 结构，而不是当前帧 placementData。
|
||
|
||
最小保守语义：
|
||
- range 中存在 `symbol` layer → placement-capable
|
||
- 无 `symbol` layer → placement-free
|
||
- custom/custom-drawable 继续由 unsupported gate 处理
|
||
|
||
不得用 `needsPlacement()==false` 证明 placement-free。
|
||
|
||
### 7.2 per-segment placement gate
|
||
|
||
每个 Retained Segment 至少形成两个明确事实：
|
||
- structural placement capability
|
||
- current full-CPU placement gate result
|
||
|
||
placement-free Segment 不受纯 global placement gate 阻塞。
|
||
placement-bearing Segment 本 Step 继续沿用旧保守 gate，不承诺稳定后 reuse。
|
||
|
||
变量/字段命名不得把 `symbolFadeChange==0` 错称为严格 placement stable。
|
||
|
||
### 7.3 full CPU mixed execution
|
||
|
||
`segmentSupported` 改为使用对应 Segment placement gate。
|
||
|
||
`globalLiveFallback` 仅移除纯 aggregate placement 条件，其他真正 global 条件继续保留。
|
||
|
||
不得重写 `visitRenderSegmentExecution()`。
|
||
|
||
### 7.4 fallback reason
|
||
|
||
`static-placement` 必须按 Segment 自身 placement capability/gate 判定，不能从 aggregate reason 无差别传播。
|
||
|
||
### 7.5 diagnostics
|
||
|
||
每个 Segment 最少新增等价语义：
|
||
- `placementCapable`
|
||
- `placementGatePassed`
|
||
- `actualExecution = composite | live`
|
||
|
||
全局最少新增等价语义：
|
||
- `placementChanged`
|
||
- `symbolFadeChange`
|
||
- `placementTransitionActive`
|
||
- `crossSourceCollisions`
|
||
- `mainBufferExecutionMode = mixed | global-live`
|
||
- `globalLiveFallbackReason`
|
||
|
||
`actualExecution` 必须反映本帧 main-buffer 最终实际执行，不能根据 cache finalDecision 推导。
|
||
Diagnostics 查询必须无副作用、不得推进 revision。
|
||
|
||
### 7.6 RN 类型
|
||
|
||
只扩展现有 diagnostics 返回类型，不新增 method，不改变 `setRenderSegmentPlan()` 输入 contract。
|
||
Android/iOS Shared Core JSON 语义保持一致。
|
||
|
||
## 8. 构建要求
|
||
|
||
Codex 本阶段**不得执行任何 Android 编译/Gradle/APK/AAR build**，也不得启动长时间 CMake/Ninja/Bazel 构建。
|
||
|
||
Codex 完成代码后只需提供精确验证命令，由后续 RDC/用户按规则执行。其中 Android 编译由用户手工执行。
|
||
|
||
Codex 可执行的机械静态检查仅限：
|
||
- `git diff --check`
|
||
- 只读 grep/rg/git diff/status
|
||
- 不产生构建产物的格式/静态检查（若仓库已有且无需安装依赖）
|
||
|
||
不得安装或升级系统依赖来制造测试 PASS。
|
||
|
||
## 9. 测试要求
|
||
|
||
Codex 必须新增/补强测试源码，但本阶段不执行大型测试。
|
||
|
||
至少覆盖：
|
||
1. placement-free R0 + placement-bearing R1：R0 可 composite，R1 live；
|
||
2. 含 symbol 但当前 placementData 为空：仍判定 placementCapable=true；
|
||
3. 两个 placement-free Retained：持续 reuse/composite；
|
||
4. source-local fading/mutation 回归不误伤 R0；
|
||
5. placement-bearing 在 transition disabled / `symbolFadeChange=1` 等状态仍不被本 Step 放宽；
|
||
6. 真正 global gate 继续 global-live/fail-closed；
|
||
7. topology 变化释放旧 resource；
|
||
8. cache decision=reuse 但 global-live 时，diagnostics 的 actualExecution 必须为 live；
|
||
9. diagnostics JSON/TS 字段语义一致且查询无副作用。
|
||
|
||
Android Validation 场景应能在后续手工构建后明确输出 STEP-102 验收所需字段，不依赖 NavSea。
|
||
|
||
## 10. 验收标准
|
||
|
||
代码审计门槛：
|
||
- [ ] 新增结构性 placement-capable 查询
|
||
- [ ] 未改变 `retainedRangeUsesPlacement()` 旧语义
|
||
- [ ] full CPU per-segment placement gate 生效
|
||
- [ ] placement-bearing 继续保守
|
||
- [ ] `globalLiveFallback` 只移除纯 aggregate placement 条件
|
||
- [ ] 真正 global gate 保留
|
||
- [ ] mixed executor 未重写
|
||
- [ ] Fast Path 无语义修改
|
||
- [ ] per-segment fallback reason 正确
|
||
- [ ] diagnostics 有 actualExecution 与 main-buffer mode/fallback reason
|
||
- [ ] RN method surface 不变
|
||
- [ ] C-001 不变
|
||
- [ ] 测试源码覆盖设计矩阵
|
||
- [ ] `git diff --check` PASS
|
||
|
||
运行态 PASS 不在 Codex 阶段宣称。Android 手工编译与真机验证未完成前，STEP-102 状态只能写“代码完成 / 等待验证”或同等非 PASS 状态。
|
||
|
||
## 11. Git 要求
|
||
|
||
- 工作分支：`step102-placement-free-retained-locality`
|
||
- 禁止修改 particle/main 工作区
|
||
- 禁止 `git add -A`、`git add .`、`git reset --hard`、`git clean`
|
||
- 只 scoped staging 本任务文件
|
||
- 不提交无关 dirty/untracked 文件
|
||
- Codex 可在实现完成、静态检查通过后创建 scoped implementation commit，但**不得 merge 到 particle/main、不得 push release 分支/tag、不得发布制品**
|
||
- 是否 push/merge 由后续独立验收决定
|
||
|
||
## 12. 必做输出
|
||
|
||
Codex 完成后必须交付：
|
||
1. 生产代码修改；
|
||
2. C++ 测试源码；
|
||
3. Android Validation STEP-102 场景源码/日志字段；
|
||
4. `docs/50_Step记录/STEP-102_RenderSegment无Placement段局部复用_v1.md`；
|
||
5. `docs/报告/STEP-102_RenderSegment无Placement段局部复用_Codex完成报告_v1.md`；
|
||
6. 追加 `粒子开发记录.md`；
|
||
7. 精确列出后续验证命令；
|
||
8. 明确列出所有 NOT RUN / BLOCKED 项；
|
||
9. Git diff/status/commit（若创建）事实。
|
||
|
||
## 13. 执行报告完整文件名
|
||
|
||
固定：
|
||
`docs/报告/STEP-102_RenderSegment无Placement段局部复用_Codex完成报告_v1.md`
|
||
|
||
同主题后续报告只递增 `_v2/_v3`，不得另造近义文件名。
|
||
|
||
## 14. 执行报告固定内容
|
||
|
||
至少包含：
|
||
1. 执行结论：只能按实际写代码完成/等待验证、PARTIAL、BLOCKED 或 FAIL；未运行 Android 不得写运行态 PASS
|
||
2. Git 基线：branch/start HEAD/end HEAD/status
|
||
3. 实际修改文件
|
||
4. 新增文件
|
||
5. 实现内容逐条对照任务书
|
||
6. 与 v3 设计差异
|
||
7. Fast Path / mixed executor / C-001 未修改审计
|
||
8. diagnostics 新字段与语义
|
||
9. 测试源码覆盖矩阵
|
||
10. 实际执行的静态检查
|
||
11. 未执行的 build/test/Android/设备项目
|
||
12. 用户手工 Android 构建命令
|
||
13. 后续 RDC/真机验收命令与硬门槛
|
||
14. 已知风险与未完成事项
|
||
15. Git commit 信息（若有）
|
||
|
||
## 15. 阻塞与停止条件
|
||
|
||
遇到以下任一情况必须停止扩大修改并报告：
|
||
- 结构性 placement capability 不能仅靠既有 layer type 安全判定，需要新增更大公共抽象；
|
||
- 必须修改 Fast Path 才能完成本任务；
|
||
- 必须重写 mixed executor；
|
||
- 必须改变 collision/Placement 核心算法；
|
||
- 必须修改 C-001 / RN method surface；
|
||
- 必须修改 NavSea；
|
||
- 必须扩大到 renderer/backend 架构重构；
|
||
- 发现 global revision 仍有未预期的 placement 推进，需要新设计；
|
||
- 需要升级工具链/依赖；
|
||
- 需要删除或弱化既有测试/安全门槛。
|
||
|
||
若实现范围保持在 v3 冻结边界内，可直接完成代码并停在“等待手工构建/运行验证”。
|