Files
adminandClaude Code 96594df72f feat(repo): 平台层/业务层分离收尾 + 六道闸门(把「尺子」变成机器)
**影响**
后端从「平台层里塞业务知识」改成「装配根 + 业务层自带 spec/菜单/路由」;闸门 5 道 → 6 道,
契约尺子 2 条 → 3 条;两把尺子**默认自起隔离后端** ⇒ 不用先起后端就能冒烟(CI 可跑)。
单测 220 passed / 0 failed;静态闸门 93 + 11 + 10 + 4 全绿;面 A 32/32、面 B 18/18 全绿。

**改动**
- 后端:新增 `platform/guard.rs`(生产档弱口令守卫六条判据 + 配置级/库内级两道检查)、
  `platform/menu.rs`(菜单 spec 的类型)、`bootstrap.rs`(装配根:唯一同时认识平台层与业务层的地方);
  业务模块的菜单与路由下沉到 `modules/<app>.rs`,平台层只 `merge(modules::router())` 一次。
- 闸门:新增 `check-boundary.sh`(分层红线 CP1–CP6)、`check-contract.sh`(契约端点表 + 官方端点台账
  ↔ 代码真实路由,CC2–CC10)、`check-citations.sh`(文档引文 `路径:行号` 逐条核对);
  `check-module.sh` 改为从契约期望值派生(63 → 93 条);三把尺子各带反自证用例。
- 契约:`docs/contract.md` 附录 A 扩成机器可读区段(`[ENDPOINT]` / `[FACE]` / `[OFFICIAL]` / `[RULER]` …)
  ⇒ 六把尺子的期望值只有一处;`[OFFICIAL]` 官方端点台账 53 行四态 ⇒ 覆盖 **8/47**(算出来的)。
- 尺子:`scripts/smoke_backend.sh` 让两把契约尺子默认自起隔离后端(显式给了 `B` ⇒ 不自起、不可达即退出码 2)。
- 文档:CLAUDE.md / SKILL.md / README.md / HANDOFF.md / HOWTO_MODULE.md / docs/* 同步到新结构与新闸门;
  裁决 96 → 98 条(P91 尺子自起设计、P92 官方端点覆盖账本)。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 11:33:25 +08:00

10 KiB
Raw Permalink Blame History

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 版 ⇒ 打到本框架跑」的对照靶场。


快速开始

# 一次性:装依赖(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 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(逐字复用)