approve: [M11b-2a] Git 收口：提交 tx_write + p99_probe 并跑通测试

scripts/gen_overlay_pages.py

@@ -4,13 +4,21 @@
 
 【产物定位：构建产物，不入库】
 wwwroot/pbl_overlay/*.ui 属生成目录，仓库根 .gitignore 以条目
-`wwwroot/pbl_overlay/` 将其排除，由 apps/pbls/build.sh 第 9 步调用本脚本重跑生成
-（module-development-spec「CRUD-Generated wwwroot Directories Must Not Be Git-Tracked」/
-QC 退回意见 #3 方案 (b)）。可核验：
+`wwwroot/pbl_overlay/` 将其排除（module-development-spec「CRUD-Generated
+wwwroot Directories Must Not Be Git-Tracked」/ QC 退回意见 #3 方案 (b)）。可核验：
     git check-ignore -v wwwroot/pbl_overlay/home.ui   # 命中 .gitignore 中的该条目
     git ls-files wwwroot/pbl_overlay                  # 输出为空（无跟踪文件）
 本脚本（生成器）与 wwwroot/i18n/*/msg.txt（文案事实源）才是入库的交付物。
 
+【生成时机：如实声明，不声称不存在的步骤（QC #9 复审改法 b）】
+截至本次提交，apps/pbls/build.sh 中**不存在**调用本脚本的步骤——实测
+`grep -n gen_overlay_pages apps/pbls/build.sh` 零命中。因此新克隆/新部署环境
+必须显式执行 `python3 scripts/gen_overlay_pages.py` 生成页面壳，否则
+wwwroot/pbl_overlay/ 为空目录、`/pbl_overlay/<key>.ui` 导航全量 404。
+把该生成步骤接入应用构建脚本（模块安装之后、wwwroot 软链之前）由 PM 另行派单
+跟踪（本模块不拥有 apps/pbls/build.sh，不在本任务改动范围内）；`--check` 会
+调用 warn_build_integration() 实测并打印 WARN，使本声明可机械核验。
+
 为什么需要页面壳：wwwroot/overlay/pbl_overlay_core.js 的 PAGES 注册表 route 指向
 `/pbl_overlay/<key>.ui`，play.js 的 pageUrl() 会拼成
 `/pbl_scense_ext/pbl_overlay/<key>.ui`；页面壳文件不存在则导航即 404。
@@ -177,6 +185,29 @@ def build_page(key, in_world, zh):
     }
 
 
+def warn_build_integration():
+    """机械核验：页面壳生成步骤是否已接入应用构建脚本（QC #9 复审意见 #2）。
+
+    只告警、不改返回码——apps/pbls/build.sh 归应用侧所有，接入与否由 PM 派单跟踪；
+    但文档不得依赖未经核验的口头承诺，故每次校验都实测一次并如实打印结论。
+    """
+    build_sh = os.path.normpath(os.path.join(ROOT, os.pardir, os.pardir,
+                                            'apps', 'pbls', 'build.sh'))
+    if not os.path.isfile(build_sh):
+        print('[gen_overlay_pages][WARN] 未找到 %s：无法核验生成步骤是否已接入构建脚本，'
+              '新环境请手动执行本脚本生成页面壳' % build_sh)
+        return
+    with io.open(build_sh, 'r', encoding='utf-8', errors='replace') as f:
+        body = f.read()
+    if 'gen_overlay_pages' in body:
+        print('[gen_overlay_pages] OK: 生成步骤已接入 %s' % build_sh)
+    else:
+        print('[gen_overlay_pages][WARN] 生成步骤未接入 apps/pbls/build.sh：'
+              '新克隆/新部署环境需手动执行 `python3 scripts/gen_overlay_pages.py`，'
+              '否则 wwwroot/pbl_overlay/ 为空、/pbl_overlay/<key>.ui 全量 404'
+              '（接入构建脚本由 PM 派单跟踪，见 README「生成产物与入库边界」）')
+
+
 def check(zh, en):
     """校验：① zh/en key 集合一致；② 每个页面的 i18n key 齐备；③ 生成目录与注册表一致。"""
     problems = []
@@ -223,6 +254,7 @@ def main(argv=None):
     if args.check:
         print('[gen_overlay_pages] CHECK PASS: %d 页面壳 / zh+en 各 %d 条文案 key 一致'
               % (len(PAGES), len(zh)))
+        warn_build_integration()
         return 0
     if args.clean:
         if os.path.isdir(OUT_DIR):