Files
ssw-platform/MIGRATION.md
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

17 KiB
Raw Blame History

迁移指南(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 说明
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(反向)

这条路本仓已经铺好轨,官方前端可以直接跑在本仓上:

  1. 官方前端照常发 Vue-Version: 3 ⇒ 本仓判为面 B ⇒ 返回官方形状。
  2. 本仓面 B 已实现的部分(JNPF_COMPAT_SURFACE.md §7 的 S1–S6): 官方登录(零改)、CurrentUser 的 PcUserVO、分页 PageListVO、 602 码、菜单 ModuleBySystem + f_en_code 判据、授权 Values 读取。
  3. 本仓不实现(如实记录在 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 子命令(推荐)

在 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 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单