Files
ssw-jnpf-lite-rust/README.md
T
adminandClaude 7c4ae39664 refactor(skill): 仓根即技能本体 —— 技能资产进版本控制 + 三处软链指向同一仓
影响:此前技能资产(SKILL.md / HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md /
JNPF_SOURCE_AUDIT.md / JNPF_COMPAT_SURFACE.md / references/ / template-boot-jnpf/)
实体住在 ~/.agents/skills/ssw-jnpf-lite-rust/(仓外、不在 git)⇒ 改仓不生效、实体与仓漂移。
现在仓根 = 技能根(对齐 ssw-jnpf-lite-react 的形态),~/.agents · ~/.claude · ~/.workbuddy
(+ ~/.qwenworkcn)四处软链全部解析到同一个仓 ⇒ 改一次仓 = 改一次技能。

改动:
- 新增根级技能文档 6 份:SKILL.md(并补 frontmatter:name/description/type,原文件没有 frontmatter
  只靠目录名兜底)/ HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md / JNPF_SOURCE_AUDIT.md /
  JNPF_COMPAT_SURFACE.md;references/ 与 template-boot-jnpf/ 一并入仓
- 根 README.md 改为技能版(选型/运行/验收门/已知限制),旧项目版 README 移入 docs/README-project.md
- docs/ 下 3 份与根级同源的文档删除(技能版取代),全仓链接改指根级(已修全部相对链接,无坏链)
- docs/ 保留契约真源 contract.md / runbook.md / decisions.md / known-limitations.md / ddl/
- Cargo.toml 取「技能版注释 + 仓版补充」合并;run.sh 用仓版(多旧名兜底 pkill)
- SKILL.md 补 frontmatter + 「技能目录 = 仓根」说明;CLAUDE.md 目录速览同步;HANDOFF.md 技能资产
  描述同步;工作日志补第三段

验证:cargo build --release 0 error · cargo test 195 passed/0 failed · check-module.sh PASS=57
FAIL=0 · 面 A 尺子 PASS=32 FAIL=0 · 面 B 尺子 PASS=18 FAIL=0 SKIP=0(覆盖 18/18)

Co-Authored-By: Claude <[email protected]>
2026-10-26 16:56:58 +08:00

13 KiB
Raw Blame History

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          # 加一个业务模块的操作手册(9 个接触点)
├── 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 条)★ 本技能独有
│   └── check-module.sh      # 业务模块 9 接触点静态自检
├── src/
│   ├── backend/             # Rust 后端(6372 行 src + 4758 行 tests)
│   │   ├── src/{main,config,db,cipher,envelope,ids,session,state}.rs
│   │   ├── src/{auth,permission,seed,sys,crud,entities,routes,lib}.rs
│   │   ├── db/schema.sql    # 10 张表(base_* 7 + 业务 3)
│   │   └── tests/           # 6 个集成测试文件
│   └── 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         # 实施期逐条裁决(88 条「什么—为什么—代价」)
    ├── 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 全绿(当前 195 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(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。

数据库:进程内原生 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/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(逐字复用)