# STEP-102 RenderSegment 无 Placement 段局部复用记录 v1

状态：**进行中（代码完成，等待独立构建与运行验证）**
日期：2026-10-08

## 目标与基线

- 工作区：`/Users/tei/dev/MapLibreParticleLab-step102`
- 分支：`step102-placement-free-retained-locality`
- 起点 HEAD：`6df21dac38f072c5ad35b8dfc7ec5217509602bc`
- 工作合同：`docs/40_任务/STEP-102_RenderSegment无Placement段局部复用_Codex任务_v1.md`
- 设计依据：`docs/20_调查/RenderSegment多Retained段全局Placement门槛_粒子管理员审查说明_v3.md`
- 发布坐标：V19/V20 工作区与发行内容冻结；本 Step 不创建版本。

目标是让结构上没有 symbol layer 的 Retained Segment 在其他段 placement 活跃时继续独立缓存并经 main-buffer composite。

## 必做项

- [x] 基于 style layer type 查询结构性 placement capability；不使用当前帧 `needsPlacement()` 证明 placement-free。
- [x] full CPU 每段计算 placement gate；含 symbol 的段仍受 changed、fade 与 transition 保守门槛约束。
- [x] `segmentSupported` 和 fallback reason 按段生成；full CPU global-live 只移除纯 aggregate placement 条件。
- [x] 保留 3D、debug、MapMode、sprite/image、light 等真实全局门槛和既有 revision/key 失效。
- [x] diagnostics 增加结构、逐段 gate、实际 main-buffer 执行及全局 placement/execution 字段；RN TS 只增加诊断字段。
- [x] 新增 C++ 源码测试与 Android STEP-102 Validation fixture/日志场景。
- [x] 静态核对 Fast Path、mixed executor、C-001、RN method surface 未修改。
- [ ] C++ 编译与定向测试、Android 用户手工构建、设备场景、iOS/Metal 验证：尚未执行。

## 允许与禁止范围

代码修改仅在任务书允许的 renderer、RN diagnostics 类型、`retained_underlay_cache.test.cpp` 和 Android Particle Validation 文件。未修改 `visitRenderSegmentExecution()`、`tryRenderParticleFastFrame()`、`retainedRangeUsesPlacement()`、Placement 算法、NavSea、C-001、发布文件或总则。既有未跟踪 v2/v3 审查说明及任务书保持原样。

## 构建、测试与当前结果

只读源码/diff 审计及 `git diff --check` 已执行，后者通过；新增未跟踪文件另用 `git diff --no-index --check` 检查，无空白错误（差异本身使退出码为 1）。CMake/Ninja/Bazel、GTest、Android Gradle、APK/AAR、ADB、设备、Jest、NavSea、发布全部 **NOT RUN**。静态检查不构成运行态 PASS。

## 必做输出

- STEP-102 生产代码、C++ 测试源码、Android Validation 场景源码。
- `docs/报告/STEP-102_RenderSegment无Placement段局部复用_Codex完成报告_v1.md`。
- 本记录与 `粒子开发记录.md` 追加。
- 报告中列出精确后续验证命令、硬门槛、NOT RUN 与剩余风险。

## 阻塞与下一步

目前没有已观察到的编译或运行失败；真正结果仍未知。由 RDC/用户按报告完成 Native focused tests、用户手工 Android APK 构建和 T1/T2 设备场景，核对 R0/R1 的 `placementCapable`、`placementGatePassed`、`actualExecution` 与 build/reuse/invalidation。构建或设备失败时保留首个真实错误与日志，再按任务边界修复；本 Step 未进入后续发行阶段。

## RDC 独立验证补记（2026-10-08）

- 从现有工作树、任务书、v3 审查依据和项目总则恢复审查；原 Codex 阶段的 NOT RUN 记录保留，以下为新增 RDC 事实。
- `git diff --check`：退出码 0，PASS；无关的 `platform/windows/vendor/vcpkg` 子模块状态变化不纳入本任务。
- 以 AppleClang 对 `test/renderer/retained_underlay_cache.test.cpp` 执行 `-std=c++20 -fsyntax-only`：退出码 0，语法检查 PASS；不是 GTest 运行结果。
- 本地临时独立 C++ helper smoke 测试：结构性 symbol 判定、placement gate、全局 live reason 共 10 个断言，10/10 PASS；测试文件位于 `/tmp/step102-placement-smoke.cpp`，不是正式 GTest。
- Mac CMake `cmake --preset macos-metal`：配置退出码 1，阻塞于缺少 `libuv`；未进入 GTest 编译或运行，未安装/升级依赖。日志 `/tmp/step102-cmake-config.log`。
- 额外审查并修复 Android STEP-102 Validation 切换入口：进入该场景时停止 STEP-093 诊断轮询、清除 STEP-093/097 标志，避免旧场景轮询污染 STEP-102 证据。
- Metal Bazel Core 构建 `bazel build -c opt --//:renderer=metal //:mbgl-core` 已完成：退出码 0，642/642 actions，耗时 875.118s，产物 `bazel-bin/libmbgl-core.a`，构建 PASS；日志 `/tmp/step102-bazel-core.log`。该 PASS 仅表示 Native Core 编译，不代表 GTest/Android/运行态 PASS。
- Android Gradle/APK/ADB 与设备验证依任务规则均未执行；STEP-102 继续保持“进行中 / 待 Android 实际验收”，不得标记 CLOSED / PASS。

## V21 发布决策（2026-10-08）

用户明确接受未执行正式 GTest、Android T1/T2、iOS/Metal 运行态验证的风险，要求 STEP-102 经源码审查即纳入 V21 发行。代码审查未发现明确阻断项；先前 Metal Core 642/642 编译通过。本步骤依然不属于运行态验收 PASS。发布须完整执行 `prepare → build → publish → finalize`；发布记录应明确验收豁免。