Files
ssw-jnpf-lite-rust/docs/MIGRATION.md
T
adminandClaude Code 806f9f8454 feat(jnpf): 面 B(官方 JNPF 契约面)S1–S6 全部落地 —— 双面后端成形
影响:同一进程现在同时提供面 A(ssw/react 契约,27 条,冻结)与面 B
(官方 JNPF 形状,5 条新增 + 2 条共用按判别头分流)。官方 JNPF 前端
可以直接打在本仓上;两把尺子由「面 B 覆盖 5/18」走到「18/18 全绿」,
面 A 尺子零回归(仍 PASS=32)。

改动:
- src/backend/src/jnpf.rs(新):判别头 `Vue-Version: 3` · `PcUserVO` 5 字段
  · `PageListVO` / `ListVO` 分页信封 · 点权限守卫 · 5 个官方 RESTful 端点。
- src/backend/src/permission.rs:新增 `has_en_code_permission()` —— 第二套
  判据(按 `base_module.f_en_code`),结构同面 A:管理员短路 → 查授权 →
  未映射放行 → 四源成员 → DB 出错拒绝。
- src/backend/src/auth.rs:`require_login_any()` —— 面 A 未登录 `600`、
  面 B 未登录 `602`(官方前端只对 `601`/`602` 清 token ⇒ 返 `600` 会卡死)。
- src/backend/src/envelope.rs:码表补齐 `401`/`500`/`601`/`602`。
- src/backend/src/routes.rs:注册面 B 5 条路由 + 两个路由表钉子测试
  (`route_table_is_pinned` 27 条 / `jnpf_route_table_is_pinned` 5 条)。
- src/backend/src/seed.rs:8 条内置菜单补 `f_en_code`(存量行只补 NULL,
  不覆盖已改值、不复活已删);src/backend/src/sys.rs:`query_param` 放开
  供面 B 复用官方分页参数。
- 文档同步:CLAUDE.md(红线 10/11 + 端点全表拆两面)、README.md、
  HANDOFF.md、docs/{contract,runbook,MIGRATION,JNPF_SOURCE_AUDIT,
  JNPF_COMPAT_SURFACE,known-limitations}.md。

设计:两套权限判据**并存**(面 A 按菜单路径、面 B 按点权限)⇒ 同一用户
可能面 A 通、面 B 拒,这不是 bug。`permissionList` 粒度 = 每菜单一条
(`modelId` = 菜单 id),依据官方前端 dynamicModel/list/index.vue:739
做 `permissionList.find(o => o.modelId === menuId)` 且容忍缺项。

已知偏差 B1–B10 记在 known-limitations.md §H(授权读 list 空数组 ·
sysConfigInfo={} · 无按钮级权限 · 无数据级权限 · 无导入导出 ·
缺 secretkey 一步 · 业务菜单 f_en_code 是自拟占位 · AsyncList 未分页)。

验证:cargo test 195 passed / 0 failed(8 个测试目标);
perm-smoke.sh(面 A)PASS=32 FAIL=0;
perm-smoke-jnpf.sh(面 B)PASS=18 FAIL=0 SKIP=0;
check-module.sh PASS=57 FAIL=0。

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 11:28:47 +08:00

16 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 规格)、 contract.md(本仓契约唯一真源)。


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)
entities.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 形状一致 ⇒ 前端零改
db/schema.sql(10 张表) 官方 DDL base_* 7 张逐字;业务表 3 张在官方没有 ⇒ 见 §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 管理员 + 若干授权)⇒ 用 docs/contract.md 的字段清单手写 INSERT 往往比导数据更快。 业务数据(demo_item / shop_product / book_shop_book)同理。

6.2 业务表 3 张:官方没有对应表 ⇒ 要先建实体

demo_item / shop_product / book_shop_book 是本仓/两版垫片自定义的(表名只为「两版后端能开同一个库」而对齐)。 迁官方时它们不是契约 ⇒ 两种做法:

  • 保留表名:在 JNPF 里建三个实体,表名照填 ⇒ 迁回本仓时零改;
  • 改成官方低代码实体名(推荐,符合官方工程习惯)⇒ 迁回本仓时改 entities.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

🔴 两把尺子必须同时绿:面 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 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单