tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a3c3b4e540ce340f47ac9229a46eb10e29d2fa75
MapLibreParticleLab/docs/40_任务/STEP-093_ContinuousRange运行态综合验收_Codex任务_v1.md
tei 66690b460e
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
Details
docs: hand off STEP-093 runtime validation
2026-09-24 14:42:25 +09:00

22 KiB
Raw Blame History

STEP-093：Continuous Range 运行态综合验收

1. 任务目标

在 STEP-092 已完成并关闭的 Continuous Range / Retained Cache 架构基础上，进入真实 Renderer 运行态综合验收。

本任务不重新设计 STEP-092 架构，不引入新的 Z-order 体系，不重做 retained cache 结构。目标是通过可重复、可观察、可诊断的运行态场景，确认以下核心事实在真实渲染过程中成立：

  1. Style Layer 顺序仍然是唯一 Z-order 真相。
  2. [startLayerId, endLayerId] 能稳定解析为一个 Continuous Range。
  3. Bottom / Continuous / Top 四种合法退化结构均能正确工作。
  4. 实际 retained cache 数量严格为 0 / 1 / 2，不存在的 range 不创建无意义 GPU 资源。
  5. Particle 连续播放时，稳定的普通 Style/PBF 内容能够命中 retained cache，而不是每帧重复完整绘制。
  6. Top range 能真实覆盖 Continuous 中的 Particle，验证最终画面顺序为：Bottom → Continuous → Top。
  7. Camera、viewport、style、layer/source 等变化发生时能够正确 invalidation、rebuild，并重新进入稳定 reuse。
  8. Fast Path 失败时必须安全退回 full CPU frame，但不得破坏 Continuous Range、retained cache 和 Z-order。
  9. Android/OpenGL 与 iOS/Metal 最终表现一致；若本阶段只能先完成 Android，则 iOS 可明确记录为后续待验收，不得虚报通过。

2. 当前基线

开始任务前必须先检查真实仓库，不得只依赖任务书中的 SHA。

预期起始基线：

  • Repository: MapLibreParticleLab
  • Branch: particle/main
  • STEP-092 最终状态：CLOSED / PASS（Mac Native 验证闭环）
  • STEP-092 最终已知 HEAD：8a5d88008c142e2a80e0ff602d228e0e67de2d83
  • HEAD == origin/particle/main
  • 工作区应为 clean

STEP-092 已完成的关键内容包括：

  • Continuous Range 显式配置；
  • Bottom / Continuous / Top 三段模型；
  • 四种合法退化拓扑；
  • 0 / 1 / 2 retained cache；
  • Bottom/Top retained cache；
  • Top 透明 RGBA + premultiplied alpha 合成；
  • Style mutation 后重新解析；
  • invalid explicit range 的安全 fallback；
  • Particle Fast Path 与 retained cache 的协同；
  • Android / iOS Bridge 接口；
  • OpenGL Native build；
  • iOS Metal-only native build；
  • 定向 Native tests 29/29 PASS。

本 STEP 不重新证明上述静态设计，而是证明它们在真实运行态画面与资源生命周期中成立。

3. 开始前必读

Codex 开始前必须读取：

  1. 仓库根目录 AGENTS.md
  2. 当前粒子系统总规则 / 架构约束文档
  3. docs/50_Step记录/STEP-092_ContinuousRange可退化分段RetainedCache_v2.md
  4. docs/报告/STEP-092_ContinuousRange可退化分段RetainedCache_Codex完成报告_v2.md
  5. STEP-092 相关实现文件与 diagnostics 实现
  6. 当前 Android/iOS Particle Test App / validation 页面 / Host runtime 实现
  7. 当前可用的测试按钮、场景、日志和 diagnostics 展示入口

如实际仓库结构与本任务书描述不一致，以当前真实代码为准，并在报告中写明差异。

4. 本任务职责划分

4.1 Codex 负责

