Files
admin a9c6bd34a3 feat(fetch): 从 Gitea Release 按 tag+目标平台拉包(本地 dist 回退)
- fetch-platform.sh: TARGET=rustc host;优先 Gitea Release web 下载
  /<repo>/releases/download/<tag>/<asset>(API assets 端点会 302 到 attachments
  且跨 host 丢 auth,实测 404,已避开);gzip 魔数校验防错误页;
  本地 dist(target/旧名)与 SSPF_TAR 作离线回退
- 文档同步 SKILL/README/HANDOFF
2026-11-05 13:45:18 +08:00

49 KiB
Raw Permalink Blame History

HANDOFF.md —— ssw-jnpf-lite-rust 交接文档

给下一个会话的你:本文件 + CLAUDE.md 两份读完就能直接开工,不需要重新推导任何设计。 目标:把「JNPF 兼容契约的 Rust 实现」从零写到验收全绿。


0. 2026-11-05:升级为方案 C —— 预编译 rlib,零重编平台(本次)

背景:上一版(§0 第二批)是「解包源码 + path 依赖」,消费方每次仍要**重编平台 17 个 crate

  • axum/tokio 等**(首次 cargo build 数分钟)。目标是「其他用户首次构建也别重编平台」, 最终落地方案 C:平台包内含预编译 rlib 完整闭包 lib/,本仓用 --extern 直接链接。

现在的依赖模型(务必按这个理解;旧文档里「path 依赖」的写法已废弃——本仓只依赖 rlib)

  • 本仓 Cargo.toml 不声明任何外部 crate 依赖([workspace.dependencies] 为空)。 平台 sspf、axum、tokio、serde、serde_json、http、bytes 全部来自平台包 lib/。
  • scripts/fetch-platform.sh vX.Y.Z:按 tag + 目标平台从 Gitea Release 拉 sspf-vX.Y.Z-<target>.tar.gz (本地 dist/ 与 SSPF_TAR 可离线回退),只解 rlib+工具链到 vendor/sspf-vX.Y.Z/,生成 .cargo/config.toml: rustflags = ["--extern","sspf=…/lib/libsspf-<hash>.rlib", … axum/tokio/serde/serde_json/http/bytes …, "-L","dependency=…/lib"],并复制包内 rust-toolchain.toml 到本仓根(锁 rustc 1.95.0)。
  • vendor/ 与 .cargo/config.toml(含本机绝对路径)不进版本库;rust-toolchain.toml 提交。

