#!/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"] menu = by_url.get(mk) if mk else 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 "", "有", "%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]` 里的实际条数」 ⇒ 天然幂等,且加包 / 加模块 / 改路由都自动跟着走。 """ if not faces: return text 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 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)) if not packs: raise SyncError("packs/ 下没有包(目录:%s)" % PACKS_DIR) 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" " ⇒ 跑 `bash scripts/new-pack.sh %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` 全文。""" L = [] L.append("//! ⚠️ **本文件由 `scripts/pack-sync.py` 生成 —— 不许手改。**") L.append("//!") L.append("//! 它是内核的**业务包清单**:每个包一条 [`sspf_plugin::load_static`]") L.append("//! 调用 + 一份 `pack.toml` 的 JSON 快照。") L.append("//!") L.append("//! 🔴 **为什么是生成的**:批次 12 时这段在 `bootstrap.rs` 里手写 ——") L.append("//! 每加一个包要抄「manifest JSON + `PackSource` + `merge(vec![…])`」三段。") L.append("//! 漏掉最后那段 `merge` 的表现是:包**装载成功**、没有报错,") L.append("//! 但 `entities` / `routes` 全丢 ⇒ **面 B 端点静默 404**。") L.append("//! ⇒ 改成生成 ⇒ 「漏一处」在机制上不存在;真忘了跑生成,") L.append("//! `scripts/verify.sh` 的第一步(`pack-sync.py --check`)会红。") L.append("//!") L.append("//! 🔴 **`packs/` 是唯一真源** —— 加包跑 `bash scripts/new-pack.sh`,") L.append("//! 改完 `packs/*` 跑 `python3 scripts/pack-sync.py`。") L.append("") L.append("use sspf_plugin::{LoadError, PackRegistry};") L.append("") L.append("/// 装载 `packs/*` 下的**全部**业务包(顺序 = `app_code` 字典序)。") L.append("///") L.append("/// 🔴 任一包装载失败 ⇒ **整体失败**(半加载的包比不加载更危险):") L.append("/// 半加载的包 = 一部分路由在、一部分不在 ⇒ 前端表现为「有的页面能用」。") L.append("pub fn registry(kernel_version: &str) -> Result {") L.append(" let mut regs: Vec = Vec::new();") L.append("") for p in packs: app = p["app"] ident = "sspf_pack_" + app.replace("-", "_") const = app.upper().replace("-", "_") + "_MANIFEST_JSON" L.append(" // ---- %s ----" % app) L.append(" regs.push(sspf_plugin::load_static(") L.append(' "%s",' % app) L.append(" %s," % const) L.append(" Box::new(%s::Pack)," % ident) L.append(" %s::DDLS," % ident) L.append(" kernel_version,") L.append(" )?);") L.append("") L.append(" Ok(sspf_plugin::merge(regs))") L.append("}") L.append("") L.append("// ---------------------------------------------------------------- 清单快照") L.append("//") L.append("// 🔴 `pack.toml` 的**权威副本**在 `packs//pack.toml`(给人看、给导出工具读);") L.append("// 这里是它的**编译期 JSON 快照**。为什么要快照、不运行期读文件:") L.append("// 内核是**单二进制部署** ⇒ 运行目录里不一定有 `packs/` 目录。") L.append("// 两份的一致性由 `scripts/pack-sync.py` 保证(`--check` 会比对)。") for p in packs: app = p["app"] const = app.upper().replace("-", "_") + "_MANIFEST_JSON" L.append("") L.append("/// `packs/%s/pack.toml` 的编译期快照。" % app) L.append('const %s: &str = r#"%s"#;' % (const, manifest_json_of(p))) return "\n".join(L).rstrip() + "\n" def gen_pack_deps(packs): """生成 `src/backend/Cargo.toml` 的包依赖段(每包一行)。""" out = [] for p in packs: cargo = os.path.join(PACKS_DIR, p["app"], "Cargo.toml") name = p["app"] if os.path.isfile(cargo): with open(cargo, "rb") as fh: name = tomllib.load(fh).get("package", {}).get("name", name) out.append('%s = { path = "../../packs/%s" }' % (name, p["app"])) return out def gen_mod_regions(mods): """生成 `modules/mod.rs` 的五个段 ⇒ `{段名: 行列表}`。 🔴 **`ALL_SPECS` 与 `ALL_ROUTES` 必须同序** —— 都按 `mods` 的顺序生成 ⇒ `mod.rs` 的测试可以按 3 条一组配对(`chunks(3)`)。 这个「同序」不是约定,是**生成保证**。 """ if not mods: raise SyncError("modules/ 下没有任何模块文件(至少要保住 demo/shop/books/asset)") decls = ["// 每个模块一行:**文件即登记**(顺序 = 文件名字典序,不代表业务顺序)。"] for app, _, _, _ in mods: decls.append("pub mod %s;" % app) specs = [ "/// 全部业务实体 spec。", "///", "/// 🔴 **本段由 `scripts/pack-sync.py` 生成** —— 加模块不用手改(见文件头)。", "pub const ALL_SPECS: &[EntitySpec] = &[", ] for app, spec, _, _ in mods: specs.append(" %s::%s," % (app, spec)) specs.append("];") routes = [ "/// **全部业务路由**(面 A:`/api/ssw/{appCode}/{Entity}/{动作}`,每模块 3 条)。", "///", "/// 🔴 **与 `ALL_SPECS` 同序**(同一份模块清单生成)⇒ 可以按 3 条一组配对。", "pub const ALL_ROUTES: &[&str] = &[", ] for app, _, _, n in mods: for i in range(n): routes.append(" %s::ROUTES[%d]," % (app, i)) routes.append("];") menus = [ "/// 全部业务内置菜单(由**装配根** [`crate::bootstrap`] 传给平台层的种子", "/// ⇒ **平台层不认任何业务菜单**,红线 12)。", "pub const ALL_MENUS: &[MenuSpec] = &[", ] for app, _, menu, _ in mods: menus.append(" %s::%s," % (app, menu)) menus.append("];") router = [ "/// **全部业务模块的路由**(`Router::merge` 进总路由)。", "///", "/// 🔴 加业务模块 ⇒ **不用改这里**(本段由 `pack-sync.py` 生成)。", "pub fn router() -> Router {", " %s::router()" % mods[0][0], ] for app, _, _, _ in mods[1:]: router.append(" .merge(%s::router())" % app) router.append("}") return { "MODS": decls, "SPECS": specs, "ROUTES": routes, "MENUS": menus, "ROUTER": router, } 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 依赖段 old = scan.read(BACKEND_CARGO) new = replace_marker_block(old, GEN_DEPS_OPEN, GEN_DEPS_CLOSE, gen_pack_deps(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))