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

+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, …}`