Codex 负责：

  • 调查当前可用的运行态测试入口；
  • 为 STEP-093 补齐必要的 Test/Validation UI、场景切换、diagnostics 展示和最小测试辅助代码；
  • 只在确有必要时补充可观察性；
  • 修复在准备阶段发现的明确、局部、与 STEP-093 验收直接相关的问题；
  • 为 RDC / 用户准备清晰、可逐项执行的运行态验收入口；
  • 更新中文 STEP 记录、完成报告和开发记录；
  • 提交并 push 自己完成的代码与文档。

4.2 RDC / 用户负责

实际 Android / iOS 编译、安装、启动、真机或模拟器运行、视觉操作与最终画面确认由 RDC / 用户执行。

Codex 不得仅依据静态代码、日志或自己推测就把运行态测试标记为 PASS。

如果没有实际执行某个运行态场景，必须写为 NOT RUN、WAITING_RUNTIME_VALIDATION 或其他明确的未完成状态，不得写成 PASS。

5. 严格保护的 STEP-092 架构

本 STEP 禁止借“测试方便”修改以下既定架构：

  1. Style 顺序是唯一 Z-order 真相。
  2. App/RN 只提供 startLayerId、endLayerId。
  3. Native 自行解析 index。
  4. Continuous Range 为闭区间 [startLayerId, endLayerId]。
  5. 内部：continuousBegin = startIndex，continuousEndExclusive = endIndex + 1。
  6. 三段：Bottom [0, begin)、Continuous [begin, endExclusive)、Top [endExclusive, layerCount)。
  7. start == end 合法。
  8. Continuous-only 合法，不是 fallback。
  9. 不允许加入 anchor / marker layer。
  10. 不允许增加第二套 BOTTOM / CONTINUOUS / TOP metadata 真相源。
  11. 不允许 Renderer 硬编码 NavSea/AIS/Alarm/Wind/Wave 等业务 Layer ID。
  12. Visibility 不改变 topology。
  13. explicit range 有效时不得再混用旧 startsRetainedDynamicRange() 作为 topology boundary。
  14. 不允许把普通 style layer 改造成新的特殊 layer type 来解决测试问题。
  15. 不做任意 N-range planner。
  16. 不做多个 Continuous Range。
  17. 不做频率分类系统。
  18. 不做 PBF 通用重构。
  19. 不做 RenderGraph 重构。
  20. 不加入 Jest。

6. STEP-093 必测场景

6.1 场景 A：Bottom + Continuous + Top

构造至少：Bottom 为普通 Style/PBF Layer，Continuous 为 Particle / Weather 动态 Layer，Top 为普通 Style/PBF Layer。

必须验证：

  • explicit range valid；
  • Bottom present = true；
  • Top present = true；
  • retained cache 实际数量 = 2；
  • Bottom cache 可 build/reuse；
  • Top cache 可 build/reuse；
  • 最终画面顺序 Bottom → Continuous → Top；
  • Top 内容能够真实覆盖 Particle；
  • 无明显黑边、错误透明、旧 cache 或层序颠倒。

6.2 场景 B：Bottom + Continuous

Continuous 结束于当前 Style 最顶层。

必须验证：

  • Bottom present = true；
  • Top present = false；
  • retained cache 实际数量 = 1；
  • 不得创建 Top texture/FBO/compositor；
  • 不存在的 Top 不得阻塞 Fast Path；
  • 画面顺序正确。

6.3 场景 C：Continuous + Top

Continuous 从当前 Style 最底层开始。

必须验证：

  • Bottom present = false；
  • Top present = true；
  • retained cache 实际数量 = 1；
  • 不得创建 Bottom texture/FBO/compositor；
  • 不存在的 Bottom 不得阻塞 Fast Path；
  • Top 可正确覆盖 Particle。

6.4 场景 D：Continuous only

Continuous 覆盖全部 Style Layer。

必须验证：

  • Bottom present = false；
  • Top present = false；
  • explicit range valid = true；
  • retained cache 实际数量 = 0；
  • 这是合法 Continuous-only，不得被识别为 fallback；
  • 不创建 retained texture/FBO/compositor；
  • Particle/continuous renderer 正常运行。

6.5 场景 E：Single-layer Continuous

