- .gitea/ISSUE_TEMPLATE/platform-issue.md:现象/最小复现/期望/环境(sspf 版本、rustc host) - config.yaml:允许空白 issue (技能仓 SKILL.md/README.md 已指向本仓 issues)
sspf —— SSPF 标准平台包
本仓是平台本体(ssw-platform),不是业务项目,也不是技能。 业务仓(如
tdc-rs)只依赖本仓发布的sspfcrate;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() 注入。
业务仓怎么接
# 消费方:先把平台发布包解包到 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" }
// 最简:平台能力全量启动(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<PGlite>
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 业务示例包 —— 它们属于技能仓,本仓只保留平台能力与自测。
快速开始
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 '*'。
验收
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 版) |