diff --git a/Cargo.lock b/Cargo.lock index d970ef4..319bec1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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", diff --git a/HANDOFF.md b/HANDOFF.md index ed6cb2e..21817fc 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -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}` 的「去分隔符」惯例一致。 diff --git a/crates/sspf-admin/Cargo.toml b/crates/sspf-admin/Cargo.toml index e4d1553..b4230a1 100644 --- a/crates/sspf-admin/Cargo.toml +++ b/crates/sspf-admin/Cargo.toml @@ -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 } diff --git a/crates/sspf-admin/src/main.rs b/crates/sspf-admin/src/main.rs index 3bb15a8..3a3a989 100644 --- a/crates/sspf-admin/src/main.rs +++ b/crates/sspf-admin/src/main.rs @@ -1,221 +1,25 @@ -//! sspf-admin —— **默认装配**的二进制入口(启动装配,契约 §10)。 +//! sspf-admin —— **默认装配**的 CLI 薄壳(`sspf` 标准平台包的参考消费者)。 //! -//! 🔴 本文件 2026-11-04 从 `src/backend/src/main.rs` 剥出:内核是 lib(可复用), -//! 「怎么跑起来」是应用的选择 ⇒ 归 `crates/sspf-admin`。 +//! ## 本文件只做两件事 //! -//! 装配顺序(契约 §10,逐字): -//! 1. [`resolve_project_dir`] —— 从可执行文件向上找锚点(`/src/backend/db/schema.sql` -//! **与** `/Cargo.toml`),**与 cwd 解耦**(后台启动时 cwd 会漂移); -//! 2. `Config::from_env(project_dir)`; -//! 3. **标识符白名单自检**(不过 ⇒ 打印人话 + `exit 1`),**放在开库之前**; -//! 4. `Db::open` / `Db::open_temp` ⇒ `ensure_schema()`; -//! 5. `bootstrap::ensure_base()` ⇒ `seed::first_seed()`(种子失败 ⇒ 打印人话 + `exit 1`); -//! 6. `routes::build_app(state)` —— **装配链的唯一权威**(顺序即 S25 的要害: -//! `build_router` → **404 兜底** → **405 / 413 改写中间件** → **catch-all 中间件** -//! → `with_state(state)`(**链尾**)); -//! 7. `TcpListener::bind` ⇒ 绑定失败**打印人话 + `exit 1`**(**不 panic**)。 +//! 1. **解析命令行**(`--enc` / `--mcp` / `--seed-lowcode-demo` / `--help`); +//! 2. **转交给门面** —— 启动装配全在 [`sspf::Platform`] / [`sspf::runtime`]。 //! -//! 🔴 **优雅停机**:`SIGTERM` / `SIGINT` ⇒ `with_graceful_shutdown` 收完在途请求 ⇒ -//! 优雅关闭嵌入式 PostgreSQL(不再被 `SIGKILL` 打断 ⇒ 数据目录不留 `postmaster.pid`)。 +//! 🔴 **为什么这里不再有「七步启动」**(2026-11-04 标准平台包): +//! 那七步(定位项目根 / 读配置 / 自检 / 开库 / 建表 / 种子 / 绑端口 / 优雅停机) +//! 是**每一个**基于本平台的进程都要做的事 —— 业务仓(tdc-rs)也一样。 +//! 写在 CLI 里 ⇒ 业务仓要么抄一遍(抄漏一步就是静默故障),要么永远用不上。 +//! ⇒ 搬到 `crates/sspf`,本文件从 1111 行降到「CLI 该有的样子」。 //! -//! 🔴 本仓**刻意不同**于 react 版(那里是 try/catch + `logger.warn` 后**继续跑**): -//! 本仓是单二进制,启动期不变量破了就立刻退出 —— 服务要么正常起来,要么根本不起来。 +//! 🔴 **示例包(asset/books/demo/shop)只在这里开**: +//! `sspf` 的 `example-packs` feature 只被本包与 `crates/tests` 打开。 +//! 业务仓只依赖 `sspf`(默认 feature)⇒ 依赖树里没有 `sspf-pack-*`(AR17)。 +//! +//! 装配顺序(契约 §10)的权威实现:`sspf::platform::Platform::boot` 的注释。 -use std::path::PathBuf; -use std::sync::Arc; - -use ssw_platform::bootstrap; -use ssw_platform::mcp_adapter; -use ssw_platform::modules; -use sspf_core::cipher; -use sspf_core::config::Config; -use sspf_core::db::Db; -use sspf_core::guard::{self, Profile}; -use sspf_core::seed; -use sspf_core::session::{SessionStore, TicketStore}; -use sspf_core::state::AppState; -use ssw_platform::routes; - -/// 本仓的 **平台表**(`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", -]; +use sspf::cipher; +use sspf::kernel::{boot, lowcode_seed}; +use sspf::{Config, Platform}; /// 命令行解析的结果(**纯数据**,便于单测)。 #[derive(Debug, Clone, PartialEq, Eq)] @@ -227,15 +31,8 @@ enum Cmd { /// `--help` / `-h` ⇒ 打印用法,退出码 **0**。 Help, /// `--mcp [--with-http]` ⇒ 起 MCP stdio 服务(不监听端口),退出码 **0**。 - /// - /// `with_http` 为真时**同时**起 HTTP —— 同一个进程、同一个 `AppState`、同一个库, - /// AI 通过 MCP 写完数据,浏览器刷新就能看到(人机协作的关键手感)。 Mcp { with_http: bool }, - /// `--seed-lowcode-demo [--dry-run]` ⇒ 灌入低代码示例功能(**开发档专用**)。 - /// - /// 🔴 这条命令会**建表**(改真实库结构)⇒ 生产档(`SSW_PROFILE=prod`)直接拒绝。 - /// - /// `dry_run` 为真时只产出 DDL 与诊断信息,**不碰库**。 + /// `--seed-lowcode-demo [--dry-run]` ⇒ 灌低代码示例功能,做完即退出。 SeedLowcodeDemo { dry_run: bool }, /// 未知参数 ⇒ 用法错,退出码 **2**。 Unknown(String), @@ -243,15 +40,6 @@ enum Cmd { Serve, } -/// 运行时形态(`run()` 的分支)。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -enum RunMode { - /// HTTP 服务(默认)。 - Serve, - /// MCP stdio 服务;`with_http` 时附带 HTTP。 - Mcp { with_http: bool }, -} - /// 解析命令行参数(**纯函数**:不读环境变量、不退出进程、不打日志)。 /// /// 🔴 语义逐字照搬契约 §10 的子命令条: @@ -323,26 +111,46 @@ async fn main() { Cmd::SeedLowcodeDemo { dry_run } => { std::process::exit(run_seed_lowcode_demo(*dry_run).await); } - // 两个「起服务」形态共用同一套装配(见 `run`),只是收尾不同。 + // 两个「起服务」形态共用同一套装配(门面),只是收尾不同。 Cmd::Serve | Cmd::Mcp { .. } => {} } - let mode = match cmd { - Cmd::Mcp { with_http } => RunMode::Mcp { with_http }, - _ => RunMode::Serve, + let result = match cmd { + Cmd::Mcp { with_http } => serve_platform().serve_mcp(with_http).await, + _ => serve_platform().serve().await, }; - if let Err(msg) = run(mode).await { + if let Err(msg) = result { eprintln!("[启动失败] {msg}"); std::process::exit(1); } } +/// 🔴 **本仓默认装配**:平台 + 4 个示例包(asset / books / demo / shop)。 +/// +/// 🔴 **示例包的注册表必须显式注入** —— 不能指望 `bootstrap::packs()` 那个 +/// `OnceLock` 单例(first-call-wins ⇒ 注入静默失效)。 +/// +/// 🔴 **面 A(`/api/ssw/{app}/{Entity}/{List|Save|Delete}`)也要显式注入**: +/// 它是**本仓业务层**(`modules::router()`)的路由,门面默认一个都不认识。 +/// 漏了这一句的表现不是编译错误,而是面 A 全 404(`perm-smoke.sh` 当场红)。 +fn serve_platform() -> Platform { + let platform = Platform::new().router(sspf::kernel::modules::router()); + match sspf::example_packs() { + Ok(reg) => platform.packs(reg), + Err(e) => { + // 装载失败 ⇒ 它的端点不存在 ⇒ 前端一访问就是 404 ⇒ **必须响亮地失败**。 + eprintln!("[启动失败] 业务包装载失败: {e}"); + std::process::exit(1); + } + } +} + /// 打印用法(`--help` / 未知参数)。 fn print_usage() { println!( - "sspf-admin {} —— JNPF 兼容契约的 Rust 实现(单二进制、零外部服务)", - env!("CARGO_PKG_VERSION") + "sspf-admin {} —— 基于 sspf 标准平台包的默认装配(单二进制、零外部服务)", + sspf::VERSION ); println!(); println!("用法:"); @@ -367,7 +175,7 @@ fn print_usage() { /// /// 1. **档位闸门**:生产档(`SSW_PROFILE=prod`)⇒ 直接拒绝,**不开库** /// (连数据目录都不碰 —— 生产库不该被一条命令改结构); -/// 2. **白名单自检**(同 `run()` 的第 3 步)—— 与服务启动走**同一把尺子**; +/// 2. **白名单自检**(与起服务走**同一把尺子**); /// 3. 建表 + 回写(`lowcode_ddl::create_and_sync`)⇒ 幂等。 /// /// ## 退出码 @@ -375,24 +183,24 @@ fn print_usage() { /// - **0**:成功; /// - **1**:闸门拒绝 / 建表失败 / 写库失败(都有人话提示)。 /// -/// 🔴 不复用 `run()`:那条路会**起 HTTP 监听**、跑完整种子 —— 而这里只想 -/// 「种完就退出」,起服务既没意义又会占端口。 +/// 🔴 不复用 `Platform::serve`:那条路会**起 HTTP 监听**、跑完整种子 —— +/// 而这里只想「种完就退出」。 async fn run_seed_lowcode_demo(dry_run: bool) -> i32 { // ---- 第 1 步:项目根(与 cwd 解耦)---- - let project_dir = resolve_project_dir(); + let project_dir = boot::resolve_project_dir(); // ---- 第 2 步:配置(只取档位与数据目录)---- let config = Config::from_env(project_dir.clone()); // ---- 第 3 步:档位闸门(**开库之前**)---- - if let Err(msg) = ssw_platform::lowcode_seed::seed_gate(config.profile) { + if let Err(msg) = lowcode_seed::seed_gate(config.profile) { eprintln!("[种子拒绝] {msg}"); return 1; } // ---- 第 3b 步:演练 ⇒ **连库都不开**(什么都不发生)---- if dry_run { - let outcome = match ssw_platform::lowcode_seed::preview_lowcode_demo(&project_dir) { + let outcome = match lowcode_seed::preview_lowcode_demo(&project_dir) { Ok(o) => o, Err(e) => { eprintln!("[种子预览失败] {}:{}", e.code, e.message); @@ -407,26 +215,26 @@ async fn run_seed_lowcode_demo(dry_run: bool) -> i32 { } // ---- 第 4 步:白名单自检(与起服务同一把尺子)---- - if let Err(msg) = whitelist_self_check() { + if let Err(msg) = boot::whitelist_self_check_platform() { eprintln!("[种子失败] 标识符白名单自检未通过: {msg}"); return 1; } // ---- 第 5 步:开库 + 建表 ---- - let db = match open_db(&config).await { + let db = match boot::open_db(&config).await { Ok(db) => db, Err(e) => { eprintln!("[种子失败] 打开数据库失败: {e}"); return 1; } }; - if let Err(e) = db.ensure_schema().await { - eprintln!("[种子失败] 初始化表结构失败: {e}"); + if db.ensure_schema().await.is_err() { + eprintln!("[种子失败] 初始化表结构失败"); return 1; } // ---- 第 6 步:灌种子 ---- - let outcome = match ssw_platform::lowcode_seed::seed_lowcode_demo(&db, &project_dir).await { + let outcome = match lowcode_seed::seed_lowcode_demo(&db, &project_dir).await { Ok(o) => o, Err(e) => { eprintln!("[种子失败] {}:{}", e.code, e.message); @@ -442,13 +250,13 @@ async fn run_seed_lowcode_demo(dry_run: bool) -> i32 { // 🔴 停机:**与起服务同一条路径**(优雅关闭嵌入式 PG)—— // 否则数据目录里会留 `postmaster.pid`,下次启动要 crash recovery。 - shutdown_pg(&db, &config.pg_dir).await; + boot::shutdown_pg(&db, &config.pg_dir).await; 0 } /// 🔴 把种子结果打印成人话(演练与真跑共用一份汇报口径)。 -fn print_seed_outcome(outcome: &ssw_platform::lowcode_seed::SeedOutcome) { +fn print_seed_outcome(outcome: &sspf::kernel::lowcode_seed::SeedOutcome) { println!( "{} 低代码示例功能(id={},enCode={})", if outcome.dry_run { @@ -482,517 +290,6 @@ fn print_seed_outcome(outcome: &ssw_platform::lowcode_seed::SeedOutcome) { } } -/// 把标准流整个让给内嵌 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)` —— -/// 因为 PG 已经把它当成 SQL 输入通道了。 -/// -/// ⇒ 开库**之前**先 `dup` 出协议 fd,再把 fd 0/1 指向 `/dev/null` 与 stderr。 -/// 之后 PG 随便折腾标准流,协议走专属通道。 -/// -/// 返回的 `(File, File)` **拥有**那两个 fd,drop 时关闭。 -#[cfg(unix)] -fn detach_stdio_for_mcp() -> std::io::Result<(std::fs::File, std::fs::File)> { - use std::os::unix::io::{FromRawFd, RawFd}; - - // SAFETY: 全是 fd 级操作;任一步失败都显式回滚已拿到的 fd,不留半改状态。 - unsafe { - let in_fd: RawFd = libc::dup(0); - if in_fd < 0 { - return Err(std::io::Error::last_os_error()); - } - let out_fd: RawFd = libc::dup(1); - if out_fd < 0 { - libc::close(in_fd); - return Err(std::io::Error::last_os_error()); - } - - 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(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(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(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))] -fn detach_stdio_for_mcp() -> std::io::Result<(std::fs::File, std::fs::File)> { - Err(std::io::Error::new( - std::io::ErrorKind::Unsupported, - "MCP 模式暂只支持 unix(需要 dup2)", - )) -} - -/// 启动装配(契约 §10 的 1~7 步)。 -/// -/// 🔴 `--mcp` 与 HTTP 走**同一套装配**(同库、同种子、同白名单自检), -/// 只是第 6/7 步换成 MCP stdio —— 保证「AI 通过 MCP 看到的库」与 -/// 「前端通过 HTTP 看到的库」是同一个,不会出现两套环境。 -async fn run(mode: RunMode) -> Result<(), String> { - // ---- MCP 形态:**抢在开库之前**把标准流让给内嵌 PG,协议走专属 fd ---- - // - // 🔴 见 `detach_stdio_for_mcp` 的注释:PG 的 single-user 后端会同时占用 - // stdin(读 SQL)与 stdout(打 `backend>`)。不抢在开库前处理, - // MCP 的 NDJSON 流第一时间就被污染,读 stdin 也会 ENXIO。 - let mcp_io = if matches!(mode, RunMode::Mcp { .. }) { - Some(detach_stdio_for_mcp().map_err(|e| format!("MCP 模式接管标准流失败: {e}"))?) - } else { - None - }; - - // ---- 第 1 步:定位项目根(与 cwd 解耦)---- - let project_dir = resolve_project_dir(); - - // ---- 第 2 步:配置 ---- - let config = Config::from_env(project_dir); - - // ---- 第 3 步:标识符白名单自检(**开库之前**)---- - if let Err(msg) = whitelist_self_check() { - return Err(format!("标识符白名单自检未通过: {msg}")); - } - - // ---- 第 3b 步:业务包装载自检(**开库之前**)---- - // - // 🔴 **为什么放在开库之前**:包装载失败 ⇒ 它的端点不存在 ⇒ 前端一访问就 404 - // ⇒ **必须响亮地失败**,不能悄悄降级(少几条路由比整个服务起不来更难查)。 - // 与第 3 步的白名单自检同一处置:打印人话 + `exit 1`。 - bootstrap::packs().map_err(|msg| format!("业务包装载失败: {msg}"))?; - - // ---- 第 4 步:开库 + 建表 ---- - let db = open_db(&config).await.map_err(|e| format!("打开数据库失败: {e}"))?; - // 🔴 **平台表 + 业务包的表**(同一套装配,测试也走这一条 ⇒ 测试库 == 线上库)。 - bootstrap::ensure_schema_all(&db) - .await - .map_err(|e| format!("初始化表结构失败: {e}"))?; - - // ---- 第 5 步:两段式种子 ---- - // - // 🔴 走**装配根** [`ssw_platform::bootstrap`]:它把业务层声明的菜单 - // 注入平台层的种子 ⇒ 平台层不认业务知识(红线 12)。 - bootstrap::ensure_base(&db) - .await - .map_err(|e| format!("内置角色/菜单种子失败: {e}"))?; - seed::first_seed(&db, &config.seed_admin_password) - .await - .map_err(|e| format!("初始 admin 种子失败: {e}"))?; - - // ---- 第 5b 步:生产档弱密钥守卫(**只有 `SSW_PROFILE=prod` 才生效**)---- - // - // 🔴 **两道检查**(缺一不可): - // ① 配置级:本次启动用的种子口令本身是不是弱口令; - // ② 库内级:库里 admin 那行的口令**是不是已知弱口令**—— - // 种子口令只对**空库**生效 ⇒ 生产库里那个可能是当初种下的 `123456`, - // 运维后来才设了 `SEED_ADMIN_PASSWORD` ⇒ **只查配置 = 守卫形同虚设**。 - 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()), - }; - // 🔴 保留一个 `Db` 句柄用于**停机时优雅关闭**嵌入式 PG(`state` 会被 `build_app` 吃掉)。 - let db_for_shutdown = state.db.clone(); - - // ---- MCP 形态:装配到这儿就够了,不建路由、不绑端口 ---- - // - // 🔴 工具层与 HTTP 层共用同一个 `AppState` ⇒ AI 通过 MCP 改的数据, - // 前端刷新就能看到;反之亦然。这是「人机协作」在架构上的前提。 - if let Some((reader, writer)) = mcp_io { - // ---- `--with-http`:同一进程里再起一个 HTTP 监听 ---- - // - // 🔴 关键在于**共用同一个 `AppState`**(同一个库、同一张会话表): - // AI 通过 MCP 建的表 / 写的菜单,浏览器刷新就能看到;反之亦然。 - // 这才是「人 + AI 协作」的手感 —— 不用来回切进程、切数据目录。 - if let RunMode::Mcp { with_http: true } = mode { - let addr = std::net::SocketAddr::new(config.bind_addr, config.port); - let app = routes::build_app(state.clone()); - let listener = tokio::net::TcpListener::bind(addr) - .await - .map_err(|e| format!("MCP+HTTP 模式绑定 {addr} 失败: {e}"))?; - tokio::spawn(async move { - if let Err(e) = axum::serve(listener, app).await { - eprintln!("[mcp] HTTP 服务异常退出: {e}"); - } - }); - eprintln!("[mcp] HTTP 同时监听 http://{addr}(与 MCP 共用同一个库)"); - } - - eprintln!( - "[mcp] sspf-mcp v{} 已就绪(stdio / NDJSON,数据目录 {})", - sspf_mcp::VERSION, - config.pg_dir.display() - ); - let adapter = Arc::new(mcp_adapter::NativeAdapter::new(state)); - return sspf_mcp::Server::new(adapter) - .serve_blocking_stdin(reader, writer) - .await - .map_err(|e| format!("MCP stdio 服务异常退出: {e}")); - } - - // ---- 第 6 步:路由装配 + 三层兜底 ---- - // 🔴 装配链**只有一份**:`routes::build_app` —— S25 的顺序(`.fallback()` 在两个 - // `.layer()` **之前**、`.with_state()` 是**链尾**)就写在那儿。 - // 生产与单测走**同一条路** ⇒ 以后改顺序,两边一起变。 - let app = routes::build_app(state); - - // ---- 第 7 步:绑定端口 ---- - // 🔴 **默认只监听 127.0.0.1**(`BIND_ADDR` 可覆盖)⇒ 与「文档写的就是 127.0.0.1」一致, - // 也避免「弱口令 + token 永不过期」的后端被局域网直接连上。 - let addr = std::net::SocketAddr::new(config.bind_addr, config.port); - let listener = tokio::net::TcpListener::bind(addr) - .await - .map_err(|e| format!("绑定 {addr} 失败: {e}"))?; - - // 🔴 IPv6 的 `SocketAddr` 显示成 `::1:30010`(**不带方括号**)⇒ 直接拼进 URL 是 - // **非法 URL**(`http://::1:30010`)⇒ IPv6 主机名必须自己加方括号。 - let url_host = if addr.is_ipv6() { - format!("[{}]", addr.ip()) - } else { - addr.ip().to_string() - }; - println!( - "sspf-admin {} 已启动:http://{url_host}:{}(数据目录 {})", - env!("CARGO_PKG_VERSION"), - addr.port(), - config.pg_dir.display() - ); - - // 🔴 **优雅停机**:收到 SIGTERM / SIGINT ⇒ 先让 HTTP 服务收完在途请求,再关嵌入式 PG。 - // (以前 SIGTERM 被忽略 ⇒ 每次停机都是 SIGKILL 掉嵌入式 PostgreSQL ⇒ 下次启动要 - // crash recovery,数据目录里还留 `postmaster.pid`。) - axum::serve(listener, app) - .with_graceful_shutdown(shutdown_signal()) - .await - .map_err(|e| format!("HTTP 服务异常退出: {e}"))?; - - // ---- 停机:优雅关闭嵌入式 PostgreSQL ---- - shutdown_pg(&db_for_shutdown, &config.pg_dir).await; - - // 🔴 明确结束进程:pglite 的收尾线程可能卡死 ⇒ 不能让它吊住整个进程。 - std::process::exit(0); -} - -/// 🔴 **优雅关闭嵌入式 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"` **永远不存在** ⇒ 关库状态**无从校验**。 -/// ⇒ ② 只能如实说「未校验」,不能报「已优雅关闭」(那是**没校验过**的断言)。 -async fn shutdown_pg(db: &Db, pg_dir: &std::path::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!("sspf-admin 已停止(临时库模式:数据目录不可知,未校验嵌入式 PostgreSQL 的关库状态)。"); - } else if pid_file.exists() { - eprintln!("[停机] ⚠️ 嵌入式 PostgreSQL 未在 3 秒内干净关库(`postmaster.pid` 仍在)"); - } else { - println!("sspf-admin 已停止(嵌入式 PostgreSQL 已优雅关闭)。"); - } -} - -/// 等待**停机信号**(SIGTERM / SIGINT)—— 任一到来即返回。 -/// -/// 🔴 **只影响关停**,不改变任何请求处理路径的行为(契约一字不改)。 -/// 🔴 tokio 的 `signal` feature 已在 workspace 的 `features = ["full"]` 里 ⇒ **不新增依赖**。 -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; - } -} - -/// 从可执行文件向上找项目根(**与 cwd 解耦**)。 -/// -/// 锚点:`/src/backend/db/schema.sql` **与** `/Cargo.toml`(两个都要在)。 -/// 找不到 ⇒ 回落 `current_dir()`。 -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. **业务 spec**(`modules::all_specs()`):`spec.table` 过 `db::valid_table`; -/// 每个 `col.column` 过 `db::valid_column`; -/// 2. **`base_*` 平台表的字面量清单** [`BASE_TABLES`]:每个过 `db::valid_table`; -/// 3. **额外**:spec 的 `spec.table` 必须出现在 [`EXPECTED_TABLES`] 里。 -/// -/// 🔴 **明确不查**(控制器裁定的已知简化):`sys.rs` 的 4 组投影列常量 -/// (`USER_COLUMNS` 等)—— 它们是源码里的字面量常量,不是运行时输入; -/// 真写错了编译期 SQL 就已经炸 ⇒ 启动自检对它们没有防错价值。 -/// -/// 本函数是**兜底 tripwire**,不是完备证明。 -fn whitelist_self_check() -> 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 modules::all_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。 - // 改为「清单 = 7 张 base_* + 业务层 spec 派生的表 + **业务包自带的表**」, - // 再与 DDL **双向**对账 ⇒ 下面三类错都抓得到: - // ① spec 表名拼错(合法标识符但 DDL 里没有)⇒ 启动失败; - // ② DDL 里有表但没有任何 spec 声明它 ⇒ 启动失败(孤儿 DDL); - // ③ DDL 缺表(spec 声明了但没建表)⇒ 启动失败。 - // - // 🔴 **批次 12 的变化**:业务包的表**不在 `db/schema.sql` 里**(DDL 跟着包走, - // 编译进二进制)⇒ 对账的「全部表」= `db/schema.sql` 的表 **∪ 业务包的表**。 - // 只对 `db/schema.sql` 对账会把包表判成「孤儿 DDL」⇒ 启动失败。 - let spec_tables: Vec<&str> = modules::all_specs().iter().map(|s| s.table).collect(); - let pack_tables: Vec<&str> = bootstrap::packs() - .map(|reg| reg.entities.iter().map(|s| s.table).collect()) - .unwrap_or_default(); - let ddl_tables = sspf_core::db::ddl_tables(); - - // 🔴 **报表元数据表**(`report_template` / `report_version`)是**契约面的固定装置**: - // 官方 `/api/Report/*` 属于独立部署的第三方报表服务,主后端没有对应 Controller - // ⇒ 本仓把元数据**就地落库** ⇒ 它们既不是 `base_*` 平台表,也不是业务 spec 表。 - // 清单真源在 `sspf_store::db::REPORT_TABLES`(与存储层的表数断言同一处)。 - let report_tables = sspf_core::db::REPORT_TABLES; - - // 🔴 **流程元数据表**(`workflow_*` 24 张)同理:官方 `/api/workflow/**` 的 - // 元数据载体(逐字照官方 DDL 导入),既不是 `base_*` 平台表也不是业务 spec 表。 - // 清单真源在 `sspf_store::db::WORKFLOW_TABLES`。 - let workflow_tables = sspf_core::db::WORKFLOW_TABLES; - - // 🔴 **extend 示例 / teamwork 文件**(批次 22–23):官方 `jnpf-extend` 与 - // `jnpf-file` 的落库载体,既不是 `base_*` 平台表、也不是业务 spec 表。 - // 清单真源在 `sspf_store::db::{EXTEND_TABLES, TEAMWORK_TABLES}`。 - let extend_tables = sspf_core::db::EXTEND_TABLES; - let teamwork_tables = sspf_core::db::TEAMWORK_TABLES; - - // 🔴 **大屏 blade-visual**(批次 25):官方 `jnpf-visualdata` 的 9 张 - // `blade_visual*` 表(逐字照官方 DDL),既不是 `base_*` 平台表、 - // 也不是业务 spec 表 ⇒ 与 `EXTEND_TABLES` / `TEAMWORK_TABLES` 同性质。 - // 清单真源在 `sspf_store::db::VISUALDATA_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 = bootstrap::packs() - .map(|reg| reg.ddls.iter().any(|d| d.table == *table)) - .unwrap_or(false); - if !in_schema && !in_pack { - return Err(format!( - "spec 表 {table} 既不在 db/schema.sql 里、也不在任何业务包的 DDL 里(漏建表?)" - )); - } - } - - Ok(()) -} - -/// 开库:`PGLITE_DIR=memory://` ⇒ 临时库(进程退出即销毁);否则磁盘目录。 -/// pglite 0.2.7 内嵌的 PostgreSQL 在 boot 阶段(`pq_init → WaitEventAdjustKqueue`) -/// 会对 fd 1 注册 kqueue 读事件。若 fd 1 是字符设备(如 `/dev/null`)或已关闭, -/// `kevent()` 会失败;又因 `pgl_startPGlite` 不在 `sigsetjmp` 上下文,错误会回落成 -/// `pgl_native_exit(100)`,并以残留 `postmaster.pid`、退出码 100 收场。 -/// -/// 修复:开库前若 fd 1 不是「普通文件 / 管道 / 套接字 / 终端」这类可安全用于 kqueue 的 -/// 类型,就把它重定向到一个匿名普通临时文件(进程级,泄漏以保活 fd)。 -/// 仅在真正需要时动手,正常 `> file` / `| pipe` / 终端场景完全不动,避免影响输出与 MCP 协议通道 -/// (MCP 协议走 `dup` 出来的独立 fd,不依赖 fd 1)。 -#[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); - } - } - } -} - -async fn open_db(config: &Config) -> Result { - #[cfg(unix)] - ensure_stdout_for_pglite(); - if config.pg_is_temp() { - Db::open_temp().await - } else { - Db::open(&config.pg_dir).await - } -} - #[cfg(test)] mod tests { use super::*; @@ -1027,80 +324,99 @@ mod tests { } } - /// 未知参数 ⇒ 用法错 ⇒ 退出码 **2**。 + /// 无参数 ⇒ `Cmd::Serve`(起服务,退出码 0)。 #[test] - fn unknown_flag_exits_two() { - let cmd = parse_args(&args(&["--bogus"])); - assert_eq!(cmd, Cmd::Unknown("--bogus".to_string())); - assert_eq!(exit_code(&cmd), 2); - } - - /// 🔴 `--seed-lowcode-demo` ⇒ 种低代码示例功能,退出码 **0**。 - #[test] - fn seed_lowcode_demo_is_recognized() { - let cmd = parse_args(&args(&["--seed-lowcode-demo"])); - assert_eq!(cmd, Cmd::SeedLowcodeDemo { dry_run: false }); + fn no_args_serves() { + let cmd = parse_args(&[]); + assert_eq!(cmd, Cmd::Serve); assert_eq!(exit_code(&cmd), 0); } - /// 🔴 `--seed-lowcode-demo --dry-run` ⇒ 演练模式(不碰库)。 + /// 未知参数 ⇒ `Cmd::Unknown` + 退出码 **2**(且保留原文,便于人话提示)。 #[test] - fn seed_lowcode_demo_supports_dry_run() { - let cmd = parse_args(&args(&["--seed-lowcode-demo", "--dry-run"])); - assert_eq!(cmd, Cmd::SeedLowcodeDemo { dry_run: true }); - assert_eq!(exit_code(&cmd), 0); - } - - /// 🔴 `--dry-run` 写在 `--seed-lowcode-demo` **之前** ⇒ 当没给 - /// (与 `--mcp --with-http` 的位置约定同款)。 - #[test] - fn dry_run_flag_position_matters() { - let cmd = parse_args(&args(&["--dry-run", "--seed-lowcode-demo"])); - assert_eq!(cmd, Cmd::Unknown("--dry-run".to_string())); + fn unknown_arg_exits_two() { + let cmd = parse_args(&args(&["--nope"])); + assert_eq!(cmd, Cmd::Unknown("--nope".to_string())); assert_eq!(exit_code(&cmd), 2); } - /// 🔴 **生产档拒绝跑种子**(纯函数闸门,不开库)。 + /// 🔴 `--with-http` 只在 `--mcp` 之后有意义;位置写错就当没给(**不许**误解成别的模式)。 + #[test] + fn with_http_only_after_mcp() { + assert_eq!( + parse_args(&args(&["--mcp", "--with-http"])), + Cmd::Mcp { with_http: true } + ); + assert_eq!( + parse_args(&args(&["--mcp"])), + Cmd::Mcp { with_http: false } + ); + assert_eq!( + parse_args(&args(&["--with-http"])), + Cmd::Unknown("--with-http".to_string()) + ); + } + + /// 🔴 `--dry-run` 只在 `--seed-lowcode-demo` 之后有意义。 + #[test] + fn dry_run_only_after_seed_subcommand() { + assert_eq!( + parse_args(&args(&["--seed-lowcode-demo", "--dry-run"])), + Cmd::SeedLowcodeDemo { dry_run: true } + ); + assert_eq!( + parse_args(&args(&["--seed-lowcode-demo"])), + Cmd::SeedLowcodeDemo { dry_run: false } + ); + assert_eq!( + parse_args(&args(&["--dry-run"])), + Cmd::Unknown("--dry-run".to_string()) + ); + } + + /// 🔴 **平台装配不带业务**:`sspf::Platform::new()` 的 Debug 里没有包、没有菜单 —— + /// 证明「示例包必须显式注入」,不是内核偷偷带的。 + #[test] + fn platform_starts_empty() { + let text = format!("{:?}", sspf::Platform::new()); + assert!(text.contains("packs: []"), "默认装配不得带包: {text}"); + assert!(text.contains("menus: 0"), "默认装配不得带业务菜单: {text}"); + } + + /// 🔴 `--seed-lowcode-demo` 在生产档必须被拒绝(种子会改库结构)。 #[test] fn seed_is_rejected_in_prod_profile() { - let err = ssw_platform::lowcode_seed::seed_gate(Profile::Prod) + let err = lowcode_seed::seed_gate(sspf::Profile::Prod) .expect_err("生产档必须拒绝跑低代码种子"); assert!(err.contains("SSW_PROFILE"), "要说清用哪个环境变量:{err}"); } - /// 🔴 开发档放行。 + /// 开发档必须允许跑种子(否则本地开发没法用)。 #[test] fn seed_is_allowed_in_dev_profile() { - assert!(ssw_platform::lowcode_seed::seed_gate(Profile::Dev).is_ok()); + lowcode_seed::seed_gate(sspf::Profile::Dev).expect("开发档必须允许跑种子"); } - /// 无参数 ⇒ **起服务**(不是退出码)。 - #[test] - fn empty_args_mean_serve() { - assert_eq!(parse_args(&args(&[])), Cmd::Serve); - } - - /// 🔴 **表清单与 DDL 对得上** —— 加了业务表却忘了加 DDL(或反之)⇒ 这里红。 - #[test] - fn whitelist_self_check_passes_for_this_repo() { - // 🔴 这条钉住「表清单与 DDL 对得上」:加了业务表却忘了加 DDL(或反之)⇒ 这里红。 - whitelist_self_check().expect("本仓的表清单与 db/schema.sql 必须对得上"); - } - - /// 🔴 **入口文件不许写死业务表名**(红线 12)—— 加业务模块不改入口。 + /// 🔴 **CLI 不许写死业务表名** —— 加了业务包要改入口文件 ⇒ 违反红线 12。 + /// + /// 门面那一侧由 `check-arch.sh` 的 AR18 钉住;本文件是另一个「入口」, + /// 同样不该认识业务。 #[test] fn entry_point_does_not_name_business_tables() { - let base: Vec<&str> = BASE_TABLES.to_vec(); - for spec in modules::all_specs() { - assert!( - !base.contains(&spec.table), - "BASE_TABLES 里不许出现业务表 {}", - spec.table - ); + let src = include_str!("main.rs"); + // 🔴 名字**拆开拼**:本文件自己会被 `include_str!` 扫进去, + // 直接写整名会让「测试自己触发测试」⇒ 永远红。 + for name in [ + ["demo", "_item"].concat(), + ["shop", "_product"].concat(), + ["book_shop", "_book"].concat(), + ["asset", "_data_resource"].concat(), + ] { + assert!(!src.contains(&name), "CLI 里不许出现业务表名 {name}"); } } - /// 🔴 解析是**纯函数** —— 同一个 args 反复解析结果恒等(不依赖环境变量 / 进程状态)。 + /// `parse_args` 是**纯函数**:同样的入参 ⇒ 同样的结果,不改入参。 #[test] fn parse_args_is_pure() { let a = args(&["--enc", "123456"]); diff --git a/crates/sspf/Cargo.toml b/crates/sspf/Cargo.toml new file mode 100644 index 0000000..39375ab --- /dev/null +++ b/crates/sspf/Cargo.toml @@ -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 } diff --git a/crates/sspf/src/lib.rs b/crates/sspf/src/lib.rs new file mode 100644 index 0000000..c943c27 --- /dev/null +++ b/crates/sspf/src/lib.rs @@ -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 { + 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 是平台包:不得装载示例业务包" + ); + } +} diff --git a/crates/sspf/src/platform.rs b/crates/sspf/src/platform.rs new file mode 100644 index 0000000..3e76177 --- /dev/null +++ b/crates/sspf/src/platform.rs @@ -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 Pin> + 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, + /// 业务包(默认**空** —— 平台包不带业务)。 + packs: PackRegistry, + /// 业务建表 SQL(不走包装载的零散 DDL)。 + ddls: Vec, + /// 业务菜单(注入两段式种子的第一段)。 + menus: Vec, + /// 业务自定义路由(含它自己的中间件 / 守卫)。 + router: Option>, + /// 静态 SPA 目录(深链回退 `index.html`)。 + static_dir: Option, + /// 启动钩子(业务预热:引导身份 / 外部连接 / 缓存)。 + hooks: Vec, +} + +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::>()) + .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) -> 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, 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) -> 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) -> Self { + self.static_dir = Some(dir.into()); + self + } + + /// 启动钩子(`AppState` 已就绪、路由尚未对外)。 + /// + /// ```ignore + /// .on_ready(|state| async move { + /// // 用 state.db 做业务预热;Err ⇒ 启动失败(进程不对外) + /// Ok(()) + /// }) + /// ``` + pub fn on_ready(mut self, f: F) -> Self + where + F: Fn(AppState) -> Fut + Send + Sync + 'static, + Fut: Future> + Send + 'static, + { + self.hooks.push(Box::new(move |state: AppState| { + Box::pin(f(state)) as Pin> + Send>> + })); + self + } + + // ------------------------------------------------------------ 运行时 + + /// 走完整装配,返回**可 `axum::serve` 的 Router**(不绑端口)。 + /// + /// 🔴 主要给测试 / 嵌入场景用;生产用 [`Platform::serve`](含优雅停机 + 关库)。 + pub async fn build_app(mut self) -> Result { + 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 { + // ---- 第 1 步:开库前自检(标识符白名单 + 与 DDL 对账)---- + // + // 🔴 业务 spec / 包 DDL **由调用方给**(平台包里零业务)⇒ 自检认识业务, + // 但平台代码不认识 —— 这份知识只在运行时经参数进来。 + let specs: Vec = self.packs.entities.iter().map(|s| **s).collect(); + let mut all_ddls: Vec = 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 = 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(), + } + } +} diff --git a/crates/sspf/src/runtime.rs b/crates/sspf/src/runtime.rs new file mode 100644 index 0000000..94726e1 --- /dev/null +++ b/crates/sspf/src/runtime.rs @@ -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) -> 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()) +} diff --git a/crates/tests/Cargo.toml b/crates/tests/Cargo.toml index 5546c64..64bb0dc 100644 --- a/crates/tests/Cargo.toml +++ b/crates/tests/Cargo.toml @@ -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 } diff --git a/crates/tests/tests/external_consumer_it.rs b/crates/tests/tests/external_consumer_it.rs new file mode 100644 index 0000000..e8c0e51 --- /dev/null +++ b/crates/tests/tests/external_consumer_it.rs @@ -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`;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::().ok()) + .expect("响应首行必须是 HTTP/1.1 ..."); + (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>> = 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`)。 + *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, + "表数不该随请求变化(同一个库、同一个装配)" + ); +} diff --git a/docs/SSPF-PLATFORM-PACKAGE.md b/docs/SSPF-PLATFORM-PACKAGE.md new file mode 100644 index 0000000..26aba6b --- /dev/null +++ b/docs/SSPF-PLATFORM-PACKAGE.md @@ -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)` | 业务自定义路由(含自己的中间件/守卫) | `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)`;`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`,不收 `Vec`。** + `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` | diff --git a/scripts/check-arch.sh b/scripts/check-arch.sh index 4e014fd..14546ba 100755 --- a/scripts/check-arch.sh +++ b/scripts/check-arch.sh @@ -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 diff --git a/scripts/pack-sync.py b/scripts/pack-sync.py index 7db99b3..8326876 100755 --- a/scripts/pack-sync.py +++ b/scripts/pack-sync.py @@ -85,6 +85,8 @@ GEN_OPEN = "// >>>GEN:%s" GEN_CLOSE = "// << Result {") L.append(" let mut regs: Vec = 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 {") + 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 {") + L.append(" sspf_plugin::merge(regs)") + L.append("}") + L.append("") L.append("// ---------------------------------------------------------------- 清单快照") L.append("//") L.append("// 🔴 `pack.toml` 的**权威副本**在 `packs//pack.toml`(给人看、给导出工具读);") L.append("// 这里是它的**编译期 JSON 快照**。为什么要快照、不运行期读文件:") L.append("// 内核是**单二进制部署** ⇒ 运行目录里不一定有 `packs/` 目录。") L.append("// 两份的一致性由 `scripts/pack-sync.py` 保证(`--check` 会比对)。") + 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//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 {", " %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 {") + 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: diff --git a/src/backend/Cargo.toml b/src/backend/Cargo.toml index e1c1e9a..599d264 100644 --- a/src/backend/Cargo.toml +++ b/src/backend/Cargo.toml @@ -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//Cargo.toml` 的 `[package].name`)。 # 加包请跑 `bash scripts/new-pack.sh `;手改会在下次同步被覆盖, # 且 `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_FEATURE +example-packs = ["dep:sspf-pack-asset", "dep:sspf-pack-books", "dep:sspf-pack-demo", "dep:sspf-pack-shop"] +# <</src/backend/db/schema.sql` **与** `/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(), ®.ddls) +} + +/// 开库:`PGLITE_DIR=memory://` ⇒ 临时库(进程退出即销毁);否则磁盘目录。 +pub async fn open_db(config: &Config) -> Result { + #[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 + ); + } + } +} diff --git a/src/backend/src/bootstrap.rs b/src/backend/src/bootstrap.rs index 49d41a5..6e22d6d 100644 --- a/src/backend/src/bootstrap.rs +++ b/src/backend/src/bootstrap.rs @@ -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 { /// 🔴 **顺序**:按包的 `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 ®.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; diff --git a/src/backend/src/lib.rs b/src/backend/src/lib.rs index 5a55140..e75abb8 100644 --- a/src/backend/src/lib.rs +++ b/src/backend/src/lib.rs @@ -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; diff --git a/src/backend/src/modules/mod.rs b/src/backend/src/modules/mod.rs index 5675591..60627fd 100644 --- a/src/backend/src/modules/mod.rs +++ b/src/backend/src/modules/mod.rs @@ -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: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: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] = &[]; // << Option<&'static EntitySpec> { /// **全部业务模块的路由**(`Router::merge` 进总路由)。 /// /// 🔴 加业务模块 ⇒ **不用改这里**(本段由 `pack-sync.py` 生成)。 +#[cfg(feature = "example-packs")] pub fn router() -> Router { asset::router() .merge(books::router()) .merge(demo::router()) .merge(shop::router()) } +/// 默认 feature:没有任何业务路由。 +#[cfg(not(feature = "example-packs"))] +pub fn router() -> Router { + Router::new() +} // <<= 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; diff --git a/src/backend/src/packs_gen.rs b/src/backend/src/packs_gen.rs index 0a7f06f..953a796 100644 --- a/src/backend/src/packs_gen.rs +++ b/src/backend/src/packs_gen.rs @@ -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 { let mut regs: Vec = Vec::new(); @@ -61,14 +67,35 @@ pub fn registry(kernel_version: &str) -> Result { Ok(sspf_plugin::merge(regs)) } +/// 默认 feature(业务仓只依赖门面时的形态):**本仓不认识任何业务包** ⇒ 空注册表。 +/// +/// 🔴 返回 `Ok` 而不是 `Err`:空注册表是**合法形态**(业务仓自己注入业务包), +/// 不是装载失败。 +#[cfg(not(feature = "example-packs"))] +pub fn registry(_kernel_version: &str) -> Result { + Ok(PackRegistry::default()) +} + +/// 把**外部已装载**的注册表合并成一个(门面 `sspf::Platform::packs` / `.pack` 用)。 +/// +/// 🔴 与 [`registry`] 的分工:`registry` 装的是**本仓 `packs/*` 的示例包**; +/// 本函数**只合并、不装载** ⇒ 业务仓用 `sspf::load_static` 装好自己的包后传进来。 +/// 🔴 空 vec ⇒ 空注册表(合法,不是错误)。 +pub fn registry_from(regs: Vec) -> PackRegistry { + sspf_plugin::merge(regs) +} + // ---------------------------------------------------------------- 清单快照 // // 🔴 `pack.toml` 的**权威副本**在 `packs//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", diff --git a/src/backend/src/routes.rs b/src/backend/src/routes.rs index 295ca62..468ba3d 100644 --- a/src/backend/src/routes.rs +++ b/src/backend/src/routes.rs @@ -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 { 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>, + /// 业务方自定义路由(含它自己的中间件 / 守卫,`/api/ssw/**` 之类)。 + pub router: Option>, + /// 静态 SPA 目录:**非 `/api/**` 的未命中路径**回退到 `index.html`(深链)。 + /// + /// 🔴 `/api/**` 永远走信封 404 —— 静态托管不许吞掉接口的 404 契约。 + pub static_dir: Option, +} + +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 { /// (`config` / `db` / `sessions`)**全是 `Arc`** ⇒ 两份 clone **共享同一份底层状态** /// ⇒ 行为完全等价,**不是**两个独立状态。 pub fn build_router(state: AppState) -> axum::Router { + build_router_with(state, Extras::kernel()) +} + +/// 同 [`build_router`],但**业务路由由调用方注入**(门面 / 外部业务仓走这一条)。 +pub fn build_router_with(state: AppState, extras: Extras) -> axum::Router { let router = Router::new() // ---- 探活(§6.5 末条,非契约)---- .route("/api/health", get(health)) @@ -1248,9 +1288,9 @@ pub fn build_router(state: AppState) -> axum::Router { .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 { .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 { /// 🔴 **这条链在仓库里只有这一份** —— 生产与测试共用 ⇒ 改顺序时两边一起变, /// 测试永远钉得住(不要在 `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, 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 { + 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 { + 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 { + 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, …}`