pbl_scense_ext/README.md

pbl_scense_ext

PBL 覆盖层前端扩展模块（scense / scense_game 之上的 pbl_scense_ext 覆盖层与页面注册，M9）。

生成产物与入库边界

• wwwroot/pbl_overlay/*.ui（12 个覆盖层页面壳）是构建产物，不入库：仓库根 .gitignore 以条目 wwwroot/pbl_overlay/ 排除该目录 （module-development-spec「CRUD-Generated wwwroot Directories Must Not Be Git-Tracked」）。
• 生成时机（如实声明，不声称不存在的步骤）：截至本提交，apps/pbls/build.sh 没有调用 scripts/gen_overlay_pages.py 的步骤——实测 grep -n 'gen_overlay_pages' apps/pbls/build.sh 零命中（该脚本的语法验证步骤为 py_compile 全量检查，与生成页面壳无关）。因此新克隆 / 新部署环境必须显式执行 python3 scripts/gen_overlay_pages.py，否则 wwwroot/pbl_overlay/ 为空目录、 /pbl_overlay/<key>.ui 导航全量 404。把生成步骤接入应用构建脚本（模块安装之后、 wwwroot 软链之前）不在本模块职权内（build.sh 归应用侧所有），已由本任务交付说明 冒泡请 PM 派单跟踪；在其落地前，本模块文档不得声称存在一个不存在的构建步骤。
• 入库的交付物是生成器与事实源：scripts/gen_overlay_pages.py（生成器）、 wwwroot/i18n/{zh,en}/msg.txt（界面文案事实源）、wwwroot/overlay/*.js|*.css （覆盖层实现）、scripts/load_path.py（RBAC 路径登记）。
• 一致性自检（四条都必须成立：前两条验「入库边界」，第三条验「生成步骤接入前提」， 第四条验「本模块文档内不存在对 build.sh 生成步骤的编号化残留表述」）：

  git check-ignore -v wwwroot/pbl_overlay/home.ui   # 命中 .gitignore 的 wwwroot/pbl_overlay/
  git ls-files wwwroot/pbl_overlay                  # 空输出（无任何跟踪文件）
  # 前提检查：生成步骤是否已接入应用构建脚本；WARN = 尚未接入，新环境须手动生成
  grep -q gen_overlay_pages ../../apps/pbls/build.sh \
    || echo 'WARN: 生成步骤未接入 apps/pbls/build.sh，新克隆环境需手动执行 scripts/gen_overlay_pages.py'
  # 文档口径自检：本模块内不得残留对构建脚本生成步骤的编号化表述（期望 rc=1，零命中）
  grep -rnE '第 ?9 ?步' . --exclude-dir=.git ; echo "rc=$? (期望 1)"
  

  说明两点：
  1. 第四条自检刻意用 ERE 形式（第 + 可选空格 + 9 + 可选空格 + 步），一次性覆盖 「数字紧贴汉字」与「数字两侧带空格」两种写法，且该写法本身不会被自己命中——若把某种 字面量抄进本文档，README 自身就会成为 grep 的命中项，使「零命中」声明再次不可复现 （QC 复审 #1 指出的正是这类自验声明与实测不符的问题）。
  2. 第三条也可由生成器自检代跑：python3 scripts/gen_overlay_pages.py --check 会实测 apps/pbls/build.sh 并打印 OK: 或 WARN:（不改变返回码）。
• 新增/删除页面壳：改 gen_overlay_pages.py 的 PAGES 注册表 + wwwroot/overlay/pbl_overlay_core.js 的 PAGES + scripts/load_path.py 的 OVERLAY_PAGES 三处同源，再跑 python3 scripts/gen_overlay_pages.py --check（rc=0 才算通过）。