From 4ee1c5df0298fa65d3a3d1093b5b3971b896a48e Mon Sep 17 00:00:00 2001 From: "agent.develop" Date: Mon, 21 Sep 2026 13:15:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(pbl=5Fscense=5Fext):=20README=20=E5=8E=BB?= =?UTF-8?q?=E6=8E=89=20build.sh=20=E6=AD=A5=E9=AA=A4=E7=BC=96=E5=8F=B7?= =?UTF-8?q?=E5=8C=96=E8=A1=A8=E8=BF=B0=E5=B9=B6=E8=A1=A5=E7=AC=AC=E5=9B=9B?= =?UTF-8?q?=E6=9D=A1=E8=87=AA=E6=A3=80=EF=BC=8C=E4=BD=BF=20QC=20=E5=A4=8D?= =?UTF-8?q?=E5=AE=A1=20grep=20=E5=8F=A3=E5=BE=84=E7=9C=9F=E4=B8=BA?= =?UTF-8?q?=E9=9B=B6=E5=91=BD=E4=B8=AD=EF=BC=88QC=20#9=20=E5=A4=8D?= =?UTF-8?q?=E5=AE=A1=20#1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6995eb0..8ad3c5c 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ PBL 覆盖层前端扩展模块（scense / scense_game 之上的 pbl_scense_ext （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` 零命中（该脚本第 9 步是 py_compile - 全量语法验证）。因此**新克隆 / 新部署环境必须显式执行** + `grep -n 'gen_overlay_pages' apps/pbls/build.sh` 零命中（该脚本的语法验证步骤为 + py_compile 全量检查，与生成页面壳无关）。因此**新克隆 / 新部署环境必须显式执行** `python3 scripts/gen_overlay_pages.py`，否则 `wwwroot/pbl_overlay/` 为空目录、 `/pbl_overlay/.ui` 导航全量 404。把生成步骤接入应用构建脚本（模块安装之后、 wwwroot 软链之前）不在本模块职权内（`build.sh` 归应用侧所有），已由本任务交付说明 @@ -18,16 +18,24 @@ PBL 覆盖层前端扩展模块（scense / scense_game 之上的 pbl_scense_ext - 入库的交付物是**生成器与事实源**：`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)" ``` - 第三条也可由生成器自检代跑：`python3 scripts/gen_overlay_pages.py --check` 会实测 - `apps/pbls/build.sh` 并打印 `OK:` 或 `WARN:`（不改变返回码）。 + 说明两点： + 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 才算通过）。