admin d8a8165dd7 fix(skill): 自检/文档同步到方案 C(SC3/SC4/SC5 + rustdocflags + description)
- check-scaffold.py: 三条判据从旧模型(sspf 必须声明为 Cargo 依赖)改为方案 C:
  SC3 应用不声明平台/框架件;SC4 业务包不声明外部依赖;
  SC5 Cargo.toml 不出现 sspf(平台由 .cargo/config.toml 的 --extern 提供)。
  _base_tree 与 VIOLATIONS 同步,反自证仍 6/6。
- fetch-platform.sh: 生成的 .cargo/config.toml 同时写 rustdocflags
  (cargo test 的 doctest 走 rustdoc,不吃 build.rustflags,之前 E0432)。
- SKILL.md frontmatter description 改为「预编译 rlib / Gitea Release 按 tag+平台取包 / 零重编」。
- Cargo.toml 头部、HOWTO_MODULE、docs/runbook、new-pack/pack-sync 注释同步。

验证:verify.sh 全量 7/7(静态 3 步 + cargo test + release 构建 + 面 A/面 B 各 18 断言)。
2026-11-05 13:54:52 +08:00

ssw-jnpf-lite-rust · Rust 全栈 MVP

平台来自 sspf 发布包(vendor/sspf-v0.5.0/ 由平台仓 scripts/release.sh 产出、本仓 scripts/fetch-platform.sh 解包,不再直接依赖 git 仓),本仓只有 业务样板(packs/)+ 面 A 适配器 + 薄装配 + 前端产物 + 两把运行时尺子。 数据库仍是进程内原生 PostgreSQL(由平台包提供),除 Node 外无需装任何东西。

🔴 2026-11-04 → 2026-11-05 架构变更:以前本仓自带一份平台实现(src/backend/src/platform/ + routes.rs,约 4000 行), 那是「示例仓里躺着一份会分叉的平台」。2026-11-04 平台搬进 sspf 一处演进,本仓锁 git tag; 2026-11-05 最终改为方案 C:预编译 rlib,零重编平台(平台仓 scripts/release.sh 0.5.1 --publish 打 dist/sspf-vX.Y.Z-<target>.tar.gz 并推到 Gitea Release,内含 lib/ 预编译 rlib 完整闭包; 本仓 scripts/fetch-platform.sh 按 tag + 目标平台 从 Gitea Release 拉取(本地 dist/ 可离线回退), 解包到 vendor/sspf-vX.Y.Z/ 并生成 .cargo/config.toml,用 --extern + -L dependency 直喂 rustc)。 不 clone monorepo、零重编平台 17 crate 与 axum/tokio——实测 cargo build 5.7s / --release 11s。 升级平台 = bash scripts/fetch-platform.sh <新版本>。Cargo.toml 不声明外部依赖; release profile 必须 lto = false(预编译 rlib 无 bitcode,开 LTO 会失败)。 判据:python3 scripts/check-scaffold.py(本仓出现 platform/ / routes.rs / crates/ 立刻红)。