设置 startLayerId == endLayerId。

必须验证：

  • range valid；
  • startIndex == endIndex；
  • continuousEndExclusive == startIndex + 1；
  • 正常参与 Bottom/Top 切分；
  • 不得 fallback；
  • 不得被误认为空 range。

7. Z-order 核心视觉验收

这是 STEP-093 的最高优先级运行态验收。

必须构造一个肉眼可以清楚确认覆盖关系的场景：

  1. Bottom 中放一个明显底图/填充层；
  2. Continuous 中运行 Particle；
  3. Top 中放一个能够明显覆盖 Particle 的普通 Style Layer。

优先使用已有普通 Style Layer；如果测试环境缺少合适图层，可添加纯测试用普通 Style Layer，但不得引入新的特殊 layer type 或业务硬编码。

建议 Top 验证至少覆盖：opaque fill、半透明 fill、line；如当前测试环境可行，再加入 symbol/text。

必须确认：

  • Top 真正绘制在 Particle 上方；
  • Particle 不会穿透 opaque Top；
  • 半透明 Top 与 Particle 合成正确；
  • 无黑边；
  • 无颜色异常变暗；
  • 无错误双重 alpha；
  • 无 cache 旧内容残留。

8. Stable Frame / Cache Reuse 验收

在 Camera、viewport、Style、普通 PBF/source 内容都不变化，仅 Particle 持续动画时，必须观察：

  • Bottom/Top retained cache build 后持续 reuse；
  • 不应每个 Particle frame 重建 retained cache；
  • 不应每 frame 重建 retained texture；
  • 不应每 frame 重建 FBO/offscreen texture；
  • 不应每 frame 重建 composite group；
  • Fast Path 在满足条件时能够持续命中；
  • diagnostics 能够区分 build / reuse / invalidation。

如果现有 diagnostics 无法证明资源生命周期，可增加最小 debug-only counter / reason 字段。禁止为了测试引入生产环境高频日志风暴。

9. Camera / Viewport invalidation

至少验证：Pan、Zoom、Rotate、Pitch、viewport resize/orientation 或等价尺寸变化，以及测试环境可实际触发时的 pixel ratio 变化。

每项检查：

  • 旧 retained cache 被正确 invalidation；
  • 下一帧或正确时点 rebuild；
  • rebuild 后重新进入 reuse；
  • 不出现 stale cache；
  • 不出现错位；
  • 不出现黑屏；
  • 不出现 Particle 与地图不同步；
  • topology 不应无故改变。

10. Style Mutation / Topology 重新解析

必须提供可重复测试入口，至少覆盖：

10.1 Continuous 内部变更

添加 Layer、删除非 endpoint Layer、reorder Continuous 内部 Layer。

预期：重新解析必要状态；range 仍有效时保持正确 topology；cache 根据需要 invalidation；不产生第二套 Z-order。

10.2 Bottom 内变更

添加、删除、reorder，检查 Bottom cache invalidation / rebuild / reuse。

10.3 Top 内变更

添加、删除、reorder，检查 Top cache invalidation / rebuild / reuse。

10.4 Layer 跨边界移动

将某个普通 Layer 做有代表性的 Bottom → Continuous、Continuous → Top 或 Top → Bottom 跨 range 移动。

必须验证：

  • ID → index 重新解析；
  • topology/cache/prepared state 正确 invalidation；
  • 新 Z-order 正确；
  • 不使用旧 index；
  • 不出现 stale cache。

11. Endpoint 删除与恢复

删除 start endpoint 时：explicit range 立即 invalid；不 crash；不猜测新 start；不继续使用 stale index/cache；进入既定安全 fallback；diagnostics 有明确 lastReason。

恢复 start endpoint 时：Native 能重新解析；explicit range 恢复 valid；正确重建需要的 cache；不需要重建整个 Map instance。

对 end endpoint 做同等验证。

12. Visibility 不改变 topology

对 start endpoint、end endpoint 或 Continuous 内普通 Layer 做 visible → hidden → visible。

