- fetch-platform.sh: 解包加 --exclude=crates/src/frontend/Cargo.toml/Cargo.lock, 只留 lib/ + rust-toolchain.toml + bin/ + docs/README(vendor 少解 ~62M 源码) - 校验改为认 vendor/.../lib/libsspf-*.rlib,不再读 crates/sspf/Cargo.toml - 所有「dev 回退 path 到 vendor 源码」改为「极端回退用 git tag 依赖」 - 文档同步 SKILL/README/HANDOFF 验证: cargo clean 后 dev 5.14s / release 9.34s,只编本仓 5 crate; vendor 无任何平台源码;二进制 --help 正常(基于 sspf v0.5.0)。
20 KiB
name, description, type
| name | description | type |
|---|---|---|
| ssw-jnpf-lite-rust | Rust 全栈 MVP 脚手架(**平台来自 sspf 发布包,vendor/ 解包,不再依赖 git 仓**;本仓只有业务样板 + 薄装配 + 前端产物 + 尺子),契约与数据模型从第一天起对齐 JNPF 标准版(cipher / ActionResult / f_ 列 / varchar(50) UUID / base_* 权限表 / 进程内原生 PostgreSQL),前后端同一进程同时提供「面 A(ssw 契约 30 条)」与「面 B(官方 JNPF 形状 5 条 + 2 条共用按 Vue-Version 头分流)」两套契约。适用于「AI 开发 MVP 阶段要 Rust 全栈快速迭代、稳定后迁 JNPF 标准栈」的场景,含用户/角色/机构/菜单/授权五套管理页与四源合并菜单守卫。加业务模块见同目录 HOWTO_MODULE.md。 | skill |
ssw-jnpf-lite-rust
技能 = 业务样板 + 薄装配 + 前端产物 + 两把尺子;平台不在本仓。
平台(登录 / 权限 / 面 A·B / 低代码 / MCP / 177 张 base_* 表 / 进程内原生 PostgreSQL)
来自已发布的 sspf 包(平台仓每版本打出的自包含发布包,不是直接依赖 git 仓)。
🔴 这条是 2026-11-04 → 2026-11-05 的架构变更(最终形态 = 方案 C:预编译 rlib,零重编平台):
- 2026-11-04:平台从「本仓自带一份实现」搬进
sspf一处演进,本仓锁 git tag 依赖。- 2026-11-05 早:改为每版本出包(
dist/sspf-vX.Y.Z.tar.gz),解包到vendor/后用path依赖; 但仍会重编平台 17 个 crate。- 2026-11-05 最终(方案 C):平台包内含预编译 rlib 完整闭包
lib/(rlib + rmeta + proc-macro dylib + 原生 a,bitcode-free)。本仓bash scripts/fetch-platform.sh vX.Y.Z解包后生成.cargo/config.toml,用--extern sspf/axum/tokio/serde/serde_json/http/bytes
-L dependency=lib直接喂 rustc。本仓Cargo.toml不声明任何外部依赖 ([workspace.dependencies]为空),cargo build只编自己的 5 个 crate (实测 dev 5.7s / release 11s),平台与 axum 全部零重编。- 🔴 两个硬约束(踩过):① 消费方必须用平台那份 axum(自己编会 E0308 类型不匹配); ② 本仓 release profile 必须
lto = false(预编译 rlib 无 bitcode,开 LTO 会失败)。- 升级平台 =
bash scripts/fetch-platform.sh <新版本>(重解包 + 重生成 config + 锁工具链)。- 极端回退(要改平台源码):删
.cargo/config.toml,改用 git 依赖(sspf = { git = …, tag = "vX.Y.Z" })+ axum/tokio 回归 registry 依赖。判据:
python3 scripts/check-scaffold.py(本仓出现platform//routes.rs/crates/立刻红)。🔴 依赖前提:不再需要 Gitea 访问;只需跑一次
scripts/fetch-platform.sh(解包平台包), 之后cargo build零重编平台。
来自 ssw-jnpf-lite-react(NestJS + React)的 Rust 全栈 counterpart——两者是并列可选的独立技能,
不是依赖关系:要 MVP 期就用 Node 栈选 ssw-jnpf-lite-react,要 MVP 期用 Rust 栈选本技能。
本技能的真身:不是「一个 JNPF 后台」,而是一个可双向搬运的框架
(axum) (NestJS) (官方 JNPF 7.0)
三方共用同一套数据模型(base_* 表名/列名逐字对齐官方 DDL)与同一套密文算法,
所以「迁到 JNPF」「从 JNPF 迁回来」「从 react 版换到 Rust 版」都是近机械翻译,不是重写。
- Rust → 官方 JNPF ⇒ 见
MIGRATION.md(逐件翻译表 + import 速查 + 数据 ETL + 口令换算) - 官方 JNPF → Rust ⇒ 走**「面 B」:本仓按官方形状提供第二套端点,官方前端能直接跑在本仓上
(判别依据 = 官方必发、而本仓前端唯一不发**的
Vue-Version: 3请求头;见JNPF_COMPAT_SURFACE.md) - react 版 NestJS → Rust ⇒ 同一套契约 ⇒ 前端零改;两边能开同一个库(业务表名故意对齐)
开发主线:加一个业务模块
只读这两份就够开发:本文件(契约红线)+ HOWTO_MODULE.md(9 个接触点、逐文件改法、验证命令)。
⚠️ 技能是模板不是项目:起项目时只复制脚手架本体 (
src/(backend+frontend)+scripts/+run.sh+Cargo.toml+.env.example+.gitignore) 到目标项目——代码固定落在项目根的src/下(src/backend+src/frontend,项目没有src/就先创建),在副本里开发。 不要cp -R整个技能目录——*.md文档和references/、template-boot-jnpf/是技能资产, 留在技能目录只读引用即可;全量复制会让项目目录混满技能噪音、日后技能升级也灌不进项目。🔴
Cargo.toml(workspace 根)必须一起复制:src/backend/Cargo.toml用的是version.workspace = true/xxx = { workspace = true }⇒ 缺了上层 workspace 根, cargo 直接报could not find Cargo.toml in ... or any parent directory,脚手架根本编译不起来。
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
# 后端 :30010 + 前端 :5173 → 打开 http://127.0.0.1:5173 → admin / 123456
🔴
packs/必须一起复制:业务真源在包里,packs_gen.rs按包清单装载; 只复制src/会得到「能起、但没有业务端点」的空壳(面 A 全 404)。 🔴 复制过去后把Cargo.toml里的sspftag 换成你项目要锁的版本 —— 那是唯一的平台版本入口。
除 Node 外无外部依赖——数据库是 pglite-rs 0.2(把 postgres-pglite 编译成原生静态库链进二进制, 进程内单 backend,真实 PostgreSQL 语义;不是浏览器 WASM 版 PGlite)。数据落盘
src/backend/data/lite.pg。 🔴 一个数据目录只能被一个进程打开 ⇒ 别把两个项目的PGLITE_DIR指到同一处。 🔴PGLITE_DIR=memory://= 系统临时目录里的一次性数据目录(进程退出即销毁), 不是真内存模式(pglite-rs 0.2.7 没有)。
何时用
- MVP 阶段想用 Rust 全栈(性能好、部署单二进制、迭代快),同时要保证「稳定后能快速迁 JNPF 标准版」。
- 需要权限/用户/角色/菜单这套基础管理能力——这是迁移最硬的一块,本技能已把
base_*表结构与契约钉死。 - 要让官方 JNPF 前端跑在 Rust 后端上(面 B)⇒ 见
JNPF_COMPAT_SURFACE.md。 - 与
ssw-jnpf-lite-react的取舍:后者 MVP 期就在 Node 栈里写(迁移零摩擦、MVP 慢);本技能把「快」放在 MVP 期 (Rust 单二进制、编译期类型安全),把「换栈」推迟并锁死到有界范围。详见README.md的「选型决策」。
模板位置
本技能即脚手架本体——模板随技能目录一起分发,无需额外拉取。
🔴 技能目录 = 仓根(SKILL.md 在仓根,源码 src/、scripts/、references/、template-boot-jnpf/ 同在仓根),
三处软链 ~/.agents/skills/ssw-jnpf-lite-rust · ~/.claude/skills/ssw-jnpf-lite-rust · ~/.workbuddy/skills/ssw-jnpf-lite-rust
全部指向同一个仓 ⇒ 改一次仓 = 改一次技能,不存在「技能副本漂移」。
Cargo.toml workspace 根:【方案 C 不声明外部依赖】members = ["src/backend","packs/*"], exclude = ["vendor"]
.cargo/config.toml(不提交)由 fetch-platform.sh 生成:--extern 喂 vendor/…/lib 的预编译 rlib
src/backend/ 示例应用(薄壳,~500 行)
src/main.rs 解析 --enc/--help + 把「配置 + 包 + 面 A 路由 + 前端」交给
sspf::Platform::new().config().packs().router().static_dir().serve()
src/lib.rs 只有两行:pub mod modules; pub mod packs_gen;
src/packs_gen.rs 业务包清单(装载 packs/*)—— 生成物,别手改
src/modules/ 面 A 适配器(/api/ssw/{app}/{Entity}/…,前端在用)
{mod,demo★,shop★,books★,asset★}.rs ← 每个只做 spec 转发 + 3 个 handler
data/ pglite 数据目录(gitignored)
src/frontend/ React+Vite(:5173, proxy /api→30010) + 已打好的 dist/(后端直接托管)
packs/ 业务真源(每个包整目录可搬)
{demo★,shop★,books★,asset★}/ {Cargo.toml, pack.toml, schema/001_init.sql, src/lib.rs}
↑ 表 DDL + 列 + 菜单 + 面 B 路由都在这儿;只依赖 sspf 门面
scripts/ verify.sh 一键验收(静态 + 全量测试 + 两把运行时尺子)
check-scaffold.py 「本仓只准有业务」6 条判据 + --self-test 6/6
pack-sync.py 从 packs/* + modules/* 生成四处派生位置;--check 防漂移
new-pack.sh 造包(packs/<app>/ + modules/<app>.rs + 跑生成)
perm-smoke.sh 面 A 尺子(32 条)—— 测 ssw 契约
perm-smoke-jnpf.sh 面 B 尺子(18 条)—— 测官方 JNPF 形状 ★ 本技能独有
smoke_backend.sh 契约尺子的「隔离后端」自启动助手(被两把尺子 source)
contract_expect.py 读 docs/contract.md 附录 A(机器可读期望值)—— 尺子的唯一期望源
references/ BaseCrudController.java(**非** JNPF 官方类)+ README
template-boot-jnpf/ JNPF 标准栈最小可运行骨架(Java)—— 迁官方时直接拷
★ = 业务模块模板(HOWTO_MODULE.md 参照实现)。
🔴 平台层 / 业务层分离(对齐 react 版的 common+auth+sys / demo+shop+books,
以及官方 JNPF 的 jnpf-common+jnpf-system / jnpf-admin):
加一个业务模块只碰 src/modules/(新文件 + mod.rs 登记)⇒ 平台层不动。
契约红线(改业务必须守住,否则迁移退化成重写)
- 登录口令加密:
md5(plain)→AES-256-ECB-PKCS7(key =md5("EY8WePvjM5GGwQzn")的 32 个 ASCII 字节)→ hex。 检验向量:encryptPassword('123456')==d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b。 前后端cipher.ts/cipher.rs同一算法,与官方DesUtil逐字节一致。 🔴 key 必须是 32 个 ASCII 字节(不是 16 字节原始摘要) ⇒ AES-256,不是 AES-128。 - 统一返回
ActionResult{code,msg,data},成功200;业务失败也是 HTTP 200(看 body 的code)。 未知路由保留 HTTP 404(body 仍是信封形状)。 🔴 鉴权失败也是 HTTP 200:600未登录 /403无菜单权限。 - 端点命名
/api/ssw/{appCode}/{Entity}/{List|Save|Delete}(ssw 约定,非官方 visualdev 路径)。 官方前端要跑 ⇒ 走面 B 的官方形状路径,不要改面 A 的路径。 - 实体列
f_前缀;主键f_id VARCHAR(50)(36 位 UUID v4 装得下)。f_tenant_id / f_last_modify_* / f_delete_time / f_delete_user_id属SuperEntity可选增强层,非强制——MVP 不必补。 - 前端模型用去前缀名(
title非fTitle);JSON 键名 = 列名去 `f_ 前缀后 camelCase。 - numeric 列必须序列化成 JSON 字符串(
"9.90",不是9.9)⇒ 在 SQL 投影里就f_price::text AS price。int列(f_delete_mark/f_stock/f_is_administrator)保持数字。 - 权限表照官方
base_*抄,别自创;字段名有两个官方陷阱故意不修正:base_role_relation里用户 id 存在f_object_id(配f_object_type='user'),不是f_user_id;- 组织/岗位关系在另一张表
base_user_relation,那里才有f_user_id。
- 授权写接口
objectType必须小写'role',module传一维数组['m1','m2',…](半选节点合进同一数组,对齐官方MenuAuth.vue)。官方对大小写错误是静默忽略(返 200 但一行不写)。 官方 body 是本仓的超集(多button/column/resource/form/systemIds)⇒ 本仓照单全收。 - 权限是四源合并:用户直授 + 角色 + 组织 + 岗位;只查
role会漏授权。管理员短路在查 SQL 之前。 - 菜单
url_address== 前端Route path(去前导斜杠)== spec 的module_key,三处一字不差。 不一致的后果是静默放行(未映射到菜单就放行)。 - 🔴 同一文件的多个 Edit 必须串行(并行 Edit = last-writer-wins 静默覆盖);改完必须 grep 复核。
- 🔴 平台 / 业务分离(靠仓库边界,不靠目录纪律):
平台 = 已发布的
sspf包(不在本仓);业务 =packs/<app>/(真源)+src/backend/src/modules/<app>.rs(面 A 适配器)。 加业务模块只碰业务,平台一个字都不用改 —— 因为它根本不在本仓。 🔴 两者唯一的接头是sspf::Platform::new().packs(reg).router(modules::router())(main.rs)。 🔴 spec 只有一份:在packs/<app>/src/lib.rs;modules/<app>.rs只pub use转发 (两份拷贝迟早分叉)。 🔴 业务菜单不要传给.menus():.packs(reg)已把PackRegistry.menus带进两段式种子, 给两次会在种子里撞主键。
判据(都要跑)
🔴 2026-11-04 起从「六道闸门」减到「两类判据」:原来的
check-module/check-boundary/check-contract/check-citations四把静态尺子测的是本仓那份平台实现(分层、契约对账、引文)。 平台搬走之后它们没有测量对象了 —— 保留等于假绿。现在只剩两类,各司其职:
scripts/check-scaffold.py |
cargo test --workspace |
scripts/perm-smoke.sh |
scripts/perm-smoke-jnpf.sh |
|
|---|---|---|---|---|
| 类别 | 静态判据 | 单元 / 集成测试 | 运行时尺子·面 A | 运行时尺子·面 B |
| 测什么 | 本仓只准有业务(SC1–SC6:没有 platform/、没有 base_* 建表、应用只依赖门面、包只依赖门面、sspf 锁 vendor 包版本、生成物不漂移) |
包自检(列/DDL/路由形状)+ 应用装配 + spec 唯一性 + sync 一致性 | 面 A 契约 32 条 | 官方 JNPF 形状 18 条 |
| 起后端 | 否 | 否 | 是(默认自起隔离实例) | 是(默认自起隔离实例) |
| 断言数 | 6(+ 反自证 6/6) | 按 workspace | 32 | 18 |
bash scripts/verify.sh # 一键:pack-sync --check → check-scaffold → 自证 → cargo test → 两把尺子
bash scripts/verify.sh --fast # 只静态 + cargo test(不起服务)
python3 scripts/check-scaffold.py # 单独跑 6 条判据
python3 scripts/check-scaffold.py --self-test # 反自证:每条判据造一个真实违规,必须红
python3 scripts/pack-sync.py --check # 生成物漂移(加包忘了跑 sync)
bash scripts/perm-smoke.sh # 面 A:32 条
bash scripts/perm-smoke-jnpf.sh # 面 B:18 条(结尾打印「面 B 覆盖 N/18」)
🔴 期望值只有一处:docs/contract.md 附录 A([MENU] / [MENU_TREE] / [MODULE] /
[ENDPOINT] / [FACE] / [RULER],由 scripts/contract_expect.py 解析)。
两把运行时尺子的菜单树与断言条数都从那里读 ⇒ 改契约只改一处;尺子被改弱(条数对不上)⇒ 自证失败。
🔴 每条判据都能被证伪(这是本仓的硬要求,不是口号):
check-scaffold.py --self-test:给 6 条判据各造一个真实违规(抄回platform/、写一条CREATE TABLE base_user、应用依赖sspf-core、包依赖axum、sspf改成 path、改pack.toml让生成物漂移),断言该条恰好变红,且注入前基线全绿。- 运行时尺子:结尾比对「实际跑了多少条」与契约
[RULER]登记的条数,对不上 ⇒ 失败。
🔴 面 B 尺子不假装全过:未落地的能力记 SKIP(不算 PASS),结尾打印「面 B 覆盖 N/18」。 当前 18/18,机制保留。
🔴 判读原则:返回了数据不能证明权限生效(管理员短路 / 菜单没映射 / 缓存没清 / 异常降级放行, 四条路径全是「放行」)。「菜单收窄 + 403 拦截」才是有说服力的信号。
🔴 不依赖 node:cipher 用后端 --enc 自证(./target/release/ssw-jnpf-lite-rust --enc 123456);
JSON 取值 jq 优先、python3 兜底。
文档导航
| 文档 | 何时读 |
|---|---|
HOWTO_MODULE.md |
开发时:加业务模块的操作手册(8 个文件 / 10 个接触点 + 逐文件改法 + 验证) |
README.md |
开发时:选型理由、运行、目录、已知限制 |
PERMISSION.md |
涉及权限/角色/授权时:表结构、四源合并、码表、两个官方陷阱 |
MIGRATION.md |
迁移期:Rust ⇄ NestJS ⇄ 官方 Java 三方映射、import 速查、数据 ETL、口令换算 |
JNPF_SOURCE_AUDIT.md |
迁移期/存疑时:官方源码逐行核对报告(标 文件:行号),开发 MVP 不必读 |
JNPF_COMPAT_SURFACE.md |
做面 B 时:官方形状的端点/响应/码表规格 + 落地顺序 S1–S6 |
references/BaseCrudController.java |
迁移期:通用 CRUD 骨架(业务 Controller 继承它可省 5 样板);非 JNPF 官方类 |
template-boot-jnpf/ |
迁移期:JNPF 标准栈最小可运行骨架(Java);包命名 ssw.{appCode}.xx.xx、master + ssw-{appCode}Ds 双数据源、@DS 切库;用法见该目录 README |
docs/contract.md |
开发时:契约唯一真源(端点 / 返回形状 / 数据模型 / 附录 A 机器可读期望值),与本文冲突以契约为准 |
docs/runbook.md |
运维时:怎么起 / 怎么冒烟 / 常见故障 |
docs/decisions.md |
存疑时:实施期 98 条裁决(什么—为什么—代价) |
docs/known-limitations.md |
验收前:分支级已知限制(被接受 / 挂起) |
CLAUDE.md / HANDOFF.md |
agent 协作:项目级红线 / 踩坑 / 端点全表 · 交接文档 |
校验
- 一键:
bash scripts/verify.sh(全量 7 步)/--fast(静态 + 测试 4 步)。 - cipher:
./target/release/ssw-jnpf-lite-rust --enc 123456⇒d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b(与官方DesUtil逐字节一致;平台侧实现在sspf包内)。 - 加/改业务包:
bash scripts/new-pack.sh <app> <Entity> --name "中文名" --columns "a:VARCHAR(200)"⇒ 建包 + 适配器 + 自动补齐四处生成物;随后cargo check与bash scripts/verify.sh。 忘了跑生成 ⇒python3 scripts/pack-sync.py --check红。 - 本仓只准有业务:
python3 scripts/check-scaffold.py(6 条)+--self-test(6/6)。 - 端到端权限闭环:
bash scripts/perm-smoke.sh(32 条)。覆盖:未登录 600 · 加密登录 · 菜单树 · 建用户 · 重复账号返 400 · 写授权(一维/二维兼容)· 非管理员菜单收窄 · 系统管理 403 · 已授权业务 200 · 未知路由 404 · 四个业务模块全链路(新建 / 36 位 UUID / numeric 往返 / 600 / 403)。 - 官方形状达标:
bash scripts/perm-smoke-jnpf.sh(18 条)⇒「面 B 覆盖 N/18」(当前 18/18)。 - 单测:
cargo test --workspace。 - 退出码约定一致:
verify.sh/check-scaffold.py/pack-sync.py/perm-smoke*.sh都是0成功 /1运行期失败 /2用法错。各脚本支持-h/--help。