diff --git a/docs/40_任务/STEP-093_ContinuousRange运行态综合验收_Codex任务_v1.md b/docs/40_任务/STEP-093_ContinuousRange运行态综合验收_Codex任务_v1.md new file mode 100644 index 000000000..7a1a033f8 --- /dev/null +++ b/docs/40_任务/STEP-093_ContinuousRange运行态综合验收_Codex任务_v1.md @@ -0,0 +1,652 @@ +# 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`。 diff --git a/docs/50_Step记录/STEP-093_ContinuousRange运行态综合验收_v1.md b/docs/50_Step记录/STEP-093_ContinuousRange运行态综合验收_v1.md new file mode 100644 index 000000000..c9591fe67 --- /dev/null +++ b/docs/50_Step记录/STEP-093_ContinuousRange运行态综合验收_v1.md @@ -0,0 +1,238 @@ +# STEP-093 Continuous Range 运行态综合验收 v1 + +## 1. 当前状态 + +**IMPLEMENTED / WAITING_RUNTIME_VALIDATION** + +Codex 已完成 Android 运行态验收入口、跨平台 diagnostics 补强、Fast Path fail-closed 原因观测、定向 Native 测试源码和 RDC 操作手册。依照仓库职责分工与本轮用户指令,Codex 未执行 Android/iOS 长时间编译、安装、ADB、模拟器/真机操作或视觉验收。因此 Android 为 `WAITING_ANDROID_RUNTIME_VALIDATION`,iOS/Metal 为 `WAITING_IOS_RUNTIME_VALIDATION`;本版不能标记 `CLOSED / PASS`。 + +## 2. 起始 Git 基线 + +- Repository:`MapLibreParticleLab` +- 机器:`Mac-mini-tei.lan` +- 路径:`/Users/tei/dev/MapLibreParticleLab` +- Branch:`particle/main` +- Starting HEAD:`8a5d88008c142e2a80e0ff602d228e0e67de2d83` +- Starting `origin/particle/main`:`8a5d88008c142e2a80e0ff602d228e0e67de2d83` +- STEP-092 基线:`CLOSED / PASS(Mac Native 验证闭环)` +- STEP-093 implementation commit:`b3ec8edc87ece404b5f7b3706f5acf2a70de6862` +- 起始工作树差异:仅有本任务书 `docs/40_任务/STEP-093_ContinuousRange运行态综合验收_Codex任务_v1.md` 为 untracked;已保留并纳入本 Step 文档提交。 + +## 3. 实际调查到的测试入口 + +Android 已有入口为 `MapLibreAndroidTestApp` 的 `ParticleCoreLayerValidationActivity`。本 Step 复用该 Activity、既有 Host-submitted particle fixture、`weather-color` 和普通 Style layer,不建立新测试框架,也不引入特殊 layer type。 + +新增底部 `STEP 093` 菜单与常驻 diagnostics 区。入口支持: + +- A:Bottom + Continuous + Top; +- B:Bottom + Continuous; +- C:Continuous + Top; +- D:Continuous only; +- E:Single-layer Continuous; +- Continuous/Bottom/Top add 与 reorder; +- 普通 layer 跨 Bottom/Continuous/Top 移动; +- start/end endpoint visibility、删除与恢复; +- missing start、missing end、reversed、style loading 期间配置、empty ID、恢复 valid; +- Camera preset 循环覆盖 pan/zoom/rotate/pitch; +- Continuous 内未知普通 layer 触发 Fast Path fail-closed; +- 1 秒一次的屏幕 pull diagnostics;仅用户点 `READ DIAGNOSTICS` 或场景切换时写一条日志,不制造逐帧日志风暴。 + +Android Activity 声明增加 `orientation|keyboardHidden|screenSize` config changes,使 RDC 可在不重建 Map/Style 的前提下用旋转或尺寸变化观察 viewport invalidation。 + +iOS 当前只有正式 `MLNMapView` diagnostics API 与 RN bridge 字段补齐,没有新增专用 STEP-093 iOS validation 页面。因此 iOS runtime 必须后续由 RDC 准备实际入口并执行,不能由 Android 结果推导。 + +## 4. 本轮新增/修改内容 + +### 4.1 Renderer diagnostics + +在既有 map-scoped diagnostics 上追加,而非另造一套状态源: + +- Range:`continuousBegin`、`continuousEndExclusive`、`rangeFallback`; +- Bottom/Top:`cacheState`、build/reuse/invalidation、last invalidation reason; +- 资源生命周期:texture create、composite create、resource release; +- Fast Path:eligible、active、fallback reason、hit、miss、full CPU frame; +- 未知 Continuous layer 的明确原因:`unsupported-continuous-layer`。 + +这些 counter 是 Map 生命周期内累计事件数,不是 GPU memory byte 数。它们用于证明 stable frame 不重复创建资源及 invalidation 后能重建/reuse;不能替代 profiler 或 GPU capture。 + +### 4.2 跨端暴露 + +- Android JNI/Java:diagnostics 字符串数组由 20 项扩为 39 项,Java 构造索引与 Native 顺序逐项一致; +- iOS ObjC++:`MLNRetainedUnderlayDiagnostics` 暴露同组字段; +- RN Android/iOS/TypeScript/Test Host:透传并显示同组字段; +- 原有 aggregate build/reuse/fallback/invalidation 字段保持,不删除兼容语义。 + +### 4.3 Android 可视场景 + +测试 Style 中仅使用普通 background/fill/line、已有 WeatherColor 与 RasterParticle: + +- Bottom:深色 background + 青色 fill; +- Continuous:WeatherColor + Particle; +- Top:半透明黄色 fill、opaque 红色 fill、白色粗 line; +- fail-closed:在 Continuous 内加入普通 fill; +- cross-range:同一个普通 fill ID 分别位于 endpoint 前、endpoint 间、endpoint 后。 + +最终 Z-order 仍完全由 Style layer 数组顺序决定。App 只调用 `setContinuousLayerRange(startLayerId, endLayerId)`;没有 anchor/marker、业务 layer metadata 或 Renderer 业务 ID 硬编码。 + +### 4.4 定向测试源码 + +新增 `RetainedUnderlayCache.RuntimeValidationDiagnosticsExposeRangeResourcesAndFastPath`,覆盖 Continuous index、cache state、资源 counter、Fast Path counter;既有 Fast Path gate 测试增加 `UnsupportedContinuousLayer` 原因断言。 + +本轮未运行 test runner。STEP-092 既有 29/29 PASS 是历史基线,不能当作新增测试已通过;RDC 运行后预期相关 filter 共 30 项,但必须以实际 runner 输出为准。 + +## 5. 静态一致性审查 + +Codex 已完成: + +- Native diagnostics 定义、runtime state、Android JNI/Java、iOS、RN 字段名与顺序逐项比对; +- 四种 topology 与 single-layer 的 Style layer 顺序/endpoint 位置审查; +- mutation、cross-range、endpoint、invalid、camera、fail-closed 菜单接线审查; +- absent Bottom/Top 仍沿用 STEP-092 `Disabled` / lazy resource 路径,没有新增固定 GPU 分配; +- Fast Path eligibility 与 decision counter 接入既有 gate,失败仍进入 full CPU frame; +- `xmllint --noout`:Android Manifest 与 layout PASS; +- `git diff --check`:PASS。 + +未执行:C++/Java/Kotlin/ObjC++/TypeScript 编译、Native tests、Gradle、APK、ADB、Android/iOS runtime。静态审查不等于运行态 PASS。 + +## 6. RDC Android 构建、安装与启动 + +在仓库根目录执行: + +```bash +./tools/particle_android_validation/build_validation_apk.sh +adb devices +adb -s install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk +adb -s shell am start -n org.maplibre.android.testapp/.activity.particle.ParticleCoreLayerValidationActivity +``` + +可选定向日志: + +```bash +adb -s logcat -c +adb -s logcat -v threadtime ParticleValidation:I MapLibre:I '*:S' +``` + +若使用非 x86_64 真机,当前 validation script 的固定 ABI 不适用;RDC 应按项目现行 Android 构建规则选择相符 ABI,并在证据中记录实际 APK、commit、ABI、设备与 renderer backend。 + +## 7. RDC Native 精确回归命令 + +如 RDC 使用 STEP-092 的现有 OpenGL build tree: + +```bash +cmake --build build-step088-opengl --target mbgl-test-runner -j3 +build-step088-opengl/mbgl-test-runner --gtest_filter='ContinuousLayerRange.*:RetainedDynamicBoundary.*:RetainedLayerGroupRange.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*' +``` + +必须记录真实 test 数与结果;不能直接抄写“30/30”。 + +## 8. Android 逐项运行手册 + +### 8.1 通用观察方法 + +启动 Activity 后点 `STEP 093`。每次切场景等待 Style READY,再观察屏幕 diagnostics;需要固化证据时点 `READ DIAGNOSTICS` 并保存日志/截图。稳定性判断建议至少间隔 10–30 秒采两次快照: + +- Particle 持续运动; +- 对存在的 cache,build/texture/composite 不再增长,reuse 与 Fast hit 应增长; +- 不存在的 range 显示 `present=false`、`state=disabled`,对应资源创建数不因稳定帧增长; +- counter 为累计值,切场景时应比较增量,不要求绝对值归零。 + +### 8.2 Topology A–E + +1. A:选 `A BOTTOM + CONTINUOUS + TOP`。预期 range valid、Bottom/Top present、cache count 2;opaque 红块完整盖住 Particle,黄色半透明区域正确混合,白线在最上层,无黑边/halo/错误变暗。 +2. B:选 `B BOTTOM + CONTINUOUS`。预期 Bottom present、Top absent、cache count 1;Top state disabled,Top 资源不增长,Fast Path 不因 Top absent 被阻断。 +3. C:选 `C CONTINUOUS + TOP`。预期 Bottom absent、Top present、cache count 1;Bottom state disabled;Top 仍正确覆盖 Particle。 +4. D:选 `D CONTINUOUS ONLY`。预期 valid、Bottom/Top 均 absent、cache count 0、不是 fallback;Particle 正常运行,Fast Path 可命中。 +5. E:选 `E SINGLE-LAYER CONTINUOUS`。预期 start ID 等于 end ID、startIndex 等于 endIndex、`continuousEndExclusive = startIndex + 1`,不 fallback。 + +### 8.3 Mutation 与跨边界 + +在 `MUTATION / FAST PATH` 子菜单依次执行: + +- `CONTINUOUS ADD` → `CONTINUOUS REORDER` → `RESTORE DEFAULT`:恢复动作也等价验证非 endpoint layer 删除; +- `BOTTOM ADD` → `BOTTOM REORDER` → restore; +- `TOP ADD` → `TOP REORDER` → restore; +- `CROSS → BOTTOM` → `CROSS → CONTINUOUS` → `CROSS → TOP`。 + +每次检查 endpoint ID 重新解析出的 index、present topology、invalidation/build/reuse 增量及最终画面顺序;不得出现旧 index、旧 cache 或自动按 layer 类型修正 range。 + +### 8.4 Endpoint 与 visibility + +在 `ENDPOINT / VISIBILITY` 子菜单: + +- start visible ↔ hidden、end visible ↔ hidden:index 与 topology 不变,hidden endpoint 仍是 endpoint; +- `DELETE START`:range invalid、fallback、无 crash/stale cache;`RESTORE START` 后恢复 valid 并 rebuild/reuse; +- 对 end 执行同样步骤。 + +### 8.5 Invalid explicit range + +在 `INVALID RANGE` 子菜单依次执行 missing start、missing end、reversed、configure while style loading、empty ID、restore valid: + +- missing/reversed/style-not-ready:不得猜测 endpoint,不复用 stale cache,diagnostics 给出原因; +- empty ID:当前 API 应同步返回 `accepted=false`; +- restore 后无需重建 Map instance,应重新 valid、build、reuse。 + +### 8.6 Camera/viewport + +连续点四次 `CAMERA NEXT`,覆盖 target/zoom/bearing/pitch 组合。每次检查 invalidation → build → reuse,topology 不变,无错位、黑屏或 Particle/地图不同步。 + +旋转设备或改变模拟器窗口尺寸,确认同一 Activity/Map 上产生 viewport invalidation;如设备支持可改变 display scale/pixel ratio,并单独记录是否实际触发。 + +### 8.7 Fast Path fail-closed + +先恢复 A,稳定后确认 eligible/active 与 hit 增长。再选 `FAST FAIL-CLOSED`: + +- Continuous Range 仍 valid; +- fallback reason 为 `unsupported-continuous-layer`; +- Fast Path 不 active,full CPU frame 增长; +- 普通未知 layer 不被跳过或移出 Continuous; +- Bottom/Top 与最终 Z-order 仍正确。 + +### 8.8 长时间运行 + +建议 RDC 在可用设备上连续运行 15–30 分钟,循环 topology、camera、mutation、endpoint、visibility、invalid/restore、再次稳定:观察 texture/composite create 与 release 增量、系统内存/GPU 工具可获得的数据、黑屏/闪屏/stale cache/偶发层序/Particle 恢复。若没有可靠 GPU byte 数,明确记录限制,不伪造内存数字。 + +## 9. PASS / FAIL 判定 + +- `PASS`:必须有实际设备/模拟器操作、画面确认与 diagnostics/log 证据,并满足该行预期。 +- `FAIL`:实际结果违背预期;保留首个真实错误、场景、截图/日志和 commit。 +- `WAITING_*`:入口已准备但平台尚未执行。 +- 编译 PASS、静态检查 PASS、另一平台 PASS 均不能替代当前平台 runtime PASS。 + +## 10. 验收矩阵 + +| 类别 | 场景 | Android | iOS/Metal | 关键证据 | 结论 | +|---|---|---|---|---|---| +| Topology | Bottom+Continuous+Top | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | A 按钮、range/index、2 cache、画面截图待采集 | NOT RUN | +| Topology | Bottom+Continuous | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | B 按钮、Top disabled/资源增量待采集 | NOT RUN | +| Topology | Continuous+Top | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | C 按钮、Bottom disabled/资源增量待采集 | NOT RUN | +| Topology | Continuous-only | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | D 按钮、valid + 0 cache + 非 fallback 待采集 | NOT RUN | +| Range | Single-layer Continuous | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | E 按钮、start=end、endExclusive=start+1 待采集 | NOT RUN | +| Z-order | Top covers Particle | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | opaque/semi-transparent/line 视觉截图待采集 | NOT RUN | +| Cache | Stable reuse | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | 两次 counter 快照待采集 | NOT RUN | +| Invalidation | Pan/Zoom/Rotate/Pitch | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | camera preset 前后 invalid/build/reuse 待采集 | NOT RUN | +| Mutation | Continuous internal mutation | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | add/reorder/restore diagnostics 待采集 | NOT RUN | +| Mutation | Cross-range move | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | cross layer 三位置的 index/Z-order 待采集 | NOT RUN | +| Endpoint | start missing/recovery | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | invalid reason + restore valid 待采集 | NOT RUN | +| Endpoint | end missing/recovery | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | invalid reason + restore valid 待采集 | NOT RUN | +| Visibility | hidden endpoint topology | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | visible/hidden index 不变待采集 | NOT RUN | +| Invalid | missing/reversed range | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | fallback/lastReason/no stale cache 待采集 | NOT RUN | +| Fast Path | eligible | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | eligible/active/hit/full counter 待采集 | NOT RUN | +| Fast Path | unknown layer fail-closed | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | unsupported reason/full CPU frame 待采集 | NOT RUN | +| Alpha | Top premultiplied composite | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | transparent/opaque/semi/line 视觉证据待采集 | NOT RUN | +| Stability | repeated operations / long run | WAITING_ANDROID_RUNTIME_VALIDATION | WAITING_IOS_RUNTIME_VALIDATION | 长时间 counter/内存/画面记录待采集 | NOT RUN | + +## 11. 问题、限制与未执行项 + +- 未发现需要修改 STEP-092 数学定义、Style 顺序、0/1/2 cache 或 Fast Path 核心模型的架构阻塞。 +- diagnostics 是累计 counter,不是 per-scene reset;RDC 应使用前后增量。 +- 资源 release counter 表示 holder 释放事件,不是释放字节数。 +- Android 场景 Style reload 是可重复的测试手段;跨场景比较必须等待 READY。 +- 当前 iOS 没有专用 STEP-093 面板,只有 diagnostics API/bridge;这是明确待办,不虚报 iOS runtime 能力完成。 +- Android/iOS build、Native tests、APK、安装、ADB、真机/模拟器、视觉、长时间运行均 NOT RUN。 + +## 12. 下一步 + +1. RDC 对 implementation commit `b3ec8edc87ece404b5f7b3706f5acf2a70de6862` 执行 Native 精确回归与 Android build/runtime 矩阵。 +2. 若 Android 核心矩阵全部实际通过,可更新为 `ANDROID CLOSED / PASS + IOS WAITING_RUNTIME_VALIDATION`。 +3. 准备 iOS/Metal 对等 validation UI 或可重复操作入口,再独立执行 iOS 矩阵。 +4. 只有任务书 24 节全部完成、Git 与文档闭环后,才能更新为 `CLOSED / PASS`。 diff --git a/docs/报告/STEP-093_ContinuousRange运行态综合验收_Codex完成报告_v1.md b/docs/报告/STEP-093_ContinuousRange运行态综合验收_Codex完成报告_v1.md new file mode 100644 index 000000000..23e5a241a --- /dev/null +++ b/docs/报告/STEP-093_ContinuousRange运行态综合验收_Codex完成报告_v1.md @@ -0,0 +1,127 @@ +# STEP-093 Continuous Range 运行态综合验收 Codex 完成报告 v1 + +## 1. 交付结论 + +**IMPLEMENTED / WAITING_RUNTIME_VALIDATION** + +Codex 已完成 STEP-093 所需的 Android 可重复运行态测试入口、最小 diagnostics 可观察性、Fast Path fail-closed 原因、跨平台字段透传与定向测试源码,并完成静态一致性审查。Android/iOS runtime 均未实际执行,所以没有任何运行态场景被标记为 PASS。 + +## 2. Git 信息 + +- Repository:`/Users/tei/dev/MapLibreParticleLab` +- Branch:`particle/main` +- Starting HEAD / starting remote:`8a5d88008c142e2a80e0ff602d228e0e67de2d83` +- Implementation commit:`b3ec8edc87ece404b5f7b3706f5acf2a70de6862`(`feat: add STEP-093 runtime validation tooling`) +- Documentation closeout:本报告所在 scoped commit,在报告写入后生成;准确 hash、push 和最终 remote 回读以最终交付消息为准。 + +## 3. 修改文件 + +Core/Renderer: + +- `include/mbgl/renderer/retained_underlay.hpp` +- `src/mbgl/renderer/particle_fast_path.hpp` +- `src/mbgl/renderer/renderer_impl.cpp/.hpp` +- `src/mbgl/renderer/retained_underlay_cache.cpp/.hpp` +- `src/mbgl/renderer/retained_underlay_runtime_state.hpp` +- `test/renderer/retained_underlay_cache.test.cpp` + +Android: + +- `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp` +- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/RetainedUnderlayDiagnostics.java` +- Test App Manifest、validation Activity 与 layout。 + +iOS / RN: + +- `platform/ios/src/MLNMapView.h/.mm` +- RN TypeScript types/spec、Android/iOS bridge、RN Test Host diagnostics display。 + +文档: + +- STEP-093 任务书、Step 记录、Codex 完成报告; +- `粒子开发记录.md` 追加记录。 + +## 4. 测试入口 + +Android:启动 `ParticleCoreLayerValidationActivity`,点击底部 `STEP 093`。菜单提供 A/B/C/D 四种 topology、E single-layer、mutation/cross-range、endpoint/visibility、invalid range、camera 与 Fast Path fail-closed;屏幕显示完整 pull diagnostics。 + +iOS:正式 diagnostics API 与 RN bridge 字段已补齐,但本轮没有建立/运行 iOS 专用 STEP-093 validation UI。状态为 `WAITING_IOS_RUNTIME_VALIDATION`。 + +完整 RDC 命令、逐项操作、判定标准和验收矩阵见同版本 Step 记录。 + +## 5. Diagnostics + +新增并端到端暴露: + +- Range configured/valid/IDs/index/continuous bounds/fallback/last reason; +- Bottom/Top present/cache state/build/reuse/invalidation/last reason; +- Bottom/Top texture create/composite create/resource release; +- Fast Path eligible/active/fallback reason/hit/miss/full CPU frame; +- unsupported Continuous layer 的 `unsupported-continuous-layer` 原因。 + +所有数据复用 STEP-092 map-scoped runtime state;没有增加 topology metadata 或 Z-order 真相源。counter 只代表事件累计,不代表 GPU memory bytes。 + +## 6. 静态审查与实际测试结果 + +实际执行并通过: + +- Native → Android/iOS → RN diagnostics 字段与 Android 39 项 ABI 索引静态核对; +- 场景 layer 顺序、endpoint 与菜单接线静态审查; +- `xmllint --noout` 检查 Test App Manifest/layout:PASS; +- `git diff --check`:PASS。 + +明确未执行: + +- CMake/Ninja/Xcode/Gradle 编译:NOT RUN; +- Native directed tests:NOT RUN; +- TypeScript/codegen/Android JNI 实际编译:NOT RUN; +- APK build/install、ADB、模拟器/真机:NOT RUN; +- Android runtime/视觉/长时间运行:`WAITING_ANDROID_RUNTIME_VALIDATION`; +- iOS/Metal runtime/视觉/长时间运行:`WAITING_IOS_RUNTIME_VALIDATION`; +- Jest:未新增、未执行。 + +STEP-092 的 OpenGL/Metal build 与 29/29 tests 是起始历史证据,不是本轮新增代码的验证结果。 + +## 7. Android runtime 结果 + +**WAITING_ANDROID_RUNTIME_VALIDATION** + +没有执行 Android Gradle、APK、ADB、安装、启动或画面操作。A–E、Z-order、stable reuse、invalidation、mutation、endpoint、visibility、invalid、Fast Path 与 alpha 全部为 NOT RUN。 + +## 8. iOS/Metal runtime 结果 + +**WAITING_IOS_RUNTIME_VALIDATION** + +没有执行 iOS build/install/simulator/device/Metal runtime。Android 后续即使 PASS,也不能自动推导 iOS PASS;Metal Native build 历史结果也不能替代 runtime rendering。 + +## 9. 架构边界 + +本轮没有: + +- 修改 `[startLayerId,endLayerId]` 闭区间或内部半开区间数学; +- 增加第二套 Bottom/Continuous/Top metadata; +- 增加 anchor/marker、特殊 layer type、多 range 或频率分类; +- 在 Renderer 硬编码业务 Layer ID; +- 重构 RenderGraph/PBF/Particle 算法; +- 把 visibility 变成 topology 规则; +- 为 Fast Path 移动未知 Continuous layer。 + +Style layer 顺序仍是唯一 Z-order 真相;App 只提供 endpoint ID,Native 解析 index。 + +## 10. 风险与已知限制 + +- 尚无任何运行态证据,不能确认真实 GPU 资源、画面合成或平台差异。 +- Android diagnostics 每秒 pull 一次但不逐秒 log;证据需手动 `READ DIAGNOSTICS`、截图或外部采样。 +- counter 在同一 Map 生命周期累计,RDC 应对比增量。 +- iOS 缺专用 STEP-093 validation 页面,需后续补齐实际可操作入口。 +- 本轮新增定向测试源码尚未编译/运行,任何预期 test 数都不能写成 PASS。 + +## 11. 最终状态 + +- 实现:完成; +- 静态一致性审查:完成; +- Android runtime:`WAITING_ANDROID_RUNTIME_VALIDATION`; +- iOS/Metal runtime:`WAITING_IOS_RUNTIME_VALIDATION`; +- 综合:**IMPLEMENTED / WAITING_RUNTIME_VALIDATION**。 + +Git push、`HEAD == origin/particle/main` 与 clean worktree 由本报告之后的 scoped 文档提交和最终回读确认;这些 Git 结果不改变 runtime 尚未执行的事实。 diff --git a/粒子开发记录.md b/粒子开发记录.md index 3abd54f85..0f70dd1ba 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -908,3 +908,11 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2` - RDC 修复两处验证期问题:legacy LayerRenderItem index 访问;runtime disable aggregate invalidation 重复计数。 - RDC 修复提交:`4908244d2 fix: close STEP-092 native validation issues`。 - 新增 v2 Step 记录与 v2 完成报告;Android Gradle/APK/ADB/实体机及 Metal frame capture 未执行,后续如需要单独做产品级验证。 + +### 2026-09-24 STEP-093 Continuous Range 运行态综合验收工具准备 + +- 复用 Android `ParticleCoreLayerValidationActivity` 新增 STEP-093 面板:一键 A/B/C/D 四种 topology、E single-layer、Bottom/Continuous/Top mutation、普通 layer 跨边界、endpoint visibility/delete/restore、invalid range、camera preset 与 Fast Path fail-closed。 +- 在 STEP-092 map-scoped diagnostics 上补充 continuous bounds、Bottom/Top cache state 与失效原因、texture/composite create/release、Fast Path eligible/active/reason/hit/miss/full CPU frame;Android JNI/Java、iOS ObjC++ 与 RN bridge/types/display 同步透传,没有建立第二套 topology 或 Z-order 真相。 +- 测试 Style 用普通 background/fill/line 构造清晰的 Bottom、Particle Continuous、Top opaque/semi-transparent/line 覆盖关系;资源与 Fast Path counter 通过屏幕低频 pull 展示,不产生逐帧日志风暴。 +- 静态字段/场景接线审查、Android Manifest/layout `xmllint` 与 `git diff --check` PASS。依照职责分工,本轮未执行 Native/Gradle/Xcode 编译、tests、APK、ADB、安装或 Android/iOS runtime;两平台均为 `WAITING_RUNTIME_VALIDATION`,不得写 PASS。 +- implementation commit:`b3ec8edc87ece404b5f7b3706f5acf2a70de6862`(`feat: add STEP-093 runtime validation tooling`)。完整 RDC 命令、操作步骤、证据要求与 18 项矩阵见 STEP-093 v1 记录。