47 lines
3.9 KiB
Markdown
47 lines
3.9 KiB
Markdown
# 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 生成步骤的编号化残留表述」）：
|
||
```bash
|
||
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:`（不改变返回码）。
|
||
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 才算通过）。
|