Files
ssw-jnpf-lite-rust/README.md
T
admin f8d2cf4cf5 feat(dep): 技能改纯 rlib 消费 —— fetch 只解 lib/,不再解包平台源码
- 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)。
2026-11-05 12:50:46 +08:00

231 lines
16 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.
# 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(逐字复用)