必须验证：

  • topology 仍以 Style 顺序解析；
  • startIndex/endIndex 不因 visibility 改变；
  • hidden endpoint 仍是 endpoint；
  • 不自动收缩 Continuous Range；
  • ON/OFF 只作为内容变化处理；
  • 如需 cache invalidation，应是内容 invalidation，不得变成新的 topology 规则。

13. Invalid Explicit Range

至少验证：

  1. startLayerId 不存在；
  2. endLayerId 不存在；
  3. startIndex > endIndex；
  4. Style 尚未 ready 时配置；
  5. 空 ID / 未配置（按实际 API 合法性处理）。

预期：不 crash；不猜测；不复用 stale cache；不按 Layer 类型自动修正；进入明确安全 fallback；diagnostics 显示 invalid 原因；条件恢复后能够重新进入 explicit range。

14. Particle Fast Path

14.1 可命中场景

Continuous 内只保留当前 Fast Path 已支持的动态内容。

检查：Fast Path 可持续命中；Bottom/Top 的存在与否只影响实际存在的 retained cache；0 cache 的 Continuous-only 不得因为“没有 retained cache”而错误阻止 Fast Path。

14.2 Fail Closed 场景

在 Continuous 中加入当前 Fast Path 不支持的普通/未知 Continuous Layer。

必须验证：

  • Fast Path 退回 full CPU frame；
  • 不 crash；
  • 不错误跳过该 Layer；
  • Continuous Range 本身保持 valid；
  • Bottom / Top retained cache Z-order 仍正确；
  • 不允许为了 Fast Path 强行把未知 Layer 移出 Continuous。

15. Top Alpha / Premultiplied Alpha 验收

必须重点看 Top retained cache 合成：transparent background、opaque fill、semi-transparent fill、line，以及可行时 symbol/text。

检查：透明区域正确露出 Particle；半透明区域正常叠加；opaque 区域完整覆盖；无黑色边缘；无 halo；无颜色被错误乘两次；无残影；OpenGL 与 Metal 设计保持一致。

16. 长时间运行与资源稳定性

在测试环境允许情况下进行持续运行测试，至少包括：Particle 连续播放、多次 Pan/Zoom/Rotate、多次 range 配置变化、endpoint 删除/恢复、visibility 切换、style mutation、再次稳定运行。

观察：

  • 无持续 GPU resource 增长迹象；
  • retained texture/FBO 不因 stable frame 每帧新建；
  • 无明显内存持续增长；
  • 无黑屏；
  • 无闪屏；
  • 无 stale cache；
  • 无偶发层序颠倒；
  • 无 Particle 停止后恢复不了的问题。

如果当前工程缺少可靠 GPU memory 数字来源，不要求伪造数值；允许使用资源创建/释放 counter、diagnostics 和稳定运行现象作为当前阶段证据，并明确限制。

17. Diagnostics 要求

STEP-093 的测试入口必须能清楚观察至少以下信息：

Range

  • configured
  • valid
  • startLayerId
  • endLayerId
  • startIndex
  • endIndex
  • continuousBegin
  • continuousEndExclusive
  • fallback / lastReason

Bottom

  • present
  • cache state
  • build count
  • reuse count
  • invalidation count
  • last invalidation reason

Top

  • present
  • cache state
  • build count
  • reuse count
  • invalidation count
  • last invalidation reason

Fast Path

  • eligible / active
  • fallback reason
  • full CPU frame count 或等价诊断（若现有已有）
  • unknown continuous layer 导致 fail-closed 的可观察原因

如当前已有字段足够，不得重复造一套 diagnostics。

18. Test UI / Playground 要求

优先复用现有 Particle Test App / validation UI。

如果需要新增 STEP-093 面板，要求：

  • 不影响生产 MapLibre API 语义；
  • 不引入 NavSea 业务逻辑；
  • 场景按钮命名明确；
  • 能一键切换四种 topology；
  • 能设置 single-layer range；
  • 能触发 invalid range；
  • 能隐藏/显示 endpoints；
  • 能删除/恢复 endpoint；
  • 能触发代表性的 reorder / cross-boundary move；
  • 能显示当前 diagnostics；
  • 能恢复默认测试场景。

