STEP-106 STEP-102 T2 Placement 边界修正 — RDC 实施报告 v1

1. 当前判定

源码修正已提交、静态检查通过；Android/Kotlin 编译 NOT RUN、FZG 修正版设备验证 NOT RUN。

本阶段专门处理 STEP-105 的 T2_TWO_FREE 未达到预期问题。保留原 STEP-105 PARTIAL 状态直至修正版 APK 手工编译和 FZG 定向运行 Gate 全部通过。没有改动核心 Renderer 的 Placement 容错判定。

2. 旧版同设备复现

设备 FZG1-2，Android 13，x86_64，ADB 192.168.200.139:5555。

先核对旧、新 APK 的包名相同为 org.maplibre.android.testapp、versionCode 均为14、证书 SHA-256 均为 e3f8fae6451ed6322259d090dd8e8788df554ab25ed89a01c78014f1d5ef8236。旧版文件 SHA-256 为 999f773276b29fffae05c1edc977e19df6cebecd94e4a4095508d0c5e97e07c2。

临时 adb install -r 安装旧版 13.4.1-particle.21，运行：

adb -s 192.168.200.139:5555 shell am start -W -n org.maplibre.android.testapp/.activity.particle.ParticleCoreLayerValidationActivity --es step102_scenario T2_TWO_FREE

流式 Logcat 在 tick29/30 记录：R0 placementCapable=false/gate=true/composite/reuse 正常；R1 placementCapable=true/gate=false/actual=live/fallback=static-placement/build0/reuse0。因而确认该现象旧 .21 同样存在，不是已证明由官方 Native 13.6.1 升级新引入。

立即 adb install -r 恢复已签名的新 13.6.1，返回 Success；设备已安装 base.apk 的 SHA-256 为 77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa，和 Mac 现有新 APK 完全一致。随后重新启动不带 Extra 的 Particle Core Layer Validation Activity，版本仍 13.6.1。

证据位于 Git 忽略目录 artifacts/maplibre-particle/step105-fzg-t2-rootcause-20261009/old21-t2-stream.log，以及先前 step105-fzg-runtime-20261009/09-step102-t2/stream.log。

3. 可核对的源级原因

13.6.1 的 src/mln/annotation/annotation_manager.cpp 中，AnnotationManager::updateStyle() 会创建名为 org.maplibre.annotations.points 的 Symbol Layer 并追加至 Style。旧 .21 的 src/mbgl/annotation/annotation_manager.cpp 保留同样逻辑。

原测试计划为 R0 RETAINED → C0 CONTINUOUS 从 step102-particle 开始 → R1 RETAINED 从 step102-upper 开始并延伸到 Style 最后一层。测试 fixture 的 T2 step102-upper 是 Fill，但 R1 还包含默认追加的 Annotation Symbol。RenderSegment 层级的 renderSegmentHasPlacementCapableLayer() 只要在范围内看到 Symbol 即正确地判 true；在 fade/placement 期间 fallback static-placement 是安全行为，不能绕过。

这是对代码结构和两版设备现象的一致解释。真实 Style 的完整 styleLayers 数组先前没有输出，因此最终边界还要等待修正版新增诊断进一步核对；不得在这里宣称 Pixel/GPU 原因已由运行时完整证明。

4. 修改与保护边界

源码分支：upgrade/android-native-13.6.1-20261009。

代码提交：86906c8a6af474a8d064c6f6d7d431e2a7e3efe6 — test(android): isolate internal annotation symbol from STEP-102 retained ranges。

两个文件：

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/Step102PlacementFixture.kt：为 T1、T2 共用计划增加最后一段 CONTINUOUS，startLayerId=org.maplibre.annotations.points，使原 R1 只包含自有上层。两场景保持相同边界。若默认 Layer 不存在，现有 Plan resolver 会因 boundary-layer-missing fail-closed，不会错误地忽略该层。
platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt：在 tick8 输出一次 STEP102_STYLE_LAYER_LAYOUT，包含 Style Layer id/type/index 与四段 begin/end，用实际测试证据验证上层边界。

没有修改 src/mln、include/mln、Renderer、Shared Core、NavSea 或 iOS，也未改变任何公开 API/ABI。

新增 C2 使本测试由 R-C-R 变为 R-C-R-C，并可能失去“仅一个 Continuous”的 Particle fast-path 优化条件：这是仅用于证明两个 Retained 在真实内部 Annotation 层存在时安全局部复用的独立测试布局，不能当作生产性能验证或建议宿主一律使用四区段布局。

5. 当前检查结果

git diff --check PASS。
静态合成 Style 解析：T1 的 R1 为 Symbol，T2 的 R1 为 Fill，Annotation Symbol 位于 C2；模拟边界覆盖完整且无空段，PASS（非 Kotlin 构建、非真实 Runtime）。
Android Gradle/Kotlin Build：NOT RUN（用户手工编译）。
更新版 Validation APK：NOT BUILT。
FZG 新计划的 T1/T2 tick8/130：NOT RUN。
其它 ABI / iOS / NavSea / Jest：NOT RUN。

6. 用户手工编译与 RDC 验收

Mac 终端：

cd /Users/tei/dev/MapLibreParticleLab-upgrade-android-1361
export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
export ANDROID_HOME=/Users/tei/Library/Android/sdk
export ANDROID_SDK_ROOT="$ANDROID_HOME"
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$PATH"
export MAPLIBRE_VALIDATION_OUT_DIR="$PWD/artifacts/maplibre-particle/step106-t2-fix"
./tools/particle_android_validation/build_validation_apk.sh

脚本自带 Gradle --console=plain、Native ABI/体积/ZIP 检查。用户编译后由 RDC 确认 Git 源码 SHA、包名、签名、APK SHA，再 adb install -r 到 FZG。

验收应分别运行 STEP-102 T1_FREE_SYMBOL 与 T2_TWO_FREE（明确传 --es step102_scenario <SCENARIO>），在 tick8 和 tick130 读取 STEP102_STYLE_LAYER_LAYOUT / STEP102_SAMPLE / STEP102_WINDOW_MARKER。对 T2 需要 R0 和 R1 同时 placementCapable=false、gate=true、actualExecution=composite；各自 buildDelta=0、invalidationDelta=0、reuseDelta>0；C2 live 且保持 Z-order。T1 的 R1 为 Symbol，应继续按现有安全 gate fallback；检查样本和崩溃日志。之后最小回归 STEP-099 T4、STEP-101 Native reset、QBIN V4 Golden，失败须保留现场。

7. Gate

SOURCE_FIXED / STATIC_PASS / BUILD_PENDING / DEVICE_PENDING。

任何未编译、未安装新版修正 APK 的设备日志不能被用来宣称 STEP-106 PASS。待 RDC 收到用户手工编译成功的制品后，才进入下一阶段设备验收和最终关闭。

6.2 KiB Raw Blame History Unescape Escape