- fetch-platform.sh: 解包加 --exclude=crates/src/frontend/Cargo.toml/Cargo.lock, 只留 lib/ + rust-toolchain.toml + bin/ + docs/README(vendor 少解 ~62M 源码) - 校验改为认 vendor/.../lib/libsspf-*.rlib,不再读 crates/sspf/Cargo.toml - 所有「dev 回退 path 到 vendor 源码」改为「极端回退用 git tag 依赖」 - 文档同步 SKILL/README/HANDOFF 验证: cargo clean 后 dev 5.14s / release 9.34s,只编本仓 5 crate; vendor 无任何平台源码;二进制 --help 正常(基于 sspf v0.5.0)。
231 lines
16 KiB
Markdown
231 lines
16 KiB
Markdown
# ssw-jnpf-lite-rust · Rust 全栈 MVP
|
||
|
||
**平台来自 `sspf` 发布包**(`vendor/sspf-v0.5.0/` 由平台仓 `scripts/release.sh` 产出、本仓
|
||
`scripts/fetch-platform.sh` 解包,不再直接依赖 git 仓),本仓只有
|
||
**业务样板(`packs/`)+ 面 A 适配器 + 薄装配 + 前端产物 + 两把运行时尺子**。
|
||
数据库仍是**进程内原生 PostgreSQL**(由平台包提供),除 Node 外无需装任何东西。
|
||
|
||
> 🔴 **2026-11-04 → 2026-11-05 架构变更**:以前本仓自带一份平台实现(`src/backend/src/platform/` + `routes.rs`,约 4000 行),
|
||
> 那是「示例仓里躺着一份会分叉的平台」。2026-11-04 平台搬进 `sspf` 一处演进,本仓**锁 git tag**;
|
||
> 2026-11-05 最终改为**方案 C:预编译 rlib,零重编平台**(平台仓 `scripts/release.sh` 打
|
||
> `dist/sspf-vX.Y.Z.tar.gz`,内含 `lib/` 预编译 rlib 完整闭包;本仓 `scripts/fetch-platform.sh`
|
||
> 解包到 `vendor/sspf-vX.Y.Z/` 并生成 `.cargo/config.toml`,用 `--extern` + `-L dependency`
|
||
> 直喂 rustc)。**不再需要 Gitea 访问、不 clone monorepo、零重编平台 17 crate 与 axum/tokio**——
|
||
> 实测 `cargo build` 5.7s / `--release` 11s,只编本仓 5 个 crate。
|
||
> 升级平台 = `bash scripts/fetch-platform.sh <新版本>`。`Cargo.toml` 不声明外部依赖;
|
||
> release profile 必须 `lto = false`(预编译 rlib 无 bitcode,开 LTO 会失败)。
|
||
> 判据:`python3 scripts/check-scaffold.py`(本仓出现 `platform/` / `routes.rs` / `crates/` 立刻红)。
|
||
|
||
来自 `ssw-jnpf-lite-react`(NestJS + React)的 **Rust 全栈 counterpart**——两者是**并列可选**的独立技能,
|
||
不是依赖关系:要 MVP 期就用 Node 栈选 `ssw-jnpf-lite-react`,要 MVP 期用 Rust 栈选本技能。
|
||
|
||
> 📌 **本仓 = 技能本体**(不是「技能的项目副本」):仓根就是技能目录(`SKILL.md` 在仓根),
|
||
> 三处软链 `~/.agents/skills/` · `~/.claude/skills/` · `~/.workbuddy/skills/` 均指向本仓,
|
||
> 所以**改一次仓 = 改一次技能**。
|
||
|
||
## 设计原则:MVP = JNPF 的 Rust 版垫片
|
||
|
||
**MVP 后端不是随便写的 Rust 服务,而是 JNPF 契约的 Rust 版垫片**——契约从第一天锁死,
|
||
使稳定期换 Java 后端是「机械翻译」而非重写。
|
||
|
||
**锁死的五件事**(详见 [`MIGRATION.md`](MIGRATION.md) §1):
|
||
|
||
| # | 锁死的东西 | 为什么 |
|
||
|---|---|---|
|
||
| 1 | `base_*` 表名 / 列名(逐字对齐官方 DDL,含两个官方陷阱) | 迁移期靠 `--data-only` 导数据,列名差一个字符就导不进去 |
|
||
| 2 | 口令密文算法(`md5 → AES-256-ECB-PKCS7 → hex`) | 前端 `cipher.ts` / 后端 `cipher.rs` / 官方 `DesUtil` 逐字节一致 |
|
||
| 3 | 统一信封 `ActionResult{code,msg,data}` + 业务失败恒 HTTP 200 | 换栈后前端零改 |
|
||
| 4 | 主键 = 36 位 UUID v4(`f_id VARCHAR(50)`) | 与官方 `IdUtil.fastUUID()` 同形 |
|
||
| 5 | JSON 键名 = 列名去 `f_` 前缀后 camelCase | 官方 Jackson 自动剥离 `f` |
|
||
|
||
**故意没锁的两件事**(就是「面 A / 面 B」要解决的):
|
||
|
||
- **端点路径**——面 A 走 ssw 约定 `/api/ssw/{app}/{Entity}/{List|Save|Delete}`,面 B 走官方 RESTful 形状。
|
||
- **列表响应形状**——面 A 是裸数组,面 B 是官方 `PageListVO{pagination,list}`。
|
||
|
||
⇒ **一个后端进程同时服务两套契约**,靠请求头 `Vue-Version: 3` 判面
|
||
(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。详见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)。
|
||
|
||
## 选型决策:Rust 版 vs react 版 vs ssw-jnpf-lite(Java)
|
||
|
||
| | **ssw-jnpf-lite-rust**(本技能) | **ssw-jnpf-lite-react** | **ssw-jnpf-lite**(Java) |
|
||
|---|---|---|---|
|
||
| MVP 期后端栈 | Rust / axum | Node / NestJS | Java / Spring Boot |
|
||
| 部署 | **单二进制**(库链进可执行文件) | Node 进程 + 前端静态产物 | JVM + 前端静态产物 |
|
||
| MVP 期迭代速度 | **快**(编译期类型安全,重构有保障) | 快(AI 也熟) | 慢(编译 + 脚手架重) |
|
||
| 迁官方 JNPF 的成本 | 低(`MIGRATION.md` 有逐件翻译表) | 低(同上,NestJS 版) | **零**(本来就在 Java 上) |
|
||
| 官方前端能跑在上面吗 | ✅ **能**(面 B) | ✅ 能(面 B) | ✅ 原生 |
|
||
| 数据模型 | 与官方逐字一致(`base_*`) | 与官方逐字一致 | 与官方逐字一致 |
|
||
| 适合谁 | 想要 Rust 性能/单二进制,且要保迁移性 | 团队/AI 更熟 Node | 已经是 Java 团队,不打算换栈 |
|
||
|
||
**一句话**:**MVP 期用哪种栈都行,代价是「稳定期迁 JNPF」这件事**。
|
||
本技能把「快」放在 MVP 期(Rust),把「换栈」推迟并**锁死到有界范围**(5 件契约 + 两把运行时尺子)。
|
||
若你**本来就要用 Java**,直接用 `ssw-jnpf-lite`(零迁移摩擦)比绕一圈更划算。
|
||
|
||
## 目录
|
||
|
||
```
|
||
ssw-jnpf-lite-rust/ ← 仓根 = 技能根(三处软链指向这里)
|
||
├── SKILL.md # 入口:是什么 / 何时用 / 契约红线 / 判据
|
||
├── README.md # 本文件:选型 / 运行 / 验收门 / 已知限制
|
||
├── HOWTO_MODULE.md # 加一个业务模块的操作手册
|
||
├── PERMISSION.md # 权限模版:表结构 / 四源合并 / 码表
|
||
├── MIGRATION.md # 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)
|
||
├── JNPF_SOURCE_AUDIT.md # 官方源码逐行核对报告(标 文件:行号)
|
||
├── JNPF_COMPAT_SURFACE.md # 面 B 规格书:官方形状端点 + 落地顺序 S1–S6
|
||
├── CLAUDE.md / HANDOFF.md # 项目级 agent 指引 / 交接文档
|
||
├── run.sh # install / build / dev / backend / frontend / stop / logs
|
||
├── Cargo.toml # workspace 根:方案 C **不声明外部依赖**;rlib 由 .cargo/config.toml 的 --extern 喂入
|
||
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR
|
||
├── scripts/
|
||
│ ├── verify.sh # 一键验收(静态 + 全量测试 + 两把运行时尺子)
|
||
│ ├── check-scaffold.py # 静态判据 SC1–SC6「本仓只准有业务」+ --self-test 6/6
|
||
│ ├── pack-sync.py # 从 packs/* + modules/* 生成四处派生位置;--check 防漂移
|
||
│ ├── new-pack.sh # 造包:packs/<app>/ + modules/<app>.rs + 跑生成
|
||
│ ├── perm-smoke.sh # 运行时尺子·面 A(32 条)
|
||
│ ├── perm-smoke-jnpf.sh # 运行时尺子·面 B(18 条)★ 本技能独有
|
||
│ ├── smoke_backend.sh # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑)
|
||
│ ├── contract_expect.py # 读 docs/contract.md 附录 A(机器可读期望值)—— 尺子的唯一期望源
|
||
│ ├── reap-ipc-leaks.sh # macOS SysV 信号量泄漏回收(PGlite 专用)
|
||
│ └── ipc-reap.c # 上面那个的 C 实现
|
||
├── packs/ # 【业务真源】整目录可搬;每个包只依赖 sspf 门面
|
||
│ ├── demo★/ # {Cargo.toml, pack.toml, schema/001_init.sql, src/lib.rs}
|
||
│ ├── shop★/ books★/ asset★/
|
||
├── src/
|
||
│ ├── backend/ # 示例应用(薄壳)
|
||
│ │ ├── src/main.rs # 解析 --enc/--help + 交给 sspf::Platform 装配
|
||
│ │ ├── src/lib.rs # pub mod modules; pub mod packs_gen;
|
||
│ │ ├── src/packs_gen.rs # 业务包清单(装载 packs/*)—— 生成物,别手改
|
||
│ │ └── src/modules/ # 【面 A 适配器】{mod,demo★,shop★,books★,asset★}.rs
|
||
│ └── frontend/ # React + Vite(含已打好的 dist/,后端直接托管)
|
||
├── references/ # BaseCrudController.java(**非** JNPF 官方类)+ README
|
||
├── template-boot-jnpf/ # JNPF 标准栈最小可运行骨架(Java)
|
||
└── docs/ # 契约真源 / 运维 / 裁决 / DDL
|
||
├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型 / 附录 A 机器段
|
||
├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障
|
||
├── decisions.md # 实施期逐条裁决
|
||
├── known-limitations.md # 分支级已知限制
|
||
└── ddl/ # 官方 DDL 摘录(说明实物,不参与运行)
|
||
```
|
||
|
||
★ = 业务模块模板(`HOWTO_MODULE.md` 参照实现)。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 一次性:装依赖(cargo fetch + npm install)
|
||
bash run.sh install
|
||
# 构建(cargo build --release + vite build)
|
||
bash run.sh build
|
||
|
||
# 日常:后台起后端(30010) + 前端(5173),日志在 .logs/,PID 在 .run/
|
||
bash run.sh dev
|
||
# 前端 http://127.0.0.1:5173 后端 http://127.0.0.1:30010
|
||
# 账号 admin / 123456
|
||
# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
|
||
|
||
bash run.sh stop # 停(幂等)
|
||
bash run.sh logs # 看日志尾部
|
||
```
|
||
|
||
| 端口 | 谁 | 说明 |
|
||
|---|---|---|
|
||
| `30010` | 后端(Rust) | **硬约定**:`run.sh` 的端口不许改 —— `PORT` ≠ 30010 时 `run.sh dev` / `run.sh backend` 报错退出 2(要换端口请**直接跑二进制**)。**后端二进制本身**吃 `PORT`(非法值回落 30010)。默认**只监听 `127.0.0.1`**;`BIND_ADDR=0.0.0.0` 才对外暴露 |
|
||
| `5173` | 前端(vite dev) | `strictPort: true` ⇒ 端口被占直接报错,不自动换端口 |
|
||
|
||
> ⚠️ 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。
|
||
|
||
## 把脚手架复制到新项目
|
||
|
||
```bash
|
||
SKILL=~/.agents/skills/ssw-jnpf-lite-rust # 软链 ⇒ 实际指向本仓
|
||
PROJ=~/Desktop/my-app
|
||
mkdir -p "$PROJ"
|
||
rsync -a --exclude node_modules --exclude target --exclude data --exclude .DS_Store \
|
||
"$SKILL"/src "$SKILL"/packs "$SKILL"/scripts "$SKILL"/run.sh \
|
||
"$SKILL"/Cargo.toml "$SKILL"/.env.example "$SKILL"/.gitignore "$PROJ"/
|
||
cd "$PROJ" && cp .env.example .env && ./run.sh install && ./run.sh dev
|
||
```
|
||
|
||
> ⚠️ **只复制脚手架本体**——`*.md` / `references/` / `template-boot-jnpf/` / `docs/` 是技能资产,
|
||
> 留在技能目录只读引用。全量 `cp -R` 会让项目目录混满技能噪音,日后技能升级也灌不进项目。
|
||
> 🔴 **`packs/` 必须一起复制**:业务真源在包里 ⇒ 少了它应用能起但**面 A 全 404**。
|
||
> 🔴 **`Cargo.toml`(workspace 根)别漏**:`members` / `workspace.package` 继承都在里面;
|
||
> 外部依赖(sspf/axum/…)由 `.cargo/config.toml` 的 `--extern` 从平台包 `lib/` 喂入,
|
||
> 缺了 config 编译不起来(先跑 `scripts/fetch-platform.sh` 生成)。
|
||
|
||
## 验收门
|
||
|
||
一条命令:`bash scripts/verify.sh`(全量 7 步)/ `--fast`(静态 + 测试 4 步)。
|
||
|
||
| 门 | 命令 | 通过标准 |
|
||
|---|---|---|
|
||
| ① 生成物 | `python3 scripts/pack-sync.py --check` | 无漂移(4 个包 / 4 个模块) |
|
||
| ② 只准有业务 | `python3 scripts/check-scaffold.py` | **SC1–SC6 全绿**;`--self-test` **6/6**(每条判据都能被证伪) |
|
||
| ③ 编译 + 单测 | `cargo build --release` + `cargo test --workspace` | 0 error;测试全绿 |
|
||
| ④ 运行时尺子·面 A | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(🔴 后端不用先起:`:30010` 不通 ⇒ 自起隔离实例,跑完即删) |
|
||
| ⑤ 运行时尺子·面 B | `bash scripts/perm-smoke-jnpf.sh` | **PASS=18 FAIL=0 SKIP=0**(结尾打印「面 B 覆盖 18/18」) |
|
||
| ⑥ 前端手验 | `bash run.sh dev` | `http://127.0.0.1:5173` → `admin/123456` → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 |
|
||
|
||
🔴 **期望值只有一处**:`docs/contract.md` **附录 A**(`[MENU]` / `[MENU_TREE]` / `[MODULE]` /
|
||
`[ENDPOINT]` / `[FACE]` / `[RULER]`),由 `scripts/contract_expect.py` 解析 ⇒ 改契约只改一处;
|
||
每把运行时尺子还**自证**自己的条数(被人改弱了 ⇒ 失败)。
|
||
|
||
🔴 **旧的「六道闸门」已退役**(`check-module` / `check-boundary` / `check-contract` / `check-citations`):
|
||
它们测的是**本仓那份平台实现**,平台搬走后没有测量对象 —— 留着就是假绿。
|
||
新的判据只有「本仓只准有业务」(`check-scaffold.py`)与「业务真的能跑」(`cargo test` + 两把尺子)。
|
||
|
||
## 数据库:进程内原生 PostgreSQL
|
||
|
||
**pglite-rs 0.2** —— 把 `postgres-pglite` 编译成**原生静态库**链进二进制 ⇒ 进程内单 backend,
|
||
**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议)。
|
||
|
||
- 🔴 **不是**浏览器 WASM 版 PGlite(`@electric-sql/pglite`)——那个禁止引入。
|
||
- 数据落盘 `src/backend/data/lite.pg`。
|
||
- 🔴 **一个数据目录只能被一个进程打开** ⇒ 集成测试要么串行、要么各自独立数据目录。
|
||
- 🔴 `PGLITE_DIR=memory://` = 系统临时目录里的一次性数据目录(进程退出即销毁),**不是**真内存模式。
|
||
- 🔴 **无 TCP 监听** ⇒ `psql` / `pg_dump` **连不上** ⇒ 数据导出要走应用内的 `COPY ... TO STDOUT`(见 `MIGRATION.md` §6)。
|
||
|
||
## 已知限制(被接受 / 挂起)
|
||
|
||
| 限制 | 说明 |
|
||
|---|---|
|
||
| **面 B 仍有 10 条偏差** | 面 B 已落地(实现在 `sspf` 包内,本仓尺子 **18/18 全绿**),但 `AuthorizeDataReturnVO.list` 返空数组 · `sysConfigInfo` 返 `{}` · 无按钮/列/表单/数据级权限 · 业务菜单 `f_en_code` 是自拟占位 · `permissionList` 粒度 = 每菜单一条 · `Organize/AsyncList` 未分页 —— 逐条见 `JNPF_COMPAT_SURFACE.md` §8(B1–B10) |
|
||
| 不分页(**面 A**) | 面 A 契约里的 `List` 就是全量(前端不分页);要分页是 JNPF 稳定期的 `SuperServiceImpl.page`(**面 B 已是分页信封**) |
|
||
| 不做按钮/列/表单/数据范围级授权 | 官方 DDL 里有 `base_module_button` / `_column` / `_form` / `_data`,v1 只做 `item_type='module'` |
|
||
| 不做多租户 | 单租户固定 `f_tenant_id='0'` |
|
||
| 无 Redis / Sa-Token | 内存 token 表即可(进程重启即失效,与 JNPF 的 Sa-Token 内存模式同代) |
|
||
| 口令存储**缺 `secretkey` 一步** | 本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`;迁官方时**一次性换算**,**不需要明文**(`MIGRATION.md` §7) |
|
||
| `f_account` 无 UNIQUE | 官方 DDL 就是没有 ⇒ 唯一性**应用层**保证(只比 `delete_mark=0` 的行) |
|
||
| **两套权限判据并存** | 面 A 按**菜单路径**(`f_url_address`)、面 B 按**点权限**(`f_en_code`)⇒ 同一用户可能**面 A 通、面 B 拒**(设计,不是 bug) |
|
||
| 低代码引擎不碰 | 表单 / 流程 / 代码生成是官方能力 |
|
||
| token 寿命 = 进程寿命 | `session.rs` 是内存 token 表、无 TTL;`expiresIn:7200` 是契约字面量、**不强制执行** |
|
||
|
||
## 三个参照物(各司其职,别混)
|
||
|
||
| 参照物 | 地位 |
|
||
|---|---|
|
||
| 官方 JNPF 源码 + DDL(`~/Desktop/workspace/jnpf/`) | **数据模型真源**(`base_*` 表名/列名) |
|
||
| `ssw-jnpf-lite-react` 技能(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/`) | **行为真源**(NestJS 版把契约跑起来了);本仓前端是它的**逐字复制** |
|
||
| `tdc-rs` 兄弟项目(`~/Desktop/workspace/tdc-rs/`) | **只抄工程手法**;不共享代码 / 端口 / 数据目录 |
|
||
|
||
## 与 react 版的关系
|
||
|
||
| | react 版 | rust 版 |
|
||
|---|---|---|
|
||
| 后端栈 | NestJS | axum |
|
||
| 端口 | **30000** | **30010** |
|
||
| 契约 | 同一套(面 A) | 同一套(面 A) |
|
||
| 前端 | 同一份 React 产物 | 同一份 React 产物 |
|
||
| 业务表名 | `demo_item` / `shop_product` / `book_shop_book` | **同名** ⇒ 两版后端能开同一个库 |
|
||
| 尺子 | `perm-smoke.sh`(22 条基线) | `perm-smoke.sh`(32 条)+ `perm-smoke-jnpf.sh`(18 条) |
|
||
|
||
🔴 **两版之间不共享代码、不共享端口、不共享数据目录**。
|
||
迁移走「换栈」路径:契约不变 ⇒ **前端零改**,只换后端进程。
|
||
详见 [`MIGRATION.md`](MIGRATION.md) §5。
|
||
|
||
## 技术栈
|
||
|
||
Rust 2021 · axum 0.8 · tokio · pglite-rs 0.2(进程内原生 PostgreSQL,零服务/零 Docker/零 WASM)·
|
||
aes 0.8 + ecb 0.1 + md-5 0.10 · React 18 + Vite 5(逐字复用)
|