# sspf —— SSPF 标准平台包 > **本仓是平台本体(ssw-platform),不是业务项目,也不是技能。** > 业务仓(如 `tdc-rs`)只依赖本仓发布的 `sspf` crate;JNPF MVP 示例、React 演示前端的 > **权威副本**在技能仓 `ssw-jnpf-lite-rust`(`~/.agents/skills/ssw-jnpf-lite-rust`)。 ## 这是什么 `sspf` 是 JNPF 契约的 Rust 实现,平台仓**每个版本打一个自包含发布包**(`dist/sspf-vX.Y.Z.tar.gz`, 含预编译 `sspf-admin` 二进制 + 平台 crate 源码 + `Cargo.lock`),消费方解包到 `vendor/` 用 `path` 依赖接入, **不再需要直接依赖 git 仓**。一个业务仓、一个进程、 一个 PGlite 实例、一个端口,同时提供: | 面 | 内容 | 由谁提供 | |---|---|---| | 面 A | ssw 约定 `/api/ssw/{app}/{Entity}/{动作}`,声明式 `EntitySpec` 驱动的 CRUD | 平台 | | 面 B | 官方 JNPF 形状(346 端点 / `base_*` 表 / cipher / 602 码) | 平台 | | 业务面 | 业务仓自带状态的 132 条端点等 | 业务仓通过 `Finish` 注入 | | 其它 | 登录 / 权限 / 低代码 / MCP / 静态 SPA 托管 | 平台 | 平台包**默认零业务**:依赖树里没有 `sspf-pack-*`,`/api/health` 是 `tables=177`。 业务通过 `Platform::packs / ddl / menus / router / static_dir / on_ready` 或 v0.3.0 的 `assemble() → Finish{ router, fallback, layers } → serve()` 注入。 ## 业务仓怎么接 ```toml # 消费方:先把平台发布包解包到 vendor/(详见 docs/SSPF-PLATFORM-PACKAGE.md §6) sspf = { path = "vendor/sspf-v0.5.0/crates/sspf", version = "0.5" } # (旧写法 git + tag 仍可用,但已不推荐:要求构建时访问 git 且每次重编整个 monorepo) # sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.5.0" } ``` ```rust // 最简:平台能力全量启动(177 表 / 面 A·面 B / 静态托管) sspf::Platform::new().static_dir("static").serve().await?; // 厚业务仓:两阶段装配(v0.3.0 起) let boot = sspf::Platform::new().ddl("biz_x", include_str!("../schema/001.sql")).assemble().await?; let pg = boot.state.db.pg(); // 同一个 Arc let biz = build_router(BizState::new(pg)).with_state(()); boot.serve(Finish { router: Some(biz), ..Finish::default() }).await?; ``` 业务仓另需:自带 `rust-toolchain.toml` 锁 **1.95.0**、`[profile.dev] incremental = false`、 release **不设** `panic = "abort"`(否则 catch-all 的 `panic ⇒ 200 + code=400` 失效)。 ## 目录 ``` ssw-platform/ ├── crates/sspf/ # 🔴 唯一发布物:门面 + Platform builder + 两阶段装配 ├── crates/sspf-*/ # 平台能力层(core / contract / store / plugin / lowcode / mcp / compat …) ├── crates/sspf-admin/ # 🔴 纯平台装配(bin `sspf-admin`):177 表、面 A 无业务端点 ├── crates/tests/ # 集成测试宿主(package `sspf-tests`) ├── src/backend/ # 内核 lib(`ssw_platform`):装配根 / 路由 / 启动原语 / 平台 DDL ├── src/frontend/ # React + Vite 演示前端(可选,随发布包保留) ├── docs/ # 契约真源 / 运维 / 裁决 / DDL / 需求与实施记录 │ ├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型(附录 A 是尺子期望源) │ ├── SSPF-PLATFORM-PACKAGE.md # P0 需求 + 实施记录(v0.2.0) │ └── SSPF-BUSINESS-COMPOSITION.md # P1 需求 + 实施记录(v0.3.0) ├── scripts/ # 出包(release.sh)/ 静态闸门(check-*)/ 运行时尺子(*-smoke)/ 生成段同步(pack-sync) ├── run.sh # install / build / dev / backend / frontend / stop / logs └── Cargo.toml # cargo workspace 根 ``` **不在本仓**:`template-boot-jnpf/`、`references/`、`JNPF_COMPAT_SURFACE.md`、 `JNPF_SOURCE_AUDIT.md`、`PERMISSION.md`、`HOWTO_MODULE.md`、`MIGRATION.md` 等技能资产, 以及 `books / demo / shop / asset` 业务示例包 —— 它们属于技能仓,本仓只保留平台能力与自测。 ## 快速开始 ```bash cargo run -p sspf-admin # http://127.0.0.1:30010,admin / 123456 bash run.sh install # cargo fetch + npm install bash run.sh build # cargo build --release + vite build bash run.sh dev # 后端 30010 + 前端 5173(都就绪才算成功) bash run.sh stop / logs ``` | 端口 | 谁 | 说明 | |---|---|---| | `30010` | 后端 | `run.sh` 硬约定;`PORT` ≠ 30010 时 dev/backend 报错退出 2 | | `5173` | 前端 vite | `strictPort: true` | > 本机 curl 走系统代理 ⇒ 打 localhost 必须加 `--noproxy '*'`。 ## 验收 ```bash cargo build --workspace --all-targets # 0 error / 0 warning cargo test --workspace # 全绿 bash scripts/verify.sh --fast # 内环:生成段同步 + 6 道静态闸门 cargo build --release -p sspf-admin # --smoke 的尺子默认读 target/release/sspf-admin bash scripts/verify.sh --smoke # 全量:+ 全量测试 + 5 把运行时尺子 bash scripts/check-arch.sh --self-test # 闸门反自证 cargo tree -p sspf | grep sspf-pack # 必须无输出(平台包零业务) ``` 静态闸门的期望值集中在 `docs/contract.md` 附录 A,由 `scripts/contract_expect.py` 解析; 每把尺子自证条数,被改弱即失败。 ## 数据库 `pglite-rs 0.2` —— 进程内**原生 PostgreSQL**(不是浏览器 WASM 版),单 backend, 真实 SQL 语义。数据落 `src/backend/data/lite.pg`,**一个数据目录只能被一个进程打开**; `PGLITE_DIR=memory://` 是临时目录的一次性库。无 TCP 监听 ⇒ `psql` 连不上, 导出走应用内 `COPY ... TO STDOUT`。 ## 版本与迁移 | tag | 内容 | |---|---| | `v0.2.0` | 标准平台包 P0:门面 `sspf`、示例包选装、AR17/AR18 | | `v0.3.0` | P1:`Db::pg()` 同句柄、`assemble()/Finish` 两阶段装配、AR19 | | `v0.4.0` | 平台包零业务清理:示例包 / 面 A 适配器 / `example-packs` 全部退役,闸门改防回流 | | `v0.5.0` | 业务库操作收进同一个 `Db`:`query_json_raw`(持锁不归一)/ `query_rows` / `lock_owned()`,闸门 AR20(**已推 `origin`**) | 发布说明见 `CHANGELOG.md`,逐版实施记录见 `HANDOFF.md` 与 `docs/SSPF-*.md`。 已发布的 tag **一字不动**;破坏性变更走新 tag。 ## 参照物 | 参照物 | 地位 | |---|---| | 官方 JNPF 源码 + DDL(`~/Desktop/workspace/jnpf/`) | `base_*` 数据模型真源 | | 技能仓 `ssw-jnpf-lite-rust` | JNPF MVP 示例、演示前端、面 B 规格与迁移说明 | | `tdc-rs` 兄弟业务仓 | 平台包的真实消费者(P2 改造参照) | | `ssw-jnpf-lite-react` | 面 A 行为真源(NestJS 版) |