契约面(面 B):从 487 涨到 588 条,官方端点覆盖 474/580 -> 574/580。 实现 - platform/compat/online_dev.rs:表单设计 / 门户 / 短链 / 在线数据 / 个人化 / 日志 / 分享 / OCR / 行政区划 / 仪表盘 共 78 条 - platform/compat/report.rs:在线报表 23 条(模板 / 版本 / 菜单) - 报表元数据就地落库(report_template + report_version,官方 DDL 逐字导入): 官方 /api/Report/* 属独立部署的第三方报表服务,主后端无对应 Controller 契约与尺子 - 新增 scripts/gen-contract-endpoints.py:从代码真实路由自动生成 [ENDPOINT] 与 [OFFICIAL] 两段(守卫复用扫描器同一套推导,幂等、不覆盖已登记条目) - check-contract-scan.py 修复守卫推导:三段路径解析、compat 文件纳入 plat_files、 跨文件常量回落、「无守卫」判据(原先 compat 模块守卫全部推不出,CC6 静默失效) - docs/contract.md 三处同步:+101 条端点、+101 条官方台账、面 B 计数 457 -> 558 修复的真 bug(集成测试抓到,静态闸门看不出来) - 3 处 SQL 引用官方 DDL 里不存在的列:base_visual_release.f_platform_release、 base_system.f_app_key/f_app_name、base_notice.f_full_name(官方是 f_title) - 3 处官方契约形状偏差:getReleaseMenu 返裸对象(非 ListVO)、 systemFilter 按官方 SystemListVO 投影(且官方忽略 category 入参)、 Dashboard/Notice 返 ListVO 且入参 typeList 是数组 - visual_dev_list 计数 SQL 参数个数与 $N 不匹配;visual_dev_update 漏写 f_last_modify_user_id;report_save_version 模板 id 兼容 id 且返 data:null 测试 - 新增 tests/batch17_it.rs:11 个集成测试(含 101 条端点逐条打一遍防 matchit 参数名冲突) 数字:check-contract PASS=10 FAIL=0;cargo test --workspace 全绿 0 failed; fe-gap 541/900(onlineDev 100/101、permission 137/137、system 196/196)
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(逐字复用)