#!/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` 的第一步)会在**没跑**的时候红。 🔴 **生成段用标记包起来**: - 契约表:`` / `` - Rust 文件:`// >>>GEN:<名字>` / `// <<` - `Cargo.toml`:`# >>>GEN:PACK_DEPS` / `# <<>>GEN:名字` … `// <<.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/.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] # 手写部分(保留) <手写行> # 🔴 以下由 scripts/pack-sync.py 生成 —— 不许手改 <生成行> ``` 🔴 **手写行里与生成行逐字相同的那几行会被移除**(见 [`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_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 后补回来,`` 会**紧贴** # 下一个段标题 ⇒ 人读起来像标记属于下一段(机器不受影响,但 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]` 面计数 ⇒ (新文本, 每段的变化)。 🔴 **只碰 `` 之间** —— 手写区(平台层 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_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() == "": 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/.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 {") 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 {") L.append(" sspf_plugin::merge(regs)") L.append("}") return "\n".join(L).rstrip() + "\n" def _pack_crate_name(app): """包目录名 ⇒ crate 名(读 `packs//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 {", " Router::new()", "}", ], } def replace_rust_region(text, region, body): """把 `// >>>GEN:` 与 `// <<` 之间换成 `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))