测试 UI 本身不应成为复杂新框架。

19. Android 运行态验收

Android 作为本 STEP 首要完整运行态验收平台。

Codex 必须准备：

  • 明确的 build/install/run 手工命令；
  • STEP-093 测试入口位置；
  • 每项场景的操作步骤；
  • 需要采集的日志/diagnostics；
  • PASS/FAIL 判定。

实际 Android Gradle / APK / ADB / 真机或模拟器操作由 RDC / 用户执行。

不得由 Codex 仅凭代码静态分析代替 Android 实机/模拟器结论。

20. iOS / Metal 运行态验收

Android 完整通过后，再进行 iOS / Metal 对等测试。

至少需要验证：四 topology、Single-layer Continuous、Top 覆盖 Particle、Stable cache reuse、Camera invalidation、endpoint missing/recovery、visibility、Fast Path fail-closed、Top alpha。

如果本 STEP 暂未执行 iOS runtime：

  • 报告必须明确写 WAITING_IOS_RUNTIME_VALIDATION；
  • Android PASS 不得自动推导为 iOS PASS；
  • Metal native build PASS 也不能替代 Metal runtime rendering PASS。

21. 编译与测试原则

  1. MapLibre Native 的 Android/iOS 开发与编译统一使用 Mac。
  2. 不安排 Linux Native 编译。
  3. noisy native build 遵循 Mac/Codex 全局构建输出节流规则。
  4. 不加入 Jest。
  5. 可运行已有 Native 精确测试；如代码变更影响 STEP-092 核心逻辑，应重跑相关现有 Native tests。
  6. 不为了“让测试绿”删除或弱化 STEP-092 已有覆盖。

22. 发现问题时的处理规则

22.1 小型、事实明确、局部问题

例如测试 UI 接线错误、diagnostics 漏展示、明确计数器错误、局部 invalidation reason 错误、编译错误、测试工具小缺陷，允许直接修复，并重新验收受影响项目。

22.2 架构级问题

如果发现需要修改 Continuous Range 数学定义、Style 顺序唯一 Z-order、0/1/2 retained cache 模型、renderer 大范围遍历结构、Fast Path 核心模型、第二套 layer metadata、新特殊 layer type、新 RenderGraph 或大规模 GPU cache redesign，必须停止当前修复扩张，先生成明确的“STEP-093 架构阻塞报告”，说明实际问题、复现方式、为什么 STEP-092 架构无法满足、建议方案和影响范围。

不得在运行态测试任务中擅自重构架构。

23. 验收矩阵

最终报告必须至少给出以下矩阵：

类别 场景 Android iOS/Metal 关键证据 结论
Topology Bottom+Continuous+Top
Topology Bottom+Continuous
Topology Continuous+Top
Topology Continuous-only
Range Single-layer Continuous
Z-order Top covers Particle
Cache Stable reuse
Invalidation Pan/Zoom/Rotate/Pitch
Mutation Continuous internal mutation
Mutation Cross-range move
Endpoint start missing/recovery
Endpoint end missing/recovery
Visibility hidden endpoint topology
Invalid missing/reversed range
Fast Path eligible
Fast Path unknown layer fail-closed
Alpha Top premultiplied composite
Stability repeated operations / long run

状态只允许使用清楚枚举，例如：PASS、FAIL、NOT RUN、BLOCKED、WAITING_ANDROID_RUNTIME_VALIDATION、WAITING_IOS_RUNTIME_VALIDATION。

24. STEP-093 完成条件

只有满足下面条件，才允许把 STEP-093 标记为 CLOSED / PASS：

  1. Android 运行态核心矩阵实际执行并通过；
  2. 四种 topology 实际验证；
  3. Single-layer Continuous 实际验证；
  4. Top 覆盖 Particle 实际验证；
  5. 0/1/2 cache 与 diagnostics 一致；
  6. Stable reuse 实际验证；
  7. Camera invalidation → rebuild → reuse 实际验证；
  8. endpoint missing/recovery 实际验证；
  9. visibility 不改变 topology 实际验证；
  10. invalid range fallback 实际验证；
  11. Fast Path eligible + fail-closed 实际验证；
  12. Top alpha 无明显错误；
  13. 发现的阻塞性缺陷已解决并回归；
  14. 文档与 Git 收尾完整；
  15. HEAD == origin/particle/main；
  16. 工作区 clean。

