Files
ssw-platform/README.md
T
admin 509c6b1d1f feat(db): v0.5.0 业务库操作收进同一个 Db —— query_json_raw / query_rows / lock_owned
- Db::query_json_raw:持 Db.lock、row_to_json 包裹、不做 JSON 键归一(给自带归一语义的厚业务仓)
- Db::query_rows:持锁返回原始 pglite::Row(pg_catalog 元数据 / 取首行首列)
- Db::lock_owned():与所有 Db::* / DbTransaction 共用同一把锁,guard 内可用裸句柄跑自有 SQL
- query_json_inner 拆出共用段 query_json_inner_raw ⇒ SQL 包裹只有一份,query_json* 行为未改
- 闸门 AR20(raw 不归一 / 共用段 / 8 个公开入口全持锁)+ 反自证 14 → 15 项
- 探针 db_raw_it(4 条):raw 不归一 · 归一路径同时成立 · guard 期间 Db::exec 被阻塞 · query_rows 读 pg_catalog
- 销掉 known-limitations 的「双锁」条;CHANGELOG / README 版本表升 0.5.0
- 验收:653 passed / 0 failed;verify.sh --smoke 14/14;check-arch 25/25 自证 15/15
2026-11-04 22:54:35 +08:00

6.3 KiB
Raw Permalink Blame History

sspf —— SSPF 标准平台包

本仓是平台本体(ssw-platform),不是业务项目,也不是技能。 业务仓(如 tdc-rs)只依赖本仓发布的 sspf crate;JNPF MVP 示例、React 演示前端的 权威副本在技能仓 ssw-jnpf-lite-rust(~/.agents/skills/ssw-jnpf-lite-rust)。

这是什么

sspf 是 JNPF 契约的 Rust 实现,按 git tag 发布给业务仓。一个业务仓、一个进程、 一个 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() 注入。

业务仓怎么接

[dependencies]
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/                 # 静态闸门(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 版)