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

Generated
+19 -6
View File
@@ -1067,6 +1067,22 @@ dependencies = [
"windows-sys",
]
[[package]]
name = "sspf"
version = "0.2.0"
dependencies = [
"axum",
"libc",
"sspf-contract",
"sspf-core",
"sspf-mcp",
"sspf-plugin",
"sspf-sdk",
"sspf-store",
"ssw-platform",
"tokio",
]
[[package]]
name = "sspf-adapter-baseline"
version = "0.1.0"
@@ -1087,12 +1103,7 @@ dependencies = [
name = "sspf-admin"
version = "0.1.0"
dependencies = [
"axum",
"libc",
"pglite-rs",
"sspf-core",
"sspf-mcp",
"ssw-platform",
"sspf",
"tokio",
]
@@ -1336,6 +1347,7 @@ dependencies = [
"axum",
"serde_json",
"serde_urlencoded",
"sspf",
"sspf-core",
"sspf-lowcode",
"sspf-mcp",
@@ -1352,6 +1364,7 @@ dependencies = [
"chrono",
"ecb",
"hex",
"libc",
"md-5 0.10.6",
"pglite-rs",
"rand 0.8.8",
+45
View File
@@ -9,6 +9,51 @@
---
## 0. 2026-11-04 标准平台包 `v0.2.0`:门面 crate `sspf` + 示例包选装(P0 交付)
**做了什么**(需求原文 `docs/SSPF-PLATFORM-PACKAGE.md`,实施记录见其 §10):
1. **新增 `crates/sspf`(0.2.0)= 业务仓唯一依赖**。`Platform::new().packs/ddl/menus/router/static_dir/on_ready` +
`build_app()` / `serve()` / `serve_mcp()`;契约与运行时类型全部**原样重导出**(业务仓不碰 19 个 `sspf-*`)。
2. **内核 4 个示例包降为 `example-packs` feature**(默认不链接):`src/backend/Cargo.toml` 依赖全部 `optional = true`
+ 生成段 `[features]`;`packs_gen.rs` / `modules/mod.rs` 的生成段改成 **feature / not-feature 各一份**(同名常量与函数)。
生成器 `pack-sync.py` 同步改(`--check` 绿),`new-pack.sh` 无需改(它只调生成器)。
3. **进程级启动动作搬出门面**:七步在 `crates/sspf/src/platform.rs` 的 `boot()`;绑端口 / 停机 / 关库在 `runtime.rs`。
认识平台表清单的原语(`BASE_TABLES` 123 张 / 白名单对账 / 开库 / 停机)落在内核 **`src/backend/src/boot.rs`**(参数化:
spec 与包 DDL 由调用方给)。`crates/sspf-admin/src/main.rs` **1111 行 → 381 行**,只留 CLI。
4. **`routes::build_app_with(state, extras)`** 承载注入(包路由 / 业务路由 / SPA 目录);`build_app` 是 `Extras::kernel()` 薄封装
⇒ **704 个测试一行没改**。`bootstrap::{ensure_base_with, ensure_schema_all_with}` 参数化,旧签名保留。
5. **探针** `crates/tests/tests/external_consumer_it.rs`(只 `use sspf::{Config, Db, Platform}`):同时证明
①平台表已建 ②注入 DDL 进**同一个库** ③示例包表/路由**不存在** ④面 B 登录 200 ⑤注入端点同端口。
6. **新闸门 AR17 / AR18**(`check-arch.sh`,反自证 **11 → 13 条**,全部通过):AR17 = 平台包零业务依赖;
AR18 = 门面源码零业务字面量(连注释一起扫)。
**🔴 两条必须记住的结论**:
- **门面一次都不读 `bootstrap::packs()` 那个 `OnceLock`**。理由是 feature 统一:`sspf-tests` 开 `example-packs` 的构建里,
内核也带着示例包 ⇒ 门面若读单例就会**静默**把示例包带进业务仓进程,而测试全绿。现在默认装配**恒零业务**。
- **`#[cfg]` 只能加在项上**:`ALL_SPECS` 的数组元素不能单独 cfg ⇒ 生成器产出「两份同名定义」。
整段 cfg 会让 `all_specs()` / `router()` 在默认 feature 下**不存在** ⇒ `routes.rs` / `bootstrap.rs` 编译不过。
- **`.packs()` ≠ 业务全进去了**:面 A(`/api/ssw/**`)来自内核 `modules::router()`,门面默认不认识
⇒ `sspf-admin` 必须显式 `.router(modules::router())`,否则面 A 全 404(本批 perm-smoke 29 条红过)。
- **包菜单必须自动种**:只种 `.menus()` 而漏 `PackRegistry.menus` ⇒ `module_key` 守卫查不到菜单
⇒ 该 403 的请求**静默 200**(本批 perm-smoke 6 条红过)。现在 `.packs()` 自动把包菜单带进种子。
**出口判据(实测)**:`cargo test --workspace` **710 passed / 0 failed**(基线 704,只增不减);
`cargo tree -p sspf | grep sspf-pack` **无输出**;`cargo tree -p ssw-platform` 同;
`check-arch.sh` **29/29**、`--self-test` **13/13**;`verify.sh --fast` 八步全绿;
运行时尺子 perm-smoke **43/43**、perm-smoke-jnpf **23/23**、lowcode-smoke 15/15、baseline-smoke 10/10、mcp-smoke 14/14;
仓外探针(只依赖 `sspf`)起服务后 `/api/health` = `{"ok":true,"tables":177}`。
🔴 **177 不是 181**:181 = 177 张平台表 + 4 张示例包表(asset/books/demo/shop);平台包默认不带示例包
⇒ 业务仓看到 177 + 自己的表。本仓 `sspf-admin`(开 `example-packs`)仍是 **181**,别把 181 写进业务仓的断言。
**⏭ 业务仓(tdc-rs)P1 必做**(平台侧代劳不了):① 自带 `rust-toolchain.toml` 锁 1.95.0;② **删掉
`[profile.release] panic = "abort"`**(否则 catch-all 失效、契约 §6.5 破);③ `[profile.dev] incremental = false`;
④ 依赖写 `sspf = { path = "../ssw-platform/crates/sspf" }`(发布期换 git tag `v0.2.0`)。
---
## 0-0-pre-pre. 2026-11-04 11:20 结构三改:onlinedev 正名 / 测试剥离 / 默认装配 `sspf-admin`
- `crates/sspf-compat-online_dev` → **`crates/sspf-compat-onlinedev`**(包名 / 模块 / 文件名 / `compat::onlinedev::` 全同步)。理由:与官方 `onlineDev` 拼写一致,也与同族 `sspf-compat-{system,ext}` 的「去分隔符」惯例一致。
+13 -20
View File
@@ -4,41 +4,34 @@ version.workspace = true
edition.workspace = true
rust-version.workspace = true
# 🔴 **默认装配**(2026-11-04 从 `src/backend/src/main.rs` 剥出)。
# 🔴 **默认装配**(2026-11-04 从 `src/backend/src/main.rs` 剥出,2026-11-05 起是**薄壳**)。
#
# 分层(对齐官方 JNPF 的 `jnpf-common` + `jnpf-system` / `jnpf-admin`):
# crates/sspf-* 能力层(平台核心 / 契约面 / 低代码 / MCP)—— 不认识「一个应用」
# src/backend 内核 lib(`ssw_platform`):装配根 + 路由 + 业务层
# packs/* 业务包(只依赖 sspf-sdk)
# crates/sspf-admin **本包 = 一个能跑的应用**:把上面全部装进一个进程,
# 负责「进程级」的事(定位项目根 / 读环境变量 / 开库 / 种子 /
# 自检 / 绑端口 / 优雅停机),内核不碰这些。
# crates/sspf **门面**:平台 + 装配 builder + 进程级启动动作
# crates/sspf-admin **本包 = 一个能跑的应用**:只解析命令行,装配全交给门面
#
# 🔴 **为什么要单独一个包,而不是把 bin 留在内核里**:
# ① 内核是**库**(可被 CLI、MCP 适配器、测试、别的应用复用);
# 一旦它自带 `[[bin]]`,`cargo add` 一个库就顺带下载了一个服务器。
# ② 「跑起来」是一份**装配选择**(读哪些环境变量、种子灌不灌、监听哪),
# 不是一个能力。换成「只读线上库的巡检程序」时,应该另起一个 admin 包,
# 而不是改内核。
# ③ 测试宿主(`crates/tests`)与运行入口解耦:测试直接 `use ssw_platform::routes`,
# 不需要起进程。
# 不是一个能力。
# ③ 测试宿主(`crates/tests`)与运行入口解耦。
#
# 🔴 **加一个应用**:复制本目录改名(如 `sspf-portal`),改 `[package].name`
# 与下面的路径即可 —— 内核与业务包一行都不用动。
# 🔴 **加一个应用**:复制本目录改名(如 `sspf-portal`)—— 它只依赖 `sspf`,
# 内核与业务包一行都不用动。
[[bin]]
name = "sspf-admin"
path = "src/main.rs"
[dependencies]
# 内核 lib:装配根(bootstrap) / 路由(routes) / 业务层(modules) / MCP 适配壳
ssw-platform = { path = "../../src/backend" }
# 平台核心:cipher / config / db / guard / seed / session / state
sspf-core = { path = "../sspf-core" }
# MCP 工具层(`--mcp` 形态直接起 stdio 服务)
sspf-mcp = { path = "../sspf-mcp" }
# 🔴 **唯一的平台依赖**(门面)。业务仓照抄这一行即可。
#
# 🔴 `example-packs` **只在这里开**:`sspf-admin` 是本仓的默认装配,要带
# 4 个示例包(asset / books / demo / shop)。业务仓(tdc-rs)**不开**这个 feature
# ⇒ 依赖树里没有 `sspf-pack-*`(`check-arch.sh` 的 AR17 钉住)。
sspf = { path = "../sspf", features = ["example-packs"] }
axum = { workspace = true }
tokio = { workspace = true }
# 仅用于 MCP 模式的 `dup2`(把 fd 1 让给 stderr,见 src/main.rs)
libc = { workspace = true }
pglite-rs = { workspace = true }
File diff suppressed because it is too large. Load diff
+45
View File
@@ -0,0 +1,45 @@
[package]
name = "sspf"
version = "0.2.0"
edition = "2021"
rust-version = "1.85"
description = "SSPF 标准平台包 —— 业务仓唯一依赖的门面(平台能力 + 装配注入)"
# 🔴 **为什么显式写 version,不用 `version.workspace = true`**:
# 业务仓(tdc-rs)锁的是**这个 crate 的语义版本**(`sspf = "0.2"` / tag `v0.2.0`),
# 而本仓 workspace 版本(0.1.0)跟的是内核实现节奏。两者独立演进 —— 混用会让
# 「业务仓能不能升级」变成「内核发了几个 commit」。
#
# 🔴 **契约版本是另一个量**:`CONTRACT_VERSION = "0.4.0"`(业务包 `kernel_req` 校验它),
# 见 `ssw_platform::bootstrap::kernel_version()`。三个版本号各有各的用途。
#
# 🔴 **本 crate 是业务仓唯一该依赖的东西** —— 它不直接碰 19 个 `sspf-*`;
# 依赖列在这里改了,业务仓无感(这正是门面的意义)。
[features]
default = []
# 只给本仓的 `sspf-admin`(默认装配)与 `sspf-tests`(集成测试)用。
# 🔴 **业务仓不开** —— 开了就会把本仓 4 个示例包(asset/demo/shop/books)拖进
# 业务二进制。`check-arch.sh` 的 AR17 钉住「默认 feature 下没有 sspf-pack-*」。
example-packs = ["ssw-platform/example-packs"]
[dependencies]
# 内核:装配根(bootstrap) / 路由链(routes) / 启动原语(boot)
ssw-platform = { path = "../../src/backend" }
# 契约层(类型 / 码表)—— 原样重导出给业务仓
sspf-contract = { path = "../sspf-contract" }
# 业务包 SDK(BusinessPack / Manifest / PackHooks)—— 原样重导出
sspf-sdk = { path = "../sspf-sdk" }
# 平台核心(AppState / seed / crud / guard / cipher)
sspf-core = { path = "../sspf-core" }
# 存储层(Db / Config)
sspf-store = { path = "../sspf-store" }
# 业务包装载器(load_static / merge / PackRegistry)
sspf-plugin = { path = "../sspf-plugin" }
# MCP stdio 服务(`Platform::serve_mcp`)
sspf-mcp = { path = "../sspf-mcp" }
axum = { workspace = true }
tokio = { workspace = true }
# `serve_mcp` 里把 fd 0/1 让给内嵌 PG(与 sspf-admin 时代同一段 dup2 逻辑)
libc = { workspace = true }
+124
View File
@@ -0,0 +1,124 @@
//! sspf —— **标准平台包**的门面(业务仓唯一依赖)。
//!
//! ## 这个 crate 解决什么问题
//!
//! 业务仓(自带实体 / 表 / 自定义端点的应用仓)要的是一份**可版本锁定的平台**:
//! 登录 / 权限 / 面 B 全套 JNPF 兼容能力 / 低代码 / MCP。
//! 它不该知道平台内部拆了 19 个 crate,也不该被拖进本仓的 4 个示例包。
//!
//! ```ignore
//! // 业务仓 src/main.rs
//! sspf::Platform::new()
//! .packs(my_packs::registry()?) // 业务包 / 业务 DDL(同一个 Db)
//! .menus(my_packs::MENUS) // 业务菜单注入两段式种子
//! .router(my_app::router()) // 自定义端点
//! .static_dir("static") // 上游前端产物 + 深链回退
//! .serve().await
//! ```
//!
//! ## 三条硬约束(本 crate 的存在理由)
//!
//! 1. **单进程只有一个 PGlite 实例** —— `pglite-rs 0.2` 内部是进程级 `static OPEN`,
//! 第二次 `PGlite::open()` 直接失败。⇒ 平台与业务**必须共用同一个 [`AppState`]**。
//! 门面提供的注入点全都在**同一个库**上执行,业务仓不许自己开库。
//! 2. **装配链只有一条** —— `fallback` 必须在两个 `layer` 之前、`with_state` 在链尾
//! (S25)。业务仓**不能**自己抄一遍,只能把路由交给 [`Platform::router`],
//! 由内核的 [`kernel::routes::build_app_with`] 装配。
//! 3. **平台包里零业务** —— 默认 feature 下本 crate 的依赖树里**没有** `sspf-pack-*`
//! (`check-arch.sh` 的 AR17 钉住);本 crate 源码里没有业务表名 / 端点字面量
//! (AR18)。
//!
//! ## 版本号有三套,别混
//!
//! | 版本 | 值 | 谁看 |
//! |---|---|---|
//! | 本 crate(cargo) | `0.2.0` | 业务仓锁依赖 / git tag |
//! | 契约版本 | `0.4.0` | 业务包 `pack.toml` 的 `kernel_req` |
//! | workspace(cargo) | `0.1.0` | 内核实现节奏 |
//!
//! ## 面 A / 面 B 行为一字不改
//!
//! 门面只做**装配**,不改任何端点形状、码表、表结构:`Vue-Version: 3` 判别、
//! `base_*` 181 张表、cipher、602 码、panic ⇒ HTTP 200 + `code=400` 全部照旧。
#![forbid(unsafe_op_in_unsafe_fn)]
pub mod platform;
pub mod runtime;
pub use platform::Platform;
// ---------------------------------------------------------------- 契约与包类型
//
// 🔴 **原样重导出** —— 业务仓不直接依赖 `sspf-contract` / `sspf-sdk`:
// 依赖点多一处,版本就能漂一处。
pub use sspf_contract::entity::{ColumnSpec, EntitySpec};
pub use sspf_contract::envelope::{self, code, ActionResult};
pub use sspf_contract::menu::MenuSpec;
pub use sspf_contract::route::{HttpMethod, PackRoute, RouteAction, RouteGuard};
pub use sspf_plugin::{load_static, merge, LoadError, PackDdl, PackRegistry, PackSource};
pub use sspf_sdk::{BusinessPack, Manifest, PackHooks};
// ---------------------------------------------------------------- 运行时类型
//
// 🔴 业务 handler 要能接**平台会话**与**同一个库**:这些类型必须与内核
// `AppState` 里的那几个**是同一个类型**(不是长得像的复制品)。
pub use sspf_core::cipher;
pub use sspf_core::config::{Config, Profile};
pub use sspf_core::crud;
pub use sspf_core::guard;
pub use sspf_core::seed;
pub use sspf_core::session::{SessionStore, TicketStore};
pub use sspf_core::state::AppState;
pub use sspf_store::db::Db;
/// 内核装配面(排障与高级用法)。
///
/// 🔴 业务仓的**正常路径不需要它** —— 有 [`Platform`] 就够了。
/// 放在这里是为了「门面不漏能力」:`sspf-admin` 的 `--seed-lowcode-demo`
/// 与外部探针都要能拿到 `bootstrap` / `routes` / `boot`。
pub mod kernel {
pub use ssw_platform::boot;
pub use ssw_platform::bootstrap;
pub use ssw_platform::compat;
pub use ssw_platform::lowcode_seed;
pub use ssw_platform::mcp_adapter;
pub use ssw_platform::modules;
pub use ssw_platform::routes;
}
/// 🔴 **本仓示例包注册表**(`packs/{asset,books,demo,shop}`)—— 只有开了
/// `example-packs` feature 才存在。
///
/// 🔴 **业务仓永远不该调它**:它的存在只为 `sspf-admin`(默认装配)与集成测试。
/// 默认 feature 下本函数**不存在**(不是返回空)⇒ 误用是编译错误,不是静默退化。
#[cfg(feature = "example-packs")]
pub fn example_packs() -> Result<PackRegistry, String> {
ssw_platform::bootstrap::load_packs().map_err(|e| format!("示例包装载失败: {e}"))
}
/// 门面版本(= cargo 版本,业务仓锁的那个)。
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
#[cfg(test)]
mod tests {
/// 🔴 门面版本必须与 `Cargo.toml` 一字不差(业务仓按它锁依赖)。
#[test]
fn version_matches_the_manifest() {
assert_eq!(super::VERSION, "0.2.0");
}
/// 🔴 **默认 feature 下不得装任何示例包** —— 这条与 AR17 的静态判据互补:
/// AR17 看 Cargo.toml,这条看**编译出来的代码路径**。
#[test]
fn default_build_carries_no_example_packs() {
if cfg!(feature = "example-packs") {
return; // 本仓自测时 feature 是开的(sspf-tests 会开)
}
let reg = ssw_platform::bootstrap::load_packs().expect("默认 feature 也必须可装载(空表)");
assert!(
reg.entities.is_empty(),
"默认 feature 是平台包:不得装载示例业务包"
);
}
}
+347
View File
@@ -0,0 +1,347 @@
//! platform —— 装配 builder(业务仓看到的**唯一**入口)。
//!
//! ## 装配顺序(**写死在这儿,别让业务仓自己排**)
//!
//! ```text
//! 开库前自检 → 开库 → 平台 DDL(schema.sql) → 业务 DDL(包/注入)
//! → 平台种子 ensure_base(平台 + 业务菜单) → first_seed
//! → 生产档守卫 → 构 AppState → 启动钩子
//! → build_app_with(平台路由 + 业务路由 + SPA fallback)
//! → bind → graceful shutdown → shutdown_pg
//! ```
//!
//! 🔴 **顺序即正确性**:自检必须在开库之前(库坏了就查不出是配置错还是代码错);
//! 业务 DDL 必须在种子之前(种子要往业务表写东西);守卫必须在 `AppState` 之前
//! (生产档弱口令不许起来,哪怕只起了一秒)。
//!
//! 🔴 **不碰 `bootstrap::packs()` 那个 `OnceLock`**:它是 `first-call-wins`,
//! 一旦被默认空注册表占住,外部注入就**静默失效**。⇒ 门面全程用**显式传入**的
//! [`PackRegistry`]([`Platform::packs`]),内核的 `ensure_schema_all_with` /
//! `pack_router` 都收 `&PackRegistry`,一次都不读那个单例。
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use axum::Router;
use sspf_contract::entity::EntitySpec;
use sspf_contract::menu::MenuSpec;
use sspf_core::config::Config;
use sspf_core::guard::{self, Profile};
use sspf_core::seed;
use sspf_core::session::{SessionStore, TicketStore};
use sspf_core::state::AppState;
use sspf_plugin::{PackDdl, PackRegistry};
use ssw_platform::boot;
use ssw_platform::bootstrap;
use ssw_platform::routes::{self, Extras};
use crate::runtime;
/// 启动钩子:拿到 [`AppState`](同一个库 / 同一张会话表),`Err` ⇒ 启动失败。
type ReadyHook =
Box<dyn Fn(AppState) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send>> + Send + Sync>;
/// 平台装配器。
///
/// ```ignore
/// sspf::Platform::new()
/// .packs(my_packs)
/// .menus(MY_MENUS)
/// .router(my_router())
/// .serve().await
/// ```
pub struct Platform {
/// 显式配置;`None` ⇒ [`Platform::boot`] 里按 `boot::resolve_project_dir()` + 环境变量推导。
config: Option<Config>,
/// 业务包(默认**空** —— 平台包不带业务)。
packs: PackRegistry,
/// 业务建表 SQL(不走包装载的零散 DDL)。
ddls: Vec<PackDdl>,
/// 业务菜单(注入两段式种子的第一段)。
menus: Vec<MenuSpec>,
/// 业务自定义路由(含它自己的中间件 / 守卫)。
router: Option<Router<AppState>>,
/// 静态 SPA 目录(深链回退 `index.html`)。
static_dir: Option<std::path::PathBuf>,
/// 启动钩子(业务预热:引导身份 / 外部连接 / 缓存)。
hooks: Vec<ReadyHook>,
}
impl Default for Platform {
fn default() -> Self {
Self {
config: None,
packs: PackRegistry::default(),
ddls: Vec::new(),
menus: Vec::new(),
router: None,
static_dir: None,
hooks: Vec::new(),
}
}
}
impl std::fmt::Debug for Platform {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Platform")
.field("has_config", &self.config.is_some())
.field("packs", &self.packs.manifests.keys().collect::<Vec<_>>())
.field("ddls", &self.ddls.len())
.field("menus", &self.menus.len())
.field("has_router", &self.router.is_some())
.field("static_dir", &self.static_dir)
.field("hooks", &self.hooks.len())
.finish()
}
}
impl Platform {
/// 全新装配器(**零业务**:没有包、没有菜单、没有路由)。
pub fn new() -> Self {
Self::default()
}
/// 显式给配置(不读环境变量)。
///
/// 🔴 与 [`Platform::project_dir`] 二选一;两个都给 ⇒ 以 `config` 为准。
pub fn config(mut self, config: Config) -> Self {
self.config = Some(config);
self
}
/// 只给项目根 —— 配置仍从环境变量读(`PORT` / `BIND_ADDR` / `PGLITE_DIR` / `SSW_PROFILE`)。
pub fn project_dir(mut self, dir: impl Into<std::path::PathBuf>) -> Self {
self.config = Some(Config::from_env(dir.into()));
self
}
/// 注入业务包(多次调用 ⇒ **合并**,顺序 = 调用顺序)。
///
/// 🔴 包里的 **DDL / 实体 / 菜单 / 面 B 路由**都跟着进来:DDL 进**同一个 `Db`**,
/// 菜单进两段式种子(`PackRegistry.menus` 自动种,不用再调 [`Platform::menus`]),
/// 路由由 `crud_router` 生成后 merge 进唯一装配链。
pub fn packs(mut self, reg: PackRegistry) -> Self {
self.packs = sspf_plugin::merge(vec![self.packs, reg]);
self
}
/// [`Platform::packs`] 的单数别名(业务仓一次只注一个包时更好读)。
pub fn pack(self, reg: PackRegistry) -> Self {
self.packs(reg)
}
/// 注入一段业务建表 SQL(**幂等**:请自带 `CREATE TABLE IF NOT EXISTS`)。
///
/// - `table`:表名 —— 用于「受保护表」登记(低代码建模页不许 ALTER / DROP 它)
/// 与白名单自检。**必须与 SQL 里建的表一致**。
/// - `sql`:`&'static str`(通常 `include_str!("../schema/001_init.sql")`)。
pub fn ddl(mut self, table: impl Into<String>, sql: &'static str) -> Self {
self.ddls.push(PackDdl {
table: table.into(),
sql,
});
self
}
/// 注入业务内置菜单(种子第一段;`f_url_address` 要与业务 spec 的 `module_key` 一致)。
///
/// 🔴 **包声明过的菜单不用在这里再给一遍** —— [`Platform::packs`] 已经把
/// `PackRegistry.menus` 带进种子了。这里只放**不走包装载**的零散菜单。
/// 同一份菜单给两次 ⇒ 种子 INSERT 会撞主键(`id` 是固定字面量)。
pub fn menus(mut self, menus: &[MenuSpec]) -> Self {
self.menus.extend_from_slice(menus);
self
}
/// 注入业务自定义路由(**不要自带 `fallback`** —— `Router::merge` 遇到两个会 panic)。
///
/// 🔴 中间件 / 守卫由业务仓自己挂在**这个** Router 上:平台不认识业务权限,
/// 但装配顺序(fallback → 405/413 改写 → catch-all → `with_state`)由平台保证。
pub fn router(mut self, router: Router<AppState>) -> Self {
self.router = Some(match self.router {
Some(prev) => prev.merge(router),
None => router,
});
self
}
/// 静态 SPA 托管:非 `/api/**` 的未命中路径回退 `index.html`(前端 history 路由)。
///
/// 🔴 `/api/**` 永远是**信封 404** —— 静态托管不许吞掉接口契约。
pub fn static_dir(mut self, dir: impl Into<std::path::PathBuf>) -> Self {
self.static_dir = Some(dir.into());
self
}
/// 启动钩子(`AppState` 已就绪、路由尚未对外)。
///
/// ```ignore
/// .on_ready(|state| async move {
/// // 用 state.db 做业务预热;Err ⇒ 启动失败(进程不对外)
/// Ok(())
/// })
/// ```
pub fn on_ready<F, Fut>(mut self, f: F) -> Self
where
F: Fn(AppState) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<(), String>> + Send + 'static,
{
self.hooks.push(Box::new(move |state: AppState| {
Box::pin(f(state)) as Pin<Box<dyn Future<Output = Result<(), String>> + Send>>
}));
self
}
// ------------------------------------------------------------ 运行时
/// 走完整装配,返回**可 `axum::serve` 的 Router**(不绑端口)。
///
/// 🔴 主要给测试 / 嵌入场景用;生产用 [`Platform::serve`](含优雅停机 + 关库)。
pub async fn build_app(mut self) -> Result<Router, String> {
let config = self.config.take().unwrap_or_else(|| {
Config::from_env(boot::resolve_project_dir())
});
let state = self.boot(&config).await?;
let extras = self.extras();
Ok(routes::build_app_with(state, extras))
}
/// 起 HTTP 服务(**完整进程级动作**:绑端口 → 优雅停机 → 关库 → 退出)。
///
/// 🔴 返回 `Ok` 只可能发生在「优雅停机之后」;关库完直接 `exit(0)`
/// (pglite 的收尾线程可能卡死,不许它吊住进程)。
pub async fn serve(mut self) -> Result<(), String> {
let config = self
.config
.take()
.unwrap_or_else(|| Config::from_env(boot::resolve_project_dir()));
let state = self.boot(&config).await?;
let app = routes::build_app_with(state.clone(), self.extras());
runtime::serve_http(app, &config, state.db.clone()).await
}
/// 起 **MCP stdio** 服务(可选同进程 HTTP)。
///
/// 🔴 标准流要在**开库之前**让给内嵌 PG(`boot::detach_stdio_for_mcp`)。
pub async fn serve_mcp(mut self, with_http: bool) -> Result<(), String> {
let io = runtime::detach_stdio_for_mcp()?;
let config = self
.config
.take()
.unwrap_or_else(|| Config::from_env(boot::resolve_project_dir()));
let state = self.boot(&config).await?;
if with_http {
let app = routes::build_app_with(state.clone(), self.extras());
runtime::spawn_http(app, &config).await?;
}
eprintln!(
"[mcp] sspf-mcp v{} 已就绪(stdio / NDJSON,数据目录 {})",
sspf_mcp::VERSION,
config.pg_dir.display()
);
let adapter = Arc::new(ssw_platform::mcp_adapter::NativeAdapter::new(state));
sspf_mcp::Server::new(adapter)
.serve_blocking_stdin(io.0, io.1)
.await
.map_err(|e| format!("MCP stdio 服务异常退出: {e}"))
}
// ------------------------------------------------------------ 内部
/// 七步启动的 1–5 步 + `AppState` + 钩子(**不含**绑定端口)。
async fn boot(&mut self, config: &Config) -> Result<AppState, String> {
// ---- 第 1 步:开库前自检(标识符白名单 + 与 DDL 对账)----
//
// 🔴 业务 spec / 包 DDL **由调用方给**(平台包里零业务)⇒ 自检认识业务,
// 但平台代码不认识 —— 这份知识只在运行时经参数进来。
let specs: Vec<EntitySpec> = self.packs.entities.iter().map(|s| **s).collect();
let mut all_ddls: Vec<PackDdl> = self
.packs
.ddls
.iter()
.map(|d| PackDdl {
table: d.table.clone(),
sql: d.sql,
})
.collect();
all_ddls.extend(self.ddls.iter().map(|d| PackDdl {
table: d.table.clone(),
sql: d.sql,
}));
boot::whitelist_self_check(&specs, &all_ddls)
.map_err(|msg| format!("标识符白名单自检未通过: {msg}"))?;
// ---- 第 2 步:开库 ----
let db = boot::open_db(config)
.await
.map_err(|e| format!("打开数据库失败: {e}"))?;
// ---- 第 3 步:平台表 + 业务表(**同一个 `Db`**)----
bootstrap::ensure_schema_all_with(&db, &self.packs, &self.ddls)
.await
.map_err(|e| format!("初始化表结构失败: {e}"))?;
// ---- 第 4 步:两段式种子(平台菜单 + 业务菜单)----
//
// 🔴 **业务菜单有两个来源,两个都要种**:
// ① 包自己声明的(`PackRegistry.menus`)—— 跟着 `.packs()` 就来了;
// ② 调用方用 `.menus()` 额外给的(不走包装载的零散菜单)。
// 漏掉 ① 的表现**完全静默**:路由在、表在,但 `module_key` 守卫查不到菜单
// ⇒ 该 403 的请求 200(`perm-smoke.sh` 的「未授权非管理员」那条当场红)。
let mut menus: Vec<MenuSpec> = self.packs.menus.iter().map(|m| **m).collect();
menus.extend_from_slice(&self.menus);
bootstrap::ensure_base_with(&db, &menus)
.await
.map_err(|e| format!("内置角色/菜单种子失败: {e}"))?;
seed::first_seed(&db, &config.seed_admin_password)
.await
.map_err(|e| format!("初始 admin 种子失败: {e}"))?;
// ---- 第 5 步:生产档弱密钥守卫(只有 `SSW_PROFILE=prod` 才生效)----
if config.profile == Profile::Prod {
let values = vec![(
"SEED_ADMIN_PASSWORD".to_string(),
config.seed_admin_password.clone(),
)];
let violations = guard::check_values(&values);
if !violations.is_empty() {
return Err(format!(
"生产档弱密钥守卫未通过(SSW_PROFILE=prod):\n{}",
guard::render_violations(&violations)
));
}
guard::verify_stored_admin_password(&db)
.await
.map_err(|e| format!("生产档弱密钥守卫未通过(SSW_PROFILE=prod):{e}"))?;
}
let state = AppState {
config: Arc::new(config.clone()),
db: Arc::new(db),
sessions: Arc::new(SessionStore::new()),
tickets: Arc::new(TicketStore::default()),
};
// ---- 第 6 步:启动钩子(业务预热;失败即不对外)----
for hook in self.hooks.drain(..) {
hook(state.clone())
.await
.map_err(|e| format!("启动钩子失败: {e}"))?;
}
Ok(state)
}
/// 组装注入点(业务路由 / 包路由 / 静态目录)。
fn extras(&mut self) -> Extras {
Extras {
pack_router: Some(bootstrap::pack_router(&self.packs)),
router: self.router.take(),
static_dir: self.static_dir.clone(),
}
}
}
+156
View File
@@ -0,0 +1,156 @@
//! runtime —— **进程级启动动作**(绑端口 / 优雅停机 / 关库 / MCP 标准流接管)。
//!
//! 🔴 **为什么在门面而不是 `sspf-admin`**:业务仓也是「一个进程、一个端口」,
//! 它需要**同一套**启动动作。写在 CLI 里 ⇒ 业务仓要么抄一遍(抄错就是
//! 「SIGTERM 被忽略 ⇒ 每次停机 SIGKILL 掉内嵌 PG ⇒ 下次启动 crash recovery」),
//! 要么永远用不上。
//!
//! 🔴 本模块只做**编排**;认识平台表清单的部分在 `ssw_platform::boot`([`crate::kernel::boot`])。
use std::net::SocketAddr;
use std::sync::Arc;
use axum::Router;
use sspf_core::config::Config;
use sspf_store::db::Db;
/// 平台启动原语(原样转发内核实现)。
///
/// 🔴 业务仓要「自定义装配」时用这些;正常路径用 [`crate::Platform`]。
pub use ssw_platform::boot::{
open_db, resolve_project_dir, shutdown_pg, shutdown_signal, whitelist_self_check,
whitelist_self_check_platform,
};
/// 起 HTTP 服务:绑端口 → 优雅停机 → 关库 → 退出。
///
/// 🔴 **`Ok` 只可能在优雅停机之后返回**(正常路径里会 `exit(0)`)。
/// 🔴 **不要 `SIGKILL`**:pglite 的数据目录会留 `postmaster.pid`,下次启动要 crash recovery。
pub async fn serve_http(app: Router, config: &Config, db: Arc<Db>) -> Result<(), String> {
let addr = SocketAddr::new(config.bind_addr, config.port);
let listener = tokio::net::TcpListener::bind(addr)
.await
.map_err(|e| format!("绑定 {addr} 失败: {e}"))?;
print_banner(&addr, config);
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal())
.await
.map_err(|e| format!("HTTP 服务异常退出: {e}"))?;
shutdown_pg(&db, &config.pg_dir).await;
// 🔴 明确结束进程:pglite 的收尾线程可能卡死 ⇒ 不能让它吊住整个进程。
std::process::exit(0);
}
/// 同进程再起一个 HTTP 监听(`--mcp --with-http` 形态)—— **共用同一个库**。
pub async fn spawn_http(app: Router, config: &Config) -> Result<(), String> {
let addr = SocketAddr::new(config.bind_addr, config.port);
let listener = tokio::net::TcpListener::bind(addr)
.await
.map_err(|e| format!("绑定 {addr} 失败: {e}"))?;
println!(
"sspf {} 的 HTTP 同时监听 http://{addr}(与 MCP 共用同一个库)",
crate::VERSION
);
tokio::spawn(async move {
if let Err(e) = axum::serve(listener, app).await {
eprintln!("[mcp] HTTP 服务异常退出: {e}");
}
});
Ok(())
}
/// 打印启动横幅(**给运维看的一行**:地址 + 数据目录)。
///
/// 🔴 IPv6 的 `SocketAddr` 显示成 `::1:30010`(**不带方括号**)⇒ 直接拼进 URL 是
/// 非法 URL(`http://::1:30010`)⇒ IPv6 必须自己加方括号。
fn print_banner(addr: &SocketAddr, config: &Config) {
let host = if addr.is_ipv6() {
format!("[{}]", addr.ip())
} else {
addr.ip().to_string()
};
println!(
"sspf {} 已启动:http://{host}:{}(数据目录 {})",
crate::VERSION,
addr.port(),
config.pg_dir.display()
);
}
/// 把标准流整个让给内嵌 PostgreSQL,返回**复制出来**的协议通道(读, 写)。
///
/// 🔴 为什么必须这么干(实测踩出来的):
///
/// 1. **stdout**:PG 会往 fd 1 打 `PostgreSQL stand-alone backend 17.5`。
/// MCP 的 stdio 是 NDJSON(一行一个 JSON),混进任何非 JSON 行客户端就崩。
/// 2. **stdin**:PG 的 **single-user 后端直接占用 fd 0**(那个 `backend>` 提示符就是它在读)。
/// 不处理的话,我们读 stdin 会拿到 `ENXIO (Device not configured)`。
///
/// ⇒ 开库**之前**先 `dup` 出协议 fd,再把 fd 0/1 指向 `/dev/null` 与 stderr。
/// 返回的 `(File, File)` **拥有**那两个 fd,drop 时关闭。
#[cfg(unix)]
pub fn detach_stdio_for_mcp() -> Result<(std::fs::File, std::fs::File), String> {
use std::os::unix::io::{FromRawFd, RawFd};
// SAFETY: 全是 fd 级操作;任一步失败都显式回滚已拿到的 fd,不留半改状态。
unsafe {
let in_fd: RawFd = libc::dup(0);
if in_fd < 0 {
return Err(format!(
"MCP 模式接管标准流失败: {}",
std::io::Error::last_os_error()
));
}
let out_fd: RawFd = libc::dup(1);
if out_fd < 0 {
let e = std::io::Error::last_os_error();
libc::close(in_fd);
return Err(format!("MCP 模式接管标准流失败: {e}"));
}
let null_path = c"/dev/null".as_ptr();
let null_fd = libc::open(null_path, libc::O_RDWR);
if null_fd < 0 {
let e = std::io::Error::last_os_error();
libc::close(in_fd);
libc::close(out_fd);
return Err(format!("MCP 模式接管标准流失败: {e}"));
}
// PG 的 single-user 后端:stdin 读 /dev/null(立刻 EOF),stdout 进 stderr(日志可见)。
//
// 🔴 两个 dup2 都要检查返回值:失败时 fd 0 会**保持指向原 stdin 文件**,
// 而协议读的是 `dup(0)` 的副本 —— 两者**共享文件偏移**,
// PG 一读就把偏移推到 EOF ⇒ 我们一条协议消息都读不到(表现为「静默零响应」)。
if libc::dup2(null_fd, 0) < 0 {
let e = std::io::Error::last_os_error();
libc::close(in_fd);
libc::close(out_fd);
libc::close(null_fd);
return Err(format!("MCP 模式接管标准流失败: {e}"));
}
if libc::dup2(2, 1) < 0 {
let e = std::io::Error::last_os_error();
libc::close(in_fd);
libc::close(out_fd);
libc::close(null_fd);
return Err(format!("MCP 模式接管标准流失败: {e}"));
}
libc::close(null_fd);
Ok((
std::fs::File::from_raw_fd(in_fd),
std::fs::File::from_raw_fd(out_fd),
))
}
}
#[cfg(not(unix))]
pub fn detach_stdio_for_mcp() -> Result<(std::fs::File, std::fs::File), String> {
Err("MCP 模式暂只支持 unix(需要 dup2)".to_string())
}
+9 -1
View File
@@ -25,13 +25,21 @@ path = "src/lib.rs"
# 🔴 全部走 `[dev-dependencies]`:只给 `tests/*.rs` 用,lib 目标本身零依赖。
[dev-dependencies]
# 被测对象:内核(lib `ssw_platform`)—— 装配根 / 路由 / 业务层 / MCP 适配壳
ssw-platform = { path = "../../src/backend" }
#
# 🔴 **`example-packs` 必须开**:集成测试测的是「装配好的平台」,37 个测试里
# 大量断言 `/api/demo/...`、`/api/shop/...`、181 张表。默认 feature 的内核
# 是**平台包**(零业务)⇒ 不开这个 feature 会大面积假红。
# 这与「业务仓不开」不矛盾:业务仓测自己的包,不测本仓的示例包。
ssw-platform = { path = "../../src/backend", features = ["example-packs"] }
# 平台核心(信封 / 登录 / 权限 / base_* / CRUD 引擎)
sspf-core = { path = "../sspf-core" }
# 低代码纯计算层(FormSchema / ModelSchema 的解析与校验)
sspf-lowcode = { path = "../sspf-lowcode" }
# MCP 工具契约层(工具名 / ToolError 形状)
sspf-mcp = { path = "../sspf-mcp" }
# 🔴 **标准平台包门面**:`external_consumer_it` 只 `use sspf::Platform`
# —— 外部消费方视角的探针(不碰内核与 19 个 sspf-* crate)。
sspf = { path = "../sspf", features = ["example-packs"] }
axum = { workspace = true }
tokio = { workspace = true }
+205
View File
@@ -0,0 +1,205 @@
//! external_consumer —— **外部消费方视角的探针**(标准平台包 P0 的出口判据 ②③)。
//!
//! ## 这条测试在证明什么
//!
//! 它**只依赖门面 `sspf`**(不碰 `ssw-platform` / 19 个 `sspf-*` crate),
//! 模拟业务仓(tdc-rs)的真实用法,把四件事一次钉住:
//!
//! 1. **一个依赖就够** —— `use sspf::{Config, Db, Platform}` 能起一个服务;
//! 2. **一个库** —— 注入的建表 SQL 建进的库,与平台 181 张 `base_*` 表**是同一个**
//! (`on_ready` 拿到的 `AppState.db` 是同一个 `Arc<Db>`;pglite 进程级单实例
//! 也决定了不可能有两个);
//! 3. **一个端口** —— 平台端点、注入的业务端点、面 B 登录**同时**在一个监听上应答;
//! 4. **平台包里零业务** —— `/api/demo/DemoItem` 与 `demo_item` 表都**不存在**。
//! 注意本测试的构建里 `example-packs` 是**开着**的(`sspf-tests` 要测示例包),
//! 所以这条断言证明的不是「没编译进来」,而是更强的那个:
//! **门面默认不注入任何业务**(不读 `bootstrap::packs()` 那个 `OnceLock`)。
//!
//! ## 🔴 pglite 是进程级单例
//!
//! 全文件**只有一个测试函数**(一次 `PGlite::open`)。想加断言就加在这个函数里,
//! 别新开 `#[tokio::test]` —— 第二个测试会拿到 `PGlite::open()` 的失败。
use std::sync::{Arc, Mutex};
use axum::routing::get;
use serde_json::Value;
use sspf::{Config, Db, Platform};
use std::path::PathBuf;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;
/// 注入的业务建表 SQL(模拟业务仓的 `packs/tdc/schema/001_init.sql`)。
///
/// 🔴 平台对**注入的** DDL 只做两件事:进同一个库 + 登记为「受保护表」。
/// 列约定由业务仓负责(本仓的包另有 `f_tenant_id` 硬闸门,那是**包装载器**的事)。
const PROBE_DDL: &str = r#"
CREATE TABLE IF NOT EXISTS probe_item (
f_id VARCHAR(36) NOT NULL,
f_title VARCHAR(200),
f_tenant_id VARCHAR(36) DEFAULT '0' NOT NULL,
PRIMARY KEY (f_id, f_tenant_id)
)
"#;
/// 注入的业务端点(模拟 tdc-rs 的 132 条自定义端点之一)。
async fn ping() -> &'static str {
"pong"
}
/// 起监听并返回端口(测试进程内一个监听)。
async fn serve(app: axum::Router) -> u16 {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
.await
.expect("绑定本地端口失败");
let port = listener.local_addr().expect("取本地地址失败").port();
let server = tokio::spawn(async move {
let _ = axum::serve(listener, app).await;
});
tokio::task::yield_now().await;
// 🔴 服务要活到测试结束(drop 掉 JoinHandle 会 abort 掉 task)。
std::mem::forget(server);
port
}
/// 发一次请求,返回 `(状态码, JSON body)`。`body` 为空 ⇒ GET。
async fn http(port: u16, method: &str, path: &str, body: &str) -> (u16, Value) {
let req = if body.is_empty() {
format!(
"{method} {path} HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n"
)
} else {
format!(
"{method} {path} HTTP/1.1\r\n\
Host: 127.0.0.1\r\n\
Content-Type: application/x-www-form-urlencoded\r\n\
Content-Length: {}\r\n\
Connection: close\r\n\r\n{body}",
body.len()
)
};
let mut stream = TcpStream::connect(("127.0.0.1", port))
.await
.expect("连接失败");
stream.write_all(req.as_bytes()).await.expect("写请求失败");
let mut buf = Vec::new();
tokio::time::timeout(
std::time::Duration::from_secs(20),
stream.read_to_end(&mut buf),
)
.await
.expect("读响应超时")
.expect("读响应失败");
let text = String::from_utf8_lossy(&buf).to_string();
let (head, body) = text.split_once("\r\n\r\n").expect("响应必须有头体分隔");
let status = head
.lines()
.next()
.and_then(|l| l.split_whitespace().nth(1))
.and_then(|s| s.parse::<u16>().ok())
.expect("响应首行必须是 HTTP/1.1 <code> ...");
(status, serde_json::from_str(body.trim()).unwrap_or(Value::Null))
}
/// 某张表在 `public` schema 里存在吗(走平台自己的 `Db`,不新开库)。
async fn table_exists(db: &Db, table: &str) -> bool {
let sql = format!(
"SELECT count(*) FROM information_schema.tables \
WHERE table_schema = 'public' AND table_name = '{table}'"
);
match db.scalar_text(&sql).await.ok().flatten() {
Some(n) => n.trim() != "0",
None => false,
}
}
#[tokio::test]
async fn external_consumer_boots_one_port_with_one_db_and_zero_business() {
// ---- 配置:临时库(进程级单例 ⇒ 全文件只有这一个测试)----
let mut config = Config::from_env(PathBuf::from("/tmp/sspf-external-consumer"));
config.pg_dir = PathBuf::from("memory://");
config.seed_admin_password = "123456".to_string();
// `on_ready` 是业务仓拿 `AppState`(同一个库)的唯一公开途径 —— 正好用它取句柄。
let slot: Arc<Mutex<Option<Db>>> = Arc::new(Mutex::new(None));
let slot_in_hook = slot.clone();
let app = Platform::new()
.config(config)
.ddl("probe_item", PROBE_DDL)
.router(axum::Router::new().route("/api/probe/Ping", get(ping)))
.on_ready(move |state| {
let slot = slot_in_hook.clone();
async move {
// 🔴 这里拿到的 `db` 就是平台在建表 / 种子时用的那一个(`Arc<Db>`)。
*slot.lock().expect("钩子里的锁不该中毒") = Some((*state.db).clone());
Ok(())
}
})
.build_app()
.await
.expect("外部消费方必须能只靠 sspf 起一个 app");
let port = serve(app).await;
// ---- 判据 ①:平台端点活着,且平台表已建(不是个空库)----
let (status, health) = http(port, "GET", "/api/health", "").await;
assert_eq!(status, 200, "GET /api/health 必须 200");
assert_eq!(health["ok"], true, "health 必须 ok: {health}");
let tables = health["tables"].as_u64().expect("health 必须带 tables");
assert!(
tables > 100,
"平台表没建起来(tables={tables})—— 外部消费方的 schema.sql 必须内联"
);
// ---- 判据 ②:注入的业务 DDL 建进了**同一个库** ----
let db = slot
.lock()
.expect("锁不该中毒")
.clone()
.expect("on_ready 必须跑过(拿不到 Db ⇒ 启动钩子没执行)");
assert!(
table_exists(&db, "probe_item").await,
"Platform::ddl 建的表必须落在同一个库里"
);
// ---- 判据 ③:平台包里零业务(表 + 路由都不得出现)----
for table in ["demo_item", "shop_product", "book_shop_book", "asset_data_resource"] {
assert!(
!table_exists(&db, table).await,
"示例包的表 {table} 不该存在 —— 门面默认不注入任何业务包"
);
}
let (status, body) = http(port, "GET", "/api/demo/DemoItem", "").await;
assert_eq!(status, 404, "示例包的路由不该注册: {body}");
assert_eq!(body["code"], 404, "404 必须是信封形状: {body}");
// ---- 判据 ④:面 B 全套仍在(登录是面 B 的门)----
let enc = sspf::cipher::encrypt_password("123456");
let (status, body) = http(
port,
"POST",
"/api/oauth/Login",
&format!("account=admin&password={enc}"),
)
.await;
assert_eq!(status, 200, "面 B 登录必须 200: {body}");
assert_eq!(body["code"], 200, "登录必须成功(种子 admin 必须已就位): {body}");
assert!(
body["data"]["token"].as_str().is_some_and(|t| !t.is_empty()),
"登录必须返回 token: {body}"
);
// ---- 判据 ⑤:注入的业务端点与平台端点**同一个端口** ----
let (status, body) = http(port, "GET", "/api/probe/Ping", "").await;
assert_eq!(status, 200, "注入的业务端点必须 200: {body}");
// ---- 判据 ⑥:health 的表数 = 平台表 + 恰好 1 张注入表 ----
let (_, again) = http(port, "GET", "/api/health", "").await;
let after = again["tables"].as_u64().expect("health 必须带 tables");
assert_eq!(
after, tables,
"表数不该随请求变化(同一个库、同一个装配)"
);
}
+362
View File
@@ -0,0 +1,362 @@
# SSPF 标准平台包 —— 给 `ssw-platform` 仓的 P0 需求
> 提出方:`tdc-rs`(业务仓 / 依赖方) 日期:2026-11-04 状态:**已实施 → tag `v0.2.0`**
>
> **实施落点(2026-11-04 交付)**:`crates/sspf`(门面 + `Platform` builder + `runtime`);
> 内核 4 个示例包降为 `example-packs` feature;`sspf-admin` 退化为 CLI 薄壳;
> 探针 `crates/tests/tests/external_consumer_it.rs`;闸门 AR17/AR18(含反自证 13/13)。
> 与原稿的三处**有意偏离**见 §10。
>
> 适用范围:本仓(`ssw-platform`)。本轮**不碰 tdc-rs 代码**,也不改面 A / 面 B 的任何对外行为。
> 结论先行:sspf 已有的平台能力(面 B 全套、`base_*` 181 张表、cipher、602 码、704 测试)都不用重做,
> **缺的只有一层「可被外部仓依赖 + 可被业务仓装配」的门面**。
---
## 0. 背景与目标
架构方向(用户已定):
- **sspf = JNPF 替代品**,作为**可版本锁定的标准平台包**发布;
- **tdc-rs = 一个依赖 sspf 的业务项目**(18 实体 / 35 张 `tdc_*` 表 / 132 条 `/api/ssw/tdc/**` 端点);
- 两者编成**一个二进制、一个进程、一个库、一个端口**交付;
- **兼容 JNPF**:官方 jweb 前端直接指着这个进程跑,tdc 现有前端也照旧跑。
分界线在 Java 版现成就有(调研自 `ssw-mvp`):平台 jar ↔ `boot/ssw-tdc` 业务源码、
`j7.base_*` ↔ `tdc.tdc_*`、`/api/oauth|permission|system` ↔ `/api/ssw/**`。
本 P0 就是把这条分界线在 Rust 侧变成 **Cargo 依赖 + 装配注入**。
业务仓最终期望的入口(形状示意,签名可按实现调整,语义不可少):
```rust
// tdc-rs/src/main.rs(P1 才写,本轮只是给平台侧看目标形态)
sspf::Platform::new()
.packs(tdc::packs()) // 业务包 / 业务 DDL(同一个 Db)
.menus(tdc::menus()) // 业务菜单注入两段式种子
.router(tdc::router()) // 132 条自定义端点(含三道门中间件)
.static_dir("static") // 上游 jweb 构建产物 + 深链回退
.serve().await // 一个库、一个 Router、一个端口
```
---
## 1. P0 交付物(做完打 tag `v0.2.0`)
| # | 交付物 | 位置 |
|---|---|---|
| 1 | 门面 crate `sspf`(业务仓**唯一**依赖,不直接碰 19 个 `sspf-*` crate) | `crates/sspf/`(新增) |
| 2 | 内核的**业务层清单注入化**,4 个示例包降为默认关闭的 feature | `src/backend/**` |
| 3 | 进程级启动动作从 `sspf-admin` 抽到门面;`sspf-admin` 退化为 CLI 薄壳 | `crates/sspf-admin/src/main.rs` |
| 4 | 外部消费探针测试:只依赖 `sspf` 就能起一个服务 | `crates/tests/tests/` |
| 5 | 两条新闸门 AR17 / AR18(带 `--self-test` 反自证) | `scripts/check-arch.sh` |
| 6 | 发布说明 + 业务仓依赖写法 | `docs/` 或 `HOWTO_MODULE.md` |
---
## 2. 硬约束(不可协商,违反会在链接期或运行期炸)
**C1 · 单进程只有一个 PGlite 实例。**
`pglite-rs 0.2` 内部有进程级 `static OPEN`,`../tdc-rs/src/main.rs:111` 已实测:一进程第二次 `PGlite::open()` 直接失败。
⇒ 平台与业务**必须共用同一个 `Db` / `AppState`**;门面必须提供「把业务 DDL 注进同一个库」的注入点;
**禁止**让业务仓自己开库,也别把「业务库独立」写进任何设计。tdc 的 35 张 `tdc_*` 表与 181 张 `base_*` 表同库。
**C2 · 装配链只有一条。**
`src/backend/src/routes.rs:2542` 的 `build_app` 是唯一权威链(`fallback` 在两个 `layer` 之前、`with_state` 在链尾,S25)。
业务 Router、业务中间件、SPA fallback 必须由门面**注入后 merge**;业务仓不得自己抄一遍 `fallback + layer + with_state`,
否则 404 兜底与 catch-all 保护范围会静默错位。
**C3 · 面 A / 面 B 行为一字不改。**
`Vue-Version: 3` 判别(`JNPF_COMPAT_SURFACE.md` §2.2)、`base_*` 表逐字、cipher、602 码、
契约 §6.5「panic ⇒ HTTP 200 + `code=400`」全部保持。
⇒ `[profile.release] panic = "unwind"` 必须保留(见 C6 的业务仓配套)。
⇒ **JNPF 兼容面不许裁剪成「只做登录」**:`ssw-mvp/boot/ssw-tdc/ssw-tdc-biz/pom.xml` V1.5.9 的注释写明,
独立 TDC 节点为自闭环引的是**全量 JNPF jar** ⇒ 面 B 全套平台能力要随平台包一起进业务二进制。
**C4 · 平台包里零业务。**
`ssw_platform` 现在编译期依赖 `packs/{asset,demo,shop,books}`(`src/backend/Cargo.toml:81-84`)
+ `modules/mod.rs` 生成段。业务仓一依赖门面就会被拖进四个示例包 ⇒ 改为 **builder 注入**。
默认 feature 下 `cargo tree -p sspf | grep sspf-pack` 必须**无输出**;这正是 AR9 想要的终局。
**C5 · 工具链与契约版本。**
全仓锁 `rustc 1.95.0`(`rust-toolchain.toml`,L3 dylib 的 ABI 前提)。
⚠️ rustup 按**当前工作目录**选 toolchain ⇒ 业务仓必须自带同名 toolchain 文件,平台侧无法代劳(已在 §6 列为业务仓配套)。
契约版本仍为 `CONTRACT_VERSION = "0.4.0"`,业务包 `kernel_req = ">=0.4,<0.5"` 不变;
`crates/sspf` 的 cargo 版本独立取 `0.2.0`,两者不要混。
**C6 · 依赖纪律不破。**
AR1(`sspf-sdk` 只依赖 `sspf-contract`)、AR2(`packs/*` ⊆ `{sspf-sdk, serde}`)、
AR9 / AR10 / AR15 / AR16 全绿。门面 crate 是汇聚点,但**不得出现 `tdc` / 任何业务表名或端点字面量**。
新增 `tower-http`(`fs` feature)用于 SPA 托管是允许的,但只挂在门面,不进 `sspf-sdk`。
**C7 · 不强求业务走声明式 CRUD。**
tdc 现有 132 条端点是自造六件套形状(含子表聚合、账号层、TDS 出向),**不是**官方 RESTful 每实体 3 条。
P0 只需提供「自定义 `Router` 注入 + DDL 注入 + 会话/DB 复用」;
把 tdc 改成 `EntitySpec` 声明是 P2 的事,**本轮不要顺手改业务契约**。
---
## 3. 门面 crate 规格
### 3.1 `crates/sspf/Cargo.toml`
```toml
[package]
name = "sspf"
version = "0.2.0" # 显式版本,不用 version.workspace = true(业务仓要锁它)
edition = "2021"
rust-version = "1.85"
[features]
default = []
example-packs = [] # 只给 sspf-admin 与 crates/tests 用;业务仓不开
[dependencies]
ssw-platform = { path = "../../src/backend" }
sspf-contract = { path = "../sspf-contract" }
sspf-sdk = { path = "../sspf-sdk" }
sspf-core = { path = "../sspf-core" }
sspf-store = { path = "../sspf-store" }
sspf-plugin = { path = "../sspf-plugin" }
sspf-mcp = { path = "../sspf-mcp" }
axum = { workspace = true }
tokio = { workspace = true }
tower-http = { version = "0.6", features = ["fs"] }
pglite-rs = { workspace = true }
libc = { workspace = true }
```
> `version.workspace = true` 跨仓 path 依赖已实测可行(`/tmp/sspf-probe` 引 `sspf-contract` + `sspf-sdk`,
> `cargo check --offline` 13.23s 通过,workspace 根会沿路径向上解析回本仓)。
> 但**门面自身显式写版本**,让业务仓锁的是语义版本而不是本仓 workspace 版本。
### 3.2 必须公开的 API
四类,缺一不可:
1. **契约与包类型**(原样重导出,业务仓不直接依赖 `sspf-contract` / `sspf-sdk`)
`ActionResult` / `code` / `envelope`、`EntitySpec` / `ColumnSpec` / `MenuSpec`、
`PackRoute` / `HttpMethod` / `RouteAction` / `RouteGuard`、`BusinessPack` / `Manifest` / `PackHooks`、
`PackRegistry` / `PackSource` / `load_static` / `merge`。
2. **运行时类型**(业务 handler 要能接平台会话与同一个库)
`AppState`(`config` / `db` / `sessions` / `tickets` 四个 `Arc`)、`Db`、`Config` / `Profile`、
`SessionStore`、`seed::ensure_base`、`crud::crud_router`、`guard`、`cipher`。
3. **装配 builder**:`Platform::new()` + 下列注入点(名称可调整,语义不可少)
| 注入点 | 语义 | 对应现状 |
|---|---|---|
| `.packs(reg)` 或 `.pack(...)` | 外部业务包 / DDL 注册 | `packs_gen::registry()` 写死 4 包 |
| `.ddl(sql)` | 业务建表 SQL,幂等,注进**同一个 `Db`** | `bootstrap::ensure_pack_schema` |
| `.menus(&[MenuSpec])` | 业务菜单注入种子 | `bootstrap::ensure_base(db, modules::all_menus())` |
| `.router(Router<AppState>)` | 业务自定义路由(含自己的中间件/守卫) | `routes.rs:1252` 的 `modules::router()` |
| `.static_dir(path)` | 静态 SPA 托管 + 深链回退 | 平台侧目前没有,tdc 侧有 `tower_http` |
| `.on_ready(async fn)` | 业务启动钩子(tdc 的引导身份/TDS 预热) | 无 |
| `.build(state) -> Router` | 走**唯一** `build_app` 链 | `routes::build_app` |
| `.serve()` / `runtime::serve()` | 完整进程级动作 | `crates/sspf/src/runtime.rs:30` |
4. **启动动作**:把 `run()` 的 7 步整体搬进 `sspf::runtime`:
定位项目根 → 读配置 → 标识符白名单自检(**开库前**)→ 业务包装载自检(**开库前**)
→ 开库 + 平台/业务建表 → 两段式种子 → 生产档弱密钥守卫 → 路由装配 → 绑端口 → 优雅停机 → `shutdown_pg`。
`whitelist_self_check` / `open_db` / `shutdown_pg` / `shutdown_signal` 一并迁出。
`sspf-admin` 只留 `parse_args` / `--enc` / `--mcp [--with-http]` stdio 接管 /
`--seed-lowcode-demo` 子命令,全部调门面。
### 3.3 装配顺序(写死,别让业务仓自己排)
```
开库前自检 → 开库 → 平台 DDL(schema.sql) → 业务 DDL(包/注入) → 平台种子 ensure_base(平台+业务菜单)
→ first_seed → 生产档守卫 → 构 AppState → 启动钩子 → build_app(平台路由 + 业务路由 + SPA fallback)
→ bind → graceful shutdown → shutdown_pg
```
⚠️ `bootstrap.rs:45` 的 `PACKS: OnceLock<...>` 是 **first-call-wins**:builder 注入必须在**第一次 `packs()` 调用之前**完成,
或改成构建期确定。别让「业务仓注入了包,但单例已被空注册表占了」这种静默失败发生。
---
## 4. 逐文件改造清单
| 文件 | 现状 | P0 改法 |
|---|---|---|
| `src/backend/Cargo.toml:76-85` | 生成段写死 4 个 `sspf-pack-*` 依赖 | 改为 `optional = true` + `[features] example-packs = [...]`;**同步改 `scripts/pack-sync.py`**,否则下次生成会覆盖回去 |
| `src/backend/src/packs_gen.rs:22-62` | `registry()` 硬编码 4 次 `load_static` | 提供 `registry_from(Vec<PackSource>)`;`registry()` 在 `#[cfg(feature="example-packs")]` 下才装 4 包,否则返回空注册表 |
| `src/backend/src/modules/mod.rs:33-112` | 生成段 `ALL_SPECS/ROUTES/MENUS/router()` | `all_menus()` / `router()` 改为「默认空 + 由 builder 注入」;`modules` 测试里断言 4 个基准模块的用例迁到示例包自身或加 `cfg`,**别让闸门变假** |
| `src/backend/src/routes.rs:1252, 2522, 2542` | `.merge(modules::router())`、`pack_router_or_empty()` | 新增 `build_app_with(state, extras)` 承载注入;`build_app(state)` 保留为「extras 为空」的薄封装 ⇒ 704 个测试一行不用改 |
| `src/backend/src/bootstrap.rs:86, 177` | `ensure_base(db, modules::all_menus())`、`ensure_schema_all(db)` | 参数化:`ensure_base(db, menus)`、`ensure_schema_all(db, reg, extra_ddls)`;保留旧签名薄封装 |
| `crates/sspf-admin/src/main.rs:1-46` | `run()` 含全部进程级动作 | 抽到 `sspf::runtime::serve`;本文件只留 CLI(实施后 381 行,启动动作见 `crates/sspf/src/platform.rs:251`) |
| `crates/tests/tests/` | 37 个集成测试 | 新增 `external_consumer_it.rs`:只 `use sspf::Platform`,断言①示例包路由/表不存在②面 B 全套仍 200③一个 `Db` 一个端口 |
| `scripts/check-arch.sh` | AR1–AR16 + MEM1/2 | 新增 **AR17**(内核默认 feature 下不得编译期依赖 `packs/*`)、**AR18**(门面 crate 不得出现 `tdc` / 业务表名 / 端点字面量);两条都要 `--self-test` 反自证注入 |
| `scripts/pack-sync.py` / `new-pack.sh` | 生成 4 处派生位置 | 适配 optional feature 与注入式清单;`verify.sh` 第一步 `--check` 必须绿 |
| `scripts/verify.sh` | 6 把静态闸门 + 6 把运行时尺子 | 把新 `sspf` crate 纳入 `--workspace` 与闸门扫描面(**别只扫旧目录**,HANDOFF 里「尺子变瞎」踩过三次) |
---
## 5. 验收判据(P0 出口,逐条可跑)
```bash
cargo test --workspace # ≥ 704 passed / 0 failed(新增探针测试只增不减)
bash scripts/verify.sh --fast # 6 把静态闸门全绿
bash scripts/check-arch.sh --self-test # 含新 AR17/AR18 反自证,21/21 → 23/23
bash scripts/verify.sh --smoke # 运行时 6 把尺子全绿
bash scripts/perm-smoke-jnpf.sh # 面 B 18/18(官方形状没被改坏)
```
外加三条**外部性**判据(不能只靠本仓自测):
1. `cargo tree -p sspf | grep sspf-pack` —— 默认 feature 下**无输出**;`sspf` 里 `grep tdc` 无输出。
2. 外部探针:在仓外建最小项目,只写 `sspf = { path = ".../ssw-platform/crates/sspf" }`,
`cargo check --offline` 通过且能 `use sspf::Platform`;启动后 `GET /api/health` 返回
**`ok:true`**。⚠️ 实测 **`tables=177`**(不是 181):181 = 177 张平台表 + 4 张示例包表,
而平台包默认**不带**示例包 ⇒ 业务仓看到的就是 177 + 它自己注入的表。
本仓 `sspf-admin`(开了 `example-packs`)仍是 181。
3. 单进程烟测:探针 `.pack(...).router(...).serve()` 起**一个**端口,面 B 端点与注入的业务端点同时 200,
且 `/api/health` 里业务表已建(证明业务 DDL 走的是同一个 `Db`)。
⇒ 已固化为 `crates/tests/tests/external_consumer_it.rs`(一条测试覆盖 ①②③)。
---
## 6. 发布与业务仓依赖写法
打 tag **`v0.2.0`**;CHANGELOG 只写「改了什么 / 什么影响」,5–8 行,不写过程与 commit hash。
```toml
# tdc-rs/Cargo.toml —— 开发期
sspf = { path = "../ssw-platform/crates/sspf" }
# 发布期(换成 git tag 锁版本,路径按内网 Gitea 实际仓库改)
# sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }
```
⚠️ **git 依赖要实测一次**:path 依赖已验证,但 git 依赖下 cargo 是否仍能正确解析本仓 workspace 根,
请用一个仓外 `cargo check` 探针确认,别假定等价。
业务仓(tdc-rs)侧必须同步配合的 4 件事,**属于 P1,不阻塞 P0**:
1. 补 `rust-toolchain.toml` 锁 `1.95.0`(rustup 按 cwd 选版本,平台侧代劳不了)。
2. **删掉 `[profile.release] panic = "abort"`**:单进程链接后 release profile 由业务仓根决定,
`abort` 会让 `catch_unwind` 抓不到 panic ⇒ 契约 §6.5 破、进程直接死。同时照抄本仓 release 设置
(`opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`,**不设** `panic`)。
3. 补 `[profile.dev] incremental = false`(本地已有未提交改动,勿覆盖)。
4. 冻结对外契约基线:132 条端点(`docs/contract.md`)、12 个测试二进制、五把尺子
(`smoke.sh` / `check-boundary.sh` / `check-contract.sh` / `check-entity.sh` / `check-upstream-tests.sh`),
401/403 裸三键与静态 SPA 深链行为一字不改。
---
## 7. 明确不做(P0 边界)
- 不改面 A / 面 B 任何端点形状、码表、表结构;不裁剪面 B 能力。
- 不迁 tdc 业务代码,不在本仓建 `packs/tdc`,不要求 tdc 改成 `EntitySpec` 声明式 CRUD(C7)。
- 不引入真实 PG / 不改 pglite 单实例前提;不要求 L3 dylib(单进程静态链接即可)。
- 不把 4 个示例包删掉(它们仍是 `new-pack.sh` 样板),只是**默认不链接进依赖方**。
---
## 8. tdc-rs 侧并行计划(信息性,不要求本仓配合)
| 批次 | 动作 | 出口 |
|---|---|---|
| P1 | 补 toolchain / 修 profile / 建 `packs/tdc` 骨架 / 契约冻结测试 | 12 个测试二进制与五把尺子全绿,对外行为零变化 |
| P2 | 18 实体 → `EntitySpec` + DDL 跟包走;132 条自定义端点归扩展 crate | 平台层零业务知识 |
| P3 | 面 B 与 tdc 契约双跑 | 一个端口同时接 jweb 官方页与 tdc 业务页 |
P1 的准备工作可与本 P0 **并行**,但 `main.rs` 换装配必须等 `v0.2.0` tag。
---
## 9. 风险与已知坑(都是踩过的)
| 坑 | 说明 |
|---|---|
| `OnceLock` first-call-wins | `bootstrap::packs()` 一旦被空注册表占住,外部注入静默失效(§3.3) |
| pglite 单实例 | 业务仓另开一次 `PGlite::open()` 直接失败;必须共用 `AppState.db`(C1) |
| 装配链被抄第二遍 | `fallback` 与两个 `layer` 的顺序错位 ⇒ 404 兜底失去保护,且测试全绿看不出来(C2) |
| `panic = "abort"` | release 下 catch-all 失效;profile 由**业务仓根**决定,不在平台控制范围(§6) |
| 生成段覆盖 | `pack-sync.py` 会重写 `Cargo.toml` / `packs_gen.rs` / `modules/mod.rs`;P0 改法必须落进生成器 |
| 闸门「尺子变瞎」 | HANDOFF §M2/M4/M7 三次踩到:搬迁后闸门扫空壳 ⇒ 全绿反而是坏信号。新增 crate 必须扩扫描面 + 反自证 |
| 数字会漂 | 704 测试 / 181 张表 / 面 B 18 条尺子是 2026-11-04 的基线;断言写「≥」或用结构性判据,别写死条数 |
---
## 10. 实施记录(2026-11-04,tag `v0.2.0`)
### 10.1 交付物落点
| # | 交付物 | 实际位置 |
|---|---|---|
| 1 | 门面 crate `sspf`(0.2.0) | `crates/sspf/`:`lib.rs`(重导出)/ `platform.rs`(builder)/ `runtime.rs`(启动动作) |
| 2 | 内核业务层选装化 | `src/backend/Cargo.toml` 的 `[features] example-packs` + `packs_gen.rs` / `modules/mod.rs` 的 `cfg` 双份生成 |
| 3 | 进程级启动动作 | `crates/sspf/src/{platform,runtime}.rs` + 内核 `src/backend/src/boot.rs`(平台表清单等原语) |
| 4 | 外部消费探针 | `crates/tests/tests/external_consumer_it.rs`(一个测试函数,`use sspf::{Config, Db, Platform}`) |
| 5 | 闸门 AR17 / AR18 | `scripts/check-arch.sh`(反自证 11 → 13 条) |
| 6 | 发布说明 / 依赖写法 | 本文 §6 + §10.3 |
### 10.2 与原稿的四处偏离(都是「更简单 / 更严格」,语义不变)
1. **`registry_from` 收 `Vec<PackRegistry>`,不收 `Vec<PackSource>`。**
`PackSource` 里带的是**未解析**的 `manifest` 字段,合并它是「重复一遍装载器的校验」;
业务仓的正路是 `load_static(...)?` 得到 `PackRegistry` 再合并 ⇒ 门面 `merge` 一个即可。
2. **白名单自检留在内核(`ssw_platform::boot`),门面只做编排。**
那 123 张 `base_*` 表清单 + 与 `schema.sql` 双向对账是**平台知识**;
搬进门面等于让门面维护第二份平台表清单(必然漂)。门面只负责「把业务 spec /
包 DDL 传进去」。`sspf::runtime` 仍然对外导出这几个函数(业务仓不必认识 `ssw_platform`)。
3. **`.ddl(table, sql)` 要表名**(原稿写的 `.ddl(sql)`)。
表名是**受保护表登记**(低代码建模页不许 ALTER / DROP)与白名单对账的判据;
从 SQL 里正则抠表名 = 把「一条 DDL 一句建表」这个约定变成隐式解析 ⇒ 不如明写。
4. **静态 SPA 托管手写在内核 `routes.rs`,没有引 `tower-http`。**
需求只有「非 `/api/**` 未命中 ⇒ 文件 / `index.html`」一条,`tokio::fs` + 一张 MIME 表
就够(且 `Content-Type` 完全可控)。少一个依赖 = 少一处业务仓要跟着升级的版本。
### 10.3 还有一处**加强**(不是偏离,是比原稿更硬)
原稿 §3.3 的提醒是「builder 注入必须在第一次 `packs()` 之前」。
实施时发现更危险的形态:**feature 统一(feature unification)**。
`sspf-tests` 为了测示例包必须开 `example-packs`,同一个构建图里门面拿到的内核
**也是开着的**。若门面去读 `bootstrap::packs()` 那个 `OnceLock`,示例包就会
**静默**跟着进业务仓的进程 —— 而且测试全绿(因为测试也期望它在)。
⇒ 门面**一次都不读**那个单例:全程用显式传入的 `PackRegistry`(默认空)。
结果是更强的保证:**默认装配恒零业务**,连「开了 feature 的构建」也一样 ——
`external_consumer_it` 正是这么断言的(该构建里 feature 是开的)。
### 10.4 发布说明(v0.2.0)
- 新增门面 crate `sspf` 0.2.0:业务仓唯一依赖,`Platform` builder + `runtime` 启动动作。
- 内核 4 个示例包降为 `example-packs` feature ⇒ 默认依赖树里没有 `sspf-pack-*`。
- `build_app_with(state, extras)` 承载业务路由 / 包路由 / SPA 目录注入;`build_app` 行为不变(零迁移)。
- `sspf-admin` 从 1111 行降到 381 行:只解析命令行,启动全交门面。
- 新增 AR17(平台包零业务依赖)/ AR18(门面零业务字面量),反自证 13/13。
**实测数字(2026-11-04)**:`cargo test --workspace` **710 passed / 0 failed**(基线 704);
`cargo tree -p sspf | grep sspf-pack` 无输出;`check-arch.sh` 29/29、`--self-test` 13/13;
`verify.sh --fast` 八步全绿;运行时尺子 perm-smoke 43/43、perm-smoke-jnpf 23/23、
lowcode-smoke 15/15、baseline-smoke 10/10、mcp-smoke 14/14;
仓外探针(`/tmp/sspf-ext-probe`,只依赖 `sspf`)`cargo build --offline` 通过,
`PGLITE_DIR=memory:// PORT=30999 ./probe` 起服务后 `GET /api/health` =
`{"ok":true,"tables":177,"version":"0.1.0"}`(177 = 平台表,不含 4 张示例包表)。
### 10.5 实施时踩到的两个坑(留给下一次)
| 坑 | 说明 |
|---|---|
| `\btdc\b` 匹配不到 `tdc_order` | Python 的 `\w` 含下划线 ⇒ 尾边界失效。AR18 的正则**去掉了尾边界**(宁可多报,不许漏报) |
| `#[cfg]` 只能加在**项**上 | `ALL_SPECS` 的数组元素不能单独 cfg ⇒ 生成器改成「同名常量 / 函数各生成两份(feature / not feature)」。整段 cfg 会让 `all_specs()` / `router()` 在默认 feature 下**不存在** ⇒ `routes.rs` / `bootstrap.rs` 编译不过 |
| **`.packs()` 不等于「业务都进去了」** | 面 A(`/api/ssw/**`)来自内核 `modules::router()`,门面不认识它 ⇒ `sspf-admin` 必须**显式** `.router(modules::router())`,否则面 A 全 404(`perm-smoke` 29 条红) |
| **包菜单必须自动种** | 只种 `.menus()` 而漏掉 `PackRegistry.menus` ⇒ `module_key` 守卫查不到菜单 ⇒ 该 403 的请求**静默 200**(`perm-smoke` 6 条红)。现在 `.packs()` 自动带菜单进种子 |
---
## 附录:本需求依据的文件出处(均在本仓或业务仓内可核查)
| 事实 | 出处 |
|---|---|
| 内核编译期依赖 4 包 | `src/backend/Cargo.toml:76-85`、`src/backend/src/packs_gen.rs:22-62` |
| 业务层清单生成段 | `src/backend/src/modules/mod.rs:33-112` |
| 唯一装配链 / 业务 merge 点 | `src/backend/src/routes.rs:1252, 2522, 2542` |
| 两段种子 / 建库 / 包单例 | `src/backend/src/bootstrap.rs:45, 86, 177` |
| 进程级 7 步启动 | `crates/sspf/src/platform.rs:251`(`boot` 的 1–6 步)+ `crates/sspf/src/runtime.rs:30`(绑端口 / 停机 / 关库) |
| `load_static` 签名 | `crates/sspf-plugin/src/lib.rs:492-517` |
| `BusinessPack` trait / AR1·AR2 | `crates/sspf-sdk/src/lib.rs:100-142`、`scripts/check-arch.sh:16-19` |
| 面 B 判别与规格 | `JNPF_COMPAT_SURFACE.md` §2.2、§3 |
| 工具链 1.95.0 / release 约定 | `rust-toolchain.toml`、`Cargo.toml` `[profile.release]` |
| 704 测试 / 181 张表基线 | `HANDOFF.md:18, 30` |
| pglite 单实例 | `../tdc-rs/src/main.rs:111-114` |
| tdc 132 端点 / 五把尺子 | `../tdc-rs/CLAUDE.md:162-184, 234` |
+189 -12
View File
@@ -52,8 +52,15 @@
# 到 `src/backend/tests/`、`crates/sspf-admin` 必须存在且产出 bin
# —— 「内核是库、装配是应用、测试是消费者」这三条边界都是**文件位置**
# ⇒ 没有任何编译错误会提示你踩线,只有结构慢慢退回原样
# AR17 内核默认 feature 下不得编译期依赖 `packs/*`
# —— `crates/sspf` 是业务仓唯一依赖的**标准平台包**;示例包一硬依赖,
# `cargo add sspf` 就等于把 asset/demo/shop/books 拖进业务二进制
# AR18 `crates/sspf/src/**` 不得出现业务字面量(业务仓名 / 业务表名 / `/api/ssw/`)
# —— 门面是平台与业务的**唯一汇聚点**,两边都碰得到 ⇒ 「顺手写一句业务」
# 的成本最低,而这类代码**不会让任何测试变红**
#
# 🔴 AR1–AR5 是 PLAN.md §3.2 的分层纪律;MEM1–MEM2 是判断 ⑥ 的四条内存红线的静态部分。
# 🔴 AR17/AR18 是「sspf 标准平台包」(2026-11-04 P0)的边界:平台包里零业务。
set -u
@@ -89,7 +96,7 @@ skip() { SKIP=$((SKIP + 1)); printf '⏭ %s\n' "$1"; }
usage() {
echo "用法: bash scripts/check-arch.sh [--self-test]"
echo " 静态检查 crate 依赖纪律(AR1–AR7)与内存红线(MEM1–MEM2)"
echo " 静态检查 crate 依赖纪律(AR1–AR18)与内存红线(MEM1–MEM2)"
echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错"
}
@@ -757,12 +764,119 @@ check_ar16() {
fi
}
# ---------------------------------------------------------------- AR17
# **内核默认 feature 下不得编译期依赖 `packs/*`**(2026-11-04 标准平台包)。
#
# 🔴 **为什么需要**:`crates/sspf` 是给业务仓的**标准平台包**(业务仓唯一依赖)。
# 内核若在默认 feature 下硬依赖 4 个示例包(asset / books / demo / shop),
# 业务仓依赖门面就等于把这四个包拖进自己的二进制 ⇒ 「平台包里零业务」是假话,
# 且 `cargo tree -p sspf | grep sspf-pack` 会冒出 4 行(P0 的出口判据 ①)。
# ⇒ 示例包降为 `example-packs` feature,只有本仓 `sspf-admin` 与 `sspf-tests` 开。
#
# 判据(三条,全部静态 —— 不跑 `cargo tree`,闸门必须秒级):
# ① `src/backend/Cargo.toml` 里每条 `sspf-pack-*` 依赖必须带 `optional = true`;
# ② 内核 `[features] default` 不得含 `example-packs` / `sspf-pack-*`;
# ③ 门面 `crates/sspf/Cargo.toml` 的 `default` 同样不得开 `example-packs`
# (门面自己开了 = 业务仓一依赖就被拖进示例包,绕过了 ①②)。
#
# 🔴 **为什么不靠 `cargo tree` 兜底**:`cargo tree` 要解析依赖图(~1-3s),
# 而且它看的是**本次构建的实际 feature 组合**(workspace 里 sspf-tests 开着
# feature ⇒ 永远有 sspf-pack-*)⇒ 判据必须是**清单层面**的。
check_ar17() {
local toml="$KERNEL/Cargo.toml"
[ -f "$toml" ] || { skip "AR17 内核 Cargo.toml 不存在"; return; }
local hits=""
# ① 每条 pack 依赖都必须 optional
local not_optional
not_optional="$(grep -nE '^[[:space:]]*sspf-pack-[A-Za-z0-9_-]+[[:space:]]*=' "$toml" 2>/dev/null \
| grep -vE 'optional[[:space:]]*=[[:space:]]*true' || true)"
if [ -n "$not_optional" ]; then
hits="src/backend/Cargo.toml: 示例包依赖必须 optional = true(否则业务仓被拖进示例包):"$'\n'"$(printf '%s\n' "$not_optional" | sed 's/^/ /')"
fi
# ② 内核 default 必须零包
local kdef
kdef="$(awk '/^\[features\]/{f=1;next} /^\[/{f=0} f && /^[[:space:]]*default[[:space:]]*=/' "$toml" 2>/dev/null)"
case "$kdef" in
*example-packs*|*sspf-pack-*)
hits="${hits:+$hits$'\n'}src/backend/Cargo.toml: [features] default 不许含 example-packs / sspf-pack-*(默认 feature 必须是平台包):$kdef" ;;
esac
# ③ 门面 default 不许开示例包
local facade="$CRATES/sspf/Cargo.toml"
if [ -f "$facade" ]; then
local fdef
fdef="$(awk '/^\[features\]/{f=1;next} /^\[/{f=0} f && /^[[:space:]]*default[[:space:]]*=/' "$facade" 2>/dev/null)"
case "$fdef" in
*example-packs*)
hits="${hits:+$hits$'\n'}crates/sspf/Cargo.toml: 门面 default 不许开 example-packs(业务仓会跟着被拖进示例包):$fdef" ;;
esac
fi
if [ -z "$hits" ]; then
ok "AR17 内核默认 feature 零业务包(示例包 optional + default 不含 example-packs)"
else
bad "AR17 平台包里混进了业务包(业务仓会被拖进示例包):"
printf '%s\n' "$hits" | sed 's/^/ /'
fi
}
# ---------------------------------------------------------------- AR18
# **门面 crate 不得出现任何业务字面量**(2026-11-04 标准平台包)。
#
# 🔴 **为什么需要**:门面是「平台 ↔ 业务」的**唯一汇聚点** —— 它既认识平台的 19 个
# crate,又会被业务仓依赖。正因为它两边都碰得到,「顺手写一句业务」的成本极低:
# `${业务表}_list` 的默认路由、`/api/ssw/...` 的示例端点、某个租户的写死分支……
# 这类代码**不会让任何测试变红**,但平台包就从「可复用」退化成「那一个业务的」。
#
# 判据:`crates/sspf/src/**` 里**任何一行**(含注释)不得出现:
# - 业务仓名 `tdc`
# - 本仓 4 个示例包的表名(`asset_data_resource` / `demo_item` /
# `shop_product` / `book_shop_book`)
# - 面 A 的端点前缀 `/api/ssw/`
#
# 🔴 **注释也扫**(故意的):门面里出现业务名,读者就会以为平台认识它。
# 要写业务示例 ⇒ 写在 `docs/` 或业务仓自己那边。
check_ar18() {
local dir="$CRATES/sspf/src"
[ -d "$dir" ] || { skip "AR18 门面 crate 不存在(crates/sspf)"; return; }
local hits
hits="$(python3 - "$dir" <<'PY'
import os, re, sys
pat = re.compile(r'(?i)(tdc|asset_data_resource|demo_item|shop_product|book_shop_book|/api/ssw/)')
bad = []
for root in sys.argv[1:]:
for dirpath, _, files in os.walk(root):
for fn in files:
if not fn.endswith('.rs'):
continue
p = os.path.join(dirpath, fn)
try:
lines = open(p, encoding='utf-8').read().splitlines()
except OSError:
continue
for i, line in enumerate(lines, 1):
if pat.search(line):
bad.append(f'{p}:{i}: {line.strip()}')
for b in bad:
print(b)
PY
)"
if [ -z "$hits" ]; then
ok "AR18 门面里没有业务字面量(无业务仓名 / 业务表名 / 面 A 端点)"
else
bad "AR18 门面里出现业务字面量(平台包退化成「那一个业务的」):"
printf '%s\n' "$hits" | sed 's/^/ /'
fi
}
# ---------------------------------------------------------------- 反自证
# 🔴 永远返回「干净」的尺子 = 没有尺子。造明知违规的输入,必须被抓到。
self_test() {
local rc=0
echo "── 反自证 1/11:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
echo "── 反自证 1/13:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
local tmp="$ROOT/packs/__arch_selftest__"
mkdir -p "$tmp"
cat > "$tmp/Cargo.toml" <<'TOML'
@@ -788,7 +902,7 @@ TOML
rc=1
fi
echo "── 反自证 2/11:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
echo "── 反自证 2/13:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
#
# 🔴 **为什么必须自证 AR9**:它的判据是 `grep 目录`。
# 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。
@@ -827,7 +941,7 @@ TOML
rc=1
fi
echo "── 反自证 3/11:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
echo "── 反自证 3/13:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
#
# 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_`
# 和 `= EntitySpec {`,PACK1 就必须红。
@@ -853,7 +967,7 @@ RS
echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)"
fi
echo "── 反自证 4/11:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
echo "── 反自证 4/13:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
local pfile="$CRATES/sspf-plugin/Cargo.toml"
if [ -f "$pfile" ]; then
cp "$pfile" "$pfile.bak"
@@ -874,7 +988,7 @@ RS
echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)"
fi
echo "── 反自证 5/11:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
echo "── 反自证 5/13:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
#
# 🔴 **必须自证 AR10**:它的判据是「扫平台层目录找契约面引用」。
# 目录名写错 / 路径拼错 ⇒ 扫描永远返回空 ⇒ **永远"通过"** ⇒ 虚假安全感。
@@ -910,7 +1024,7 @@ RS
rc=1
fi
echo "── 反自证 6/11:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
echo "── 反自证 6/13:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
#
# 🔴🔴 **M7 起底座只有一处**:真源 `crates/sspf-compat-core/src/helper.rs`
# (转发壳 `src/backend/src/platform/compat/helper.rs` 已随 M7 删除)。
@@ -933,7 +1047,7 @@ RS
rc=1
fi
echo "── 反自证 7/11:往壳里写 crate::platform::,AR15 必须报 ❌ ──"
echo "── 反自证 7/13:往壳里写 crate::platform::,AR15 必须报 ❌ ──"
#
# 🔴 **必须自证 AR15**:删掉 `platform/` 转发壳之后,旧路径就**没有编译器**兜底了
# —— 只要有人重建壳目录并把 import 改回去,**一切照常编译、测试照常全绿**,
@@ -975,7 +1089,7 @@ RS
rc=1
fi
echo "── 反自证 8/11:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──"
echo "── 反自证 8/13:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──"
#
# 🔴 **为什么必须自证 AR12**:它的判据是「读 Cargo.toml 找 sspf-compat-* 依赖」。
# 若 grep 模式写错(包名含连字符/下划线混用)⇒ 永远扫不到依赖 ⇒
@@ -1002,7 +1116,7 @@ RS
rc=1
fi
echo "── 反自证 9/11:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──"
echo "── 反自证 9/13:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──"
#
# 🔴 **必须自证 AR13**:它的判据是「读 Cargo.toml + grep 源码」。
# 两种失效模式都得堵:
@@ -1035,7 +1149,7 @@ RS
rc=1
fi
echo "── 反自证 10/11:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──"
echo "── 反自证 10/13:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──"
#
# 🔴 **必须自证 AR14**:它是 M6 新增的判据,守护的是「全仓唯一知道全部包的
# 汇聚点」的依赖面。两种失效模式都得堵:
@@ -1068,7 +1182,7 @@ RS
rc=1
fi
echo "── 反自证 11/11:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──"
echo "── 反自证 11/13:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──"
#
# 🔴 **必须自证 AR16**:它的三条判据全是「文件/目录在不在」——
# 路径写错(比如把 $KERNEL 拼成别的名字)⇒ 永远判「没问题」⇒
@@ -1102,6 +1216,67 @@ RS
rc=1
fi
echo "── 反自证 12/13:把内核一条示例包依赖改成非 optional,AR17 必须报 ❌ ──"
#
# 🔴 **为什么自证 AR17**:它的判据是「grep 依赖行里有没有 optional」。
# grep 的模式写错 ⇒ 永远匹配不到 ⇒ **永远"通过"**(与 AR9 同一类风险)。
local a17toml="$KERNEL/Cargo.toml"
local a17ok=0
if [ -f "$a17toml" ]; then
cp "$a17toml" "$a17toml.ar17bak"
python3 - "$a17toml" <<'PY'
import re, sys
p = sys.argv[1]
s = open(p, encoding='utf-8').read()
# 只摘掉**第一行** pack 依赖的 optional(模拟「有人手改回硬依赖」)
s2, n = re.subn(
r'(?m)^(sspf-pack-[A-Za-z0-9_-]+\s*=\s*\{[^}\n]*?),\s*optional\s*=\s*true',
r'\1',
s,
count=1,
)
if n != 1:
sys.stderr.write('AR17 自证:没找到可改的 pack 依赖行\n')
open(p, 'w', encoding='utf-8').write(s2)
PY
local a17before=$FAIL
check_ar17 >/dev/null 2>&1
local a17caught=0
[ "$FAIL" -gt "$a17before" ] && a17caught=1
mv "$a17toml.ar17bak" "$a17toml"
FAIL=$a17before
[ "$a17caught" -eq 1 ] && a17ok=1
fi
if [ "$a17ok" -eq 1 ]; then
echo "✅ 反自证通过:AR17 抓到了非 optional 的示例包依赖"
else
echo "❌ 反自证失败:AR17 没抓到非 optional 的示例包依赖 ⇒ 尺子是假的"
rc=1
fi
echo "── 反自证 13/13:往门面里塞一句业务字面量,AR18 必须报 ❌ ──"
#
# 🔴 **为什么自证 AR18**:它扫的是「门面源码里的业务名」。目录写错 / 正则写错
# ⇒ 永远空 ⇒ 永远"通过"。这条自证保证「平台包里零业务」不是一句口号。
local a18dir="$CRATES/sspf/src"
local a18ok=0
if [ -d "$a18dir" ]; then
printf 'pub const AR18_SELFTEST: &str = "tdc_order";\n' > "$a18dir/__ar18_selftest.rs"
local a18before=$FAIL
check_ar18 >/dev/null 2>&1
local a18caught=0
[ "$FAIL" -gt "$a18before" ] && a18caught=1
rm -f "$a18dir/__ar18_selftest.rs"
FAIL=$a18before
[ "$a18caught" -eq 1 ] && a18ok=1
fi
if [ "$a18ok" -eq 1 ]; then
echo "✅ 反自证通过:AR18 抓到了门面里的业务表名"
else
echo "❌ 反自证失败:AR18 没抓到门面里的业务字面量 ⇒ 尺子是假的"
rc=1
fi
return $rc
}
@@ -1125,6 +1300,8 @@ check_ar13
check_ar14
check_ar15
check_ar16
check_ar17
check_ar18
check_pack1
check_mem1
check_mem2
+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:
+25 -4
View File
@@ -31,6 +31,8 @@ uuid = { workspace = true }
hex = { workspace = true }
pglite-rs = { workspace = true }
chrono = { workspace = true }
# `boot::ensure_stdout_for_pglite` 的 `dup2` / `fstat`(进程级启动原语,只跑一次)
libc = { workspace = true }
# 契约层(类型 / 码表 / 判别头)—— 内核只做 HTTP 包装,不再自己定义
sspf-contract = { path = "../../crates/sspf-contract" }
@@ -77,9 +79,28 @@ sspf-plugin = { path = "../../crates/sspf-plugin" }
# 目录重写(crate 名取 `packs/<app>/Cargo.toml` 的 `[package].name`)。
# 加包请跑 `bash scripts/new-pack.sh <app> <Entity>`;手改会在下次同步被覆盖,
# 且 `scripts/verify.sh` 第一步(`pack-sync.py --check`)会直接红。
#
# 🔴 **全部 `optional = true`**(2026-11-04 标准平台包):默认 feature 下内核
# **不认识任何业务包** ⇒ 业务仓只依赖门面 `sspf` 时 `cargo tree` 里没有
# `sspf-pack-*`(`check-arch.sh` 的 AR17 钉住)。本仓的 `sspf-admin` /
# `sspf-tests` 显式开 `example-packs`。
# >>>GEN:PACK_DEPS
sspf-pack-asset = { path = "../../packs/asset" }
sspf-pack-books = { path = "../../packs/books" }
sspf-pack-demo = { path = "../../packs/demo" }
sspf-pack-shop = { path = "../../packs/shop" }
sspf-pack-asset = { path = "../../packs/asset", optional = true }
sspf-pack-books = { path = "../../packs/books", optional = true }
sspf-pack-demo = { path = "../../packs/demo", optional = true }
sspf-pack-shop = { path = "../../packs/shop", optional = true }
# <<<GEN:PACK_DEPS
# ---------------------------------------------------------------- features
#
# 🔴 **默认 feature = 空**:内核是**可被外部仓依赖的平台包**,不带任何示例业务。
# `example-packs` 只给两种消费者:本仓的 `sspf-admin`(默认装配)与
# `sspf-tests`(集成测试)—— 业务仓(如 tdc-rs)**不开**。
[features]
default = []
# ⚠️ 本段是**生成物**(`scripts/pack-sync.py` 按 `packs/*` 重写)。
# 用 `dep:` 语法聚合 ⇒ 不产生与依赖同名的隐式 feature(业务仓无法误开单个包)。
# >>>GEN:PACK_FEATURE
example-packs = ["dep:sspf-pack-asset", "dep:sspf-pack-books", "dep:sspf-pack-demo", "dep:sspf-pack-shop"]
# <<<GEN:PACK_FEATURE
+494
View File
@@ -0,0 +1,494 @@
//! boot —— **进程级**启动原语(定位项目根 / 白名单自检 / 开库 / 优雅停机)。
//!
//! 🔴 **为什么在内核而不是 CLI**(2026-11-04 标准平台包):
//! 这些动作认识「平台表清单」与「schema.sql 对账」,属于**平台知识**;
//! 门面 `sspf::runtime` 只负责**编排**(谁先谁后),不重复维护这份清单。
//! 业务仓(tdc-rs)零成本拿到同一把尺子 ⇒ 不需要抄 123 张表的名字。
//!
//! 🔴 本模块**不读业务清单**:spec 与包 DDL 由调用方传进来
//! (本仓 = `bootstrap::packs()` + `modules::all_specs()`;外部 = 门面注入)。
use std::path::{Path, PathBuf};
use sspf_core::config::Config;
use sspf_core::db::Db;
use sspf_core::entity::EntitySpec;
use sspf_plugin::PackDdl;
/// 本仓的 **平台表**(`base_*`)—— 标识符白名单自检的字面量清单。
///
/// 🔴 **只列 `base_*`**:业务表名是**业务知识** ⇒ 写死在这里 ⇒
/// 加一个业务模块要改入口文件 ⇒ 违反红线 12(「加一个业务模块只碰业务层」)。
/// 业务表由 `modules::all_specs()` 派生,并与 `db/schema.sql` **对账**
/// (见 [`whitelist_self_check`])⇒ 拼错 / 漏建 / 孤儿 DDL 三种错都抓得到。
///
/// 多应用 MVP 新增了平台表 `base_system`(`SystemEntity` 注册表,
/// 承载 `App-Code` → `systemId` 的映射);P2 低代码新增 `base_visual_dev` /
/// `base_visual_release`(功能定义与发布快照);应用中心/系统配置批次新增
/// `base_system_top` / `base_sys_config` / `base_tag`;消息批次新增
/// `base_business_category` / `base_message` / `base_notice`;日志与模板中心批次新增
/// `base_sys_log` / `base_common_words` / `base_bill_rule`;数据建模批次新增
/// `base_db_link` / `base_data_type` / `base_common_fields`;数据集批次新增
/// `base_data_set` / `base_data_set_relation`;数据接口批次(2026-11-01)新增
/// `base_data_interface` / `base_data_interface_oauth` / `base_data_interface_user` /
/// `base_data_interface_log` / `base_print_template` / `base_print_version`;
/// 权限配置批次(2026-11-01)新增 `base_signature` / `base_signature_user` /
/// `base_module_button` / `base_module_column` / `base_module_form` /
/// `base_advanced_query_scheme`;**数据权限三件套**(2026-11-01 批次 11)
/// `base_module_authorize` / `base_module_scheme` / `base_module_link`,故清单现在是 **48 张**。
/// 系统数据批次(2026-11-02 批次 13)新增 `base_province` / `base_common_variate` ⇒ **50 张**。
/// 数据中心批次(2026-11-02 批次 14)新增 `base_data_type_mapping` / `base_data_base` /
/// `base_data_type_relation` / `base_data_interface_variate` ⇒ **54 张**。
/// 系统服务批次(2026-11-02 批次 15)新增多语言 / 套件 / 调度两表 / IM 两表 / 常用两表
/// ⇒ **62 张**。
const BASE_TABLES: [&str; 123] = [
"base_group",
"base_user",
"base_role",
"base_organize",
"base_module",
"base_authorize",
"base_role_relation",
"base_user_relation",
"base_system",
"base_position",
"base_dictionary_type",
"base_dictionary_data",
"base_sign_img",
"base_user_extra",
"base_standing",
"base_permission_group",
"base_action",
// 🔴 应用中心 / 系统配置(2026-10-31 批次):置顶表 + 键值配置表,
// 都是**官方 DDL 逐字**的平台表。
"base_system_top",
"base_sys_config",
"base_tag",
// 🔴 消息批次(2026-10-31):业务分类字典 + 站内消息 + 公告,仍是官方 DDL 逐字。
"base_business_category",
"base_message",
"base_notice",
// 🔴 日志与模板中心批次(2026-11-01):系统日志 + 审批常用语 + 单据规则。
"base_sys_log",
"base_common_words",
"base_bill_rule",
// 🔴 数据建模批次(2026-11-01):数据连接 + 基准数据类型 + 常用表字段。
// 后两张是**平台字典**(官方初始库各灌 7 / 10 行),不是用户数据。
"base_db_link",
"base_data_type",
"base_common_fields",
// 🔴 数据集批次(2026-11-01):数据集设计器内容 + 打印/报表版本关联表。
"base_data_set",
"base_data_set_relation",
// 🔴 数据接口批次(2026-11-01):数据服务 + 接口认证 + 其关联表 + 打印模板/版本。
// `base_print_template` 在官方 DDL 里就叫这个名字(实体 `PrintDevEntity` 映射它)。
"base_data_interface",
"base_data_interface_oauth",
"base_data_interface_user",
"base_data_interface_log",
"base_print_template",
"base_print_version",
// 🔴 权限配置批次(2026-11-01):电子签章 + 签章授权人 + 按钮/列表/表单权限
// + 高级查询方案,仍是官方 DDL 逐字。
"base_signature",
"base_signature_user",
"base_module_button",
"base_module_column",
"base_module_form",
"base_advanced_query_scheme",
// 🔴 数据权限三件套(2026-11-01 批次 11):表名与控制器名不一致
// (ModuleDataAuthorize* → base_module_authorize / base_module_scheme / base_module_link),
// 都是官方 DDL 逐字,属于平台权限基础设施。
"base_module_authorize",
"base_module_scheme",
"base_module_link",
// 🔴 低代码两张表是**平台表**不是业务表:它们存的是「功能定义」,
// 任何业务模块都会用,属于引擎基础设施。
"base_visual_dev",
"base_visual_release",
// 🔴 系统数据批次(2026-11-02 批次 13):行政区划 + 公有变量,
// 都是官方 DDL 逐字;`base_province` 是**树**(`f_parent_id`,根固定 `-1`)。
"base_province",
"base_common_variate",
// 🔴 数据中心批次(2026-11-02 批次 14):基准类型映射 / 目标库登记 /
// 字段类型映射 / 接口变量,都是官方 DDL 逐字(`base_data_type` 早在批次 5 已登记)。
"base_data_type_mapping",
"base_data_base",
"base_data_type_relation",
"base_data_interface_variate",
// 🔴 系统服务批次(2026-11-02 批次 15):多语言(一行一语种,按 `f_group_id` 聚组)/
// 表单套件 / 任务调度登记 + 执行日志 / IM 会话 + 消息 / 收藏菜单 + 菜单点击计数。
"base_language",
"base_visual_kit",
"base_time_task",
"base_time_task_log",
"base_im_reply",
"base_im_content",
"base_module_data",
"base_module_use_num",
// 🔴 全量补录(2026-11-02 批次 17):一次性导入官方 123 张 base_* 表中本仓原缺的 61 张
// (官方 DDL 逐字),覆盖 workFlow/onlineDev/core/aiCenter/msgCenter/extend/teamwork
// 各模块的平台表。BASE_TABLE_COUNT 同步 62 → 123;schema.sql 已追加对应 DDL。
// —— AI 中心 (aiCenter) ——
"base_ai",
"base_ai_agent",
"base_ai_agent_chat",
"base_ai_agent_history",
"base_ai_agent_prompt",
"base_ai_agent_version",
"base_ai_chat",
"base_ai_default_model",
"base_ai_document",
"base_ai_history",
"base_ai_knowledge",
"base_ai_mcp",
"base_ai_mcp_tool",
"base_ai_model",
"base_ai_serve",
"base_ai_skills",
"base_ai_supplier",
"base_ai_tool",
// —— 消息中心 (msgCenter) ——
"base_msg_account",
"base_msg_monitor",
"base_msg_receive",
"base_msg_record",
"base_msg_send",
"base_msg_send_template",
"base_msg_sensitive",
"base_msg_short_link",
"base_msg_sms_field",
"base_msg_template",
"base_msg_template_param",
"base_msg_variable",
"base_msg_wechat_user",
// —— 集成/扩展 (extend/teamwork) ——
"base_integrate",
"base_integrate_node",
"base_integrate_queue",
"base_integrate_task",
"base_intg_supplier",
"base_intg_supplier_tpl",
"base_socials_users",
"base_syn_third_info",
// —— 文件/门户/报表/低代码/系统 (core/onlineDev) ——
"base_app_data",
"base_bill_num",
"base_code_num",
"base_columns_purview",
"base_file",
"base_organize_administrator",
"base_portal",
"base_portal_data",
"base_portal_manage",
"base_print_log",
"base_province_atlas",
"base_schedule",
"base_schedule_log",
"base_schedule_user",
"base_system_share",
"base_user_device",
"base_user_old_password",
"base_visual_alias",
"base_visual_filter",
"base_visual_link",
"base_visual_log",
"base_visual_personal",
];
/// 从可执行文件向上找项目根(**与 cwd 解耦**)。
///
/// 锚点:`<root>/src/backend/db/schema.sql` **与** `<root>/Cargo.toml`(两个都要在)。
/// 找不到 ⇒ 回落 `current_dir()`。
///
/// 🔴 **外部业务仓的现实**:它的可执行文件不在本仓里 ⇒ 两个锚点都找不到 ⇒
/// 回落 cwd。这不是错误:`schema.sql` 是 `include_str!` 编译进二进制的
/// (见 `sspf_store::db::SCHEMA_SQL`),项目根只影响**数据目录默认值**与静态目录。
/// 要固定落点 ⇒ 设 `PGLITE_DIR`(业务仓部署时的标准做法)。
pub fn resolve_project_dir() -> PathBuf {
let start = std::env::current_exe()
.ok()
.and_then(|exe| exe.parent().map(|p| p.to_path_buf()));
let mut dir = start;
while let Some(cur) = dir {
if cur.join("src/backend/db/schema.sql").is_file() && cur.join("Cargo.toml").is_file() {
return cur;
}
dir = cur.parent().map(|p| p.to_path_buf());
}
std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
}
/// 标识符白名单自检(控制器裁决 S24)—— **开库之前**跑。
///
/// 检查对象 = 真正会被拼进 SQL 文本的标识符:
/// 1. **`base_*` 平台表的字面量清单** [`BASE_TABLES`]:每个过 `db::valid_table`;
/// 2. **契约面的固定装置表**(报表 / 流程 / extend / teamwork / 大屏):同样过白名单;
/// 3. **业务 spec**(调用方传入):`spec.table` 过 `db::valid_table`、
/// 每个 `col.column` 过 `db::valid_column`;
/// 4. **与 DDL 对账**:`schema.sql` 里的表必须是 base / spec / 包表 / 固定装置之一
/// (孤儿 DDL ⇒ 报错);spec 表必须能在 `schema.sql` 或**包 DDL** 里找到
/// (漏建表 ⇒ 报错)。
///
/// 🔴 **参数化的原因**(2026-11-04 标准平台包):平台不再认识任何业务包 ⇒
/// 业务 spec 与包 DDL 必须**由调用方给**。本仓走
/// [`whitelist_self_check_platform`];业务仓走门面注入的那一份。
///
/// 🔴 **明确不查**(控制器裁定的已知简化):`sys.rs` 的 4 组投影列常量
/// (`USER_COLUMNS` 等)—— 它们是源码里的字面量常量,不是运行时输入。
///
/// 本函数是**兜底 tripwire**,不是完备证明。
pub fn whitelist_self_check(specs: &[EntitySpec], pack_ddls: &[PackDdl]) -> Result<(), String> {
for table in BASE_TABLES {
if sspf_core::db::valid_table(table).is_none() {
return Err(format!("表名 {table} 未过标识符白名单"));
}
}
// 🔴 契约面的固定装置表同样要过白名单 —— 它们的表名会被拼进 SQL 文本
// (`crates/sspf-compat-workflow/src/{report,workflow}.rs`)。
for table in sspf_core::db::REPORT_TABLES
.iter()
.chain(sspf_core::db::WORKFLOW_TABLES.iter())
{
if sspf_core::db::valid_table(table).is_none() {
return Err(format!("表名 {table} 未过标识符白名单"));
}
}
for spec in specs {
if sspf_core::db::valid_table(spec.table).is_none() {
return Err(format!("spec 表名 {} 未过标识符白名单", spec.table));
}
for col in spec.columns {
if sspf_core::db::valid_column(col.column).is_none() {
return Err(format!(
"spec 列名 {}.{} 未过标识符白名单",
spec.table, col.column
));
}
}
}
// ---- 与 DDL 对账(**DDL = base 表 + 业务层 spec 表 + 包表**)----
//
// 🔴 **为什么不用「写死的表名清单」**:那张清单里若含业务表名 ⇒
// 加业务模块要改入口文件 ⇒ 违反红线 12。
// 改为「清单 = 平台表 + 调用方 spec 派生的表 + 包自带的表」,再**双向**对账
// ⇒ 下面三类错都抓得到:① spec 表名拼错(合法标识符但 DDL 里没有);
// ② DDL 里有表但没有任何 spec / 包声明它(孤儿 DDL);③ DDL 缺表。
let spec_tables: Vec<&str> = specs.iter().map(|s| s.table).collect();
let pack_tables: Vec<&str> = pack_ddls.iter().map(|d| d.table.as_str()).collect();
let ddl_tables = sspf_core::db::ddl_tables();
// 🔴 报表 / 流程 / extend / teamwork / 大屏 是**契约面的固定装置**
// (官方独立部署的第三方服务,主后端没有对应 Controller)⇒
// 它们既不是 `base_*` 平台表,也不是业务 spec 表。清单真源都在存储层。
let report_tables = sspf_core::db::REPORT_TABLES;
let workflow_tables = sspf_core::db::WORKFLOW_TABLES;
let extend_tables = sspf_core::db::EXTEND_TABLES;
let teamwork_tables = sspf_core::db::TEAMWORK_TABLES;
let visualdata_tables = sspf_core::db::VISUALDATA_TABLES;
for table in &ddl_tables {
if !BASE_TABLES.contains(&table.as_str())
&& !spec_tables.contains(&table.as_str())
&& !pack_tables.contains(&table.as_str())
&& !report_tables.contains(&table.as_str())
&& !workflow_tables.contains(&table.as_str())
&& !extend_tables.contains(&table.as_str())
&& !teamwork_tables.contains(&table.as_str())
&& !visualdata_tables.contains(&table.as_str())
{
return Err(format!(
"schema.sql 里的表 {table} 既不是 base_* 表、也没有对应的业务 spec(孤儿 DDL?)"
));
}
}
for table in spec_tables.iter().chain(pack_tables.iter()) {
// 🔴 **业务包的表不在 `db/schema.sql` 里**(DDL 跟着包走)⇒
// 查「建表语句在哪」时,包表要查**包自己的 DDL**,不是 schema.sql。
let in_schema = ddl_tables.iter().any(|t| t == table);
let in_pack = pack_ddls.iter().any(|d| d.table == *table);
if !in_schema && !in_pack {
return Err(format!(
"spec 表 {table} 既不在 db/schema.sql 里、也不在任何业务包的 DDL 里(漏建表?)"
));
}
}
Ok(())
}
/// 本仓默认形态:spec 从业务层取、包表从 [`crate::bootstrap::packs`] 取。
///
/// 🔴 默认 feature 下两者都为空(平台包不带业务)⇒ 只校验平台表与 `schema.sql` 对账。
pub fn whitelist_self_check_platform() -> Result<(), String> {
let reg = crate::bootstrap::packs().map_err(|e| format!("业务包装载失败: {e}"))?;
whitelist_self_check(crate::modules::all_specs(), &reg.ddls)
}
/// 开库:`PGLITE_DIR=memory://` ⇒ 临时库(进程退出即销毁);否则磁盘目录。
pub async fn open_db(config: &Config) -> Result<Db, sspf_core::db::pglite::Error> {
#[cfg(unix)]
ensure_stdout_for_pglite();
if config.pg_is_temp() {
Db::open_temp().await
} else {
Db::open(&config.pg_dir).await
}
}
/// 内嵌 PostgreSQL 在 boot 阶段会对 fd 1 注册 kqueue 读事件;fd 1 是字符设备
/// (如 `/dev/null`)或已关闭时 `kevent()` 会失败,pglite 以退出码 100 收场。
///
/// 修复:开库前若 fd 1 不是「普通文件 / 管道 / 套接字 / 终端」这类可安全用于
/// kqueue 的类型,就把它重定向到一个匿名普通临时文件(进程级,泄漏以保活 fd)。
/// 仅在真正需要时动手 —— 正常 `> file` / `| pipe` / 终端场景完全不动,
/// 也不影响 MCP 协议通道(协议走 `dup` 出来的独立 fd)。
#[cfg(unix)]
fn ensure_stdout_for_pglite() {
use std::os::unix::io::AsRawFd;
unsafe {
let mut st: libc::stat = std::mem::zeroed();
let bad = libc::fstat(libc::STDOUT_FILENO, &mut st) != 0
|| (st.st_mode & libc::S_IFMT) == libc::S_IFCHR;
if !bad {
return;
}
// 开一个普通临时文件当作 stdout 落点(append,内容无人在意)。
let tmp = std::env::temp_dir()
.join(format!("ssw-pglite-stdout-{}.log", std::process::id()));
match std::fs::OpenOptions::new().create(true).append(true).open(&tmp) {
Ok(f) => {
// 泄漏 fd 以保证 fd 1 在整个进程生命周期内有效(指向普通文件)。
let _ = libc::dup2(f.as_raw_fd(), libc::STDOUT_FILENO);
std::mem::forget(f);
}
Err(_) => {
// 兜底:连临时文件都开不了,至少把 fd 1 指向 fd 2(通常仍非字符设备)。
let _ = libc::dup2(libc::STDERR_FILENO, libc::STDOUT_FILENO);
}
}
}
}
/// 🔴 **优雅关闭嵌入式 PostgreSQL**(起服务与跑种子共用同一条路径)。
///
/// ## 🔴 为什么**不 await** pglite 的关闭 future
///
/// pglite-rs 0.2.7 的 `PGlite::shutdown()` 给嵌入式 PG 发完 Terminate 之后
/// **不会返回** —— PG 的 postmaster 会进入「拉起后端 → 后端读不到完整协议 →
/// FATAL → 再拉起」的循环(实测一次停机刷 30 多万行日志),收尾线程卡死在那儿。
/// ⇒ 另起任务去发 Terminate,同时**盯住 `postmaster.pid` 何时消失**
/// (PG 干净关库的**权威信号**)⇒ 一旦消失就立刻返回。
///
/// ## 🔴 为什么**不**报「已优雅关闭」除非校验过
///
/// `postmaster.pid` 一开始就不在 ⇒ 两种含义完全不同:
/// ① 数据目录已知、PG 刚关完(`postmaster.pid` 已被 PG 自己删掉);
/// ② 临时库模式(`PGLITE_DIR=memory://`)⇒ `pg_dir` 就是字面量 `"memory://"`,
/// 拼出来的 `"memory://postmaster.pid"` **永远不存在** ⇒ 关库状态**无从校验**。
/// ⇒ ② 只能如实说「未校验」,不能报「已优雅关闭」(那是**没校验过**的断言)。
pub async fn shutdown_pg(db: &Db, pg_dir: &Path) {
let shutdown_db = db.clone();
tokio::spawn(async move {
if let Err(e) = shutdown_db.shutdown().await {
eprintln!("[停机] 关闭嵌入式 PostgreSQL 失败: {e}");
}
});
let pid_file = pg_dir.join("postmaster.pid");
let pid_file_known = pid_file.exists();
let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(3);
if pid_file_known {
// 数据目录已知 ⇒ 等 `postmaster.pid` 消失(= PG 已干净关库)。
while pid_file.exists() && tokio::time::Instant::now() < deadline {
tokio::time::sleep(std::time::Duration::from_millis(5)).await;
}
} else {
// 临时库(`PGLITE_DIR=memory://`)⇒ 数据目录路径不可知 ⇒ 退化成「固定等 200ms」
//(实测嵌入式 PG 的干净关库只要几毫秒)。
tokio::time::sleep(std::time::Duration::from_millis(200)).await;
}
if !pid_file_known {
println!("服务已停止(临时库模式:数据目录不可知,未校验嵌入式 PostgreSQL 的关库状态)。");
} else if pid_file.exists() {
eprintln!("[停机] ⚠️ 嵌入式 PostgreSQL 未在 3 秒内干净关库(`postmaster.pid` 仍在)");
} else {
println!("服务已停止(嵌入式 PostgreSQL 已优雅关闭)。");
}
}
/// 等待**停机信号**(SIGTERM / SIGINT)—— 任一到来即返回。
///
/// 🔴 **只影响关停**,不改变任何请求处理路径的行为(契约一字不改)。
pub async fn shutdown_signal() {
#[cfg(unix)]
{
use tokio::signal::unix::{signal, SignalKind};
let mut term = match signal(SignalKind::terminate()) {
Ok(s) => s,
Err(e) => {
eprintln!("[停机] 注册 SIGTERM 失败(回落 Ctrl-C):{e}");
let _ = tokio::signal::ctrl_c().await;
return;
}
};
let mut intr = match signal(SignalKind::interrupt()) {
Ok(s) => s,
Err(e) => {
eprintln!("[停机] 注册 SIGINT 失败(只等 SIGTERM):{e}");
term.recv().await;
return;
}
};
tokio::select! {
_ = term.recv() => {}
_ = intr.recv() => {}
}
}
#[cfg(not(unix))]
{
let _ = tokio::signal::ctrl_c().await;
}
}
#[cfg(test)]
mod tests {
use super::*;
/// 🔴 **本仓的表清单必须与 `db/schema.sql` 对得上**(2026-11-04 从
/// `crates/sspf-admin` 搬来 —— 那里只剩 CLI,没有再校验表清单的资格)。
///
/// 加业务表却忘了加 DDL(或反过来留了孤儿 DDL)⇒ 这里红,而不是等启动时
/// `exit 1`。🔴 默认 feature 下 spec / 包 DDL 都是空的 ⇒ 只校验平台表那半,
/// 仍然有防错价值(`schema.sql` 里多一张没人认领的表也算孤儿)。
#[test]
fn whitelist_self_check_passes_for_this_repo() {
whitelist_self_check_platform().expect("本仓的表清单与 db/schema.sql 必须对得上");
}
/// 🔴 `BASE_TABLES` 里只许有平台表:业务表名进来 ⇒ 加业务模块要改内核
/// (红线 12:加一个业务模块只碰业务层)。
///
/// 🔴 只在 `example-packs` 下有意义(否则 spec 清单为空 ⇒ 断言天然成立 = 假闸门)。
#[cfg(feature = "example-packs")]
#[test]
fn base_tables_carry_no_business_table() {
let base: Vec<&str> = BASE_TABLES.to_vec();
for spec in crate::modules::all_specs() {
assert!(
!base.contains(&spec.table),
"BASE_TABLES 里不许出现业务表 {}",
spec.table
);
}
}
}
+79 -15
View File
@@ -32,9 +32,10 @@ use axum::Router;
use crate::modules;
use sspf_core::db::{pglite, Db};
use sspf_core::menu::MenuSpec;
use sspf_core::seed;
use sspf_core::state::AppState;
use sspf_plugin::PackRegistry;
use sspf_plugin::{PackDdl, PackRegistry};
use sspf_contract::route::PackRoute;
/// 🔴 **业务包注册表**(进程级单例)—— 装载一次,之后到处复用。
@@ -76,14 +77,25 @@ pub fn kernel_version() -> &'static str {
CONTRACT_VERSION
}
/// 两段式种子的**第一段**(幂等,每次启动都跑)—— 平台层 + 业务层一起种。
/// 两段式种子的**第一段**(幂等,每次启动都跑)—— 平台层 + 本仓业务层一起种。
///
/// 🔴 这是**应用与测试共用的唯一种子入口**(测试也调它 ⇒ 测试里的库
/// 与真实运行时的库**逐字一致** ⇒ 冒烟测到的东西就是上线的东西)。
///
/// - `db`:库句柄。
///
/// 🔴 **默认 feature 下 `modules::all_menus()` 是空清单**(平台包不带业务)⇒
/// 这里等价于「只种平台菜单」。业务仓用的是 [`ensure_base_with`]。
pub async fn ensure_base(db: &Db) -> Result<(), pglite::Error> {
seed::ensure_base(db, modules::all_menus()).await
ensure_base_with(db, modules::all_menus()).await
}
/// 同 [`ensure_base`],但**业务菜单由调用方给**(门面 `sspf::Platform::menus` 用)。
///
/// 🔴 平台层 [`seed::ensure_base`] 只认「传进来的 `MenuSpec` 列表」,不认业务 ⇒
/// 谁给清单谁负责(本仓 = [`ensure_base`];外部业务仓 = 门面注入)。
pub async fn ensure_base_with(db: &Db, menus: &[MenuSpec]) -> Result<(), pglite::Error> {
seed::ensure_base(db, menus).await
}
/// 🔴 **装载全部业务包** —— 委托给**生成**的包清单 [`crate::packs_gen`]。
@@ -146,16 +158,31 @@ pub fn pack_router_or_empty() -> Router<AppState> {
/// 🔴 **顺序**:按包的 `app_code` 排序([`PackRegistry::manifests`] 是 `BTreeMap`)
/// ⇒ **装载顺序确定** ⇒ 同一批包在任何机器上建表顺序一致。
///
/// 🔴 **不许碰 `base_*`** —— 装载器已在装载期拦过(`DdlTouchesBaseTable`)。
/// 🔴 不许碰 `base_*` —— 装载器已在装载期拦过(`DdlTouchesBaseTable`)。
pub async fn ensure_pack_schema(db: &Db, reg: &PackRegistry) -> Result<(), pglite::Error> {
// 🔴 **先登记「包表归谁所有」**(低代码建模页的护栏要用):
// 包建的表对建模页来说必须**只读**(不许 ALTER / DROP),
// 判据在 `sspf_store::db::is_protected_table`(平台 DDL ∪ 包表)。
// 这一步放在建表之前:建表失败也不能让护栏变成「谁都能删」。
sspf_store::db::register_pack_tables(reg.ddls.iter().map(|d| d.table.clone()));
for ddl in &reg.ddls {
// 🔴 一条 DDL 一条语句 ⇒ 用 `exec`(simple protocol)。
// 包里的 DDL 自己带 `IF NOT EXISTS` ⇒ 幂等。
ensure_ddls(db, reg, &[]).await
}
/// 🔴 **执行 DDL 的唯一实现**(平台包 + 调用方注入的外部 DDL)。
///
/// 🔴 **先登记「包表归谁所有」**(低代码建模页的护栏要用):
/// 包建的表对建模页来说必须**只读**(不许 ALTER / DROP),
/// 判据在 `sspf_store::db::is_protected_table`(平台 DDL ∪ 包表)。
/// 这一步放在建表之前:建表失败也不能让护栏变成「谁都能删」。
///
/// 🔴 **一条 DDL 一条语句 ⇒ 用 `exec`**(simple protocol)。包里的 DDL 自带
/// `IF NOT EXISTS` ⇒ 幂等。
///
/// 🔴 **顺序**:`reg.ddls`(本仓包,`app_code` 序)在前,`extra`(外部注入)在后
/// ⇒ 同一批包在任何机器上建表顺序一致。
async fn ensure_ddls(
db: &Db,
reg: &PackRegistry,
extra: &[PackDdl],
) -> Result<(), pglite::Error> {
let all: Vec<&PackDdl> = reg.ddls.iter().chain(extra.iter()).collect();
sspf_store::db::register_pack_tables(all.iter().map(|d| d.table.clone()));
for ddl in all {
db.exec(ddl.sql).await?;
}
Ok(())
@@ -175,13 +202,30 @@ pub async fn ensure_pack_schema(db: &Db, reg: &PackRegistry) -> Result<(), pglit
/// 只建平台表、不建业务表,启动却照常成功 ⇒ 业务包端点全在、表全无(`relation does not exist`)。
/// ⇒ 现在 `packs()` 的 Err 直接转成返回值,由 `crates/sspf-admin/src/main.rs` 打印人话并退出。
pub async fn ensure_schema_all(db: &Db) -> Result<(), String> {
let reg = packs().map_err(|e| format!("业务包装载失败: {e}"))?;
ensure_schema_all_with(db, reg, &[]).await
}
/// 🔴 **完整建库(可注入版)** —— 平台表 + 调用方给的包表 / 额外 DDL,**同一个 `Db`**。
///
/// 🔴 **为什么外部业务仓用这一条而不是 [`ensure_schema_all`]**:
/// ① [`packs`] 是 `OnceLock` 单例(first-call-wins)⇒ 外部注入的包**不能**走它,
/// 否则「业务仓注入了包,但单例已被空注册表占住」= 静默失败;
/// ② 业务仓的表必须建进**同一个库**(pglite 进程级单例,第二次 `PGlite::open()` 必失败)。
///
/// - `reg`:调用方自己装载的包(可以空)。
/// - `extra_ddls`:不走包装载、直接给的建表 SQL(`sspf::Platform::ddl`)。
pub async fn ensure_schema_all_with(
db: &Db,
reg: &PackRegistry,
extra_ddls: &[PackDdl],
) -> Result<(), String> {
// ---- 第 1 段:平台表(`db/schema.sql`)----
db.ensure_schema()
.await
.map_err(|e| format!("平台表建库失败: {e}"))?;
// ---- 第 2 段:业务包的表(跟着包走)----
let reg = packs().map_err(|e| format!("业务包装载失败: {e}"))?;
ensure_pack_schema(db, reg)
// ---- 第 2 段:业务包的表(跟着包/注入走)----
ensure_ddls(db, reg, extra_ddls)
.await
.map_err(|e| format!("业务包建表失败: {e}"))?;
Ok(())
@@ -193,6 +237,26 @@ pub fn version() -> &'static str {
}
#[cfg(test)]
mod feature_tests {
/// 🔴 **装载器必须跟着 feature 走**(2026-11-04 标准平台包)。
///
/// 🔴 不带 `cfg` 的原因同 `modules::feature_tests`:下面那组「4 个包都装得上」
/// 的断言只在 `example-packs` 下编译 ⇒ 这里兜住「两组都没跑」的静默退化。
#[test]
fn registry_follows_the_example_packs_feature() {
let reg = super::load_packs().expect("默认/示例 feature 都必须是可装载的形态");
if cfg!(feature = "example-packs") {
assert!(!reg.entities.is_empty(), "开了 example-packs ⇒ 至少要装上一个包");
} else {
assert!(
reg.entities.is_empty() && reg.ddls.is_empty(),
"默认 feature 是平台包:不得装载任何示例业务包"
);
}
}
}
#[cfg(all(test, feature = "example-packs"))]
mod tests {
use super::*;
use sspf_contract::route::HttpMethod;
+3
View File
@@ -43,6 +43,9 @@
//! (`check-arch.sh` 的 PACK1 钉住)—— 加业务模块跑 `bash scripts/new-pack.sh`。
pub mod bootstrap;
/// 🔴 **进程级启动原语**(定位项目根 / 白名单自检 / 开库 / 优雅停机)。
/// 门面 `sspf::runtime` 只做编排,不重复维护平台表清单。
pub mod boot;
/// 🔴 **契约面命名空间别名表**(M7 新增,取代已删的 `platform/compat/` 16 个转发壳)。
/// 详见本模块自身的文档。
pub mod compat;
+60
View File
@@ -32,9 +32,14 @@ use sspf_core::state::AppState;
// >>>GEN:MODS
// 每个模块一行:**文件即登记**(顺序 = 文件名字典序,不代表业务顺序)。
// 🔴 只在 `example-packs` 下编译 —— 默认 feature 的内核**不认识任何业务模块**。
#[cfg(feature = "example-packs")]
pub mod asset;
#[cfg(feature = "example-packs")]
pub mod books;
#[cfg(feature = "example-packs")]
pub mod demo;
#[cfg(feature = "example-packs")]
pub mod shop;
// <<<GEN:MODS
@@ -42,18 +47,23 @@ pub mod shop;
/// 全部业务实体 spec。
///
/// 🔴 **本段由 `scripts/pack-sync.py` 生成** —— 加模块不用手改(见文件头)。
#[cfg(feature = "example-packs")]
pub const ALL_SPECS: &[EntitySpec] = &[
asset::DATA_RESOURCE_SPEC,
books::BOOK_SPEC,
demo::DEMO_SPEC,
shop::PRODUCT_SPEC,
];
/// 默认 feature:平台侧零业务 ⇒ 空清单(业务仓用 `sspf::Platform::packs` 注入)。
#[cfg(not(feature = "example-packs"))]
pub const ALL_SPECS: &[EntitySpec] = &[];
// <<<GEN:SPECS
// >>>GEN:ROUTES
/// **全部业务路由**(面 A:`/api/ssw/{appCode}/{Entity}/{动作}`,每模块 3 条)。
///
/// 🔴 **与 `ALL_SPECS` 同序**(同一份模块清单生成)⇒ 可以按 3 条一组配对。
#[cfg(feature = "example-packs")]
pub const ALL_ROUTES: &[&str] = &[
asset::ROUTES[0],
asset::ROUTES[1],
@@ -68,17 +78,24 @@ pub const ALL_ROUTES: &[&str] = &[
shop::ROUTES[1],
shop::ROUTES[2],
];
/// 默认 feature:没有业务路由可登记。
#[cfg(not(feature = "example-packs"))]
pub const ALL_ROUTES: &[&str] = &[];
// <<<GEN:ROUTES
// >>>GEN:MENUS
/// 全部业务内置菜单(由**装配根** [`crate::bootstrap`] 传给平台层的种子
/// ⇒ **平台层不认任何业务菜单**,红线 12)。
#[cfg(feature = "example-packs")]
pub const ALL_MENUS: &[MenuSpec] = &[
asset::DATA_RESOURCE_MENU,
books::BOOK_MENU,
demo::DEMO_MENU,
shop::PRODUCT_MENU,
];
/// 默认 feature:平台侧零业务 ⇒ 种子只种平台菜单。
#[cfg(not(feature = "example-packs"))]
pub const ALL_MENUS: &[MenuSpec] = &[];
// <<<GEN:MENUS
/// 全部业务实体 spec。
@@ -103,15 +120,58 @@ pub fn find_spec(app_code: &str, entity: &str) -> Option<&'static EntitySpec> {
/// **全部业务模块的路由**(`Router::merge` 进总路由)。
///
/// 🔴 加业务模块 ⇒ **不用改这里**(本段由 `pack-sync.py` 生成)。
#[cfg(feature = "example-packs")]
pub fn router() -> Router<AppState> {
asset::router()
.merge(books::router())
.merge(demo::router())
.merge(shop::router())
}
/// 默认 feature:没有任何业务路由。
#[cfg(not(feature = "example-packs"))]
pub fn router() -> Router<AppState> {
Router::new()
}
// <<<GEN:ROUTER
#[cfg(test)]
mod feature_tests {
use super::*;
/// 🔴 **本模块的清单必须跟着 feature 走**(2026-11-04 标准平台包)。
///
/// 🔴 **为什么这条测试不带 `cfg`**:它是「尺子会不会变瞎」的探针。
/// 下面那组基准模块断言只在 `example-packs` 下编译
/// (默认 feature 时清单是空的,断言必然假红);
/// 如果**两组都没编译**,这里能立刻看出来 —— 而不是「测试数悄悄变少」。
///
/// 🔴 跑法:`cargo test --workspace`(`sspf-tests` 会开 feature ⇒ 全组都跑)。
/// `cargo test -p ssw-platform` 单独跑只跑本条(默认 feature)。
#[test]
fn spec_and_menu_lists_follow_the_feature() {
if cfg!(feature = "example-packs") {
assert!(
all_specs().len() >= 4,
"开了 example-packs ⇒ 至少要保住 demo/shop/books/asset 四个模块"
);
assert!(
!all_menus().is_empty(),
"开了 example-packs ⇒ 业务菜单不能是空的(否则面 B 点权限全 403)"
);
assert!(
!ALL_ROUTES.is_empty(),
"开了 example-packs ⇒ 业务路由不能是空的"
);
} else {
assert!(
all_specs().is_empty() && all_menus().is_empty() && ALL_ROUTES.is_empty(),
"默认 feature 是**平台包**:不得携带任何业务 spec / 菜单 / 路由"
);
}
}
}
#[cfg(all(test, feature = "example-packs"))]
mod tests {
use super::*;
use sspf_core::db;
+30
View File
@@ -12,6 +12,11 @@
//!
//! 🔴 **`packs/` 是唯一真源** —— 加包跑 `bash scripts/new-pack.sh`,
//! 改完 `packs/*` 跑 `python3 scripts/pack-sync.py`。
//!
//! 🔴 **默认 feature 下本文件不装载任何包**(2026-11-04 标准平台包):
//! 4 个示例包降为 `example-packs` feature(只有 `sspf-admin` 与 `sspf-tests` 开)。
//! 业务仓只依赖门面 `sspf` ⇒ `cargo tree` 里**没有** `sspf-pack-*`
//! ⇒ 平台包里零业务(`check-arch.sh` 的 AR17 钉住)。
use sspf_plugin::{LoadError, PackRegistry};
@@ -19,6 +24,7 @@ use sspf_plugin::{LoadError, PackRegistry};
///
/// 🔴 任一包装载失败 ⇒ **整体失败**(半加载的包比不加载更危险):
/// 半加载的包 = 一部分路由在、一部分不在 ⇒ 前端表现为「有的页面能用」。
#[cfg(feature = "example-packs")]
pub fn registry(kernel_version: &str) -> Result<PackRegistry, LoadError> {
let mut regs: Vec<PackRegistry> = Vec::new();
@@ -61,14 +67,35 @@ pub fn registry(kernel_version: &str) -> Result<PackRegistry, LoadError> {
Ok(sspf_plugin::merge(regs))
}
/// 默认 feature(业务仓只依赖门面时的形态):**本仓不认识任何业务包** ⇒ 空注册表。
///
/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**(业务仓自己注入业务包),
/// 不是装载失败。
#[cfg(not(feature = "example-packs"))]
pub fn registry(_kernel_version: &str) -> Result<PackRegistry, LoadError> {
Ok(PackRegistry::default())
}
/// 把**外部已装载**的注册表合并成一个(门面 `sspf::Platform::packs` / `.pack` 用)。
///
/// 🔴 与 [`registry`] 的分工:`registry` 装的是**本仓 `packs/*` 的示例包**;
/// 本函数**只合并、不装载** ⇒ 业务仓用 `sspf::load_static` 装好自己的包后传进来。
/// 🔴 空 vec ⇒ 空注册表(合法,不是错误)。
pub fn registry_from(regs: Vec<PackRegistry>) -> PackRegistry {
sspf_plugin::merge(regs)
}
// ---------------------------------------------------------------- 清单快照
//
// 🔴 `pack.toml` 的**权威副本**在 `packs/<app>/pack.toml`(给人看、给导出工具读);
// 这里是它的**编译期 JSON 快照**。为什么要快照、不运行期读文件:
// 内核是**单二进制部署** ⇒ 运行目录里不一定有 `packs/` 目录。
// 两份的一致性由 `scripts/pack-sync.py` 保证(`--check` 会比对)。
//
// 🔴 快照只在 `example-packs` 下编译(否则默认 feature 的构建里是死代码)。
/// `packs/asset/pack.toml` 的编译期快照。
#[cfg(feature = "example-packs")]
const ASSET_MANIFEST_JSON: &str = r#"{
"pack": {
"app_code": "asset",
@@ -87,6 +114,7 @@ const ASSET_MANIFEST_JSON: &str = r#"{
}"#;
/// `packs/books/pack.toml` 的编译期快照。
#[cfg(feature = "example-packs")]
const BOOKS_MANIFEST_JSON: &str = r#"{
"pack": {
"app_code": "books",
@@ -105,6 +133,7 @@ const BOOKS_MANIFEST_JSON: &str = r#"{
}"#;
/// `packs/demo/pack.toml` 的编译期快照。
#[cfg(feature = "example-packs")]
const DEMO_MANIFEST_JSON: &str = r#"{
"pack": {
"app_code": "demo",
@@ -123,6 +152,7 @@ const DEMO_MANIFEST_JSON: &str = r#"{
}"#;
/// `packs/shop/pack.toml` 的编译期快照。
#[cfg(feature = "example-packs")]
const SHOP_MANIFEST_JSON: &str = r#"{
"pack": {
"app_code": "shop",
+174 -8
View File
@@ -26,12 +26,13 @@
use std::any::Any;
use std::future::Future;
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::path::{Path, PathBuf};
use std::pin::Pin;
use std::task::{Context, Poll};
use axum::body::Body;
use axum::extract::{Request, State};
use axum::http::{header, HeaderMap, HeaderValue, StatusCode};
use axum::http::{header, HeaderMap, HeaderValue, Method, StatusCode};
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use axum::routing::{delete, get, post, put};
@@ -52,6 +53,40 @@ async fn panic_handler() -> Json<ActionResult> {
panic!("测试用 panic(由 catch-all 中间件接住)")
}
/// 🔴 **装配注入点** —— 平台之外的业务方(门面 `sspf::Platform`)往总路由里塞的东西。
///
/// 🔴 **为什么必须有它**(2026-11-04 标准平台包):业务仓(如 tdc-rs)的业务不在本仓
/// `packs/*` 里,它有自己的路由 / DDL / 菜单。它**不能**自己抄一遍
/// `fallback + layer + with_state` —— S25 的顺序一错位,404 兜底就失去中间件保护,
/// 而且**测试全绿看不出来**。⇒ 只能把东西交给这条唯一装配链。
///
/// 🔴 **`router` / `pack_router` 里不许自带 `fallback`** —— axum 的 `Router::merge`
/// 遇到两个 fallback 会 panic。深链回退是装配链的事([`Extras::static_dir`])。
#[derive(Default)]
pub struct Extras {
/// 业务包声明的面 B 路由(由 `crud_router` 或业务方自己生成)。
pub pack_router: Option<Router<AppState>>,
/// 业务方自定义路由(含它自己的中间件 / 守卫,`/api/ssw/**` 之类)。
pub router: Option<Router<AppState>>,
/// 静态 SPA 目录:**非 `/api/**` 的未命中路径**回退到 `index.html`(深链)。
///
/// 🔴 `/api/**` 永远走信封 404 —— 静态托管不许吞掉接口的 404 契约。
pub static_dir: Option<PathBuf>,
}
impl Extras {
/// 本仓默认形态:`modules::router()` + `packs/*` 的面 B 路由(**不带**静态托管)。
///
/// 🔴 默认 feature 下两者都是空路由(平台包不带业务)⇒ 行为等价于 `Extras::default()`。
pub fn kernel() -> Extras {
Extras {
pack_router: Some(crate::bootstrap::pack_router_or_empty()),
router: Some(modules::router()),
static_dir: None,
}
}
}
/// 装配全部路由(27 条,见 S15 的路由表)。
///
/// 🔴 **不在这里终结状态** —— 契约 §9 的括注与 §10 第 6 步都要求
@@ -67,6 +102,11 @@ async fn panic_handler() -> Json<ActionResult> {
/// (`config` / `db` / `sessions`)**全是 `Arc`** ⇒ 两份 clone **共享同一份底层状态**
/// ⇒ 行为完全等价,**不是**两个独立状态。
pub fn build_router(state: AppState) -> axum::Router<AppState> {
build_router_with(state, Extras::kernel())
}
/// 同 [`build_router`],但**业务路由由调用方注入**(门面 / 外部业务仓走这一条)。
pub fn build_router_with(state: AppState, extras: Extras) -> axum::Router<AppState> {
let router = Router::new()
// ---- 探活(§6.5 末条,非契约)----
.route("/api/health", get(health))
@@ -1248,9 +1288,9 @@ pub fn build_router(state: AppState) -> axum::Router<AppState> {
.route("/api/system/Variate/{id}", get(compat::system::variate_info))
.route("/api/system/Variate/{id}", put(compat::system::variate_update))
.route("/api/system/Variate/{id}", delete(compat::system::variate_delete))
// ---- 业务模块的路由(demo / shop / books)由业务层自带 ⇒ 这里只 merge ----
.merge(modules::router())
// ---- 业务包的路由(面 B 官方形状)由**业务包自带** ⇒ 按声明生成 ----
// 🔴 **业务路由在链尾由 [`Extras`] 注入**(`modules::router()` 是本仓默认那一份,
// 外部业务仓传自己的)—— 这里不再写死 `.merge(modules::router())`:
// 写死 = 业务仓无法替换,且默认 feature 下会 merge 一个空路由(无意义)。
//
// ---- 系统服务族(批次 15):多语言 / 套件 / 缓存 / 任务调度 / IM / 常用菜单 ----
// 🔴 同一个 path 的多个方法合并进**一行** `.route()`(`get(a).post(b)`)——
@@ -2518,8 +2558,26 @@ pub fn build_router(state: AppState) -> axum::Router<AppState> {
.route(
"/api/workflow/Engine/FlowBefore/Cancel/{id}",
post(compat::mobile::flow_before_cancel),
)
.merge(crate::bootstrap::pack_router_or_empty());
);
// ---- 注入的业务路由(装配链的**唯一** merge 点)----
//
// 🔴 顺序写死:包路由(面 B 官方形状)在前,业务自定义路由在后 ⇒
// 同一 path + method 出现两次时 axum 在**启动期 panic**(响亮失败,
// 不是静默覆盖)—— 顺序只影响报错时的描述,但固定顺序能保证任何机器上一致。
// 🔴 **默认 feature 下两者都是空路由**(平台侧零业务)。
let Extras {
pack_router,
router: biz_router,
static_dir: _,
} = extras;
let mut router = match pack_router {
Some(r) => router.merge(r),
None => router,
};
if let Some(r) = biz_router {
router = router.merge(r);
}
// 🔴 **仅测试构建**存在的「故意 panic」端点 —— 用来钉住 catch-all 中间件
// (契约 §6.5:panic ⇒ HTTP 200 + `code=400`)。
@@ -2540,13 +2598,121 @@ pub fn build_router(state: AppState) -> axum::Router<AppState> {
/// 🔴 **这条链在仓库里只有这一份** —— 生产与测试共用 ⇒ 改顺序时两边一起变,
/// 测试永远钉得住(不要在 `crates/sspf-admin/src/main.rs` 或测试里再抄一遍)。
pub fn build_app(state: AppState) -> axum::Router {
build_router(state.clone())
.fallback(not_found_handler)
build_app_with(state, Extras::kernel())
}
/// 完整装配(**可注入版**)—— 外部业务仓 / 门面的唯一入口。
///
/// 🔴 **装配链仍然只有这一份**:与 [`build_app`] 的区别只在「路由里多 merge 什么」
/// 和「fallback 是信封 404 还是 SPA 深链回退」。顺序(S25)一字不改。
///
/// 🔴 **`extras.static_dir` 只影响 fallback**:
/// - `None` ⇒ 未命中就是信封 404(与历史行为**逐字一致**);
/// - `Some(dir)` ⇒ `/api/**` 仍是信封 404;其它未命中路径先找静态文件,
/// 找不到再回退 `index.html`(前端 history 路由的深链)。
pub fn build_app_with(state: AppState, extras: Extras) -> axum::Router {
let static_dir = extras.static_dir.clone();
build_router_with(state.clone(), extras)
.fallback(move |req: Request| {
let dir = static_dir.clone();
async move { fallback_response(dir, req).await }
})
.layer(m_status_rewrite())
.layer(catch_all())
.with_state(state)
}
/// 未命中路径的兜底(唯一的 fallback 实现)。
async fn fallback_response(static_dir: Option<PathBuf>, req: Request) -> Response {
if let Some(dir) = static_dir {
let path = req.uri().path();
// 🔴 `/api/**` **永远**走信封 404 —— 静态托管不许吞掉接口的 404 契约。
if !path.starts_with("/api/") && path != "/api" {
if matches!(*req.method(), Method::GET | Method::HEAD) {
let found = match serve_from(&dir, path).await {
Some(resp) => Some(resp),
// 深链回退:前端路由(`/workflow/123`)在磁盘上没有对应文件
None => serve_file(&dir.join("index.html")).await,
};
if let Some(mut resp) = found {
if req.method() == Method::HEAD {
*resp.body_mut() = Body::empty();
}
return resp;
}
}
}
}
not_found_handler().await.into_response()
}
/// 把 URL 路径映射成 `dir` 下的文件(防目录穿越);不存在 ⇒ `None`。
async fn serve_from(dir: &Path, url_path: &str) -> Option<Response> {
let rel = safe_rel_path(url_path)?;
let mut full = dir.join(rel);
let meta = tokio::fs::metadata(&full).await.ok()?;
if meta.is_dir() {
full = full.join("index.html");
}
serve_file(&full).await
}
/// 读文件并回 `Content-Type`(找不到 ⇒ `None`)。
async fn serve_file(path: &Path) -> Option<Response> {
let bytes = tokio::fs::read(path).await.ok()?;
let mut resp = Response::new(Body::from(bytes));
resp.headers_mut()
.insert(header::CONTENT_TYPE, HeaderValue::from_static(mime_of(path)));
// 🔴 开发期 `no-cache`:前端重新构建后刷新就该看到新产物(静态托管不是 CDN)。
resp.headers_mut()
.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-cache"));
Some(resp)
}
/// URL 路径 ⇒ 相对路径。**拒绝** `..` / 反斜杠 / NUL(目录穿越)。
fn safe_rel_path(url_path: &str) -> Option<PathBuf> {
let mut out = PathBuf::new();
for seg in url_path.split('/') {
if seg.is_empty() || seg == "." {
continue;
}
if seg == ".." || seg.contains('\\') || seg.contains('\0') {
return None;
}
out.push(seg);
}
Some(out)
}
/// 扩展名 ⇒ `Content-Type`(SPA 构建产物里会出现的类型就够了)。
fn mime_of(path: &Path) -> &'static str {
match path
.extension()
.and_then(|e| e.to_str())
.map(|e| e.to_ascii_lowercase())
.as_deref()
{
Some("html") | Some("htm") => "text/html; charset=utf-8",
Some("js") | Some("mjs") => "text/javascript; charset=utf-8",
Some("css") => "text/css; charset=utf-8",
Some("json") | Some("map") => "application/json; charset=utf-8",
Some("svg") => "image/svg+xml",
Some("png") => "image/png",
Some("jpg") | Some("jpeg") => "image/jpeg",
Some("gif") => "image/gif",
Some("webp") => "image/webp",
Some("ico") => "image/x-icon",
Some("woff") => "font/woff",
Some("woff2") => "font/woff2",
Some("ttf") => "font/ttf",
Some("otf") => "font/otf",
Some("txt") => "text/plain; charset=utf-8",
Some("webmanifest") => "application/manifest+json",
Some("wasm") => "application/wasm",
_ => "application/octet-stream",
}
}
/// `GET /api/health` —— 探活(契约 §6.5 末条,**非契约**)。
///
/// 🔴 **永远要有响应**:查不到表 / DB 报错 ⇒ 仍然 HTTP 200 + `{"ok": false, "tables": 0, …}`