- 内核只有 lib:启动装配 → crates/sspf-admin(bin sspf-admin);37 个集成测试 → crates/tests(package sspf-tests)。
- demo/shop/books 的 spec/菜单/DDL/面 B 路由搬进 packs/{demo,shop,books};内核 modules/*.rs 只剩「面 A 适配器 + pub use」⇒ 内核零业务知识,示例可整目录搬走。面 A 与前端零改动。
- 示例表 DDL 按平台规则补 f_tenant_id + 复合主键(spec 不加 ⇒ JSON 键与响应逐字不变)。
- 修 is_builtin_table 只认 schema.sql 的漏洞:包表(含 asset_data_resource)此前可被建模页删除/改;现为「平台 DDL ∪ 包表」。
- sspf-compat-online_dev → onlinedev(包名/模块/文件/路由别名同步);6 个 5 行转发壳合并为 forward.rs。
- 新增 AR16 闸门 + lib.rs「30 秒地图」+ src/backend/README.md;pack-sync 补两处判据(module_key=None 的 urlAddress、apiFile 查存在性)。
- 回归:704 tests / 6 道静态闸门全绿;health 181 表;四个包面 A/面 B 运行时全部 200。
17 KiB
迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)
本技能的价值不是「一个 JNPF 后台」,而是一个可双向搬运的框架: 官方 JNPF Java ↔ 本技能 Rust 模板 ⇄ react 版 NestJS,三者数据模型逐字同形(同一套
base_*表、同一套 cipher、同一套信封)。先读:
JNPF_SOURCE_AUDIT.md(官方源码逐行核对,带文件:行号)、JNPF_COMPAT_SURFACE.md(面 B 规格)、PERMISSION.md(权限与base_*表的红线)、SKILL.md§契约红线。
📌 本文的「本仓」= 本技能的 Rust 模板(
src/backend+src/frontend)。 模板与参照实现仓~/Desktop/workspace/ssw-jnpf-lite-rust/的src/逐字节一致(只差data/与dist/), 所以文中提到的文件/行号在两处都成立。
0. 迁移地图
| 起点 | 终点 | 性质 | 依据 |
|---|---|---|---|
| 本仓 Rust | 官方 JNPF Java | 近机械翻译(后端)+ 数据 ETL(base_*) |
本文 §2 / §6 / §7 |
| 本仓 Rust | react 版 NestJS | 换实现,不换契约 ⇒ 前端零改 | 本文 §5 |
| 官方 JNPF Java | 本仓 Rust | 走「面 B」(本仓已实现官方形状的那一面) | 本文 §4 |
| react 版 NestJS | 官方 JNPF Java | 见 react 技能 MIGRATION.md(同一套约定) |
— |
🔴 一句话:数据模型(base_* 表名/列名)与密文算法是三方共用的契约;
端点路径、响应形状、权限判定不是——那三层各框架自有风格,靠「双面后端」在同一个进程里并存。
1. 为什么"搬得快"——被刻意锁死的五件事
| # | 锁死的东西 | 值 | 不这么做会怎样 |
|---|---|---|---|
| 1 | base_* 表名/列名 |
官方 DDL 逐字(含两个故意不修正的陷阱) | 迁官方时导不进数据 ⇒ 重写 |
| 2 | 口令 cipher | md5(明文) → AES-256-ECB-PKCS7(key = md5("EY8WePvjM5GGwQzn") 的 32 个 ASCII 字节)→ hex |
前后端对不上 ⇒ 登录全挂 |
| 3 | 响应信封 | {code,msg,data},业务失败也 HTTP 200 |
前端拦截器全改 |
| 4 | 主键 | 36 位 UUID v4,列 varchar(50) |
数据类型/长度对不上 ⇒ 导不进 |
| 5 | JSON 键名 | 列名去 f_ 前缀后 camelCase |
前端全改 |
注意:这五条不包含「端点路径」和「列表响应形状」——那两件官方与本仓不同,
由「面 A / 面 B」两套并存来解决(见 JNPF_COMPAT_SURFACE.md §2)。
2. 后端:本仓 Rust → 官方 JNPF Java
2.1 逐件翻译表
| 本仓(Rust / axum 0.8) | 官方 JNPF Java | 说明 |
|---|---|---|
crates/sspf-admin/src/main.rs(装配 + --enc) |
ssw-admin(@SpringBootApplication) |
启动入口 |
routes.rs(Router 32 条路径 = 面 A 27 + 面 B 5) |
ssw-{appCode} 的 @RestController |
路径按官方风格改(见 §2.3) |
modules/<app>.rs 里的 EntitySpec / ColumnSpec |
Java 实体 extends SuperBaseEntity + @TableField("f_title") |
一个 spec ≈ 一个实体类:列清单逐字对应 |
crud.rs(spec 驱动的 CRUD 引擎) |
XxxService extends SuperServiceImpl<XxxMapper, XxxEntity> + XxxMapper extends SuperMapper |
官方是 MyBatis-Plus Join,不是 JPA |
sys.rs(5 组 base_* 显式 handler,1290 行) |
UserController / RoleController / OrganizeController / ModuleController / AuthorizeController |
本仓 5 个 handler → 官方 5 个 controller(一对一) |
permission.rs(四源合并 + 管理员短路) |
官方 @SaCheckPermission("permission.user") + SswPermissionGuard |
判据从「菜单路径」换成「权限编码」(base_module.f_en_code)⇒ 见 §2.4 |
auth.rs(登录 + 守卫) |
jnpf-oauth(Sa-Token)+ PasswordTokenGranter |
官方多一层 secretkey(§7) |
cipher.rs(md5 + AES-256-ECB) |
DesUtil.aesOrDecode + SecurityProperties.securityKey |
算法逐字节等价 ⇒ 不重写,只对齐两个配置值 |
envelope.rs(ActionResult{code,msg,data}) |
jnpf.base.ActionResult |
形状一致 ⇒ 前端零改 |
🔴 本仓代码分两层(迁官方时一一对应):
src/backend/src/platform/*(= 官方jnpf-common+jnpf-system)↔src/backend/src/modules/*(= 官方jnpf-admin)。 |db/schema.sql(12 张表) | 官方 DDL |base_*8 张逐字(含base_system,官方JNPF-PostgreSQL.sql:4243);业务表 4 张在官方没有 ⇒ 见 §6.2 | |db.rs(pglite 进程内 PG) | 真实 PostgreSQL(application.yml的master.url) | 方言一致 ⇒ SQL 基本不用改 | |ids.rs(UUID v4) |IdUtil.fastUUID()| 都是 36 位 | |session.rs(内存 token 表) | Sa-Token(Redis) | 官方多两个码601/602(见 §2.5) |
2.2 迁 JNPF 必备 import 速查
| 用途 | import |
|---|---|
| 实体基类 | jnpf.base.entity.SuperBaseEntity / SuperEntity / SuperExtendEntity |
| Mapper | jnpf.base.mapper.SuperMapper |
| Service | jnpf.base.service.SuperService + jnpf.base.service.SuperServiceImpl<M, T> |
| 返回信封 | jnpf.base.ActionResult.{success/fail/page} |
| 分页 | jnpf.base.Pagination + jnpf.base.vo.PaginationVO + jnpf.base.vo.PageListVO |
| 工具 | jnpf.util.{RandomUtil, UserProvider, JsonUtil} |
| 异常处理 | jnpf.exception.ResultExceptionHand(@RestControllerAdvice,裸异常 ⇒ code:400) |
| 鉴权(点权限) | Sa-Token @SaCheckPermission("permission.user") |
| 鉴权(菜单) | SswPermissionGuard.requireMenu(XxxController.class) |
SuperBaseEntity只有f_id一个字段(唯一强制)。f_tenant_id / f_last_modify_* / f_delete_time / f_delete_user_id属SuperEntity的可选增强层,不必补。
2.3 端点路径:这是唯一需要改设计的地方
本仓面 A 用 ssw 约定 /api/ssw/{appCode}/{Entity}/{List|Save|Delete};
官方是 RESTful:/api/permission/Users、/api/permission/Role(官方自己也不统一,单数)、
/api/system/Menu、/api/permission/Organize、/api/permission/Authority、动作 /{id}/Actions/{action}。
| 本仓面 A | 官方 |
|---|---|
GET/POST/DELETE /api/ssw/sys/User/{List,Save,Delete?id=} |
GET/POST /api/permission/Users · GET/PUT/DELETE /api/permission/Users/{id} |
GET/POST/DELETE /api/ssw/sys/Role/{…} |
/api/permission/Role(单数)· /{id} |
GET/POST/DELETE /api/ssw/sys/Organize/{…} |
/api/permission/Organize · /AsyncList/{id} |
GET/POST/DELETE /api/ssw/sys/Module/{…} |
/api/system/Menu · /{id} · /ModuleBySystem |
PUT /api/permission/Authority/Data/{objectId} |
同路径 ✅(body 官方是超集,本仓已兼容) |
GET /api/ssw/sys/Role/Modules?roleId= |
POST /api/permission/Authority/Data/{objectId}/Values |
🔴 不要把面 A 路径改成官方路径 —— 面 A 是 react 技能的前端在用的,改了就破契约。
要官方形状,走面 B(JNPF_COMPAT_SURFACE.md §3),两套并存于同一进程。
2.4 权限判据:菜单路径 → 权限编码
| 本仓 | 官方 | |
|---|---|---|
| 判据 | 菜单 f_url_address(如 system/User) |
base_module.f_en_code(如 permission.user) |
| 来源 | base_module 表 |
同一张表,另一个列 |
| 声明方式 | 路由守卫按 key 查 | @SaCheckPermission("permission.user") |
🔴 本仓的种子菜单目前没有 f_en_code(seed.rs 的 BuiltinMenu 结构体里没这个字段,
base_module 的 INSERT 是 12 个参数、不含它)⇒ 迁官方前必须补 f_en_code,
否则官方侧权限判据全是空(官方 PermissionConst.java:8-77 定义了对象码与 btn_* 码两套)。
2.5 码表补齐
| 码 | 含义 | 本仓 | 官方 | 动作 |
|---|---|---|---|---|
| 200 | 成功 | ✅ | ✅ | — |
| 400 | 业务失败 | ✅ | ✅ | — |
| 401 | 校验失败 | ❌ | ✅ | 迁官方时用上 |
| 403 | 无权限 | ✅ | ✅ | — |
| 500 | 异常 | ❌ | ✅ | 迁官方时用上 |
| 600 | 会话过期 | ✅ | ✅ | — |
| 601 | 会话离线 | ❌ | ✅ | — |
| 602 | 会话错误 | ❌ | ✅ | 🔴 官方前端 request.ts:78-80 只在 601/602 清 token ⇒ 只返 600 会让页面挂住 |
⇒ 面 B 落地时,面 B 的路由无 token 时返 602,面 A 保持 600。
3. 前端:三条路
| 方案 | 做法 | 代价 |
|---|---|---|
| A. 保留 React 前端 | 后端换 Java 后契约不变 ⇒ 零改 | 官方那套 Vue 组件库用不上 |
| B. 换 jweb (Vue) | 官方前端工程 apps/jnpf-web-apps-main/,按 api/<module>/<entity>.ts 封装 |
页面要重写(但 UX 可搬) |
| C. 双前端并存 | React 走面 A、jweb 走面 B,同一后端进程 | 需要两套构建;本仓「面 A/面 B」设计就是为它准备的 |
🔴 接官方 jweb 时前端必须补三个头(App-Code / Jnpf-Origin: pc / Vue-Version: 3,
官方 jnpf-web-apps-main/src/api/request.ts:109-112)。
其中 Vue-Version: 3 才是面 A/面 B 的判别依据——本仓 React 前端也发 App-Code 与
Jnpf-Origin: pc(src/frontend/src/api/request.ts:35-36,与官方同款),只有 Vue-Version 不发 ⇒ 零歧义。
菜单挂载:jweb 由菜单自动生成路由(base_module.f_url_address ↔ Route path 一一对应),
不要再手写 router.beforeEach。
4. 官方 JNPF → 本仓 Rust(反向)
这条路本仓已经铺好轨,官方前端可以直接跑在本仓上:
- 官方前端照常发
Vue-Version: 3⇒ 本仓判为面 B ⇒ 返回官方形状。 - 本仓面 B 已实现的部分(
JNPF_COMPAT_SURFACE.md§7 的 S1–S6): 官方登录(零改)、CurrentUser的PcUserVO、分页PageListVO、602码、菜单ModuleBySystem+f_en_code判据、授权Values读取。 - 本仓不实现(如实记录在
JNPF_COMPAT_SURFACE.md§8):按钮级权限(btn_*)、 数据权限方案、导入导出、完整权限树模型。
⇒ 官方前端的登录 + 菜单 + 用户/角色/组织/菜单列表能在本仓上跑; 授权弹窗的树、数据权限页、导入导出跑不了(这些页面会报错,但不影响其它页)。
验收:bash scripts/perm-smoke-jnpf.sh ⇒ 打印 「面 B 覆盖 N/18」,N 就是官方前端能跑通的面。
5. react 版 NestJS → 本仓 Rust
同一套契约 ⇒ 前端零改。两边可以开同一个库(业务表名故意对齐:demo_item / shop_product / book_shop_book)。
| 能力 | react 版(NestJS) | 本仓(Rust) |
|---|---|---|
| 端口 | 后端 :30000 |
后端 :30010(🔴 tdc-rs 占了 :30000) |
| 数据库 | 嵌入式 PGlite(WASM) | pglite-rs(进程内原生 PG) |
| 冒烟尺子 | scripts/perm-smoke.sh(22 条基线) |
scripts/perm-smoke.sh(32 条)+ perm-smoke-jnpf.sh(18 条) |
⚠️ 两版不要把数据目录指到同一处(pglite 单实例独占目录 ⇒ 第二个进程起不来)。
⚠️ 两版的 base_* 种子可以并存于同一库(表名/列名逐字同形),
但 f_account 官方无 UNIQUE ⇒ 建了同名账号会建两份。
6. 数据 ETL(诚实版)
6.1 base_* 7 张:表结构逐字同形 ⇒ 只导数据
官方 base_* 表由 JNPF 平台自动创建 ⇒ 不要用本仓 DDL 覆盖官方表结构,只导数据。
🔴 本仓的 pglite 是「进程内单用户 Postgres」,没有 TCP 端口
⇒ pg_dump / psql 连不上 ⇒ 常规 --data-only 那条路在本仓这侧走不通。
可行做法有两条:
(a) 给本仓加一个 --dump 子命令(推荐)
在 crates/sspf-admin/src/main.rs 的 parse_args(现只有 --enc)旁加一个 Cmd::Dump,
用 db.rs 里现成的执行入口跑:
COPY (SELECT * FROM base_user) TO STDOUT WITH CSV HEADER;
COPY (SELECT * FROM base_module) TO STDOUT WITH CSV HEADER;
-- …其余 5 张
把 CSV 交给官方侧 COPY base_user FROM STDIN WITH CSV HEADER 导入。
(db.rs 已有「持 db_lock 跑 SQL」的能力,dump 只是同一套机制多跑几条 SQL。)
(b) 直接在官方库侧手写 INSERT
本仓种子数据量极小(内置 2 角色 + 8 菜单 + 1 管理员 + 若干授权)⇒
用 PERMISSION.md §一的字段清单手写 INSERT 往往比导数据更快。
业务数据(demo_item / shop_product / book_shop_book)同理。
6.2 业务表 3 张:官方没有对应表 ⇒ 要先建实体
demo_item / shop_product / book_shop_book 是本仓/两版垫片自定义的(表名只为「两版后端能开同一个库」而对齐)。
迁官方时它们不是契约 ⇒ 两种做法:
- 保留表名:在 JNPF 里建三个实体,表名照填 ⇒ 迁回本仓时零改;
- 改成官方低代码实体名(推荐,符合官方工程习惯)⇒ 迁回本仓时改
modules/<app>.rs的table字段即可。
6.3 官方 DDL 的两个"故意不修正"的陷阱(迁的时候别顺手改)
| 陷阱 | 事实 | 后果 |
|---|---|---|
base_role_relation |
用户 id 在 f_object_id(配 f_object_type='user'),没有 f_user_id |
写错列 ⇒ 角色授权永不生效 |
base_user_relation |
组织/岗位关系在另一张表,那里才有 f_user_id |
写错表 ⇒ 组织/岗位授权永不生效 |
另:base_module.f_type 是 INTEGER(1 目录 / 2 页面),f_category 是 VARCHAR。
7. 口令换算(迁官方时必做,否则全员登不上)
7.1 两个公式
| 公式 | 出处 | |
|---|---|---|
| 本仓 / react 版 | 存 md5(明文) 的小写 hex |
本仓 cipher.rs / UserServiceImpl 简化版 |
| 官方 | 存 md5( lower(md5(明文)) + lower(secretkey) ),secretkey = 每用户随机 UUID |
UserServiceImpl.java:547-549、:704-706 |
官方登录时:decrypt(密文) 得 md5(明文) ⇒ 取 lower() ⇒ 拼 lower(secretkey) ⇒ md5 ⇒ 与库值比。
7.2 🔴 关键洞察:不需要明文
本仓库里的值 = md5(明文) 的小写 hex = 官方公式的第一个加数(lower(md5(明文)))。
⇒ 换算公式(一次 SQL 就能做完):
-- 对每一行:先给一个随机 secretkey,再把口令重算成官方格式
UPDATE base_user
SET f_secretkey = <新随机 UUID>,
f_password = md5(lower(f_password) || lower(<新随机 UUID>));
f_password列已存在(本仓db/schema.sql:142;官方 DDL:4503)⇒ DDL 不用改。- 换算幂等性要注意:公式只适用于「
f_password还是裸md5(明文)」的库。 重复执行会把公式套在公式上 ⇒ 不可逆地错。⇒ 换算前先备份(backup_create/pg_dump)。
7.3 换算自证
# 1. 换算前:取一行,记住 account 与 f_password
# 2. 换算后:用**同一个明文**走一遍官方登录链路
# 本仓的等价物:md5(明文) → AES 密文 → POST /api/oauth/Login
# 3. 官方侧登录成功 ⇒ 换算正确
⚠️ 本仓的登录只比 md5(明文) ⇒ 换算成官方格式后本仓就登不上了(预期)。
⇒ 换算是单向操作:迁到官方前做一次,且先备份。
8. 验证
迁移前(本仓基线必须全绿):
bash scripts/perm-smoke.sh # 面 A:32 条 —— 「没把原契约改坏」
bash scripts/perm-smoke-jnpf.sh # 面 B:18 条 —— 「官方形状达标」(打印「面 B 覆盖 N/18」)
bash scripts/check-module.sh # 业务模块 9 接触点静态自检
迁移后(官方库上):
# 面 A 尺子打官方后端:路径不同 ⇒ 只能打面 B 尺子
B=http://<官方后端> bash scripts/perm-smoke-jnpf.sh
🔴 两把契约尺子必须同时绿(perm-smoke.sh / perm-smoke-jnpf.sh;另有四道静态闸门 ⇒ 合计六道闸门):
面 A 绿证明「没把原契约改坏」,面 B 绿证明「官方形状达标」。
9. 明确不做
- 低代码引擎(表单/流程/代码生成)—— 官方能力,本仓不碰。
- 多租户(
jnpf-tenant*)—— 单租户固定f_tenant_id='0'。 - 按钮/列/表单/数据范围级授权 —— 官方 DDL 里都有,v1 只做
item_type='module'(菜单)。 - Redis / Sa-Token —— 内存 token 表即可。
- 分页(面 A) —— 面 A 的
List就是全量(前端不分页);分页是面 B 的事。
10. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-26 | 首版:三方双向迁移地图、Rust→Java 逐件翻译、import 速查、端点路径差异表、权限判据差异、码表补齐表、三条前端路线、数据 ETL(pglite 无 TCP 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单 |