- docs/JNPF_SOURCE_AUDIT.md:官方 Java/Vue 源码逐行核对(标 文件:行号), 差异清单 D1–D8(端点风格 / 列表响应 / CurrentUser 形状 / 码表 / 菜单接口 / 鉴权模型 / 请求头 / 口令存储)。 - docs/JNPF_COMPAT_SURFACE.md:面 B 规格 —— 官方形状的端点 / 响应 / 码表 / 分流规则 / 落地顺序 S1–S6。 - docs/MIGRATION.md:本仓 ↔ 官方逐项映射 + 数据 ETL + 口令 secretkey 换算 (一次性换算即可,不需要明文)。 - scripts/perm-smoke-jnpf.sh:第二把尺子,18 条官方形状断言;未落地记 SKIP 且不计入 PASS(当前 PASS=5 FAIL=0 SKIP=13 ⇒ 覆盖 5/18)。 fix(spec): 面 A/面 B 判别头纠错 —— 改用 `Vue-Version: 3` 规格初稿断言「本仓前端一个官方头都不带」并用 `Jnpf-Origin: pc` 判面, 但本仓前端 request.ts:35-36 **也发** App-Code 与 Jnpf-Origin(与官方同款) ⇒ 按字面实现会把每个面 A 请求都误判成面 B。三个官方头里只有 Vue-Version 是本仓前端唯一不发的 ⇒ 判别只能用它。已在规格(§2.2 / D7 / A13 / §3.7) 统一改正,并在 check-module.sh 的「全局红线」段静态钉住两侧: 本仓前端禁发该头 + 面 B 尺子必带该头。 docs: 导航文档补链 + 已知限制新增 §H CLAUDE.md 红线加第 9 条(判别头)、README.md 目录与「第二把尺子」、 HANDOFF.md §0/§6/§9(已知限制 + 下一步 S1–S6)、known-limitations.md §H (面 B 只有规格没有实现 / 缺 secretkey 一步 / 判据是菜单路径不是点权限 / 码表缺 602)。 验证:cargo test 179 passed / 0 failed;check-module.sh PASS=57 FAIL=0; perm-smoke.sh(面 A)PASS=32 FAIL=0;perm-smoke-jnpf.sh PASS=5 SKIP=13。 Co-Authored-By: Claude Code <[email protected]>
8.7 KiB
tds-lite-rs
JNPF 兼容契约的 Rust 实现 —— 单二进制、零外部服务(进程内原生 PostgreSQL)。
它的存在意义只有一条:让「用 Rust 写业务」和「迁回官方 JNPF(Java)」之间是机械翻译,而不是重写。
为此本仓的数据模型(base_* 表名/列名/语义)与 HTTP 契约从第一天起就锁死成官方 JNPF 的形状。
- 📘 契约唯一真源:
docs/contract.md—— 与本文件冲突时以契约为准。 - 🧭 agent 指引:
CLAUDE.md(红线 / 踩坑 / 端点全表)·HANDOFF.md(交接)。 - 🛠 怎么起 / 怎么冒烟 / 常见故障:
docs/runbook.md。 - 🧾 实施期裁决(88 条「什么—为什么—代价」):
docs/decisions.md· 分支级已知限制:docs/known-limitations.md。
快速开始
# 一次性:装依赖(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 ⇒ 端口被占直接报错,不自动换端口 |
目录
tds-lite-rs/
├── 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 张表,27 条路由)
├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)
├── scripts/perm-smoke-jnpf.sh # 官方 JNPF 形状冒烟(18 条断言;面 B 未落地 ⇒ 诚实记 SKIP,不算 PASS)
├── 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)
- 业务失败一律 HTTP 200 +
{code,msg,data};成败只看 body 的code。 唯一例外:未知路由 = HTTP 404(body 仍是信封)。鉴权失败也是 200(600未登录 /403无菜单权限)。 base_*表名/列名逐字对齐官方 JNPF DDL(含两个「故意不修正」的陷阱,见CLAUDE.md)。- numeric 列必须是 JSON 字符串(
"9.90",不是9.9);int 列保持数字。 - 口令不得外泄:库里存
md5(明文),对外响应手工挑字段(用户列表去掉password)。 - schema DDL 绝不可从 HTTP 下载。
验收门
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | cargo build --release |
0 error 0 warning |
| ② 单测 | cargo test |
全绿(当前 179 passed / 0 failed) |
| ③ 冒烟 | bash scripts/perm-smoke.sh |
PASS=32 FAIL=0(需后端已起在 :30010) |
| ④ 前端手验 | 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 scripts/perm-smoke-jnpf.sh # 18 条断言,打印「面 B 覆盖 N/18」
面 B = 官方 JNPF 契约面(官方形状的端点 / 响应 / 码表),规格见 docs/JNPF_COMPAT_SURFACE.md。
🔴 代码尚未实现 ⇒ 该尺子目前报 PASS=5 FAIL=0 SKIP=13(未落地记 SKIP,不算 PASS)——
它是一把诚实量进度的尺子,不是「假装全过」的开关。
面 B 的判别头是 Vue-Version: 3(官方前端必发,本仓前端唯一不发的一头 ⇒ 零歧义)。
本机 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(官方 JNPF 契约面)只有规格、没有实现:端点 / 响应形状 / 码表见
docs/JNPF_COMPAT_SURFACE.md, 落地顺序 S1–S6 见其 §7;scripts/perm-smoke-jnpf.sh目前报覆盖 5/18(其余记 SKIP)。 ⇒ 官方 JNPF 前端目前还跑不进本仓(CurrentUser形状、列表分页、602码都还没做)。 -
口令存储缺官方
secretkey一步:本仓存md5(明文),官方存md5(md5(明文)+secretkey)。 迁官方时一次性换算即可,不需要明文(见docs/MIGRATION.md§7)。 -
权限判据是菜单路径,不是官方的点权限(官方取
base_module.f_en_code;本仓种子菜单没有f_en_code)。 ⇒ 迁官方前必须补f_en_code(docs/MIGRATION.md§2.4)。 -
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 同款行为,契约未要求清理)。 -
冒烟脚本在「重复账号 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(逐字复用)