Files
ssw-platform/README.md
T
admin ecb77b230f 平台包零业务:示例移到技能仓、解绑 example-packs、闸门全部改防回流
- 物理移出 packs/{asset,books,demo,shop}、modules/ 四个面 A 适配器、纯技能副本、
  纯业务测试 crud_it.rs 与 new-pack 脚手架(v0.3.0 tag 完整保留旧形态)。
- 删 example-packs feature / example_packs() / sspf-pack-* 依赖 / packs/* member;
  packs_gen.rs 与 modules/mod.rs 生成段降级为恒空的注入点,装配链一条不删;
  pack-sync.py 把「零包」钉成合法目标态。
- 尺子不再「跳过」:CP1 防回流清单、check-module 三条、AR2/PACK1 正向断言、
  AR17 升级为零业务依赖判据(含注入式反自证)、契约反自证换平台锚点、FACE 零包重算。
- 面 A 冒烟 43→21 条(17 条平台权限闭环 + 4 条业务端点 404);pack_smoke_it 改
  运行时防回流探针;auth/db/batch7/permission/seed/routes 单测换平台内置夹具。
- 契约 [MENU_TREE] 收成 5 条系统菜单、[RULER] 改 21/3;README/CLAUDE/HANDOFF/
  CHANGELOG/contract §5.1/schema.sql/db.rs 注释同步。

验收:cargo test --workspace --no-fail-fast 649 passed / 0 failed / 6 ignored;
verify.sh --smoke 14/14;check-arch 24/24 + 反自证 14/14;
cargo tree -p sspf 无 sspf-pack-*。前端 src/frontend 按要求保留。
2026-11-04 21:54:22 +08:00

125 lines
6.1 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.3.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 |
| 未发布 | 平台包零业务清理:示例包 / 面 A 适配器 / `example-packs` 全部退役,闸门改防回流 |
发布说明见 `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 版) |