- 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
126 lines
6.3 KiB
Markdown
126 lines
6.3 KiB
Markdown
# 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()` 注入。
|
||
|
||
## 业务仓怎么接
|
||
|
||
```toml
|
||
[dependencies]
|
||
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<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` 业务示例包 —— 它们属于技能仓,本仓只保留平台能力与自测。
|
||
|
||
## 快速开始
|
||
|
||
```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 版) |
|