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

126 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 版) |