feat(platform): 标准平台包 v0.2.0 —— 门面 crate sspf + 示例包选装

- 新增 crates/sspf(0.2.0):Platform builder(packs/ddl/menus/router/static_dir/on_ready)
  + build_app/serve/serve_mcp;契约与运行时类型原样重导出(业务仓不碰 19 个 sspf-*)
- 内核 4 个示例包降为 example-packs feature(依赖 optional + 生成段 [features]);
  packs_gen.rs / modules/mod.rs 改为 feature/not-feature 两份同名定义(整段 cfg 会让
  all_specs() 在默认 feature 下不存在)
- 七步启动迁入门面;平台表清单 / 白名单对账落在内核 boot.rs;sspf-admin 1111 → 381 行
- routes::build_app_with(state, extras) + bootstrap::{ensure_base_with, ensure_schema_all_with},
  旧签名保留 ⇒ 既有 704 个测试零改动;静态 SPA 托管手写在 routes.rs(不引 tower-http)
- 新增探针 crates/tests/tests/external_consumer_it.rs;闸门 AR17/AR18(反自证 13/13)

影响:业务仓只依赖 sspf 即可起服务;默认依赖树无 sspf-pack-*;面 A/B 行为一字未改。
回归:710 passed / 0 failed;check-arch 29/29;perm-smoke 43、perm-smoke-jnpf 23、
lowcode/baseline/mcp-smoke 15/10/14 全绿;仓外探针 /api/health = {"ok":true,"tables":177}。
This commit is contained in:
admin committed 2026-11-04 16:39:47 +08:00
1 parent acf076df5a
commit 9083394b8a
20 files changed
+2604 -887

No files matched your search

