5403f8ef1b
- .gitignore：注释补全「生成 + 模块 wwwroot 软链挂载」两步链路，指向 README 可机械核验的前提检查 - README.md：一致性自检由四条扩为五条（新增第五条=应用侧可达性），补「应用侧可达性（模块 wwwroot 挂载，已接入）」段，说明 pageUrl() 请求的应用侧 URL 与 website.root 的边界、软链非拷贝的理由、应用仓以 wwwroot/pbl_* 排除不入库 - scripts/gen_overlay_pages.py：warn_build_integration() 由「只验生成步骤」加强为「同时实测生成调用与模块 wwwroot 挂载步骤」，两项齐备才打印 OK，任一项被回退打印 WARN（只告警不改返回码）；docstring 同步「生成 + 自动挂载」口径 - 选择性 git add：仅上述 3 个文件，未 add wwwroot/（生成产物目录 wwwroot/pbl_overlay/ 已由 .gitignore:19 排除，git ls-files 为 0） - 自检：gen_overlay_pages.py --check rc=0（12 页壳 / zh+en 各 24 key 一致 / 生成+挂载均已接入）、load_path.py --audit rc=0（零输出）
5.5 KiB
5.5 KiB
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）」）：
说明三点：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- 第四条自检刻意用 ERE 形式（
第+可选空格+9+可选空格+步），一次性覆盖 「数字紧贴汉字」与「数字两侧带空格」两种写法，且该写法本身不会被自己命中——若把某种 字面量抄进本文档，README 自身就会成为 grep 的命中项，使「零命中」声明再次不可复现 （QC 复审 #1 指出的正是这类自验声明与实测不符的问题）。 - 第三条也可由生成器自检代跑：
python3 scripts/gen_overlay_pages.py --check会实测apps/pbls/build.sh并打印OK:（当前状态：已接入）或WARN:（接入被回退时）。warn_build_integration()作为常驻前提检查长期保留，只告警不改变返回码；真正决定 部署成败的是构建脚本内紧随生成之后的那次--check门禁。 - 第四条自检的口径边界（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」为判定口径，勿把交付说明的引述计入命中项。
- 第四条自检刻意用 ERE 形式（
- 新增/删除页面壳：改
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 才算通过）。