Files
ssw-jnpf-lite-rust/SKILL.md
T
admin f8d2cf4cf5 feat(dep): 技能改纯 rlib 消费 —— fetch 只解 lib/,不再解包平台源码
- 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)。
2026-11-05 12:50:46 +08:00

20 KiB
Raw Blame History

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 里的 sspf tag 换成你项目要锁的版本 —— 那是唯一的平台版本入口。

除 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 登记)⇒ 平台层不动。

契约红线(改业务必须守住,否则迁移退化成重写)

  1. 登录口令加密: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。
  2. 统一返回 ActionResult{code,msg,data},成功 200;业务失败也是 HTTP 200(看 body 的 code)。 未知路由保留 HTTP 404(body 仍是信封形状)。 🔴 鉴权失败也是 HTTP 200:600 未登录 / 403 无菜单权限。
  3. 端点命名 /api/ssw/{appCode}/{Entity}/{List|Save|Delete}(ssw 约定,非官方 visualdev 路径)。 官方前端要跑 ⇒ 走面 B 的官方形状路径,不要改面 A 的路径。
  4. 实体列 f_ 前缀;主键 f_id VARCHAR(50)(36 位 UUID v4 装得下)。 f_tenant_id / f_last_modify_* / f_delete_time / f_delete_user_id 属 SuperEntity 可选增强层,非强制——MVP 不必补。
  5. 前端模型用去前缀名(title 非 fTitle);JSON 键名 = 列名去 `f_ 前缀后 camelCase。
  6. numeric 列必须序列化成 JSON 字符串("9.90",不是 9.9)⇒ 在 SQL 投影里就 f_price::text AS price。 int 列(f_delete_mark / f_stock / f_is_administrator)保持数字。
  7. 权限表照官方 base_* 抄,别自创;字段名有两个官方陷阱故意不修正:
    • base_role_relation 里用户 id 存在 f_object_id(配 f_object_type='user'),不是 f_user_id;
    • 组织/岗位关系在另一张表 base_user_relation,那里才有 f_user_id。
  8. 授权写接口 objectType 必须小写 'role',module 传一维数组 ['m1','m2',…] (半选节点合进同一数组,对齐官方 MenuAuth.vue)。官方对大小写错误是静默忽略(返 200 但一行不写)。 官方 body 是本仓的超集(多 button/column/resource/form/systemIds)⇒ 本仓照单全收。
  9. 权限是四源合并:用户直授 + 角色 + 组织 + 岗位;只查 role 会漏授权。管理员短路在查 SQL 之前。
  10. 菜单 url_address == 前端 Route path(去前导斜杠)== spec 的 module_key,三处一字不差。 不一致的后果是静默放行(未映射到菜单就放行)。
  11. 🔴 同一文件的多个 Edit 必须串行(并行 Edit = last-writer-wins 静默覆盖);改完必须 grep 复核。
  12. 🔴 平台 / 业务分离(靠仓库边界,不靠目录纪律): 平台 = 已发布的 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。