+97 -9
View File
@@ -85,6 +85,8 @@ 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"
@@ -639,6 +641,11 @@ def gen_packs_gen(packs):
L.append("//!")
L.append("//! 🔴 **`packs/` 是唯一真源** —— 加包跑 `bash scripts/new-pack.sh`,")
L.append("//! 改完 `packs/*` 跑 `python3 scripts/pack-sync.py`。")
L.append("//!")
L.append("//! 🔴 **默认 feature 下本文件不装载任何包**(2026-11-04 标准平台包):")
L.append("//! 4 个示例包降为 `example-packs` feature(只有 `sspf-admin` 与 `sspf-tests` 开)。")
L.append("//! 业务仓只依赖门面 `sspf` ⇒ `cargo tree` 里**没有** `sspf-pack-*`")
L.append("//! ⇒ 平台包里零业务(`check-arch.sh` 的 AR17 钉住)。")
L.append("")
L.append("use sspf_plugin::{LoadError, PackRegistry};")
L.append("")
@@ -646,6 +653,7 @@ def gen_packs_gen(packs):
L.append("///")
L.append("/// 🔴 任一包装载失败 ⇒ **整体失败**(半加载的包比不加载更危险):")
L.append("/// 半加载的包 = 一部分路由在、一部分不在 ⇒ 前端表现为「有的页面能用」。")
L.append('#[cfg(feature = "example-packs")]')
L.append("pub fn registry(kernel_version: &str) -> Result<PackRegistry, LoadError> {")
L.append(" let mut regs: Vec<PackRegistry> = Vec::new();")
L.append("")
@@ -665,88 +673,167 @@ def gen_packs_gen(packs):
L.append(" Ok(sspf_plugin::merge(regs))")
L.append("}")
L.append("")
L.append("/// 默认 feature(业务仓只依赖门面时的形态):**本仓不认识任何业务包** ⇒ 空注册表。")
L.append("///")
L.append("/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**(业务仓自己注入业务包),")
L.append("/// 不是装载失败。")
L.append('#[cfg(not(feature = "example-packs"))]')
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` / `.pack` 用)。")
L.append("///")
L.append("/// 🔴 与 [`registry`] 的分工:`registry` 装的是**本仓 `packs/*` 的示例包**;")
L.append("/// 本函数**只合并、不装载** ⇒ 业务仓用 `sspf::load_static` 装好自己的包后传进来。")
L.append("/// 🔴 空 vec ⇒ 空注册表(合法,不是错误)。")
L.append("pub fn registry_from(regs: Vec<PackRegistry>) -> PackRegistry {")
L.append(" sspf_plugin::merge(regs)")
L.append("}")
L.append("")
L.append("// ---------------------------------------------------------------- 清单快照")
L.append("//")
L.append("// 🔴 `pack.toml` 的**权威副本**在 `packs/<app>/pack.toml`(给人看、给导出工具读);")
L.append("// 这里是它的**编译期 JSON 快照**。为什么要快照、不运行期读文件:")
L.append("// 内核是**单二进制部署** ⇒ 运行目录里不一定有 `packs/` 目录。")
L.append("// 两份的一致性由 `scripts/pack-sync.py` 保证(`--check` 会比对)。")
L.append("//")
L.append("// 🔴 快照只在 `example-packs` 下编译(否则默认 feature 的构建里是死代码)。")
for p in packs:
app = p["app"]
const = app.upper().replace("-", "_") + "_MANIFEST_JSON"
L.append("")
L.append("/// `packs/%s/pack.toml` 的编译期快照。" % app)
L.append('#[cfg(feature = "example-packs")]')
L.append('const %s: &str = r#"%s"#;' % (const, manifest_json_of(p)))
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` 的包依赖段(每包一行)。"""
"""生成 `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:
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"]))
out.append(
'%s = { path = "../../packs/%s", optional = true }'
% (_pack_crate_name(p["app"]), p["app"])
)
return out
def gen_pack_feature(packs):
"""生成 `src/backend/Cargo.toml` 的 `[features]` 段(`example-packs` 聚合开关)。
🔴 用 `dep:` 语法 ⇒ 不产生「与依赖同名的隐式 feature」,
业务仓不可能误开单个 `sspf-pack-demo`。
🔴 **空列表也要生成**(`example-packs = []`)—— 标记段必须存在,
否则 `pack-sync.py --check` 与闸门 AR17 都会失去判据。
"""
names = ['"dep:%s"' % _pack_crate_name(p["app"]) for p in packs]
return ["example-packs = [" + ", ".join(names) + "]"]
def gen_mod_regions(mods):
"""生成 `modules/mod.rs` 的五个段 ⇒ `{段名: 行列表}`。
🔴 **`ALL_SPECS` 与 `ALL_ROUTES` 必须同序** —— 都按 `mods` 的顺序生成
⇒ `mod.rs` 的测试可以按 3 条一组配对(`chunks(3)`)。
这个「同序」不是约定,是**生成保证**。
🔴 **每个段都生成两份**(2026-11-04 标准平台包):
`#[cfg(feature = "example-packs")]` 的**实体清单**,
与 `#[cfg(not(feature = "example-packs"))]` 的**空清单**。
为什么不用「整段 cfg」:那会让 `all_specs()` / `all_menus()` / `router()`
在默认 feature 下**根本不存在** ⇒ `routes.rs` / `bootstrap.rs` 编译不过。
两份定义同名常量 / 函数 ⇒ 默认 feature 下**结构在、内容空**
(业务仓注入自己的东西,平台侧零业务)。
"""
if not mods:
raise SyncError("modules/ 下没有任何模块文件(至少要保住 demo/shop/books/asset)")
decls = ["// 每个模块一行:**文件即登记**(顺序 = 文件名字典序,不代表业务顺序)。"]
FEAT = '#[cfg(feature = "example-packs")]'
NOFEAT = '#[cfg(not(feature = "example-packs"))]'
decls = ["// 每个模块一行:**文件即登记**(顺序 = 文件名字典序,不代表业务顺序)。",
"// 🔴 只在 `example-packs` 下编译 —— 默认 feature 的内核**不认识任何业务模块**。"]
for app, _, _, _ in mods:
decls.append(FEAT)
decls.append("pub mod %s;" % app)
specs = [
"/// 全部业务实体 spec。",
"///",
"/// 🔴 **本段由 `scripts/pack-sync.py` 生成** —— 加模块不用手改(见文件头)。",
FEAT,
"pub const ALL_SPECS: &[EntitySpec] = &[",
]
for app, spec, _, _ in mods:
specs.append(" %s::%s," % (app, spec))
specs.append("];")
specs.append("/// 默认 feature:平台侧零业务 ⇒ 空清单(业务仓用 `sspf::Platform::packs` 注入)。")
specs.append(NOFEAT)
specs.append("pub const ALL_SPECS: &[EntitySpec] = &[];")
routes = [
"/// **全部业务路由**(面 A:`/api/ssw/{appCode}/{Entity}/{动作}`,每模块 3 条)。",
"///",
"/// 🔴 **与 `ALL_SPECS` 同序**(同一份模块清单生成)⇒ 可以按 3 条一组配对。",
FEAT,
"pub const ALL_ROUTES: &[&str] = &[",
]
for app, _, _, n in mods:
for i in range(n):
routes.append(" %s::ROUTES[%d]," % (app, i))
routes.append("];")
routes.append("/// 默认 feature:没有业务路由可登记。")
routes.append(NOFEAT)
routes.append("pub const ALL_ROUTES: &[&str] = &[];")
menus = [
"/// 全部业务内置菜单(由**装配根** [`crate::bootstrap`] 传给平台层的种子",
"/// ⇒ **平台层不认任何业务菜单**,红线 12)。",
FEAT,
"pub const ALL_MENUS: &[MenuSpec] = &[",
]
for app, _, menu, _ in mods:
menus.append(" %s::%s," % (app, menu))
menus.append("];")
menus.append("/// 默认 feature:平台侧零业务 ⇒ 种子只种平台菜单。")
menus.append(NOFEAT)
menus.append("pub const ALL_MENUS: &[MenuSpec] = &[];")
router = [
"/// **全部业务模块的路由**(`Router::merge` 进总路由)。",
"///",
"/// 🔴 加业务模块 ⇒ **不用改这里**(本段由 `pack-sync.py` 生成)。",
FEAT,
"pub fn router() -> Router<AppState> {",
" %s::router()" % mods[0][0],
]
for app, _, _, _ in mods[1:]:
router.append(" .merge(%s::router())" % app)
router.append("}")
router.append("/// 默认 feature:没有任何业务路由。")
router.append(NOFEAT)
router.append("pub fn router() -> Router<AppState> {")
router.append(" Router::new()")
router.append("}")
return {
"MODS": decls,
@@ -820,9 +907,10 @@ def sync(write=True):
new = replace_rust_region(new, region, body)
artifacts.append(("src/backend/src/modules/mod.rs", old, new, None))
# ④ Cargo 依赖段
# ④ Cargo 依赖段 + ⑤ `[features]` 段(两段都生成 ⇒ 「漏一处」不存在)
old = scan.read(BACKEND_CARGO)
new = replace_marker_block(old, GEN_DEPS_OPEN, GEN_DEPS_CLOSE, gen_pack_deps(packs))
new = replace_marker_block(new, GEN_FEAT_OPEN, GEN_FEAT_CLOSE, gen_pack_feature(packs))
artifacts.append(("src/backend/Cargo.toml", old, new, None))
if write: