- 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/:前端接口清单、页面依赖反查、运行时探针
153 lines
10 KiB
Markdown
153 lines
10 KiB
Markdown
# ssw-jnpf-lite-rust
|
||
|
||
**JNPF 兼容契约的 Rust 实现** —— 单二进制、零外部服务(进程内原生 PostgreSQL)。
|
||
|
||
它的存在意义只有一条:**让「用 Rust 写业务」和「迁回官方 JNPF(Java)」之间是机械翻译,而不是重写。**
|
||
为此本仓的**数据模型(`base_*` 表名/列名/语义)与 HTTP 契约**从第一天起就锁死成官方 JNPF 的形状。
|
||
|
||
本仓是**双面后端**:**同一进程**同时提供
|
||
**面 A**(ssw/react 契约,27 条路由,冻结)与 **面 B**(官方 JNPF 契约,5 条路由 + 2 条共用路由按 `Vue-Version: 3` 分流),
|
||
共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径 / 面 B 按 `f_en_code` 点权限)。
|
||
⇒ 既是「Rust ⇒ 官方 JNPF」的**可移植性验证床**,也是「官方 JNPF / React 版 ⇒ 打到本框架跑」的**对照靶场**。
|
||
|
||
- 📘 **契约唯一真源**:[`docs/contract.md`](contract.md) —— 与本文件冲突时以契约为准。
|
||
- 🧭 **agent 指引**:[`CLAUDE.md`](../CLAUDE.md)(红线 / 踩坑 / 端点全表)· [`HANDOFF.md`](../HANDOFF.md)(交接)。
|
||
- 🛠 **怎么起 / 怎么冒烟 / 常见故障**:[`docs/runbook.md`](runbook.md)。
|
||
- 🧾 **实施期裁决(98 条「什么—为什么—代价」)**:[`docs/decisions.md`](decisions.md)
|
||
· **分支级已知限制**:[`docs/known-limitations.md`](known-limitations.md)。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 一次性:装依赖(cargo fetch + npm install)+ 构建(cargo build --release + vite build)
|
||
bash run.sh install
|
||
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` ⇒ 端口被占直接报错,不自动换端口 |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
```
|
||
ssw-jnpf-lite-rust/
|
||
├── Cargo.toml # cargo workspace 根(成员 = src/backend)+ release profile
|
||
├── run.sh # install / build / dev / backend / frontend / stop / logs
|
||
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
|
||
├── src/backend/ # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,32 条路由 = 面 A 27 + 面 B 5)
|
||
├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
|
||
├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)—— 面 A 尺子
|
||
├── scripts/perm-smoke-jnpf.sh # 官方 JNPF 形状冒烟(18 条断言)—— 面 B 尺子(**已全绿 18/18**)
|
||
├── scripts/smoke_backend.sh # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑)
|
||
├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端)
|
||
└── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制)
|
||
# JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格)· MIGRATION.md(迁移指南)· ddl/
|
||
```
|
||
|
||
---
|
||
|
||
## 它做了什么(v1 = 全量契约对齐)
|
||
|
||
- **登录 / `CurrentUser`**:`POST /api/oauth/Login`(form-urlencoded,密文 hex)⇒ `{token, expiresIn:7200, tokenTypeName:'bearer'}`;
|
||
`GET /api/oauth/CurrentUser` ⇒ `{userInfo, menuList}`。
|
||
- **5 组 `base_*` 管理 CRUD**:用户 / 角色 / 机构 / 菜单 / 授权。
|
||
- **统一授权**:`PUT /api/permission/Authority/Data/{objectId}`(body `{objectType:'role', module:[...]}`,**小写 + 一维数组**)。
|
||
- **四源权限合并**:用户直授 + 角色 + 组织 + 岗位;**管理员在任何 SQL 之前短路放行**;**菜单未映射 ⇒ 放行**。
|
||
- **两段式种子**:`ensure_base`(每次启动补内置角色/菜单/授权)+ `first_seed`(仅首次建 `admin/123456`)。
|
||
- **3 个业务模块**(spec 驱动 CRUD 引擎):`demo/DemoItem` · `shop/Product` · `books/Book`。
|
||
|
||
### 契约红线(摘要,完整版见 `CLAUDE.md`)
|
||
|
||
1. **业务失败一律 HTTP 200 + `{code,msg,data}`**;成败只看 body 的 `code`。
|
||
唯一例外:**未知路由 = HTTP 404**(body 仍是信封)。鉴权失败也是 200(`600` 未登录 / `403` 无菜单权限)。
|
||
2. **`base_*` 表名/列名逐字对齐官方 JNPF DDL**(含两个「故意不修正」的陷阱,见 `CLAUDE.md`)。
|
||
3. **numeric 列必须是 JSON 字符串**(`"9.90"`,不是 `9.9`);int 列保持数字。
|
||
4. **口令不得外泄**:库里存 `md5(明文)`,对外响应手工挑字段(用户列表去掉 `password`)。
|
||
5. **schema DDL 绝不可从 HTTP 下载**。
|
||
|
||
---
|
||
|
||
## 验收门
|
||
|
||
| 门 | 命令 | 通过标准 |
|
||
|---|---|---|
|
||
| ① 编译 | `cargo build --release` | 0 error **0 warning** |
|
||
| ② 单测 | `cargo test` | 全绿(当前 **197 passed / 0 failed**) |
|
||
| ③ 冒烟 | `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`(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。
|
||
|
||
### 第二把尺子(面 B:官方 JNPF 形状)
|
||
|
||
```bash
|
||
bash scripts/perm-smoke-jnpf.sh # 18 条断言,打印「面 B 覆盖 N/18」
|
||
```
|
||
|
||
**面 B = 官方 JNPF 契约面**(官方形状的端点 / 响应 / 码表),规格见 `../JNPF_COMPAT_SURFACE.md`。
|
||
✅ **已落地**(`src/backend/src/platform/jnpf.rs`,S1–S6 全完成)⇒ 当前报 **`PASS=18 FAIL=0 SKIP=0`(面 B 覆盖 18/18)**。
|
||
面 B 的判别头是 **`Vue-Version: 3`**(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。
|
||
面 A 27 条路由**冻结**、面 B 5 条新增 ⇒ **同一进程**同时提供两套契约。
|
||
|
||
> 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。
|
||
|
||
---
|
||
|
||
## 三个参照物(各司其职,别混)
|
||
|
||
| 参照物 | 地位 |
|
||
|---|---|
|
||
| 官方 JNPF 源码 + DDL(`~/Desktop/workspace/jnpf/`) | **数据模型真源**(`base_*` 表名/列名) |
|
||
| `ssw-jnpf-lite-react` 技能(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/`) | **行为真源**(NestJS 版把契约跑起来了);本仓前端是它的**逐字复制** |
|
||
| `tdc-rs` 兄弟项目(`~/Desktop/workspace/tdc-rs/`) | **只抄工程手法**;不共享代码 / 端口 / 数据目录 |
|
||
|
||
---
|
||
|
||
## 已知限制(分支级)
|
||
|
||
- **面 B 的 10 条已知偏差**(B1–B10,逐条见 `../JNPF_COMPAT_SURFACE.md` §8 与 `docs/known-limitations.md` §H):
|
||
授权读 `list` 返空数组 · `sysConfigInfo` 返 `{}` · `currentSystemId` 固定 ·
|
||
**无按钮/列/表单/数据级权限** · 三个业务菜单的 `f_en_code` 是自拟占位 ·
|
||
`permissionList` 粒度 = 每菜单一条(`modelId` = 菜单 id)· `Organize/AsyncList` 未分页。
|
||
- **口令存储缺官方 `secretkey` 一步**:本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`。
|
||
迁官方时**一次性换算**即可,**不需要明文**(见 `../MIGRATION.md` §7)。
|
||
- **两套权限判据并存**:面 A 按菜单路径(`f_url_address`)、面 B 按点权限编码(`f_en_code`)。
|
||
⇒ 同一用户可能**面 A 通、面 B 拒**(这是设计,不是 bug);种子菜单已补 `f_en_code`(8 条),
|
||
业务菜单的 `f_en_code` 仍是自拟值,迁官方前须换成官方真实编码。
|
||
|
||
- **release 二进制没有 catch-all 的自动化覆盖**:触发 panic 的端点是 `#[cfg(test)]` 专属;
|
||
catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile **无** `panic = "abort"` ⇒ 行为等价。
|
||
- **`Path<String>` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz`
|
||
返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。
|
||
- **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
|
||
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
|
||
(进程不重启就永不过期);契约未覆盖 TTL ⇒ 不改。
|
||
- **冒烟脚本每次跑会往库里留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`(react 同款行为,契约未要求清理)。
|
||
🔴 **但只在「复用外部后端」时**:尺子**默认自起隔离实例**(临时数据目录)⇒ 跑完即删、**不留脏数据**、
|
||
两把尺子**互不污染**、**CI 可跑**;显式给了 `B` 才打外部库。
|
||
- 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
|
||
- 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同(退出码都是 2)。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
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(逐字复用)
|