来自 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          # 加一个业务模块的操作手册
├── 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               # workspace 根:方案 C **不声明外部依赖**;rlib 由 .cargo/config.toml 的 --extern 喂入
├── .env.example             # PORT / BIND_ADDR / PGLITE_DIR
├── scripts/
│   ├── verify.sh            # 一键验收(静态 + 全量测试 + 两把运行时尺子)
│   ├── check-scaffold.py    # 静态判据 SC1–SC6「本仓只准有业务」+ --self-test 6/6
│   ├── pack-sync.py         # 从 packs/* + modules/* 生成四处派生位置;--check 防漂移
│   ├── new-pack.sh          # 造包:packs/<app>/ + modules/<app>.rs + 跑生成
│   ├── perm-smoke.sh        # 运行时尺子·面 A(32 条)
│   ├── perm-smoke-jnpf.sh   # 运行时尺子·面 B(18 条)★ 本技能独有
│   ├── smoke_backend.sh     # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑)
│   ├── contract_expect.py   # 读 docs/contract.md 附录 A(机器可读期望值)—— 尺子的唯一期望源
│   ├── reap-ipc-leaks.sh    # macOS SysV 信号量泄漏回收(PGlite 专用)
│   └── ipc-reap.c           # 上面那个的 C 实现
├── packs/                   # 【业务真源】整目录可搬;每个包只依赖 sspf 门面
│   ├── demo★/               # {Cargo.toml, pack.toml, schema/001_init.sql, src/lib.rs}
│   ├── shop★/ books★/ asset★/
├── src/
│   ├── backend/             # 示例应用(薄壳)
│   │   ├── src/main.rs      # 解析 --enc/--help + 交给 sspf::Platform 装配
│   │   ├── src/lib.rs       # pub mod modules; pub mod packs_gen;
│   │   ├── src/packs_gen.rs # 业务包清单(装载 packs/*)—— 生成物,别手改
│   │   └── src/modules/     # 【面 A 适配器】{mod,demo★,shop★,books★,asset★}.rs
│   └── frontend/            # React + Vite(含已打好的 dist/,后端直接托管)
├── references/              # BaseCrudController.java(**非** JNPF 官方类)+ README
├── template-boot-jnpf/      # JNPF 标准栈最小可运行骨架(Java)
└── docs/                    # 契约真源 / 运维 / 裁决 / DDL
    ├── contract.md          # 【契约唯一真源】端点 / 返回形状 / 数据模型 / 附录 A 机器段
    ├── runbook.md           # 怎么起 / 怎么冒烟 / 常见故障
    ├── decisions.md         # 实施期逐条裁决
    ├── 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"
rsync -a --exclude node_modules --exclude target --exclude data --exclude .DS_Store \
  "$SKILL"/src "$SKILL"/packs "$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/ / docs/ 是技能资产, 留在技能目录只读引用。全量 cp -R 会让项目目录混满技能噪音,日后技能升级也灌不进项目。 🔴 packs/ 必须一起复制:业务真源在包里 ⇒ 少了它应用能起但面 A 全 404。 🔴 Cargo.toml(workspace 根)别漏:members / workspace.package 继承都在里面; 外部依赖(sspf/axum/…)由 .cargo/config.toml 的 --extern 从平台包 lib/ 喂入, 缺了 config 编译不起来(先跑 scripts/fetch-platform.sh 生成)。

验收门

一条命令:bash scripts/verify.sh(全量 7 步)/ --fast(静态 + 测试 4 步)。

门 命令 通过标准
① 生成物 python3 scripts/pack-sync.py --check 无漂移(4 个包 / 4 个模块)
② 只准有业务 python3 scripts/check-scaffold.py SC1–SC6 全绿;--self-test 6/6(每条判据都能被证伪)
③ 编译 + 单测 cargo build --release + cargo test --workspace 0 error;测试全绿
④ 运行时尺子·面 A bash scripts/perm-smoke.sh PASS=32 FAIL=0(🔴 后端不用先起::30010 不通 ⇒ 自起隔离实例,跑完即删)
⑤ 运行时尺子·面 B bash scripts/perm-smoke-jnpf.sh PASS=18 FAIL=0 SKIP=0(结尾打印「面 B 覆盖 18/18」)
⑥ 前端手验 bash run.sh dev http://127.0.0.1:5173 → admin/123456 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用

🔴 期望值只有一处:docs/contract.md 附录 A([MENU] / [MENU_TREE] / [MODULE] / [ENDPOINT] / [FACE] / [RULER]),由 scripts/contract_expect.py 解析 ⇒ 改契约只改一处; 每把运行时尺子还自证自己的条数(被人改弱了 ⇒ 失败)。

🔴 旧的「六道闸门」已退役(check-module / check-boundary / check-contract / check-citations): 它们测的是本仓那份平台实现,平台搬走后没有测量对象 —— 留着就是假绿。 新的判据只有「本仓只准有业务」(check-scaffold.py)与「业务真的能跑」(cargo test + 两把尺子)。

数据库:进程内原生 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 已落地(实现在 sspf 包内,本仓尺子 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 兼容契约的 Rust 实现(单二进制、零外部服务,进程内原生 PostgreSQL)
Readme
834 KiB
0 Stars 1 Watchers 0 Forks
Languages
Shell 31.1%
Rust 25.7%
Python 18.5%
TypeScript 15.3%
Java 7.6%
Other 1.8%