如果 Android 已全部通过但 iOS 尚未运行，可记录为：ANDROID CLOSED / PASS + IOS WAITING_RUNTIME_VALIDATION。不得把未运行的平台写成 PASS。

25. 必做输出

本任务所有需要 ChatGPT/RDC 后续审查的文件必须由 Codex 在任务中实际生成，不得在结束后临时补要。

25.1 STEP 记录

生成：

docs/50_Step记录/STEP-093_ContinuousRange运行态综合验收_v1.md

如果同名主题已有版本，递增为 v2/v3……，不得覆盖旧版。

内容至少包括：起始 Git 基线、调查到的实际测试入口、新增/修改内容、Android/iOS 实际执行状态、验收矩阵、问题与修复、未执行项、当前状态、下一步。

25.2 Codex 完成报告

生成：

docs/报告/STEP-093_ContinuousRange运行态综合验收_Codex完成报告_v1.md

同主题已有版本时递增版本号。

报告至少包含：任务目标、修改文件、测试入口、diagnostics、build/test 实际结果、Android runtime 实际结果、iOS runtime 实际结果、PASS/FAIL/WAITING 状态、Git commit、push、Final HEAD、origin/particle/main、git status、未执行事项、风险与已知限制。

25.3 开发记录

追加：

粒子开发记录.md

只追加，不覆盖历史内容。

26. Git 规则

严格遵守项目 Git 规则：

  • 只提交本任务相关文件；
  • 禁止 git add -A；
  • 禁止 git add .；
  • 禁止 git reset --hard；
  • 禁止 git clean；
  • 不触碰无关 dirty/untracked；
  • 功能代码与文档可按合理 scoped commit 拆分；
  • push 到 origin/particle/main；
  • push 后确认 HEAD == origin/particle/main；
  • 最终确认 git status --short；
  • push 失败不得标记任务完成。

27. Codex 执行终态规则

Codex 本轮结束时必须给出真实状态，而不是默认写 PASS。

建议状态：

  • IMPLEMENTED / WAITING_RUNTIME_VALIDATION
  • PARTIAL / WAITING_ANDROID_RUNTIME_VALIDATION
  • ANDROID PASS / WAITING_IOS_RUNTIME_VALIDATION
  • CLOSED / PASS
  • BLOCKED
  • FAILED

如果只是完成测试工具与代码准备，而 RDC/用户尚未真正运行 Android，则只能标记等待运行态验收。

28. 明确不做

STEP-093 不做：

  • 任意 N-range planner；
  • 多 Continuous Range；
  • frequency class 自动分类；
  • 自动 Z-order；
  • anchor/marker layer；
  • 第二套 BOTTOM/CONTINUOUS/TOP metadata；
  • NavSea AIS 专用优化；
  • Alarm 专用优化；
  • Weather provider；
  • Route ETA；
  • LandMask 业务系统；
  • Wave/Tide 业务系统；
  • PBF 通用重构；
  • RenderGraph 大改；
  • 新粒子算法；
  • 粒子视觉美化；
  • unrelated performance tuning；
  • Jest。

29. 最终核心判定

STEP-093 最终不是检查“按钮能不能点”，而是验证 STEP-092 的核心架构在真实渲染中确实成立：

普通地图内容可以被合理拆成 Bottom / Top retained cache，Particle 所在 Continuous Range 保持高频实时绘制；Style 顺序仍然决定最终 Z-order；不存在的 retained range 不产生资源；缓存只在需要时失效，并在稳定状态持续复用。

只要这个结论还没有通过真实运行态证据建立，STEP-093 就不能写成最终 CLOSED / PASS。

Reference in New Issue View Git Blame Copy Permalink