- 物理移出 packs/{asset,books,demo,shop}、modules/ 四个面 A 适配器、纯技能副本、
纯业务测试 crud_it.rs 与 new-pack 脚手架(v0.3.0 tag 完整保留旧形态)。
- 删 example-packs feature / example_packs() / sspf-pack-* 依赖 / packs/* member;
packs_gen.rs 与 modules/mod.rs 生成段降级为恒空的注入点,装配链一条不删;
pack-sync.py 把「零包」钉成合法目标态。
- 尺子不再「跳过」:CP1 防回流清单、check-module 三条、AR2/PACK1 正向断言、
AR17 升级为零业务依赖判据(含注入式反自证)、契约反自证换平台锚点、FACE 零包重算。
- 面 A 冒烟 43→21 条(17 条平台权限闭环 + 4 条业务端点 404);pack_smoke_it 改
运行时防回流探针;auth/db/batch7/permission/seed/routes 单测换平台内置夹具。
- 契约 [MENU_TREE] 收成 5 条系统菜单、[RULER] 改 21/3;README/CLAUDE/HANDOFF/
CHANGELOG/contract §5.1/schema.sql/db.rs 注释同步。
验收:cargo test --workspace --no-fail-fast 649 passed / 0 failed / 6 ignored;
verify.sh --smoke 14/14;check-arch 24/24 + 反自证 14/14;
cargo tree -p sspf 无 sspf-pack-*。前端 src/frontend 按要求保留。
896 lines
37 KiB
Python
Executable File
896 lines
37 KiB
Python
Executable File
#!/usr/bin/env python3
|
||
# -*- coding: utf-8 -*-
|
||
"""pack-sync —— **把业务包 / 业务模块的声明同步到所有「派生位置」**。
|
||
|
||
🔴 **为什么存在**(HANDOFF §3 批次 12 交付物 ④ + 批次 12.5):
|
||
契约表 `docs/contract.md` 附录 A 的 `[MODULE]` / `[MENU]` / `[ENDPOINT]` 三段
|
||
原先是**手写** ⇒ **加一个业务包必须手抄三处** ⇒
|
||
「加业务模块从改 6~8 处降到写 1 个包文件 + 改 2 处」这个目标就**落不了地**。
|
||
|
||
⇒ 本脚本把「手抄」这件事**在机制上消灭**。它负责四处派生位置:
|
||
|
||
| # | 派生位置 | 内容 | 漏了会怎样 |
|
||
|---|---|---|---|
|
||
| ① | `docs/contract.md` 附录 A 三段 | `[MODULE]` / `[MENU]` / `[ENDPOINT]` | CC2/CC3 红(响亮) |
|
||
| ② | `src/backend/src/packs_gen.rs` | 内核的**包清单**(manifest 快照 + 装载调用) | 🔴 **面 B 静默 404** |
|
||
| ③ | `src/backend/src/modules/mod.rs` 五个生成段 | `pub mod` / `ALL_SPECS` / `ALL_ROUTES` / `ALL_MENUS` / `router()` | 🔴 **面 A 静默 404 + 菜单不种 ⇒ 守卫查不到** |
|
||
| ④ | `src/backend/Cargo.toml` 的 `>>>GEN:PACK_DEPS` 段 | 每个包的 crate 依赖 | 编译报错(响亮) |
|
||
|
||
🔴 **②③ 才是真危险的**:漏了**不报错**,只表现为「路由不存在 / 列表空 / 越权放行」。
|
||
⇒ 它们由同一份「`packs/*` + `modules/*.rs`」清单生成 ⇒ 只要跑本脚本就不会漏,
|
||
而 `--check`(`scripts/verify.sh` 的第一步)会在**没跑**的时候红。
|
||
|
||
🔴 **生成段用标记包起来**:
|
||
- 契约表:`<!-- PACK:BEGIN -->` / `<!-- PACK:END -->`
|
||
- Rust 文件:`// >>>GEN:<名字>` / `// <<<GEN:<名字>`
|
||
- `Cargo.toml`:`# >>>GEN:PACK_DEPS` / `# <<<GEN:PACK_DEPS`
|
||
⇒ 标记**之间**是生成物(**不许手改**),标记**之外**是手写的 ⇒ 不会被碰。
|
||
⇒ 幂等:跑第二次**字节级不变**。
|
||
|
||
用法:
|
||
python3 scripts/pack-sync.py # 同步(幂等)
|
||
python3 scripts/pack-sync.py --check # 只检查(不写)⇒ 有漂移就退出 1
|
||
python3 scripts/pack-sync.py --dry-run # 打印将要写入的契约表全文
|
||
|
||
退出码:0 = 同步成功 / 1 = --check 发现漂移 / 2 = 用法错或前置错误
|
||
"""
|
||
|
||
import io
|
||
import json
|
||
import os
|
||
import re
|
||
import sys
|
||
import tomllib
|
||
import importlib.util
|
||
|
||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||
ROOT = os.path.dirname(HERE)
|
||
if HERE not in sys.path:
|
||
sys.path.insert(0, HERE)
|
||
|
||
import contract_expect # noqa: E402 (同目录)
|
||
|
||
|
||
def _load_scanner():
|
||
"""按路径加载 `check-contract-scan.py`(文件名带连字符 ⇒ 不能 `import`)。
|
||
|
||
🔴 **为什么要复用它**:它里面有成熟的 Rust 源码扫描(`mask_rust` /
|
||
`scan_pack_routes` / `brace_span` …)⇒ 复制一份就会**产生第二份解析器**
|
||
⇒ 两份解析器迟早分叉 ⇒ 契约表与扫描器的口径就不一致了。
|
||
"""
|
||
path = os.path.join(HERE, "check-contract-scan.py")
|
||
spec = importlib.util.spec_from_file_location("check_contract_scan", path)
|
||
if spec is None or spec.loader is None:
|
||
raise SyncError("加载扫描器失败:%s" % path)
|
||
mod = importlib.util.module_from_spec(spec)
|
||
spec.loader.exec_module(mod)
|
||
return mod
|
||
|
||
|
||
scan = _load_scanner()
|
||
|
||
PACKS_DIR = os.path.join(ROOT, "packs")
|
||
CONTRACT = os.path.join(ROOT, "docs", "contract.md")
|
||
|
||
# 🔴 **四处派生位置**(见模块文档的表格)。
|
||
MODULES_DIR = os.path.join(ROOT, "src", "backend", "src", "modules")
|
||
PACKS_GEN = os.path.join(ROOT, "src", "backend", "src", "packs_gen.rs")
|
||
BACKEND_CARGO = os.path.join(ROOT, "src", "backend", "Cargo.toml")
|
||
|
||
BEGIN_MARK = "<!-- PACK:BEGIN -->"
|
||
END_MARK = "<!-- PACK:END -->"
|
||
|
||
# Rust / TOML 的生成段标记(`// >>>GEN:名字` … `// <<<GEN:名字`)。
|
||
GEN_OPEN = "// >>>GEN:%s"
|
||
GEN_CLOSE = "// <<<GEN:%s"
|
||
GEN_DEPS_OPEN = "# >>>GEN:PACK_DEPS"
|
||
GEN_DEPS_CLOSE = "# <<<GEN:PACK_DEPS"
|
||
GEN_FEAT_OPEN = "# >>>GEN:PACK_FEATURE"
|
||
GEN_FEAT_CLOSE = "# <<<GEN:PACK_FEATURE"
|
||
|
||
# 🔴 **契约表的段名**(与 `contract_expect.py` 的 SCHEMAS 对齐)。
|
||
SEC_MODULE = "MODULE"
|
||
SEC_MENU = "MENU"
|
||
SEC_ENDPOINT = "ENDPOINT"
|
||
SEC_FACE = "FACE"
|
||
|
||
|
||
class SyncError(Exception):
|
||
"""同步前置错误(包读不出来 / 声明不自洽)。"""
|
||
|
||
|
||
# ---------------------------------------------------------------- 扫包
|
||
|
||
def read_pack(app):
|
||
"""读一个业务包 ⇒ {manifest, entities, menus, routes}。
|
||
|
||
🔴 **实体/菜单/路由的解析器全部复用 `check-contract-scan.py`** ——
|
||
本文件**不再自己写一份**。理由:同一份 `EntitySpec` 会被
|
||
① 本脚本(生成契约段)与 ② 扫描器(从 spec ⇒ module_key ⇒ 菜单 en_code
|
||
推导面 B 守卫)**两处**消费 ⇒ 两份解析器迟早分叉 ⇒
|
||
生成段与守卫对账的**口径不一致**(两边都"对",结论相反 —— 最难查的一类)。
|
||
"""
|
||
pkg_dir = os.path.join(PACKS_DIR, app)
|
||
toml_path = os.path.join(pkg_dir, "pack.toml")
|
||
lib_path = os.path.join(pkg_dir, "src", "lib.rs")
|
||
if not os.path.isfile(toml_path):
|
||
raise SyncError("包 %s 缺 pack.toml" % app)
|
||
if not os.path.isfile(lib_path):
|
||
raise SyncError("包 %s 缺 src/lib.rs" % app)
|
||
|
||
with open(toml_path, "rb") as fh:
|
||
manifest = tomllib.load(fh).get("pack", {})
|
||
|
||
orig = scan.read(lib_path)
|
||
masked = scan.mask_rust(orig)
|
||
|
||
entities = scan.scan_entities(orig, masked)
|
||
menus = scan.scan_menus(orig, masked)
|
||
routes, _, _ = scan.scan_pack_routes(lib_path, app)
|
||
|
||
return {
|
||
"app": app,
|
||
"manifest": manifest,
|
||
"entities": entities,
|
||
"menus": menus,
|
||
"routes": routes,
|
||
"toml_path": toml_path,
|
||
}
|
||
|
||
|
||
# ---------------------------------------------------------------- 生成三段
|
||
|
||
def gen_module_rows(packs):
|
||
"""生成 `[MODULE]` 段的包部分行(**8 列**,与表头逐字对齐)。
|
||
|
||
🔴 **列口径**(`scripts/contract_expect.py` 的 `SCHEMAS["MODULE"]` 钉死 8 列):
|
||
`app / entity / table / urlAddress / moduleKey / menuId / apiFile / rsFile`
|
||
|
||
- `urlAddress` = **菜单的** `url_address`(= 前端 Route path);**不是** module_key。
|
||
两者**通常相同**(本仓的规矩),但 demo 这种「菜单有、守卫无」的模块会不同
|
||
⇒ 混用会在这类模块上静默错列。
|
||
- `moduleKey` = spec 的 `module_key`;**`None`** = 仅需登录 ⇒ 用字面量 `None`
|
||
(不是空串)⇒ 与手写部分同一口径(`check-module.sh` 按字面 `None` 判)。
|
||
- `menuId` = 包声明的菜单 id。
|
||
- `apiFile` = 前端 `src/frontend/src/api/<name>.ts` 该不该有 ⇒ 包带来的模块**有**。
|
||
- `rsFile` = 🔴 **相对 `src/backend/src/modules/` 的文件名**(如 `asset.rs`),
|
||
**不是**包路径 —— `check-module.sh` 的 `MODFILE="$MODULES_DIR/${rsFile}"` 就按这个拼。
|
||
包里的 spec 是**真源**,但模块文件仍在(做 `pub use` 转发)⇒ 这一列指的是**模块文件**。
|
||
"""
|
||
rows = []
|
||
for p in packs:
|
||
# `url_address` ⇒ 菜单 id(同一个包里的菜单按 url_address 索引)
|
||
by_url = {m["urlAddress"]: m for m in p["menus"]}
|
||
for e in p["entities"]:
|
||
mk = e["module_key"]
|
||
# 🔴 **`module_key: None` 的包(如 demo)也要落 `urlAddress` / `menuId`**:
|
||
# 这类包「菜单有、守卫无」⇒ 按 `module_key` 查必然查不到,
|
||
# 但它声明的菜单就是自己的(通常恰好 1 条)⇒ 用它。
|
||
# 以前这里直接给空串 ⇒ `check-boundary.sh` 的 CP6 会把
|
||
# 「契约菜单 6 条 − 业务菜单 1 条」算错 ⇒ 假红(2026-11-04 踩过)。
|
||
if mk:
|
||
menu = by_url.get(mk)
|
||
elif len(p["menus"]) == 1:
|
||
menu = p["menus"][0]
|
||
else:
|
||
menu = None
|
||
rows.append([
|
||
e["app"],
|
||
e["entity"],
|
||
e["table"],
|
||
menu["urlAddress"] if menu else (mk or ""),
|
||
mk if mk else "None",
|
||
menu["id"] if menu else "",
|
||
# 🔴 `apiFile` = **真实存在性**,不是「包带来的都算有」:
|
||
# `check-module.sh` 的第 5 个接触点按这一列决定「缺文件算不算错」,
|
||
# 写死 `有` 会让没有 api 层的模块(demo 就是)**假红**(2026-11-04 踩过)。
|
||
"有" if os.path.isfile(
|
||
os.path.join(ROOT, "src", "frontend", "src", "api", "%s.ts" % e["entity"].lower())
|
||
) else "无",
|
||
"%s.rs" % p["app"],
|
||
])
|
||
return rows
|
||
|
||
|
||
def gen_menu_rows(packs):
|
||
"""生成 `[MENU]` 段的包部分行。"""
|
||
rows = []
|
||
for p in packs:
|
||
for m in p["menus"]:
|
||
rows.append([
|
||
m["id"],
|
||
m["fullName"],
|
||
m["enCode"],
|
||
m["urlAddress"],
|
||
m["parentId"],
|
||
m["type"],
|
||
m["icon"],
|
||
m["sortCode"],
|
||
])
|
||
return rows
|
||
|
||
|
||
def gen_endpoint_rows(packs, mods):
|
||
"""生成 `[ENDPOINT]` 段的包/模块部分行。
|
||
|
||
🔴 **两块都要生成**(批次 12.5 补的第二块):
|
||
- **面 A**(`/api/ssw/{app}/{Entity}/{List|Save|Delete}`)—— 由
|
||
`modules/<app>.rs` 的 `router()` 里**真实注册**的 `.route(...)` 读出;
|
||
- **面 B**(官方 RESTful 形状)—— 由包的 `PackRoute` 声明读出。
|
||
|
||
🔴 **为什么要生成面 A**:批次 12 只生成了面 B ⇒ 新加的模块在代码里注册了
|
||
3 条面 A,但契约表里没有 ⇒ `check-contract` 的 CC2/CC4 立刻红
|
||
(「契约 382 / 代码 385」)⇒ **加一个模块就必须手抄三行**,
|
||
而手抄就是本脚本要消灭的东西。
|
||
|
||
🔴 **面 A 的 guard = 菜单的 `url_address`**(**不是** `f_en_code`)——
|
||
面 A 的守卫判据是菜单路径,面 B 是点权限,两套并存(见 `docs/contract.md`)。
|
||
"""
|
||
rows = []
|
||
|
||
# ---- 面 A:模块文件里真实注册的路由 ----
|
||
for app, spec_const, _menu, _n in mods:
|
||
guard = module_guard(app, spec_const, packs)
|
||
path = os.path.join(MODULES_DIR, "%s.rs" % app)
|
||
# `scan_routes` 返回 `(路由列表, 原文, 掩码后原文)` —— 只取第一项。
|
||
face_a, _, _ = scan.scan_routes(path, app)
|
||
for r in face_a:
|
||
rows.append(["A", r["method"], r["path"], guard or "登录", app])
|
||
|
||
# ---- 面 B:包声明的路由(官方形状)----
|
||
for p in packs:
|
||
for r in p["routes"]:
|
||
rows.append([
|
||
"B",
|
||
r["method"],
|
||
r["path"],
|
||
r.get("guard") or "登录",
|
||
p["app"],
|
||
])
|
||
return rows
|
||
|
||
|
||
def module_guard(app, spec_const, packs):
|
||
"""模块的 `module_key`(= 面 A 的守卫 = 菜单 `url_address`);`None` ⇒ 仅登录。
|
||
|
||
🔴 **两种形态都要认**:
|
||
① 模块自己声明 spec(demo / shop / books)⇒ 直接读 `module_key`;
|
||
② 模块只是转发包的 spec(asset / 新加的包)⇒ 回落包里那个实体。
|
||
漏了回落 ⇒ 面 A 的 guard 变成「登录」⇒ 契约里登记成无守卫 ⇒
|
||
CC6 立刻红(而且红得很像「代码写错了」)。
|
||
"""
|
||
path = os.path.join(MODULES_DIR, "%s.rs" % app)
|
||
orig = scan.read(path)
|
||
masked = scan.mask_rust(orig)
|
||
body = scan.const_body(orig, masked, spec_const)
|
||
if body:
|
||
return scan.module_key_of(body)
|
||
for p in packs:
|
||
if p["app"] != app:
|
||
continue
|
||
for e in p["entities"]:
|
||
if e["module_key"]:
|
||
return e["module_key"]
|
||
return None
|
||
|
||
|
||
def rows_to_text(rows):
|
||
"""行列表 ⇒ 制表符分隔的文本(**不带**表头注释)。"""
|
||
return "\n".join("\t".join(c for c in row) for row in rows)
|
||
|
||
|
||
# ---------------------------------------------------------------- 写回契约
|
||
|
||
def replace_generated(text, rows, section):
|
||
"""把生成段替换成 `rows`(幂等)⇒ 返回 (新文本, 删掉的手写行数)。
|
||
|
||
🔴 **段落结构**(每次都一样 ⇒ 幂等):
|
||
```
|
||
[SECTION]
|
||
# 手写部分(保留)
|
||
<手写行>
|
||
<!-- PACK:BEGIN -->
|
||
# 🔴 以下由 scripts/pack-sync.py 生成 —— 不许手改
|
||
<生成行>
|
||
<!-- PACK:END -->
|
||
```
|
||
|
||
🔴 **手写行里与生成行逐字相同的那几行会被移除**(见 [`strip_owned_rows`]):
|
||
否则**同一条端点登记两遍** ⇒ CC2 的总数对不上。
|
||
"""
|
||
lines = text.split("\n")
|
||
try:
|
||
sec_at = lines.index("[%s]" % section)
|
||
except ValueError:
|
||
raise SyncError("契约里找不到 [%s] 段" % section)
|
||
|
||
# 段的结束 = 下一个 `[SECTION]` 或 CONTRACT-EXPECT 结束标记。
|
||
end_at = len(lines)
|
||
for i in range(sec_at + 1, len(lines)):
|
||
if lines[i].startswith("["):
|
||
end_at = i
|
||
break
|
||
if lines[i].strip() == "<!-- END CONTRACT-EXPECT -->":
|
||
end_at = i
|
||
break
|
||
|
||
seg = lines[sec_at + 1:end_at]
|
||
# 去掉旧的生成段(连同它的标记与说明行)。
|
||
kept = []
|
||
i = 0
|
||
while i < len(seg):
|
||
if seg[i].strip() == BEGIN_MARK:
|
||
# 跳过到 END_MARK(含)。
|
||
j = i
|
||
while j < len(seg) and seg[j].strip() != END_MARK:
|
||
j += 1
|
||
i = j + 1
|
||
continue
|
||
kept.append(seg[i])
|
||
i += 1
|
||
|
||
# 🔴 **移除「与生成行重复的手写行」**(否则与生成段重复登记)。
|
||
kept, dropped = strip_owned_rows(kept, rows, section)
|
||
|
||
# 去掉尾部空行(生成段要贴在段末)。
|
||
while kept and not kept[-1].strip():
|
||
kept.pop()
|
||
|
||
block = []
|
||
if rows:
|
||
block.append(BEGIN_MARK)
|
||
block.append("# 🔴 以下由 `scripts/pack-sync.py` 从 `packs/*` 生成 —— **不许手改**")
|
||
block.append("# (下次同步会被覆盖;改包就够)")
|
||
block.extend(rows_to_text(rows).split("\n"))
|
||
block.append(END_MARK)
|
||
|
||
# 🔴 **保留段间空行**:原来的手写段在末尾有一个空行(分隔下一段 `[...]`)。
|
||
# pop 掉它再重排 ⇒ 若不在 block 后补回来,`<!-- PACK:END -->` 会**紧贴**
|
||
# 下一个段标题 ⇒ 人读起来像标记属于下一段(机器不受影响,但 review 会看错)。
|
||
new_seg = kept + ([""] + block + [""] if block else [])
|
||
return "\n".join(lines[:sec_at + 1] + new_seg + lines[end_at:]), dropped
|
||
|
||
|
||
def strip_owned_rows(kept, rows, section):
|
||
"""删掉「**与生成行重复**的手写行」(按**整行内容**逐字比对)。
|
||
|
||
🔴 **为什么不能按 `owner` / `app` 一刀切**(差点踩的坑):
|
||
业务包 `asset` 与业务模块 `asset` **同 app_code**。模块侧还有 3 条**面 A**
|
||
路由(`/api/ssw/asset/DataResource/{List|Save|Delete}`)**真实注册**在
|
||
`modules/asset.rs` 里、**必须**留在契约表。
|
||
按 owner 删 ⇒ 把这 3 条面 A 也删了 ⇒ 契约立刻少 3 条 ⇒ CC2/CC3 红。
|
||
⇒ **只删与生成行逐字相同的那几行**,其余(含同 owner 的面 A 行)一根汗毛不动。
|
||
|
||
🔴 **这正是「生成段负责哪几行」的精确边界**:
|
||
生成段 = 包的声明;手写段 = 其它所有(平台层 / 面 A / 别的模块)。
|
||
两者**内容冲突**时以生成为准(包是真源)⇒ 删掉手写那份。
|
||
"""
|
||
# 归一化:末尾空列差异不算差异(制表符尾随)
|
||
def norm(line):
|
||
return "\t".join(line.split("\t")).rstrip("\t")
|
||
|
||
owned = set(norm("\t".join(r)) for r in rows)
|
||
out = []
|
||
dropped = 0
|
||
for line in kept:
|
||
if not line.strip() or line.lstrip().startswith("#") or line.startswith("["):
|
||
out.append(line)
|
||
continue
|
||
if norm(line) in owned:
|
||
dropped += 1
|
||
continue
|
||
out.append(line)
|
||
return out, dropped
|
||
|
||
|
||
def sync_contract(text, packs, mods):
|
||
"""同步契约表的三段 + `[FACE]` 面计数 ⇒ (新文本, 每段的变化)。
|
||
|
||
🔴 **只碰 `<!-- PACK:BEGIN/END -->` 之间** —— 手写区(平台层 30 条端点、
|
||
48 条 `base_*` 菜单、官方台账)一根汗毛都不动。
|
||
"""
|
||
out = text
|
||
changes = {}
|
||
|
||
ep_rows = gen_endpoint_rows(packs, mods)
|
||
for section, rows in (
|
||
(SEC_MODULE, gen_module_rows(packs)),
|
||
(SEC_MENU, gen_menu_rows(packs)),
|
||
(SEC_ENDPOINT, ep_rows),
|
||
):
|
||
before = out
|
||
out, dropped = replace_generated(out, rows, section)
|
||
changes[section] = (before, out, dropped)
|
||
|
||
# 🔴 **`[FACE]` 的条数必须跟着变**(CC9 会对账):
|
||
# 生成的端点进了 `[ENDPOINT]` ⇒ 对应面的条数要跟着动。
|
||
# **不写死数字** ⇒ 从生成行里数出来(加包/加模块自动跟着走)。
|
||
out = sync_face_counts(out, {row[0] for row in ep_rows})
|
||
return out, changes
|
||
|
||
|
||
def sync_face_counts(text, faces):
|
||
"""把 `[FACE]` 里 `faces` 各行的条数改成「`[ENDPOINT]` 里的实际条数」(幂等)。
|
||
|
||
🔴 **为什么必须做**:`[FACE]` 是**自洽对账**用的(CC9 检查
|
||
「登记的条数 == `[ENDPOINT]` 里实际条数」)。包的 3 条面 B 与模块的
|
||
3 条面 A 进了 `[ENDPOINT]`,若 `[FACE]` 不跟着改 ⇒ CC9 立刻红
|
||
⇒ 加包变成「必须记得改三处」,本交付物的目的(**加包不手抄**)就落空了。
|
||
|
||
🔴 **不写死增量**:直接写「当前 `[ENDPOINT]` 里的实际条数」
|
||
⇒ 天然幂等,且加包 / 加模块 / 改路由都自动跟着走。
|
||
"""
|
||
# 🔴 零包时 `faces` 是空集合 —— **不能短路返回**:业务端点被清空后
|
||
# `[FACE]` 的旧条数必须跟着重算,否则 CC9 立刻红(2026-11-04 清理踩到)。
|
||
# ⇒ 空集合 = 「重算 [FACE] 里的**全部**面」。
|
||
recount_all = not faces
|
||
|
||
lines = text.split("\n")
|
||
try:
|
||
sec_at = lines.index("[%s]" % SEC_FACE)
|
||
except ValueError:
|
||
raise SyncError("契约里找不到 [%s] 段(CC9 需要它对账)" % SEC_FACE)
|
||
|
||
# 段尾
|
||
end_at = len(lines)
|
||
for i in range(sec_at + 1, len(lines)):
|
||
if lines[i].startswith("[") or lines[i].strip() == "<!-- END CONTRACT-EXPECT -->":
|
||
end_at = i
|
||
break
|
||
|
||
face_now = count_faces(lines, sec_at)
|
||
|
||
for i in range(sec_at + 1, end_at):
|
||
cols = lines[i].split("\t")
|
||
if len(cols) < 2 or cols[0].startswith("#") or not cols[0]:
|
||
continue
|
||
face = cols[0]
|
||
if not recount_all and face not in faces:
|
||
continue
|
||
# 本函数在三次替换**之后**调用 ⇒ `count_faces` 读到的是更新后的值。
|
||
cols[1] = str(face_now.get(face, 0))
|
||
lines[i] = "\t".join(cols)
|
||
return "\n".join(lines)
|
||
|
||
|
||
def count_faces(lines, face_sec_at):
|
||
"""数 `[ENDPOINT]` 段里各 face 的实际条数(忽略注释 / 标记 / 空行)。
|
||
|
||
🔴 从 `[FACE]` 段**往前**找 `[ENDPOINT]` 段 —— 两段的相对顺序在契约里固定,
|
||
但**不假设**(遍历全表找段落头,比硬编码行号稳)。
|
||
"""
|
||
# 找 [ENDPOINT] 段
|
||
start = None
|
||
for i, line in enumerate(lines):
|
||
if line == "[%s]" % SEC_ENDPOINT:
|
||
start = i + 1
|
||
break
|
||
if start is None:
|
||
return {}
|
||
counts = {}
|
||
for i in range(start, len(lines)):
|
||
line = lines[i]
|
||
if line.startswith("[") or line.strip() == "<!-- END CONTRACT-EXPECT -->":
|
||
break
|
||
if not line.strip() or line.lstrip().startswith("#"):
|
||
continue
|
||
if line.strip() in (BEGIN_MARK, END_MARK):
|
||
continue
|
||
cols = line.split("\t")
|
||
if len(cols) < 5:
|
||
continue
|
||
counts[cols[0]] = counts.get(cols[0], 0) + 1
|
||
return counts
|
||
|
||
|
||
# ================================================================ 内核接线生成
|
||
#
|
||
# 🔴 这一节回答「加包之后,内核怎么知道它」。
|
||
#
|
||
# 三个派生位置,全部由 `packs/*` + `modules/*.rs` 推出 —— **没有一处靠手抄**:
|
||
#
|
||
# ② `packs_gen.rs` ← 包的清单 + 装载调用
|
||
# ③ `modules/mod.rs` 五段 ← 模块的 spec / 菜单 / 面 A 路由 / 总路由
|
||
# ④ `Cargo.toml` 依赖段 ← 包的 crate 名
|
||
#
|
||
# 🔴 **②③ 漏了是「静默」的**(面 B 404 / 面 A 404 / 菜单不种 ⇒ 守卫查不到菜单),
|
||
# 而这三种现象在浏览器里都表现为「页面空着」⇒ 最难查。
|
||
# ⇒ 把「记住改哪几处」换成「跑一次脚本」,再用 `--check` 钉住。
|
||
|
||
|
||
def read_all_packs():
|
||
"""读 `packs/*` 全部包(按目录名字典序 ⇒ 生成结果确定)。"""
|
||
packs = []
|
||
if os.path.isdir(PACKS_DIR):
|
||
for app in sorted(os.listdir(PACKS_DIR)):
|
||
if os.path.isdir(os.path.join(PACKS_DIR, app)):
|
||
packs.append(read_pack(app))
|
||
# 🔴 **零包是合法目标态**(2026-11-04 清理):示例包已整体搬到技能仓
|
||
# `ssw-jnpf-lite-rust`,平台仓不认识任何业务包。此时四处派生位置
|
||
# 全部归零(`--check` 会把它们钉成空)⇒ 业务一旦回流立刻红。
|
||
return packs
|
||
|
||
|
||
def scan_module_files():
|
||
"""列 `src/backend/src/modules/*.rs`(排除 `mod.rs`)⇒ [(app, 绝对路径)]。
|
||
|
||
🔴 **顺序 = 文件名字典序** —— 生成段(`ALL_SPECS` / `ALL_ROUTES` …)按这个顺序排,
|
||
两次生成的字节必然一致(幂等的前提)。
|
||
"""
|
||
if not os.path.isdir(MODULES_DIR):
|
||
return []
|
||
out = []
|
||
for name in sorted(os.listdir(MODULES_DIR)):
|
||
if not name.endswith(".rs") or name == "mod.rs":
|
||
continue
|
||
out.append((name[:-3], os.path.join(MODULES_DIR, name)))
|
||
return out
|
||
|
||
|
||
def module_decls(app, path):
|
||
"""从一个模块文件读出 `(spec 常量名, menu 常量名, ROUTES 长度)`。
|
||
|
||
🔴 **两种写法都认**(批次 12 把 spec 搬进包之后,asset 是第二种):
|
||
① 自己声明:`pub const DEMO_SPEC: EntitySpec = …;`
|
||
② 转发包的:`pub use sspf_pack_asset::DATA_RESOURCE_SPEC;`
|
||
|
||
🔴 **为什么要求「1 个 spec + 1 个 menu + 3 条路由」**:
|
||
`ALL_ROUTES` 与 `ALL_SPECS` 是两份独立的数组 ⇒ 唯一的配对依据就是
|
||
「每个模块固定 3 条」这个约定(`modules/mod.rs` 的测试按 `chunks(3)` 校验)。
|
||
允许「一个模块多实体」就得引入 `模块 → (起点, 条数)` 的映射表 ⇒
|
||
又多一处会漂的结构。⇒ **一个模块文件一个实体**,要加就再建一个文件。
|
||
"""
|
||
orig = scan.read(path)
|
||
masked = scan.mask_rust(orig)
|
||
|
||
names = [m.group(1) for m in re.finditer(r"pub\s+use\s+[\w:]+::(\w+)\s*;", masked)]
|
||
names += [
|
||
m.group(1)
|
||
for m in re.finditer(
|
||
r"pub\s+const\s+(\w+)\s*:\s*(?:EntitySpec|MenuSpec)\s*=", masked
|
||
)
|
||
]
|
||
|
||
specs, menus = [], []
|
||
for n in names:
|
||
if n.endswith("_SPEC") and n not in specs:
|
||
specs.append(n)
|
||
elif n.endswith("_MENU") and n not in menus:
|
||
menus.append(n)
|
||
|
||
rm = re.search(r"pub\s+const\s+ROUTES\s*:\s*\[&str;\s*(\d+)\s*\]", masked)
|
||
routes = int(rm.group(1)) if rm else 0
|
||
|
||
if len(specs) != 1 or len(menus) != 1 or routes != 3:
|
||
raise SyncError(
|
||
"模块 %s 的声明形状不对:spec=%r menu=%r ROUTES=%d\n"
|
||
" 🔴 一个模块文件必须恰好 1 个 `*_SPEC` + 1 个 `*_MENU` + "
|
||
"`pub const ROUTES: [&str; 3]`\n"
|
||
" (`ALL_ROUTES` 与 `ALL_SPECS` 按「每模块 3 条」配对)。\n"
|
||
" 要加第二个实体 ⇒ 另建一个模块文件。" % (app, specs, menus, routes)
|
||
)
|
||
return specs[0], menus[0], routes
|
||
|
||
|
||
def require_module_for_every_pack(packs, mods):
|
||
"""🔴 **每个有实体的包都必须有 `modules/<app>.rs`**(面 A 适配器 + 菜单登记)。
|
||
|
||
缺了会怎样(都是**静默**的,所以在这里拦):
|
||
- 菜单只从 `modules::all_menus()` 进种子 ⇒ 包自己的菜单**不会被种**;
|
||
- 面 B 的守卫按 `f_en_code` 查菜单,查不到就走「未映射放行」⇒ **越权**;
|
||
- MVP 前端(React)走的是面 A `/api/ssw/...` ⇒ 端点根本不存在 ⇒ 页面空着。
|
||
"""
|
||
have = {m[0] for m in mods}
|
||
for p in packs:
|
||
if p["entities"] and p["app"] not in have:
|
||
raise SyncError(
|
||
"包 %s 声明了实体,但缺 `src/backend/src/modules/%s.rs`\n"
|
||
" 🔴 缺它的后果是**静默**的:菜单不会被种 ⇒ 面 B 守卫查不到菜单\n"
|
||
" ⇒ 走「未映射放行」(越权);面 A 端点也不存在 ⇒ MVP 前端页面空着。\n"
|
||
" ⇒ 平台仓不允许自带业务包;请把 %s 放回业务仓 / 技能仓。"
|
||
% (p["app"], p["app"], p["app"])
|
||
)
|
||
|
||
|
||
def manifest_json_of(p):
|
||
"""把 `pack.toml` 裁成**装载器实际读的字段**,输出稳定 JSON。
|
||
|
||
🔴 **只留 `sspf_plugin::PackTomlPack` 认的字段** —— `[pack.compat]` /
|
||
`[pack.metadata]` / `[pack.build]` 是给导出 / 迁移工具读的,
|
||
内核不认 ⇒ 带进来只会让「两份清单到底谁说了算」变模糊。
|
||
"""
|
||
m = p["manifest"]
|
||
tables = []
|
||
for t in m.get("tables", []) or []:
|
||
item = {"name": t["name"]}
|
||
if t.get("ddl"):
|
||
item["ddl"] = t["ddl"]
|
||
if t.get("baseline_table"):
|
||
item["baseline_table"] = t["baseline_table"]
|
||
tables.append(item)
|
||
obj = {
|
||
"pack": {
|
||
"app_code": m.get("app_code", p["app"]),
|
||
"name": m.get("name", p["app"]),
|
||
"version": m.get("version", "0.0.0"),
|
||
"kernel": m.get("kernel", ""),
|
||
"migratable": bool(m.get("migratable", False)),
|
||
"tables": tables,
|
||
}
|
||
}
|
||
text = json.dumps(obj, ensure_ascii=False, indent=2)
|
||
# Rust 的 `r#"…"#` 遇到 `"#` 就提前结束 ⇒ 有这种内容必须换定界符(宁可报错)。
|
||
if '"#' in text:
|
||
raise SyncError(
|
||
"包 %s 的清单里出现了 '\"#'(会截断 Rust 的 raw string)" % p["app"]
|
||
)
|
||
return text
|
||
|
||
|
||
def gen_packs_gen(packs):
|
||
"""生成 `src/backend/src/packs_gen.rs` 全文。
|
||
|
||
🔴 **2026-11-04 清理**:示例包已搬到技能仓,本仓恒为零包。
|
||
本文件从「业务包清单」降级为**平台注入点的空实现**:
|
||
- [`registry`] 恒返回空注册表(本仓不认识任何业务包);
|
||
- [`registry_from`] 保留,供门面 `sspf::Platform::packs` 合并外部注册表。
|
||
⇒ 平台能力(包路由装配 / 包 DDL 建表 / 白名单自检)一个不动,
|
||
只是「默认带哪些包」变成空。
|
||
"""
|
||
if packs:
|
||
raise SyncError(
|
||
"平台仓不允许自带业务包(发现 %d 个)⇒ 业务包请用 sspf::Platform::packs() 注入"
|
||
% len(packs)
|
||
)
|
||
L = []
|
||
L.append("//! ⚠️ **本文件由 `scripts/pack-sync.py` 生成 —— 不许手改。**")
|
||
L.append("//!")
|
||
L.append("//! **平台包零业务**(2026-11-04):本仓不认识任何业务包。")
|
||
L.append("//! 业务仓通过 `sspf::Platform::packs(reg)` 注入自己装载的注册表,")
|
||
L.append("//! 由 `crate::bootstrap` 在**同一个 `Db`** 上装配路由与 DDL。")
|
||
L.append("//!")
|
||
L.append("//! 🔴 为什么留着这个空文件:`bootstrap::load_packs()` / 白名单自检 /")
|
||
L.append("//! `Extras::kernel()` 都是**平台能力**(业务仓要用),删掉会逼着每个")
|
||
L.append("//! 业务仓自己抄一遍。留一个恒空的默认实现 ⇒ 平台侧零业务且不破装配链。")
|
||
L.append("")
|
||
L.append("use sspf_plugin::{LoadError, PackRegistry};")
|
||
L.append("")
|
||
L.append("/// 本仓业务包清单:恒为空。")
|
||
L.append("///")
|
||
L.append("/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**,不是装载失败。")
|
||
L.append("pub fn registry(_kernel_version: &str) -> Result<PackRegistry, LoadError> {")
|
||
L.append(" Ok(PackRegistry::default())")
|
||
L.append("}")
|
||
L.append("")
|
||
L.append("/// 把**外部已装载**的注册表合并成一个(门面 `sspf::Platform::packs` 用)。")
|
||
L.append("/// 🔴 只合并、不装载;空 vec ⇒ 空注册表(合法)。")
|
||
L.append("pub fn registry_from(regs: Vec<PackRegistry>) -> PackRegistry {")
|
||
L.append(" sspf_plugin::merge(regs)")
|
||
L.append("}")
|
||
return "\n".join(L).rstrip() + "\n"
|
||
|
||
|
||
def _pack_crate_name(app):
|
||
"""包目录名 ⇒ crate 名(读 `packs/<app>/Cargo.toml` 的 `[package].name`)。"""
|
||
cargo = os.path.join(PACKS_DIR, app, "Cargo.toml")
|
||
name = app
|
||
if os.path.isfile(cargo):
|
||
with open(cargo, "rb") as fh:
|
||
name = tomllib.load(fh).get("package", {}).get("name", name)
|
||
return name
|
||
|
||
|
||
def gen_pack_deps(packs):
|
||
"""生成 `src/backend/Cargo.toml` 的包依赖段(每包一行,**全部 optional**)。
|
||
|
||
🔴 **为什么 `optional = true`**(2026-11-04,标准平台包 / P0):
|
||
内核是**可被外部仓依赖的平台包**。业务仓(tdc-rs)只该拿到平台能力,
|
||
不该被拖进本仓的 4 个示例包(`asset` / `demo` / `shop` / `books`)。
|
||
⇒ 依赖降为可选,默认 feature 下 `cargo tree -p sspf` 里**没有**
|
||
`sspf-pack-*`(`check-arch.sh` 的 AR17 钉住)。
|
||
"""
|
||
out = []
|
||
for p in packs:
|
||
out.append(
|
||
'%s = { path = "../../packs/%s", optional = true }'
|
||
% (_pack_crate_name(p["app"]), p["app"])
|
||
)
|
||
return out
|
||
|
||
|
||
def gen_pack_feature(packs):
|
||
"""🔴 **已退役**(2026-11-04 清理):`example-packs` feature 随示例包一起搬走。
|
||
|
||
平台仓现在**没有** `[features]` 段,也没有任何可选业务依赖;业务仓通过
|
||
`sspf::Platform::packs(reg)` 注入自己的注册表,不开任何平台 feature。
|
||
⇒ 本函数保留为「非空即报错」的护栏:谁把示例包塞回 `packs/`,同步直接失败。
|
||
"""
|
||
if packs:
|
||
raise SyncError(
|
||
"平台仓不允许自带业务包(发现 %d 个:%s)\n"
|
||
" ⇒ 业务包属于业务仓 / 技能仓,请通过 sspf::Platform::packs() 注入。"
|
||
% (len(packs), ", ".join(p["app"] for p in packs))
|
||
)
|
||
return []
|
||
|
||
|
||
def gen_mod_regions(mods):
|
||
"""生成 `modules/mod.rs` 的五个段 ⇒ `{段名: 行列表}`。
|
||
|
||
🔴 **2026-11-04 清理**:示例模块已搬到技能仓,本仓恒为零模块。
|
||
五个生成段全部归零 ⇒ `all_specs()` / `all_menus()` / `ALL_ROUTES` /
|
||
`router()` 都还在(装配链不破),只是**内容为空**。
|
||
业务仓用自己的路由 + `sspf::Platform` 注入,不需要往内核塞文件。
|
||
"""
|
||
if mods:
|
||
raise SyncError(
|
||
"平台仓不允许自带业务模块(发现 %d 个:%s)\n"
|
||
" ⇒ 面 A 适配器属于业务仓,请用 sspf::Platform::router() 注入。"
|
||
% (len(mods), ", ".join(m[0] for m in mods))
|
||
)
|
||
|
||
return {
|
||
"MODS": [
|
||
"// 🔴 **平台包零业务**:本仓不认识任何业务模块。",
|
||
"// 业务模块的路由由业务仓经 `sspf::Platform::router()` 注入。",
|
||
],
|
||
"SPECS": [
|
||
"/// 本仓业务实体 spec:恒为空(平台包零业务)。",
|
||
"pub const ALL_SPECS: &[EntitySpec] = &[];",
|
||
],
|
||
"ROUTES": [
|
||
"/// 本仓业务路由表:恒为空(平台包零业务)。",
|
||
"pub const ALL_ROUTES: &[&str] = &[];",
|
||
],
|
||
"MENUS": [
|
||
"/// 本仓业务内置菜单:恒为空;业务菜单由 `.menus()` / `.packs()` 注入。",
|
||
"pub const ALL_MENUS: &[MenuSpec] = &[];",
|
||
],
|
||
"ROUTER": [
|
||
"/// 本仓业务路由:恒为空。",
|
||
"pub fn router() -> Router<AppState> {",
|
||
" Router::new()",
|
||
"}",
|
||
],
|
||
}
|
||
|
||
|
||
def replace_rust_region(text, region, body):
|
||
"""把 `// >>>GEN:<region>` 与 `// <<<GEN:<region>` 之间换成 `body`(行列表)。
|
||
|
||
🔴 **标记必须已存在** —— 找不到就报错,**不自动追加**。
|
||
自动追加会让「标记被误删」变成「悄悄多出一段代码」,比报错难查得多。
|
||
"""
|
||
lines = text.split("\n")
|
||
begin = GEN_OPEN % region
|
||
end = GEN_CLOSE % region
|
||
try:
|
||
i = lines.index(begin)
|
||
except ValueError:
|
||
raise SyncError("找不到生成段标记 %r(%s)" % (begin, region))
|
||
try:
|
||
j = lines.index(end, i + 1)
|
||
except ValueError:
|
||
raise SyncError("找不到生成段结束标记 %r(%s)" % (end, region))
|
||
return "\n".join(lines[: i + 1] + list(body) + lines[j:])
|
||
|
||
|
||
def replace_marker_block(text, open_mark, close_mark, body):
|
||
"""同 [`replace_rust_region`],但标记是任意前缀(`Cargo.toml` 用 `#`)。"""
|
||
lines = text.split("\n")
|
||
try:
|
||
i = lines.index(open_mark)
|
||
except ValueError:
|
||
raise SyncError("找不到标记 %r" % open_mark)
|
||
try:
|
||
j = lines.index(close_mark, i + 1)
|
||
except ValueError:
|
||
raise SyncError("找不到标记 %r" % close_mark)
|
||
return "\n".join(lines[: i + 1] + list(body) + lines[j:])
|
||
|
||
|
||
def sync(write=True):
|
||
"""把**四处派生位置**全部同步一遍 ⇒ `(packs, artifacts)`。
|
||
|
||
`artifacts` = `[(相对路径, 旧文本, 新文本, 契约段变化 or None)]`,
|
||
顺序 = ① 契约表 → ② 内核包清单 → ③ 模块登记段 → ④ Cargo 依赖段。
|
||
"""
|
||
packs = read_all_packs()
|
||
mods = [(app,) + module_decls(app, path) for app, path in scan_module_files()]
|
||
require_module_for_every_pack(packs, mods)
|
||
|
||
artifacts = []
|
||
|
||
# ① 契约表
|
||
old = scan.read(CONTRACT)
|
||
new, changes = sync_contract(old, packs, mods)
|
||
artifacts.append(("docs/contract.md", old, new, changes))
|
||
|
||
# ② 内核包清单(整文件生成)
|
||
old = scan.read(PACKS_GEN) if os.path.isfile(PACKS_GEN) else ""
|
||
artifacts.append(("src/backend/src/packs_gen.rs", old, gen_packs_gen(packs), None))
|
||
|
||
# ③ 模块登记段(五个标记段)
|
||
mod_rs = os.path.join(MODULES_DIR, "mod.rs")
|
||
old = scan.read(mod_rs)
|
||
new = old
|
||
for region, body in gen_mod_regions(mods).items():
|
||
new = replace_rust_region(new, region, body)
|
||
artifacts.append(("src/backend/src/modules/mod.rs", old, new, None))
|
||
|
||
# ④ Cargo 依赖段 + ⑤ `[features]` 段(两段都生成 ⇒ 「漏一处」不存在)
|
||
old = scan.read(BACKEND_CARGO)
|
||
new = replace_marker_block(old, GEN_DEPS_OPEN, GEN_DEPS_CLOSE, gen_pack_deps(packs))
|
||
# 🔴 `[features]` 段随示例包一起退役(2026-11-04):平台仓不再有任何
|
||
# 可选业务依赖 ⇒ 没有 feature 可生成。gen_pack_feature 只做「非空即报错」的护栏。
|
||
gen_pack_feature(packs)
|
||
artifacts.append(("src/backend/Cargo.toml", old, new, None))
|
||
|
||
if write:
|
||
for rel, before, after, _ in artifacts:
|
||
if before != after:
|
||
with io.open(os.path.join(ROOT, rel), "w", encoding="utf-8") as fh:
|
||
fh.write(after)
|
||
return packs, artifacts
|
||
|
||
|
||
def main(argv):
|
||
check = "--check" in argv
|
||
dry = "--dry-run" in argv
|
||
for a in argv[1:]:
|
||
if a not in ("--check", "--dry-run"):
|
||
sys.stderr.write("pack-sync: 未知参数 %r\n" % a)
|
||
return 2
|
||
|
||
try:
|
||
packs, artifacts = sync(write=not check and not dry)
|
||
except (SyncError, contract_expect.ContractError) as exc:
|
||
sys.stderr.write("pack-sync: %s\n" % exc)
|
||
return 2
|
||
|
||
drifted = [(rel, b, a, ch) for rel, b, a, ch in artifacts if b != a]
|
||
|
||
if dry:
|
||
# 只打印契约表全文(人要看的是那段);其余三处是「结构性生成」,
|
||
# 打印整份 Rust 源码没有意义。
|
||
for rel, _b, after, _ch in artifacts:
|
||
if rel == "docs/contract.md":
|
||
sys.stdout.write(after)
|
||
return 0
|
||
|
||
if check:
|
||
if drifted:
|
||
sys.stderr.write(
|
||
"pack-sync: 以下派生位置与 `packs/*` + `modules/*.rs` **不一致**:\n")
|
||
for rel, _b, _a, _ch in drifted:
|
||
sys.stderr.write(" · %s\n" % rel)
|
||
sys.stderr.write(
|
||
" ⇒ 跑 `python3 scripts/pack-sync.py` 重新生成\n"
|
||
" (这些位置是生成物:手改会被覆盖,漏改的后果是路由静默消失)\n")
|
||
return 1
|
||
print("pack-sync: %d 处派生位置与 packs/* + modules/*.rs 一致 ✅" % len(artifacts))
|
||
return 0
|
||
|
||
if not drifted:
|
||
print("pack-sync: 无变化(幂等 ✅)")
|
||
else:
|
||
print("pack-sync: 已更新 %d 处派生位置:" % len(drifted))
|
||
for rel, _b, _a, changes in drifted:
|
||
if not changes:
|
||
print(" · %s(整段重新生成)" % rel)
|
||
continue
|
||
for section, (before, after, dropped) in changes.items():
|
||
if before != after:
|
||
note = (
|
||
"(并移除 %d 条与生成行重复的手写行)" % dropped
|
||
if dropped
|
||
else ""
|
||
)
|
||
print(" · %s 的 [%s] 已更新%s" % (rel, section, note))
|
||
print(" 包:%s" % "、".join(p["app"] for p in packs))
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main(sys.argv))
|