# 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` 生成页面壳，并紧随其后以 `--check` 作为门禁
  （rc≠0 终止部署并打印原因）——实测 `grep -n 'gen_overlay_pages' apps/pbls/build.sh`
  命中。调用位置在模块安装（`pip install -e modules/pbl_*`）之后、模块 wwwroot 软链
  挂载之前，因此新克隆 / 新部署环境执行 `build.sh` 即自动产出 `wwwroot/pbl_overlay/*.ui`，
  无需人工干预。人工执行 `python3 scripts/gen_overlay_pages.py` 仅用于本地开发调试。
  反之，若该目录为空则 `/pbl_overlay/<key>.ui` 导航全量 404——构建期的 `--check`
  门禁就是为此前置拦截。
- **应用侧可达性（模块 wwwroot 挂载，已接入）**：页面壳生成在**本模块仓**的
  `wwwroot/pbl_overlay/` 下，而 `wwwroot/overlay/pbl_overlay_play.js` 的 `pageUrl()`
  请求的是应用侧 URL `/pbl_scense_ext/pbl_overlay/<key>.ui`；应用 `conf/config.json`
  的 `website.root=wwwroot` 只指向应用自身目录。因此 `apps/pbls/build.sh` 在生成 +
  `--check` 之后还有一步**模块 wwwroot 软链挂载**（`ln -sfn
  "${WS_DIR}/modules/<m>/wwwroot" "${APP_DIR}/wwwroot/<m>"`，对所有含 `wwwroot/`
  的 `pbl_*` 模块执行），并紧随其后以应用侧路径实测页面壳数量作为门禁
  （`find -L apps/pbls/wwwroot/pbl_scense_ext/pbl_overlay -maxdepth 1 -name '*.ui'`
  必须为 12，否则终止部署）。缺了这一步，生成物虽在磁盘上、应用侧仍取不到——
  这正是 QC 退回意见 #1 指出的「生成步骤接了、可达链路仍断」。软链（非拷贝）保证
  与模块仓单一副本同步；该软链由构建脚本产出，在应用仓 `.gitignore` 中以
  `wwwroot/pbl_*/` 排除，不入库。
- 入库的交付物是**生成器与事实源**：`scripts/gen_overlay_pages.py`（生成器）、
  `wwwroot/i18n/{zh,en}/msg.txt`（界面文案事实源）、`wwwroot/overlay/*.js|*.css`
  （覆盖层实现）、`scripts/load_path.py`（RBAC 路径登记）。
- 一致性自检（五条都必须成立：前两条验「入库边界」，第三条验「生成步骤接入前提」，
  第四条验「本模块文档内不存在对 build.sh 生成步骤的编号化残留表述」，第五条验
  「应用侧可达性（模块 wwwroot 已挂载进应用 wwwroot）」）：
  ```bash
  git check-ignore -v wwwroot/pbl_overlay/home.ui   # 命中 .gitignore 的 wwwroot/pbl_overlay/
  git ls-files wwwroot/pbl_overlay                  # 空输出（无任何跟踪文件）
  # 前提检查：生成步骤已接入应用构建脚本；未命中 = 接入被回退，须立即修复构建脚本
  grep -q gen_overlay_pages ../../apps/pbls/build.sh \
    && echo 'OK: 生成步骤已接入 apps/pbls/build.sh（构建期自动生成页面壳）' \
    || echo 'FAIL: 生成步骤未接入 apps/pbls/build.sh，新克隆环境 wwwroot/pbl_overlay/ 将为空'
  # 文档口径自检：本模块内不得残留对构建脚本生成步骤的编号化表述（期望 rc=1，零命中）
  grep -rnE '第 ?9 ?步' . --exclude-dir=.git ; echo "rc=$? (期望 1)"
  # 可达性自检：页面壳必须经应用 wwwroot 的模块软链取到（期望 12，先执行过 apps/pbls/build.sh）
  ls ../../apps/pbls/wwwroot/pbl_scense_ext/pbl_overlay/*.ui | wc -l
  ```
  说明三点：
  1. 第四条自检**刻意**用 ERE 形式（`第`+可选空格+`9`+可选空格+`步`），一次性覆盖
     「数字紧贴汉字」与「数字两侧带空格」两种写法，且该写法本身不会被自己命中——若把某种
     字面量抄进本文档，README 自身就会成为 grep 的命中项，使「零命中」声明再次不可复现
     （QC 复审 #1 指出的正是这类自验声明与实测不符的问题）。
  2. 第三条也可由生成器自检代跑：`python3 scripts/gen_overlay_pages.py --check` 会实测
     `apps/pbls/build.sh` 并打印 `OK:`（当前状态：已接入）或 `WARN:`（接入被回退时）。
     `warn_build_integration()` 作为常驻前提检查长期保留，只告警不改变返回码；真正决定
     部署成败的是构建脚本内紧随生成之后的那次 `--check` 门禁。
  3. 第四条自检的口径边界（QC 复审 #1 要求如实声明，避免后续复检误判）：该 grep 的作用域是
     **本模块仓库目录**（`modules/pbl_scense_ext`，排除 `.git`），实测 rc=1 零命中；而项目
     交付说明 `projects/pbls/docs/02-develop/dev-notes-m9-gitignore-build-integration.md`
     位于本模块仓库之外，因需原样引述退回意见原文与改动前后对照，仍会出现在该 grep 口径之外
     的编号化字样。后续复检请以「模块仓径 rc=1」为判定口径，勿把交付说明的引述计入命中项。
- 新增/删除页面壳：改 `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 才算通过）。