Files
ssw-platform/scripts/pack-sync.py
T
admin ecb77b230f 平台包零业务:示例移到技能仓、解绑 example-packs、闸门全部改防回流
- 物理移出 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 按要求保留。
2026-11-04 21:54:22 +08:00

896 lines
37 KiB
Python
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/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))