admin c55d111e88 feat(mcp): 参考 dacli 扩面到 49 个业务工具
- 新增 workflow×7 / form.create|update|delete / ops×4 / dict×3 / menu×2 / permission×3 / context.app.list
- 实现方式:mcp_compat 进程内直调契约面 handler(与 HTTP 同一函数),不重写 SQL
- 自动把 formData 等对象字段序列化为 TEXT,避免 value_to_text 静默丢弃
- 管理员头缓存按 SessionStore 实例缓存并设上界(防地址复用 602 与无界内存)
- 新增 tests/mcp_tools_it.rs 6 条;全量 667 passed,verify.sh --smoke 14 步全绿
2026-11-02 23:46:17 +08:00

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 §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。

选型决策: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 参照实现)。

快速开始

# 一次性:装依赖(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 '*'。

把脚手架复制到新项目

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 §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(逐字复用)

S
Description
尚数网平台(JNPF 7.0 兼容)Rust 后端
Readme
3.9 MiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 85.1%
Shell 7.9%
Python 5.9%
TypeScript 1%