Files
admin f6c3ff64ee feat(pkg): 每版本出包替代 git 依赖(release.sh + 文档同步)
- 新增 scripts/release.sh:读 crates/sspf 版本 → 编译预编译 sspf-admin 二进制
  → 组装自包含发布包 dist/sspf-vX.Y.Z.tar.gz(预编译二进制 + 平台 crate 闭包
  + Cargo.lock + rust-toolchain.toml + 前端源码),并自检验证离线可编。
- docs/SSPF-PLATFORM-PACKAGE.md §6 改为「每版本出包、消费方 path 依赖」模型,
  废弃原 git tag 依赖写法;README/HANDOFF/CHANGELOG 同步。
- .gitignore 忽略 dist/
2026-11-05 09:28:47 +08:00

130 lines
6.8 KiB
Markdown
Raw Permalink 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 实现,平台仓**每个版本打一个自包含发布包**(`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<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` 业务示例包 —— 它们属于技能仓,本仓只保留平台能力与自测。
## 快速开始
```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 版) |