- 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
49 KiB
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。
四个踩过的坑(平台侧/消费侧各修了,留作教训)
lib/必须是构建产物deps/的整目录副本(.rlib+.rmeta+ proc-macro.dylib- 原生
.a)。只拷lib*.rlib会漏serde_derive/tokio_macros的.dylib⇒E0463 can't find crate for sspf。
- 原生
- 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会选到旧的那个。) - 消费方必须用平台那份 axum:sspf 公共 API 带
axum::Json/http::HeaderMap/bytes::Bytes。 本仓若自己编 axum 就是「同名 crate 两实例」⇒ 跨边界E0308 mismatched types。 ⇒ 本仓[workspace.dependencies]清空、backend 去掉 axum/tokio,全部走--extern。 - 消费方 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)。
做了什么
- 删除自研平台:
src/backend/src/platform/(17 文件)、routes.rs(35K)、bootstrap.rs、db/schema.sql、tests/(7 个集成测试,测的是被删的那份实现)。 备份在/tmp/skill-backup/backend-2216/。 - 平台改为依赖已发布包:根
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-*被平台带进来。 - 示例业务包迁入:
packs/{demo,shop,books,asset}/(表 DDL + 列 + 菜单 + 面 B 路由), 依赖从sspf-sdk改为门面sspf;use sspf_sdk::…→use sspf::…。 - 应用瘦成薄壳(
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转发)。
- 脚本重构:
- 新增
check-scaffold.py(SC1–SC6「本仓只准有业务」+--self-test6/6); - 新增
pack-sync.py(重写:4 处派生位置,--check防漂移); - 新增
new-pack.sh/new-pack.py(造包脚手架,端到端验证过); - 新增
verify.sh(一键 7 步 /--fast4 步); - 删除
check-module.sh/check-boundary{,-scan}/check-contract{,-scan}/check-citations{,-scan}: 它们测的是本仓那份平台实现(分层 / 契约对账 / 引文),平台搬走后没有测量对象 ⇒ 留着就是假绿。
- 新增
- 契约同步:
docs/contract.md补入asset包 ——[MENU]+1、[MENU_TREE]→ 9 菜单 (…|图书超市:|数据资源:)、[MODULE]+1、[ENDPOINT]+3(面 A)、[FACE]A 25 → 28。 §8.4 的「值住在哪」改为「平台在sspf,业务在packs/<app>/」。 - 文档:
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 |
|
| 4 | 运行时拓扑? | 先不碰 tdc-rs,独立仓做 | tdc-rs 已占它自己的后端端口,且已有自己的 /api/oauth/Login(JSON 账号库),两套同路径不同语义会打架 |
| 5 | 目录名? | ssw-jnpf-lite-rust(正式名称,2026-10-26 用户改定) |
tds-lite-rs |
| 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 做完的样子):
- 用 Rust 起一个单二进制、零外部服务的后端,行为与
ssw-jnpf-lite-react(NestJS)逐条一致。 - 前端一行不改就能跑通(直接复用 react 技能的
src/frontend)。 base_*表结构与官方 DDL 逐字一致 ⇒ 迁 JNPF 时导数据即可(--data-only)。- 权限闭环(登录 → 菜单树 → 建用户 → 授权 → 收窄 → 403)有自动化冒烟钉住。
- 跑通之后,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/enCodeadmin/管理员/sort 1;role_user/enCodeuser/使用者/sort 2 - 菜单(
f_type:1=目录 2=页面):id fullName urlAddress parentId type icon sortCode m_sys系统管理 system01 setting 1 m_user用户管理 system/Userm_sys2 — 2 m_role角色管理 system/Rolem_sys2 — 3 m_org机构管理 system/Organizem_sys2 — 4 m_menu菜单管理 system/Modulem_sys2 — 5 m_demoDemo 示例 demo-item02 app 6 m_product产品管理 shop/Product02 app 7 m_book图书超市 books/Book02 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 三个关键取舍
- 业务实体走 spec 引擎,
base_*走显式 handler。 理由:业务模块语义同构(列表/保存/软删/守卫),声明化后"加一个模块 = 加一条 spec"; 而base_*的语义(一维授权数组、用户↔角色关系、机构树防环、账号唯一性)塞不进通用引擎, 硬塞会得到一个既不懂 JNPF 又难懂的框架。 - numeric 列在 SQL 投影里就 cast 成 text。
理由:
row_to_json直接给数字 ⇒ serde_json 解析成 f64 ⇒ 回显9.9⇒ 契约破。 在投影层f_price::text AS price才是"一次解决、处处一致"。 - 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 逐条移植):
- 无 token 访问
User/List⇒code=600 - 加密登录 ⇒
code=200;3. 拿到 token(非空) CurrentUser⇒code=200- 菜单树与种子表逐字相等(推荐做法:把 §3.2 的菜单表搬进脚本作字面量)
- 建用户 ⇒
code=200 - 重复账号 ⇒ HTTP 200(不是 500)且
code=400且 msg'账号已存在:smoke_user' - 写授权(一维数组)⇒
code=200;9. 写授权(二维兼容)⇒code=200 - 非管理员登录 ⇒
code=200 - 非管理员菜单已收窄(字符串比对)
- 非管理员访问
User/List⇒code=403 - 已授权业务(demo)⇒
code=200 - 未知路由 ⇒ HTTP 404(不被吞掉)
- admin 短路 ⇒ Product 列表
code=200 - Product 新建 ⇒
code=200;17. 主键 36 位;18. numeric 往返"9.90" - 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. 开放问题(开工时按需裁决,不阻塞)
git首个 commit 何时做 —— 目录已git init但未 commit。建议步骤 0 结束就 commit 一次骨架。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 复制。--enc子命令的参数形式 —— 建议./ssw-jnpf-lite-rust --enc 123456(打印 hex 到 stdout,退出码 0); 未知参数按--help处理。- 是否需要
/api/health—— react 版没有。建议加({ok, tables, version}),便于冒烟探活,但不是契约。 - 抽技能的目标目录名 —— 建议
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;无参 ⇒ 查全部三个业务模块)。
门④ 的浏览器手验清单(逐条):
admin/123456登录 ⇒ Dashboard 出现「功能菜单」;- 菜单树 = 系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
- 4 个管理页(用户/角色/机构/菜单)从菜单按钮进入,页面标题正确,且可增删改;
- 3 个业务页(DemoItem / Product / Book)可达、可增删;
- 退出 ⇒ 回登录页 ⇒ 再登录 ⇒ 仍正常。
⚠️ 已知: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)
⇒ ���� 已推翻 (最终整体评审修复轮 R=3 实测):axum 0.8.9 接受该转义 ——Path<String>遇畸形百分号编码 ⇒ axum 默认返非信封的 400 响应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=无vscode=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。
下一步(候选,需人拍板才动代码):
- 补齐面 B 的 B1–B10 偏差(按价值排序):
B4/B5 按钮级 + 数据级权限(官方
base_module_button/_data)· B1 授权读list真返回 · B2sysConfigInfo真配置 · B6 导入导出 · B7secretkey换算链。 - 把官方 JNPF 前端真接进来(目前是「后端已就位,官方前端未实测」)——
验证
Vue-Version: 3分流在真实官方 axios 拦截器下无歧义。 - 反向验证路径:拿 react 版后端/官方 JNPF 版的数据灌进本仓,跑两把契约尺子, 证明「迁移期数据可比对」(这是本仓作为转换/验证框架的核心价值,目前只验了正向)。