实测结果:cargo build 5.7s / cargo build --release 11s,只编译本仓 5 个 crate (packs/* + src/backend),零编译平台 17 crate、零编译 axum/tokio。

四个踩过的坑(平台侧/消费侧各修了,留作教训)

  1. lib/ 必须是构建产物 deps/ 的整目录副本(.rlib + .rmeta + proc-macro .dylib
    • 原生 .a)。只拷 lib*.rlib 会漏 serde_derive/tokio_macros 的 .dylib ⇒ E0463 can't find crate for sspf。
  2. rlib 必须 bitcode-free:平台 release.sh 出包时 cargo clean 隔离目录 + --config profile.release.lto=false --config profile.release.embed-bitcode=false。 否则 rlib 带 LLVM22 bitcode,macOS 系统 ld(libLTO 21)解析不了 ⇒ could not parse bitcode object file。 (顺带:clean 是必须的,否则旧 profile 的多 hash rlib 残留,head -1 会选到旧的那个。)
  3. 消费方必须用平台那份 axum:sspf 公共 API 带 axum::Json/http::HeaderMap/bytes::Bytes。 本仓若自己编 axum 就是「同名 crate 两实例」⇒ 跨边界 E0308 mismatched types。 ⇒ 本仓 [workspace.dependencies] 清空、backend 去掉 axum/tokio,全部走 --extern。
  4. 消费方 release profile 必须 lto = false:预编译 rlib 无 bitcode,开 LTO 会 failed to get bitcode from object file for LTO。平台 rlib 已 opt-level=2,损失很小。

本次改动文件:根 Cargo.toml(清空 workspace.dependencies + lto=false)、 src/backend/Cargo.toml(去 axum/tokio)、scripts/fetch-platform.sh(整包移旧目录 + 生成多 --extern)、 .gitignore(忽略 .cargo/config.toml),新增 rust-toolchain.toml(提交)。 平台侧见 ssw-platform 仓 scripts/release.sh + docs/SSPF-PLATFORM-PACKAGE.md §6。


0. 2026-11-04 第二批:技能仓改为「依赖已发布的 sspf 包」(历史)

上一批(平台仓 ssw-platform)把示例搬出去并发布 v0.4.0;本批把技能仓改成消费者。 🔴 2026-11-04 深夜:平台发了 v0.5.0(Db::query_json_raw / query_rows / lock_owned), 本仓依赖随之升到 v0.5.0(业务侧无代码改动:本仓不直接碰 PGlite)。

做了什么

  1. 删除自研平台:src/backend/src/platform/(17 文件)、routes.rs(35K)、 bootstrap.rs、db/schema.sql、tests/(7 个集成测试,测的是被删的那份实现)。 备份在 /tmp/skill-backup/backend-2216/。
  2. 平台改为依赖已发布包:根 Cargo.toml 的 [workspace.dependencies] sspf = { path = "vendor/sspf-v0.5.0/crates/sspf", version = "0.5" }(历史写法:现已是方案 C 的 rlib 消费,fetch-platform.sh 不再解包平台源码), 成员一律 sspf = { workspace = true }。解析结果: sspf v0.4.0 (...?tag=v0.4.0#ff34ca50),0 个 sspf-pack-* 被平台带进来。
  3. 示例业务包迁入:packs/{demo,shop,books,asset}/(表 DDL + 列 + 菜单 + 面 B 路由), 依赖从 sspf-sdk 改为门面 sspf;use sspf_sdk::… → use sspf::…。
  4. 应用瘦成薄壳(src/backend/ 从 ~4000 行降到 ~500 行):
    • main.rs:--enc / --help + Platform::new().config().packs().router().static_dir().serve();
    • lib.rs:pub mod modules; pub mod packs_gen;;
    • packs_gen.rs:4 个 load_static + manifest 快照(生成物);
    • modules/:4 个面 A 适配器(spec 只 pub use 转发)。
  5. 脚本重构:
    • 新增 check-scaffold.py(SC1–SC6「本仓只准有业务」+ --self-test 6/6);
    • 新增 pack-sync.py(重写:4 处派生位置,--check 防漂移);
    • 新增 new-pack.sh / new-pack.py(造包脚手架,端到端验证过);
    • 新增 verify.sh(一键 7 步 / --fast 4 步);
    • 删除 check-module.sh / check-boundary{,-scan} / check-contract{,-scan} / check-citations{,-scan}: 它们测的是本仓那份平台实现(分层 / 契约对账 / 引文),平台搬走后没有测量对象 ⇒ 留着就是假绿。
  6. 契约同步:docs/contract.md 补入 asset 包 —— [MENU] +1、[MENU_TREE] → 9 菜单 (…|图书超市:|数据资源:)、[MODULE] +1、[ENDPOINT] +3(面 A)、[FACE] A 25 → 28。 §8.4 的「值住在哪」改为「平台在 sspf,业务在 packs/<app>/」。
  7. 文档:SKILL.md / README.md / CLAUDE.md / HOWTO_MODULE.md / docs/runbook.md 全部按新架构重写关键章节(「自包含」→「依赖已发布包 + 锁 tag」;「六道闸门」→「两类判据」)。

验收(全部实际跑过)

项 结果
cargo build / cargo build --release ✅ 通过(平台来自 vendor/sspf-v0.5.0/lib/ 的预编译 rlib,零重编;无需 Gitea)
cargo test --workspace ✅ 全绿(4 个包各自 14/14/3/3 条包自检 + 应用单测)
python3 scripts/check-scaffold.py ✅ PASS=6 FAIL=0
python3 scripts/check-scaffold.py --self-test ✅ 反自证 6/6
python3 scripts/pack-sync.py --check ✅ 4 个包 / 4 个模块,无漂移
bash scripts/perm-smoke.sh ✅ PASS=32 FAIL=0
bash scripts/perm-smoke-jnpf.sh ✅ PASS=18 FAIL=0 SKIP=0(覆盖 18/18)
new-pack.sh probe Widget 端到端 ✅ 生成 → 编译 → 起服务 → 面 A 600 / 面 B 602 / 表数 182(177 + 5)→ 删包

踩过 / 别踩

  • 🔴 pack-sync.py 的 ROOT 不能用脚本自身路径:反自证在临时树里跑时, 它会把「真实仓库」当成目标 ⇒ SC6 自证假绿。已加 PACK_SYNC_ROOT 环境变量。
  • 🔴 生成段不能只放「数组元素」:replace_region 会把 pub const … = &[ 连同 ]; 一起盖掉 ⇒ 语法错。正确做法是生成器输出完整声明块。
  • 🔴 业务菜单不要传给 .menus():.packs(reg) 已经把 PackRegistry.menus 带进种子, 给两次会在种子 INSERT 撞主键。
  • 🔴 resolve_project_dir 找不到本仓:平台默认锚点是 src/backend/db/schema.sql(本仓已删) ⇒ main.rs 自己按 SSW_PROJECT_DIR → Cargo.toml + packs/ 向上找 → cwd。
  • 🔴 加了 asset 包 ⇒ 菜单树从 8 变 9,[MENU_TREE] 不改 ⇒ 面 A 尺子当场红(它是对的)。

第二批遗留(可选)

  • MIGRATION.md / JNPF_COMPAT_SURFACE.md / JNPF_SOURCE_AUDIT.md 是历史技术报告, 其中引用的 src/backend/src/platform/* 路径已不存在 —— 需要时按 sspf 包的模块对位, 不必逐条改(它们描述的是行为规格,不是本仓结构)。
  • 前端 src/frontend/dist/ 目前 gitignore;若要「开箱即用」,可把构建产物一起提交。

0. 当前状态

v1 已完成 + v1.1 双面后端(面 B)已落地,验收全绿(每一条 ✅ 都有实际执行输出,见 §9 与各任务报告)。

项 状态
目录 ~/Desktop/workspace/ssw-jnpf-lite-rust/ ✅ 已建并已 commit(main 分支)
CLAUDE.md ✅ 已写;已逐条核对并与代码同步(Task 12;2026-10-26 再同步面 B)
HANDOFF.md(本文件) ✅ 已写并已同步(§0 状态表 / §9 交接话术,Task 12;2026-10-26 再同步面 B)
代码 ✅ 后端已实现(src/backend/,Rust 2021 + axum 0.8 + pglite-rs 0.2,10 张表、32 条路由 = 面 A 27 + 面 B 5)
面 B(官方 JNPF 契约面) ✅ 已落地(src/backend/src/platform/jnpf.rs,S1–S6 全完成):判别头 Vue-Version: 3 分流 · PcUserVO 5 字段 · PageListVO 分页 · 点权限(f_en_code)守卫 · 未登录 602
前端 ✅ 已逐字复制(src/frontend/;唯一改动 = vite 代理端口改成 30010,其余文件逐字节相同)
脚本 ✅ scripts/perm-smoke.sh(32 条断言)+ scripts/check-module.sh(9 接触点静态自检,57 条 ✅)+ scripts/perm-smoke-jnpf.sh(面 B 尺子,18 条断言;已全绿 PASS=18 / SKIP=0)
工程脚本 ✅ run.sh(install/build/dev/backend/frontend/stop/logs,退出码 0/1/2)
文档 ✅ README.md / docs/runbook.md / .env.example
官方对齐文档 ✅ JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格 + 落地状态)· MIGRATION.md(迁移指南)
技能资产 ✅ 仓根 = 技能根(SKILL.md 与 src/ scripts/ references/ 同仓,改一次仓 = 改一次技能);~/.agents/skills/ssw-jnpf-lite-rust → 仓根(绝对软链),~/.claude/skills / ~/.workbuddy/skills / ~/.qwenworkcn/skills 三处相对软链已验证可读 SKILL.md
验收门 ✅ 全绿(编译 0 error 0 warning · 单测 197 passed / 0 failed · 面 A 冒烟 PASS=32 FAIL=0 · 面 B 冒烟 PASS=18 FAIL=0 SKIP=0 · 前端浏览器手验全过)

读法:CLAUDE.md(红线与坑位,日常改代码必读)→ §9(怎么起 / 怎么复现验收)。 §3(设计)与 §5(实施顺序 step 0–12)已完结,留作背景与决策记录,不要再照着实施一遍。


1. 决策记录(本轮问答全过程,含被推翻的方案)

保留被推翻的方案,是为了避免下个会话"重新考虑"已经讨论过的问题。

# 问题 决定 理由
1 Rust 版做成什么形态? 先做真实项目,验证后再抽技能 技能是模板;没跑通的模板没有价值
2 v1 做多大? 全量契约对齐(auth + 5 组 base_* + 四源权限 + 两段种子 + 3 业务模块 + 冒烟) 迁移价值全在权限与数据模型这两块,缺一块就不成立
3 落在哪个仓? 独立仓 ssw-jnpf-lite-rust 原方案:tdc-rs 开分支(已被 #4 推翻)
4 运行时拓扑? 先不碰 tdc-rs,独立仓做 tdc-rs 已占它自己的后端端口,且已有自己的 /api/oauth/Login(JSON 账号库),两套同路径不同语义会打架
5 目录名? ssw-jnpf-lite-rust(正式名称,2026-10-26 用户改定) 原方案:tds-lite-rs(crate/binary 名已一并改名)
6 数据库? pglite-rs 0.2(进程内原生 PG) 沿用 tdc-rs 已验证的形态;零服务零 Docker
7 后端端口? :30010(前端 vite :5173) 避开 tdc-rs 已占用的后端端口
8 前端怎么办? 逐字复制 react 技能的前端,零改动 前端零改 = 契约真的对齐了(改了就说明后端在迁就前端)
9 业务实体怎么实现? spec 驱动 CRUD 引擎;5 组 base_* 走显式 handler 业务模块语义简单可声明化;base_* 的语义(一维授权数组 / 用户↔角色 / 机构树防环)塞不进通用引擎
10 冒烟脚本的 node 依赖? Rust 二进制加 --enc <明文> 模式,脚本自证 cipher,不依赖 node 去掉 node 依赖 = 冒烟可在任何装了 Rust 的机器上跑
11 抽技能的时机? 验收门全绿之后再抽 目录结构现在就和 react 技能对齐(src/backend + src/frontend + scripts/ + run.sh),届时 1:1 复制即可

关键约束:tdc-rs 只读。本仓不 import 它的代码、不共享数据目录、不共享端口。 可以读它的 src/cipher.rs / src/db.rs / src/envelope.rs 作工程手法参考。

🔴 实施期的逐条裁决(98 条)另见 docs/decisions.md —— 上面这张表是立项期的问答;实现过程里还有 98 条「什么 — 为什么 — 判错了的代价」级别的裁决 (契约歧义、pglite 的坑、评审发现的取舍、挂起的限制),那是代码之外的「为什么」。


2. 目标与非目标

目标(v1 做完的样子):

  1. 用 Rust 起一个单二进制、零外部服务的后端,行为与 ssw-jnpf-lite-react(NestJS)逐条一致。
  2. 前端一行不改就能跑通(直接复用 react 技能的 src/frontend)。
  3. base_* 表结构与官方 DDL 逐字一致 ⇒ 迁 JNPF 时导数据即可(--data-only)。
  4. 权限闭环(登录 → 菜单树 → 建用户 → 授权 → 收窄 → 403)有自动化冒烟钉住。
  5. 跑通之后,1:1 复制成技能(ssw-jnpf-lite-rust)。

非目标(明确不做):低代码引擎 / 多租户 / 按钮·列·表单·数据范围级授权 / Redis+Sa-Token / 分页 / secretkey 的官方双层 md5 算法。理由见 CLAUDE.md「明确不在 v1 范围」。


3. 设计(已定稿)

3.1 落点与边界

ssw-jnpf-lite-rust/                      ← 独立 git 仓(已 init,未 commit)
├── Cargo.toml                    ← 【workspace 根】members=["src/backend"] + [profile.release]
├── src/backend/  ← 名字保留是为了将来抽技能时目录与 react 版对齐
│   ├── src/*.rs                  ← 16 个模块(见 §3.3)
│   ├── db/schema.sql             ← 10 张表完整 DDL
│   └── data/                     ← 运行期(gitignore)
├── src/frontend/                 ← react 技能前端逐字复制(零改)
├── scripts/{perm-smoke.sh,check-module.sh}
├── run.sh                        ← install/build/dev/stop/logs
└── .env.example

端口:后端 30010 · 前端 5173(vite)· vite proxy /api → http://127.0.0.1:30010。 🔴 本仓端口是硬约定:run.sh 的端口常量不许改 —— PORT 被设成 ≠ 30010 时 run.sh dev / run.sh backend 报错退出 2(要换端口请直接跑二进制); 后端二进制本身确实吃 PORT(非法值回落 30010)。 🔴 后端默认只监听 127.0.0.1(BIND_ADDR 可覆盖);BIND_ADDR=0.0.0.0 才对外暴露。

数据库:pglite-rs,默认落盘 src/backend/data/lite.pg;PGLITE_DIR=memory:// ⇒ 临时库 (系统临时目录里的一次性数据目录,进程退出即销毁;pglite-rs 0.2.7 没有真内存模式)。

3.2 契约逐字对齐表(对着 react 技能源码抄)

契约点 精确口径 react 源码位置
统一返回 {code,msg,data};成功 code=200,msg='成功';失败 data=null src/backend/src/common/action-result.ts
HTTP 状态 业务失败/鉴权失败 HTTP 200;未知路由 HTTP 404(body 仍是 ActionResult) common/action-result.filter.ts
错误码 未登录 600 · 无菜单权限 403 · 业务失败 400(msg 透传) 同上 + 各 controller
登录 POST /api/oauth/Login,form-urlencoded account/password(密文 hex)/grant_type=password auth/auth.controller.ts:19
登录失败文案 缺参 → 400 '缺少 account / password';grant_type 不支持 → 400;口令错 → 400 '账号或密码错误' auth/auth.controller.ts
登录成功体 {token, expiresIn:7200, tokenTypeName:'bearer'} auth/auth.service.ts
CurrentUser GET /api/oauth/CurrentUser → {userInfo:{userId,userAccount,userName,isAdministrator}, menuList} auth/auth.controller.ts:34
cipher md5(明文) → AES-256-ECB-PKCS7(key=md5("EY8WePvjM5GGwQzn") 的 32 ASCII 字节)→ hex common/cipher.ts
检验向量 encryptPassword('123456') = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b common/cipher.ts 注释
口令比对 库内存 md5(明文) 小写 hex;登录解出 md5(明文) ⇒ 大小写不敏感比较 auth/auth.service.ts
权限四源 直授 + 角色 + 组织 + 岗位;管理员短路在 SQL 之前;菜单未映射 ⇒ 放行 sys/permission.service.ts
菜单树 `parentId
授权写入 PUT /api/permission/Authority/Data/{objectId},body {objectType:'role'(小写), module:[...]}(一维) sys/authorize.controller.ts:39
授权读取 GET /api/permission/Authority/RoleModules?roleId= → string[] sys/authorize.controller.ts:52
角色授权写 旧行软删(delete_mark=1)后插新行 sys/sys.service.ts:saveRoleModules
用户↔角色 setUserRoles = 先 delete 旧 base_role_relation 行再插新行 sys/sys.service.ts
用户列表 去掉 password,追加 roleIds / roleNames sys/sys.service.ts:listUsers
账号唯一 应用层保证,只比 delete_mark=0(官方 DDL 无 UNIQUE) sys/sys.service.ts:saveUser
机构删除 有子机构 ⇒ 400 '该机构下还有子机构,先删除子机构' sys/sys.service.ts:deleteOrganize
业务 List 软删过滤 + creatorTime DESC shop/product.service.ts
业务 Save 无 id ⇒ 新 36 位 UUID + creatorUserId='admin' + creatorTime=now + deleteMark=0;有 id ⇒ 覆盖更新 shop/product.service.ts
业务 Delete 软删(f_delete_mark=1) shop/product.service.ts
numeric 列 JSON 字符串("9.90") shop/product.entity.ts + TypeORM numeric→string
int 列 JSON 数字 books/book.entity.ts
端点命名 `/api/ssw/{appCode}/{Entity}/{List Save

种子里必须逐字保留的常量(sys/seed.service.ts 的字面量数组):

  • 角色:role_admin/enCode admin/管理员/sort 1;role_user/enCode user/使用者/sort 2
  • 菜单(f_type:1=目录 2=页面):
    id fullName urlAddress parentId type icon sortCode
    m_sys 系统管理 system 0 1 setting 1
    m_user 用户管理 system/User m_sys 2 — 2
    m_role 角色管理 system/Role m_sys 2 — 3
    m_org 机构管理 system/Organize m_sys 2 — 4
    m_menu 菜单管理 system/Module m_sys 2 — 5
    m_demo Demo 示例 demo-item 0 2 app 6
    m_product 产品管理 shop/Product 0 2 app 7
    m_book 图书超市 books/Book 0 2 app 8

⚠️ perm-smoke.sh 在 react 版里是从 seed.service.ts 的字面量动态算期望菜单树的。 Rust 版没有那个文件 ⇒ 两种做法二选一: (a) 把上表搬进冒烟脚本作为字面量;或 (b) 后端暴露一个只读端点/二进制子命令打印期望树。 推荐 (a):脚本自包含、离线可跑。菜单增删时同步改脚本(这是刻意的耦合,不是缺陷)。

两段式种子(sys/seed.service.ts):

  • ensureBase(每次启动都跑,幂等):按 enCode 补内置角色、按 urlAddress 补内置菜单、 补齐 admin 角色对内置菜单的授权(取库里真实行 id)。 只补缺项:不覆盖已改值;同 urlAddress 已有行(含软删)不复活。
  • firstSeed(仅 users==0 时跑一次):admin/123456(f_is_administrator=1, f_organize_id='0')
    • 一条 base_role_relation(object_type='user', object_id='admin', role_id='role_admin')。 角色/菜单/授权行已由 ensureBase 建出,不重复写。

3.3 后端模块划分

模块 职责 备注
main.rs 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听(+ 优雅停机) with_state 必须是最后一步
config.rs PORT / BIND_ADDR / PGLITE_DIR / 静态目录 / 种子开关 环境变量
db.rs pglite 封装:open() / open_temp() / ensure_schema() / query_json() / query_json_params() / exec() / exec_params() / scalar_text() 单 backend ⇒ 进程级 db_lock
cipher.rs md5_hex() / encrypt_password() / decrypt_to_md5() 逐字对齐 cipher.ts + 上游向量单测
envelope.rs ActionResult{code,msg,data} + ok() / fail() 业务失败恒 HTTP 200
ids.rs new_uuid() → 36 位 UUID v4 不是 tdc-rs 的雪花
session.rs 内存 token 表(lite- 前缀 + 32 hex) 进程重启即失效
auth.rs 登录 / CurrentUser / require_login() / require_module() / require_login_any() 守卫返回 ActionResult(600 / 403 / 602)
jnpf.rs 【面 B】 判别头 Vue-Version: 3 · PcUserVO / PageListVO / ListVO 构造 · 点权限守卫(f_en_code)· 5 个官方 RESTful 端点 与面 A 共用 base_* 表 / cipher / seed,但权限判据不同
permission.rs resolve_user_module_ids() 四源合并 / has_module() 管理员短路+未映射放行 / build_menu_list() 四源 + 两条放行路径都要有测试
seed.rs ensure_base() + first_seed() 幂等 + 只补缺项
sys.rs 5 组 base_* 的显式 handler 语义 用户/角色/机构/菜单/授权
crud.rs spec 驱动的通用 CRUD 引擎(List/Save/Delete)—— 不含任何业务表名 / app_code 业务实体用
entity.rs EntitySpec / ColumnSpec 的类型定义(不含任何业务 spec) 引擎与业务层之间的契约
routes.rs 路由装配(404 / 405 / 413 改写 / catch-all 三层兜底)+ merge(modules::router())
state.rs AppState{config, db, sessions}(三个字段全是 Arc) axum State 的载体
lib.rs 库入口:pub mod platform / modules / routes 让单测 / 集成测试能直接引用各模块

🔴 上表除 routes.rs / lib.rs 外全部在 src/backend/src/platform/(平台层)。 业务层的 src/backend/src/modules/{mod,demo,shop,books}.rs = 每个业务模块自带 spec + 3 个 handler + 自己的 router() ⇒ 加业务模块只碰业务层。

3.4 三个关键取舍

  1. 业务实体走 spec 引擎,base_* 走显式 handler。 理由:业务模块语义同构(列表/保存/软删/守卫),声明化后"加一个模块 = 加一条 spec"; 而 base_* 的语义(一维授权数组、用户↔角色关系、机构树防环、账号唯一性)塞不进通用引擎, 硬塞会得到一个既不懂 JNPF 又难懂的框架。
  2. numeric 列在 SQL 投影里就 cast 成 text。 理由:row_to_json 直接给数字 ⇒ serde_json 解析成 f64 ⇒ 回显 9.9 ⇒ 契约破。 在投影层 f_price::text AS price 才是"一次解决、处处一致"。
  3. HTTP 状态语义刻意不同于 tdc-rs(那边是 401/403 裸 body,这边是 200 + code 600/403)。 理由:react 前端的拦截器只认 body.code;两边同时跑时更不能混形状,否则冒烟脚本得写两套。

3.5 前端

  • 逐字复制 ssw-jnpf-lite-react/src/frontend → src/frontend(package.json / vite.config.ts / src/**)。
  • 唯一允许的改动:vite 的 proxy 目标端口改成 30010(以及 baseURL 仍是 /api,不变)。
  • 前端 utils/cipher.ts 保持不变(它是浏览器侧算法;后端 Rust 侧必须与它逐字节等价——由上游向量钉住)。
  • 路由 path(App.tsx):/login /demo-item /shop/Product /books/Book /system/User /system/Role /system/Organize /system/Module ⇒ 去掉前导斜杠就是 base_module.f_url_address ⇒ 也是后端守卫的 module key。三处一字不差。

3.6 目录/文件对照(react 技能 → 本仓)

react 技能 本仓
src/backend/src/common/cipher.ts src/backend/src/platform/cipher.rs
src/backend/src/common/action-result.ts + .filter.ts src/backend/src/platform/envelope.rs
src/backend/src/auth/* src/backend/src/platform/auth.rs
src/backend/src/sys/permission.service.ts src/backend/src/platform/permission.rs
src/backend/src/sys/seed.service.ts src/backend/src/platform/seed.rs
src/backend/src/sys/sys.service.ts src/backend/src/platform/sys.rs
src/backend/src/{demo,shop,books}/* src/backend/src/modules/{demo,shop,books}.rs(各自带 spec + handler + router)
src/backend/db/schema.sql src/backend/db/schema.sql(本仓要写全 10 张表)
src/frontend/** src/frontend/**(逐字复制)
scripts/perm-smoke.sh scripts/perm-smoke.sh(移植,cipher 改用 --enc)
scripts/check-module.sh scripts/check-module.sh(移植,grep 模式按 Rust 调整)
run.sh run.sh(改成 cargo 版本)

4. 四道验收门("做完"的唯一判据)

门 命令 通过标准
① 编译 cargo build --release 0 error 0 warning;release 配置:opt-level=2 / lto="thin" / strip="symbols" / codegen-units=16。🔴 catch-all 依赖默认的 unwind 型 panic 策略(Ruling P19)⇒ 禁止在 release profile 里启用 abort 型 panic(确切写法见根 Cargo.toml 里的注释)—— 那会让 catch-all 抓不到 panic ⇒ 契约 §6.5 的「uncaught panic ⇒ HTTP 200 + {code:400}」直接失效
② 单测 cargo test 实测 197 passed / 0 failed(8 个测试目标:83+6+19+24+3+18+7+37)。覆盖清单见契约 §12(docs/contract.md:940):cipher 上游向量 · 信封形状(200/400/600/403)· 四源合并 · 管理员短路 · 未映射放行 · 种子幂等(跑两次结果一致 + 不复活软删行)· CRUD 往返(36 位 UUID / numeric→"9.90" / int→100)· 账号重复返 400 而非 500 · 面 B(判别头 / PcUserVO 5 字段 / PageListVO / 点权限守卫 / 602)
③ 冒烟 bash scripts/perm-smoke.sh 32 条断言全绿(实测 PASS=32 FAIL=0,退出码 0),与 react 版断言集逐条对应(见 §5 步骤 11 的清单)
③' 冒烟(面 B) bash scripts/perm-smoke-jnpf.sh 18 条断言全绿(实测 PASS=18 FAIL=0 SKIP=0 ⇒ 面 B 覆盖 18/18)。尺子必须带判别头 Vue-Version: 3
④ 前端手验 cd src/frontend && npm run dev 浏览器 http://127.0.0.1:5173 → admin/123456 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录

外加:scripts/check-module.sh(9 接触点静态自检)的 Rust 版移植,作为"加模块后立刻跑"的前置闸门。


5. 建议实施顺序(step 0–12)

每步都带完成判据。做完一步先跑该步的判据,再进下一步。

step 内容 完成判据
0 建 cargo workspace(根 Cargo.toml:[workspace] members=["src/backend"] + [profile.release])+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) 根目录 cargo build 通过(哪怕是空 main)
1 src/cipher.rs + 单测 上游向量逐字节相等;md5_hex 与 decrypt_to_md5 往返一致
2 src/envelope.rs + 单测 业务失败 HTTP 200 + code=400;code=600/403 同形
3 src/db.rs + src/config.rs + db/schema.sql(10 张表) 进程能开库并建表;query_json() 能取回 JSON
4 src/ids.rs + src/session.rs UUID 36 位带连字符;token 登录后可查回
5 src/seed.rs(ensure_base + first_seed) 空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;再启动一次库内容不变
6 src/permission.rs + 单测 四源合并各源单独可注入;管理员短路不查 SQL(可用「无授权记录的管理员仍放行」验证);未映射菜单放行
7 src/auth.rs + /api/oauth/* 登录返 {token,expiresIn:7200,tokenTypeName:'bearer'};CurrentUser 返 {userInfo,menuList};无 token ⇒ code=600
8 src/sys.rs + /api/ssw/sys/* + /api/permission/Authority/* 5 组 CRUD 语义对齐;重复账号返 code=400 + msg '账号已存在:xxx'(不是 500);授权写 objectType='role' 小写 + 一维数组
9 src/modules/{demo,shop,books}.rs + src/platform/crud.rs + 3 个业务模块端点 demo/shop/books 三个模块端点可用;numeric 往返 "9.90";未授权非管理员访问 shop/books ⇒ code=403
10 src/routes.rs + main.rs 装配 + 404/405 兜底 未知路由 HTTP 404 + code=404;405 返回 JSON;with_state 在链尾
11 scripts/perm-smoke.sh 移植(逐条对应 react 版) 32 条断言全绿(PASS=32 FAIL=0)
12 前端复制 + run.sh + .env.example + 文档 ✅ 已完成(Task 12):门④ 手验全过(浏览器实测);run.sh install/build/dev/stop/logs 可用

step 11 的断言清单(照 react 版 scripts/perm-smoke.sh 逐条移植):

  1. 无 token 访问 User/List ⇒ code=600
  2. 加密登录 ⇒ code=200;3. 拿到 token(非空)
  3. CurrentUser ⇒ code=200
  4. 菜单树与种子表逐字相等(推荐做法:把 §3.2 的菜单表搬进脚本作字面量)
  5. 建用户 ⇒ code=200
  6. 重复账号 ⇒ HTTP 200(不是 500)且 code=400 且 msg '账号已存在:smoke_user'
  7. 写授权(一维数组)⇒ code=200;9. 写授权(二维兼容)⇒ code=200
  8. 非管理员登录 ⇒ code=200
  9. 非管理员菜单已收窄(字符串比对)
  10. 非管理员访问 User/List ⇒ code=403
  11. 已授权业务(demo)⇒ code=200
  12. 未知路由 ⇒ HTTP 404(不被吞掉)
  13. admin 短路 ⇒ Product 列表 code=200
  14. Product 新建 ⇒ code=200;17. 主键 36 位;18. numeric 往返 "9.90"
  15. Product 无 token ⇒ code=600;20. 未授权非管理员 ⇒ code=403

(react 版断言条数更多,上表是主干;移植时以 react 脚本为准逐条对齐,一条不落。)

另外:scripts/check-module.sh(9 接触点静态自检)移植为 Rust 版—— 把「grep TS 文件里的字符串」换成「grep Rust 源 + 检查 spec 注册」,保持同样的 ❌ 判定与退出码约定 (0 全过 / 1 有 ❌ / 2 用法错)。

脚本退出码约定(三个入口一致,照抄 react 技能):

入口 0 1 2
run.sh 执行成功 运行期失败 用法错
scripts/check-module.sh 接触点全过 有 ❌ 项 用法错
scripts/perm-smoke.sh 全绿(FAIL=0) 有断言失败 前置错误(后端不可达)

6. 必读参考文件(绝对路径)

契约真源(react 技能,只读)

~/Desktop/workspace/skills/ssw-jnpf-lite-react/
├── src/backend/src/common/cipher.ts                  ← cipher 算法 + 检验向量
├── src/backend/src/common/action-result.ts           ← {code,msg,data}
├── src/backend/src/common/action-result.filter.ts    ← HTTP 状态映射(200/404 的来源)
├── src/backend/src/auth/auth.controller.ts           ← 登录 / CurrentUser 端点与文案
├── src/backend/src/auth/auth.service.ts              ← 口令比对、token 生成
├── src/backend/src/sys/permission.service.ts         ← 四源合并 + 管理员短路 + 未映射放行 + 菜单树
├── src/backend/src/sys/seed.service.ts               ← roles/menus 字面量 + 两段式种子
├── src/backend/src/sys/sys.service.ts                ← 5 组 base_* CRUD 语义
├── src/backend/src/sys/authorize.controller.ts       ← 授权写/读 + 一维 module 归一化
├── src/backend/src/sys/base-*.entity.ts              ← 7 张表的列 ↔ JSON 键映射
├── src/backend/src/{demo,shop,books}/*               ← 业务模块参照实现
├── src/frontend/src/api/{request,auth,sys,product,book}.ts  ← 前端实际调用的端点
├── src/frontend/src/App.tsx                          ← 前端路由 path(= urlAddress)
├── src/frontend/src/utils/cipher.ts                  ← 浏览器侧 cipher(后端必须等价)
├── scripts/perm-smoke.sh                             ← 断言集(逐条移植)
├── scripts/check-module.sh                           ← 9 接触点静态自检
└── run.sh                                            ← 脚本骨架(改成 cargo 版)

官方 JNPF(数据模型真源,只读)

~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql
  base_authorize        :812
  base_module           :2209
  base_organize         :3178
  base_role             :3686
  base_role_relation    :3729
  base_user             :4479
  base_user_relation    :4707
(另有 base_module_{authorize,button,column,data,form,link,scheme,use_num}、
  base_organize_administrator、base_user_{device,extra,old_password} —— v1 不做)
同目录还有 jnpf_db_init.sql(base_user 的 INSERT 可二次确证列名)等 9 个 init 文件

本仓的官方对齐文档(面 B / 迁移期必读)

文件 何时读 内容
JNPF_SOURCE_AUDIT.md 迁移期 / 存疑时 官方源码(Java + Vue)逐行核对报告,全部结论标 文件:行号;含本仓与官方的差异清单 D1–D8
JNPF_COMPAT_SURFACE.md 改面 B 时 面 B 规格:官方形状的端点 / 响应形状 / 码表 / 判别头 / 落地顺序 S1–S6(已全部落地)+ §8 已知偏差 B1–B10
MIGRATION.md 稳定期迁 JNPF 本仓 ↔ 官方的逐项映射 + 数据 ETL + 口令 secretkey 换算(不需要明文)
scripts/perm-smoke-jnpf.sh 改面 B 时 第二把尺子:18 条官方形状断言(打 Vue-Version: 3 头);当前 PASS=18 SKIP=0
src/backend/src/platform/jnpf.rs 改面 B 时 面 B 全部实现(判别头 / VO 构造 / 点权限守卫 / 602 码)

🔴 面 A / 面 B 的判别头 = Vue-Version: 3(官方前端必发、本仓前端唯一不发的一头)。 🔴 本仓前端禁止发 Vue-Version(发了 ⇒ 面 A 请求被误判成面 B)⇒ scripts/check-module.sh 的「全局红线」段静态钉住这一条。

工程手法参考(tdc-rs,只读、不共享代码)

~/Desktop/workspace/tdc-rs/src/cipher.rs      ← cipher 的 Rust 版逐字实现 + 坑位注释
~/Desktop/workspace/tdc-rs/src/envelope.rs    ← 信封形状
~/Desktop/workspace/tdc-rs/src/db.rs          ← pglite 封装 / query_json / valid_table
~/Desktop/workspace/tdc-rs/src/main.rs        ← resolve_project_dir / 404 兜底 / with_state 收口
~/Desktop/workspace/tdc-rs/src/routes/mw.rs   ← 405 JSON 兜底中间件
~/Desktop/workspace/tdc-rs/Cargo.toml         ← release 配置

7. 风险与坑(开工前先知道)

风险 表现 处置
pglite 单实例独占数据目录 第二个进程起不来(postmaster.pid 锁) 换数据目录/端口;集成测试串行或各用独立目录
pglite 体积 debug 二进制 ~35 MB(内嵌 PG 引擎) 与 tdc-rs 同量级,可接受
cipher 的 ASCII-hex key 坑 一旦当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂 单测钉死上游向量(步骤 1)
numeric 变 9.9 前端金额显示错、冒烟第 18 条红 投影层 ::text(步骤 9)
base_role_relation 无 f_user_id 角色授权不生效 建表时逐字照官方 DDL(步骤 3)
npm 装 esbuild 被拦 vite 起不来 / 端口 000 且报错不指根因 npm install-scripts approve esbuild 后在 src/frontend 重跑 npm install
前端端口 macOS 上 localhost:5173 失败 用 127.0.0.1:5173(vite 模板固定 bind IPv4)
冒烟脚本依赖 node 换机器跑不了 Rust 侧 --enc 自证(步骤 11)
权限"看起来生效"其实没测到 返回了数据 ≠ 权限生效(管理员短路/菜单没映射/未清缓存/异常降级放行,四条路径全是放行) 必须以「菜单收窄 + 403 拦截」为判据

8. 开放问题(开工时按需裁决,不阻塞)

  1. git 首个 commit 何时做 —— 目录已 git init 但未 commit。建议步骤 0 结束就 commit 一次骨架。
  2. Cargo workspace 还是单 crate —— ✅ 已定:workspace。 根 Cargo.toml = [workspace] members = ["src/backend"] resolver = "2" + [workspace.dependencies] + [profile.release](release profile 只在 workspace 根生效,别写到成员里); src/backend/Cargo.toml = 成员 crate(crate 名 ssw-jnpf-lite-rust,src/main.rs 在 src/backend/src/main.rs)。 理由:保持目录与 react 版对齐 ⇒ 抽技能时 1:1 复制。
  3. --enc 子命令的参数形式 —— 建议 ./ssw-jnpf-lite-rust --enc 123456(打印 hex 到 stdout,退出码 0); 未知参数按 --help 处理。
  4. 是否需要 /api/health —— react 版没有。建议加({ok, tables, version}),便于冒烟探活,但不是契约。
  5. 抽技能的目标目录名 —— 建议 ssw-jnpf-lite-rust,落在 ~/Desktop/workspace/skills/, 与 ssw-jnpf-lite-react 并列。验收全绿后再做。

9. 交接话术(交付态:这个仓是什么、怎么跑、怎么复现验收)

读 CLAUDE.md + HANDOFF.md(本文件)。设计已定稿且已实现完毕,不要重新设计、不要重写。

一句话

ssw-jnpf-lite-rust = JNPF 兼容契约的 Rust 实现(单二进制、零外部服务:Rust 2021 + axum 0.8 + pglite-rs 0.2 进程内原生 PostgreSQL;10 张表、32 条路由 = 面 A 27 + 面 B 5)。 状态:v1 + v1.1(双面后端)已完成,验收门全绿(见 §0)。

怎么起

cd ~/Desktop/workspace/ssw-jnpf-lite-rust
bash run.sh install     # 一次性:cargo fetch + npm --prefix src/frontend install
bash run.sh build       # 一次性:cargo build --release + vite build
bash run.sh dev         # 日常:后台起后端(30010) + 前端(5173)
  • 前端:http://127.0.0.1:5173(vite dev server,/api 代理到后端)
  • 后端:http://127.0.0.1:30010(默认只监听本机;BIND_ADDR=0.0.0.0 才对外暴露)
  • 账号:admin / 123456(首次启动自动种子)
  • bash run.sh dev 的后端与前端都就绪才算成功(任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
  • bash run.sh logs 看日志(.logs/backend.log、.logs/frontend.log);bash run.sh stop 停(幂等)
  • 🔴 run.sh 的 kill_ports 是 kill -9 ⇒ 只清 30010 / 5173,绝不碰兄弟项目 tdc-rs 的端口
  • 🔴 打 localhost 用 curl 必须加 --noproxy '*'(本机 curl 走系统代理)

怎么复现验收(四门,逐字命令 + 通过标准)

门 命令 通过标准
① 编译 cargo build --release 0 error 0 warning
② 单测 cargo test 197 passed / 0 failed(8 个测试目标:83+6+19+24+3+18+7+37)
③ 冒烟 bash scripts/perm-smoke.sh(后端先起在 :30010) PASS=32 FAIL=0,退出码 0
③' 冒烟(面 B) bash scripts/perm-smoke-jnpf.sh(后端先起在 :30010) PASS=18 FAIL=0 SKIP=0 ⇒ 面 B 覆盖 18/18
④ 前端手验 bash run.sh dev ⇒ 浏览器开 http://127.0.0.1:5173 admin/123456 登录 → 菜单树正确 → 5 个管理页可增删改 → 3 个业务页可用 → 退出再登录

外加前置闸门:bash scripts/check-module.sh(9 接触点静态自检,纯静态、零 node 依赖; 期望 PASS=57 FAIL=0;无参 ⇒ 查全部三个业务模块)。

门④ 的浏览器手验清单(逐条):

  1. admin/123456 登录 ⇒ Dashboard 出现「功能菜单」;
  2. 菜单树 = 系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
  3. 4 个管理页(用户/角色/机构/菜单)从菜单按钮进入,页面标题正确,且可增删改;
  4. 3 个业务页(DemoItem / Product / Book)可达、可增删;
  5. 退出 ⇒ 回登录页 ⇒ 再登录 ⇒ 仍正常。

⚠️ 已知:react 版 Dashboard 只渲染「目录的子项」(node.children)⇒ Demo 示例 / 产品管理 / 图书超市是顶层页面型菜单(parentId='0',无子项)⇒ Dashboard 里没有按钮,只能按 URL 直达(/demo-item、/shop/Product、/books/Book)。 这是参照物原样行为(前端逐字复制 ⇒ 本仓未改),不是本仓的 bug。

已知限制(分支级)

摘自 docs/known-limitations.md 的「分支级已知限制清单」(完整版;下面是摘要):

  • (k) release 二进制没有 catch-all 的自动化覆盖(触发 panic 的端点是 #[cfg(test)] 专属; catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile 没有启用 abort 型 panic ⇒ 行为等价)。
  • (l) Path<String> 遇畸形百分号编码 ⇒ axum 默认返非信封的 400 响应 ⇒ ���� 已推翻 (最终整体评审修复轮 R=3 实测):axum 0.8.9 接受该转义 —— PUT /api/permission/Authority/Data/%zz 实测返回 HTTP 200 + {"code":600,"msg":"未登录","data":null} (信封,正常)⇒ 不存在「返非信封 400」这种破口,原裁决的前提不成立 ⇒ 不改代码。
  • (n) 冒烟脚本每次跑会往库里留一行 shop_product + 一行 book_shop_book + 一行 smoke_user (react 同款行为;契约 §13 未要求清理 ⇒ 不改)。 🔴 仅在复用外部后端时:两把尺子默认自起隔离实例(临时 PGLITE_DIR)⇒ 跑完即删、不留脏数据、 互不污染、CI 可跑(显式给了 B 才打外部库)。
  • (o) 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 cat: … No such file(观感,判据不受影响)。
  • (p) 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同 (code=无 vs code=ERR),退出码都是 2。
  • (x) token 的真实寿命 = 后端进程寿命(session.rs 是内存 token 表、没有 TTL): 登录响应里的 expiresIn: 7200 是契约 §6.1 逐字定死的字面量、不会被强制执行 (进程不重启就永不过期);契约未覆盖 TTL ⇒ 不改。

面 B(官方 JNPF 契约面)这一轮的已知限制(详见 docs/known-limitations.md §H 与 JNPF_COMPAT_SURFACE.md §8 的 B1–B10):

  • 面 B 已落地但仍有 10 条偏差:AuthorizeDataReturnVO.list 返空数组 · sysConfigInfo 返 {} · currentSystemId 固定为 ssw-jnpf-lite-rust · 无按钮/列/表单/数据级权限(B4/B5)· 三个业务菜单的 f_en_code 是自拟占位(B8,迁官方前须换真实编码)· permissionList 粒度 = 每菜单一条、modelId = 菜单 id(B9)· Organize/AsyncList 未分页(B10)。
  • 口令存储缺官方 secretkey 一步:本仓存 md5(明文),官方存 md5(lower(md5(明文)) + lower(secretkey)) ⇒ 迁官方时一次性换算即可,不需要明文(MIGRATION.md §7)。
  • 两套权限判据并存(不是 bug):面 A 按菜单路径 f_url_address,面 B 按点权限 f_en_code ⇒ 同一用户可能面 A 通、面 B 拒;种子菜单已补 8 条 f_en_code(存量库启动时只补 NULL,不覆盖已改值)。

Task 12 修复轮 R=1 另记两条 run.sh 的行为口径(不是缺陷,是刻意设计):

  • run.sh backend 用 exec 跑后端 ⇒ 后端自己的退出码原样透传(后端 panic 时是 101,不是子命令表里写的 1)。
  • run.sh stop 的实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ kill_ports(按端口 kill -9); pkill 只是最后一道兜底,且模式收窄到后端本体的完整路径 (macOS/BSD 的 pkill -f 匹配完整命令行,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉); vite 由 kill_ports 5173 按端口收,不会误杀别的项目的 vite dev server。

本任务(Task 12)另记四条已观察、未改的观察(留给最终整体评审裁决):

  • react 版 Dashboard 只渲染「目录的子项」 ⇒ 3 个顶层业务页在菜单里没有入口按钮(只能按 URL 直达: /demo-item、/shop/Product、/books/Book)。前端是逐字复制 ⇒ 改它会破「除代理端口外一字不改」的 硬约束 ⇒ 不改,只记档。(与契约 §8.4 的菜单表一致:m_demo/m_product/m_book 的 parent_id='0'。)
  • src/frontend/vite.config.ts 的注释仍写着「转发到 NestJS 后端(30010)」—— 本仓后端是 Rust。该注释行属于「代理目标行 + 紧邻注释行」两行允许改动范围, 但 brief 只授权把端口改成 30010 ⇒ 框架名逐字保留,不「顺手修好」(最终评审按 Minor 记)。
  • src/api/request.ts:5 的陈旧端口注释(写的仍是旧端口号)与 :31 的 axios 30 秒超时 (timeout 毫秒数,不是端口)⇒ 逐字保留(改了就破「除代理外一字不改」的 diff 门)。
  • /favicon.ico 在 vite dev server 上返 404(index.html 没有 favicon 引用)⇒ 浏览器 console 会有两条 404。 无害,且 index.html 是逐字复制 ⇒ 不改,只记档。

下一步(按 plan)

已完成:验收门全绿;本仓本体就是技能 ssw-jnpf-lite-rust(2026-10-26 第三段重排,见 .workbuddy/memory/2026-10-26.md)——仓根 = 技能根:SKILL.md 与 src/ scripts/ run.sh Cargo.toml references/ template-boot-jnpf/ 同仓(不再有「仓外技能副本」⇒ 不漂移、进 git)。 ~/.agents/skills/ssw-jnpf-lite-rust → 仓根(绝对软链); ~/.claude/skills/、~/.workbuddy/skills/、~/.qwenworkcn/skills/ 三处各放相对软链 ../../.agents/skills/ssw-jnpf-lite-rust,已逐一验证能读到 SKILL.md。 技能比 react 版多三份资产:面 B 规格(JNPF_COMPAT_SURFACE.md)· 官方源码核对(JNPF_SOURCE_AUDIT.md)· 迁移指南(MIGRATION.md),并自带第二把尺子 scripts/perm-smoke-jnpf.sh。

面 B 已落地(2026-10-26) —— S1–S6 全部完成,对照表见 JNPF_COMPAT_SURFACE.md §7:

步 内容 落点 状态
S1 判别头分流(Vue-Version: 3 ⇒ 面 B)+ 第二套守卫(f_en_code 判据) jnpf.rs / permission.rs / routes.rs ✅
S2 官方形状的 CurrentUser(PcUserVO 五字段) jnpf.rs / auth.rs ✅
S3 分页信封({pagination:{currentPage,pageSize,total}, list:[…]}) jnpf.rs ✅
S4 码表补齐(401 / 500 / 601 / 602——官方前端只在 601/602 清 token) envelope.rs ✅
S5 官方 RESTful 路径(/api/permission/Users / Role / Organize / Authority / /api/system/Menu) routes.rs ✅
S6 f_en_code 种子(8 条,存量库只补 NULL) seed.rs ✅

⇒ bash scripts/perm-smoke-jnpf.sh 已从 覆盖 5/18 走到 18/18; 面 A 零改动 ⇒ perm-smoke.sh 仍是 PASS=32 FAIL=0。

下一步(候选,需人拍板才动代码):

  1. 补齐面 B 的 B1–B10 偏差(按价值排序): B4/B5 按钮级 + 数据级权限(官方 base_module_button / _data)· B1 授权读 list 真返回 · B2 sysConfigInfo 真配置 · B6 导入导出 · B7 secretkey 换算链。
  2. 把官方 JNPF 前端真接进来(目前是「后端已就位,官方前端未实测」)—— 验证 Vue-Version: 3 分流在真实官方 axios 拦截器下无歧义。
  3. 反向验证路径:拿 react 版后端/官方 JNPF 版的数据灌进本仓,跑两把契约尺子, 证明「迁移期数据可比对」(这是本仓作为转换/验证框架的核心价值,目前只验了正向)。