Files
ssw-platform/README.md
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

222 lines
15 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
**自包含技能**:模板、契约实现、权限模版、冒烟脚本全部在技能目录内,**不依赖任何其它技能或外部服务**,
除 Node 外无需安装任何东西(数据库是**进程内原生 PostgreSQL**)。
来自 `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 # 加一个业务模块的操作手册(8 个文件 / 10 个接触点)
├── 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 # 🔴 cargo workspace 根(**复制脚手架时必须一起带走**)
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR
├── scripts/
│ ├── perm-smoke.sh # 契约尺子·面 A(32 条)
│ ├── perm-smoke-jnpf.sh # 契约尺子·面 B(18 条)★ 本技能独有
│ ├── smoke_backend.sh # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑)
│ ├── check-module.sh # 静态闸门 1:业务模块 10 接触点自检(93 条)
│ ├── check-boundary.sh # 静态闸门 2:分层红线 CP1–CP6 自检(11 条)
│ ├── check-boundary-scan.py # 分层闸门的扫描器(禁用词表由业务层反推 + 自测模式)
│ ├── check-contract.sh # 静态闸门 3:契约端点表 + 官方端点台账 ↔ 代码真实路由 对账(10 条)★ 本技能独有
│ ├── check-contract-scan.py # 上面那个的扫描器(Rust 源码静态解析 + 9 例反自证)
│ ├── check-citations.sh # 静态闸门 4:文档引文 `路径:行号` 逐条核对(4 条)★ 本技能独有
│ ├── check-citations-scan.py # 上面那个的扫描器(引文解析 + 3 例反自证)
│ ├── contract_expect.py # 读 docs/contract.md 附录 A(机器可读期望值)—— 尺子的唯一期望源
│ ├── reap-ipc-leaks.sh # macOS SysV 信号量泄漏回收(PGlite 专用)
│ └── ipc-reap.c # 上面那个的 C 实现
├── src/
│ ├── backend/ # Rust 后端
│ │ ├── src/{main,lib,routes,bootstrap}.rs # bootstrap = 装配根(唯一同时认识两层的地方)
│ │ ├── src/platform/ # 【平台层】{config,db,cipher,envelope,ids,session,state,auth,permission,seed,sys,jnpf,entity,crud,menu,guard}.rs
│ │ ├── src/modules/ # 【业务层】{mod,demo★,shop★,books★}.rs(各带 spec + handler + router + 菜单声明)
│ │ ├── db/schema.sql # 10 张表(base_* 7 + 业务 3)
│ │ └── tests/ # 7 个集成测试文件
│ └── frontend/ # React + Vite(1374 行)
│ ├── utils/cipher · api/{request,auth,sys,product,book}
│ └── views/{Login,Dashboard,DemoItem★,Product★,Book★,UserManage,RoleManage,OrganizeManage,MenuManage}
├── references/ # BaseCrudController.java(**非** JNPF 官方类)+ README
├── template-boot-jnpf/ # JNPF 标准栈最小可运行骨架(Java)
└── docs/ # 项目级文档(契约真源 / 运维 / 裁决 / DDL)
├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型
├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障
├── decisions.md # 实施期逐条裁决(98 条「什么—为什么—代价」)
├── 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/src" # 脚手架固定进 src/:没有则创建,已有则并入
rsync -a --exclude node_modules --exclude dist --exclude target --exclude data --exclude .DS_Store \
"$SKILL"/src "$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/` 是技能资产,留在技能目录只读引用。
> 全量 `cp -R` 会让项目目录混满技能噪音,日后技能升级也灌不进项目。
> 🔴 **`Cargo.toml`(workspace 根)别漏**:缺了它 `src/backend` 的 `workspace = true` 继承无处可依 ⇒ cargo 直接报
> `could not find Cargo.toml in ... or any parent directory`,**脚手架编译不起来**。
## 验收门
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error **0 warning** |
| ② 单测 | `cargo test` | 全绿(当前 **220 passed / 0 failed**) |
| ③ 冒烟(面 A) | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(🔴 **后端不用先起**:`:30010` 不通 ⇒ 尺子自起隔离实例,跑完即删) |
| ③' 冒烟(面 B) | `bash scripts/perm-smoke-jnpf.sh` | **PASS=18 FAIL=0 SKIP=0**(**已达标**;同样默认自起隔离实例) |
| ④ 前端手验 | `bash run.sh dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
外加四道**静态闸门**(纯静态,不起后端,加业务模块后立刻跑):
`bash scripts/check-module.sh`(10 接触点,93 条)+ `bash scripts/check-boundary.sh`(分层红线 CP1–CP6,11 条)
+ `bash scripts/check-contract.sh`(契约端点表 + 官方端点台账 ↔ 代码真实路由,10 条)
+ `bash scripts/check-citations.sh`(文档引文 `路径:行号`,4 条)。
🔴 **六把尺子的期望值只有一处**:`docs/contract.md` **附录 A**(机器可读),
由 `scripts/contract_expect.py` 解析 ⇒ 改契约只改一处;代码漂移尺子立刻报;
每把尺子还**自证**自己的条数(被人改弱了 ⇒ 失败)。
📊 **官方端点覆盖是一本「账」**:附录 A 的 `[OFFICIAL]` 区段(53 行)把官方 JNPF 契约面的
端点全表变成**机器可读**的覆盖账本(`implemented` / `partial` / `absent` / `oos` 四态)⇒
`check-contract.sh` 的 **CC10** 拿它与**代码真实路由双向对账**,并打印
**「官方端点覆盖 N/M」**(当前 **8/47**)—— **算出来的,不是人数的**;
台账的 `src` 列是官方出处 `文件:行号` ⇒ 由引文闸门**逐条核对**。
## 数据库:进程内原生 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 已落地(`src/backend/src/platform/jnpf.rs`,尺子 **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(逐字复用)