docs(pbl_scense_ext): 回收覆盖层页面壳生成步骤「尚未接入」表述为已接入正向口径
- README「生成产物与入库边界」生成时机条目：改为构建期由 apps/pbls/build.sh 自动生成 + --check 门禁 - .gitignore 注释：生成方式改为构建脚本自动调用，人工执行仅用于本地调试 - gen_overlay_pages.py docstring【生成时机】段与 warn_build_integration() WARN 文案同步 - warn_build_integration() 作为常驻前提检查保留（当前实测打印 OK） - 自检：grep -rnE '第 ?9 ?步' 与 grep -rn '第9步\|第 9 步' 模块仓径均 rc=1 零命中
This commit is contained in:
agent.develop
parent
7e232a06f2
commit
4c96792df0
6
.gitignore
vendored
6
.gitignore
vendored
@ -11,7 +11,7 @@ build/
|
||||
.venv/
|
||||
venv/
|
||||
|
||||
# M9 覆盖层页面壳：构建产物，不入库。生成方式=在新克隆/新部署环境显式执行
|
||||
# python3 scripts/gen_overlay_pages.py（截至本提交 apps/pbls/build.sh 尚无调用本脚本的步骤，
|
||||
# 接入构建脚本由 PM 派单跟踪；README「生成产物与入库边界」有可机械核验的前提检查）
|
||||
# M9 覆盖层页面壳：构建产物，不入库。生成方式=由 apps/pbls/build.sh 在构建期调用
|
||||
# python3 scripts/gen_overlay_pages.py 自动生成（已接入，并紧随其后以 --check 作为门禁），
|
||||
# 本地开发调试可手动执行同一命令；README「生成产物与入库边界」有可机械核验的前提检查
|
||||
wwwroot/pbl_overlay/
|
||||
|
||||
25
README.md
25
README.md
@ -7,14 +7,14 @@ PBL 覆盖层前端扩展模块（scense / scense_game 之上的 pbl_scense_ext
|
||||
- `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 派单跟踪；在其落地前，本模块文档不得声称存在一个不存在的构建步骤。
|
||||
- **生成时机（已接入应用构建脚本，构建期自动生成）**：`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`
|
||||
门禁就是为此前置拦截。
|
||||
- 入库的交付物是**生成器与事实源**：`scripts/gen_overlay_pages.py`（生成器）、
|
||||
`wwwroot/i18n/{zh,en}/msg.txt`（界面文案事实源）、`wwwroot/overlay/*.js|*.css`
|
||||
（覆盖层实现）、`scripts/load_path.py`（RBAC 路径登记）。
|
||||
@ -23,9 +23,10 @@ PBL 覆盖层前端扩展模块（scense / scense_game 之上的 pbl_scense_ext
|
||||
```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'
|
||||
&& 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)"
|
||||
```
|
||||
@ -35,7 +36,9 @@ PBL 覆盖层前端扩展模块（scense / scense_game 之上的 pbl_scense_ext
|
||||
字面量抄进本文档，README 自身就会成为 grep 的命中项，使「零命中」声明再次不可复现
|
||||
（QC 复审 #1 指出的正是这类自验声明与实测不符的问题）。
|
||||
2. 第三条也可由生成器自检代跑：`python3 scripts/gen_overlay_pages.py --check` 会实测
|
||||
`apps/pbls/build.sh` 并打印 `OK:` 或 `WARN:`（不改变返回码）。
|
||||
`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`
|
||||
|
||||
@ -10,14 +10,15 @@ wwwroot Directories Must Not Be Git-Tracked」/ QC 退回意见 #3 方案 (b)）
|
||||
git ls-files wwwroot/pbl_overlay # 输出为空（无跟踪文件）
|
||||
本脚本（生成器）与 wwwroot/i18n/*/msg.txt（文案事实源）才是入库的交付物。
|
||||
|
||||
【生成时机：如实声明，不声称不存在的步骤（QC #9 复审改法 b）】
|
||||
截至本次提交，apps/pbls/build.sh 中**不存在**调用本脚本的步骤——实测
|
||||
`grep -n gen_overlay_pages apps/pbls/build.sh` 零命中。因此新克隆/新部署环境
|
||||
必须显式执行 `python3 scripts/gen_overlay_pages.py` 生成页面壳，否则
|
||||
wwwroot/pbl_overlay/ 为空目录、`/pbl_overlay/<key>.ui` 导航全量 404。
|
||||
把该生成步骤接入应用构建脚本（模块安装之后、wwwroot 软链之前）由 PM 另行派单
|
||||
跟踪（本模块不拥有 apps/pbls/build.sh，不在本任务改动范围内）；`--check` 会
|
||||
调用 warn_build_integration() 实测并打印 WARN，使本声明可机械核验。
|
||||
【生成时机：已接入应用构建脚本，构建期自动生成】
|
||||
apps/pbls/build.sh 已调用本脚本生成页面壳，并紧随其后以 `--check` 作为门禁
|
||||
（rc≠0 终止部署并打印原因）——实测 `grep -n gen_overlay_pages apps/pbls/build.sh`
|
||||
命中。调用位置在模块安装（pip install -e modules/pbl_*）之后、模块 wwwroot 软链
|
||||
之前，故新克隆/新部署环境执行 build.sh 即自动产出页面壳；若该目录为空，
|
||||
`/pbl_overlay/<key>.ui` 导航会全量 404，构建期门禁即为此前置拦截。
|
||||
人工执行 `python3 scripts/gen_overlay_pages.py` 仅用于本地开发调试。
|
||||
warn_build_integration() 作为常驻前提检查保留：`--check` 每次实测 apps/pbls/build.sh
|
||||
并打印 OK（当前状态：已接入）或 WARN（接入被回退时），只告警不改变返回码。
|
||||
|
||||
为什么需要页面壳：wwwroot/overlay/pbl_overlay_core.js 的 PAGES 注册表 route 指向
|
||||
`/pbl_overlay/<key>.ui`，play.js 的 pageUrl() 会拼成
|
||||
@ -202,10 +203,10 @@ def warn_build_integration():
|
||||
if 'gen_overlay_pages' in body:
|
||||
print('[gen_overlay_pages] OK: 生成步骤已接入 %s' % build_sh)
|
||||
else:
|
||||
print('[gen_overlay_pages][WARN] 生成步骤未接入 apps/pbls/build.sh：'
|
||||
'新克隆/新部署环境需手动执行 `python3 scripts/gen_overlay_pages.py`，'
|
||||
'否则 wwwroot/pbl_overlay/ 为空、/pbl_overlay/<key>.ui 全量 404'
|
||||
'（接入构建脚本由 PM 派单跟踪，见 README「生成产物与入库边界」）')
|
||||
print('[gen_overlay_pages][WARN] 前提检查失败：apps/pbls/build.sh 内已无本脚本调用，'
|
||||
'说明构建期自动生成已被回退。新克隆/新部署环境 wwwroot/pbl_overlay/ 将为空、'
|
||||
'/pbl_overlay/<key>.ui 全量 404，请恢复构建脚本中的生成步骤'
|
||||
'（见 README「生成产物与入库边界」）')
|
||||
|
||||
|
||||
def check(zh, en):
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user