# 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java) > 本技能的价值不是「一个 JNPF 后台」,而是**一个可双向搬运的框架**: > 官方 JNPF Java ↔ 本技能 Rust 模板 ⇄ react 版 NestJS,三者**数据模型逐字同形**(同一套 `base_*` 表、同一套 cipher、同一套信封)。 > > **先读**:[`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(官方源码逐行核对,带 `文件:行号`)、 > [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)(面 B 规格)、 > [`PERMISSION.md`](PERMISSION.md)(权限与 `base_*` 表的红线)、 > [`SKILL.md`](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/.rs` 里的 `EntitySpec` / `ColumnSpec` | Java 实体 `extends SuperBaseEntity` + `@TableField("f_title")` | **一个 spec ≈ 一个实体类**:列清单逐字对应 | | `crud.rs`(spec 驱动的 CRUD 引擎) | `XxxService extends SuperServiceImpl` + `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` | | 返回信封 | `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//.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` 子命令(推荐)** 在 `crates/sspf-admin/src/main.rs` 的 `parse_args`(现只有 `--enc`)旁加一个 `Cmd::Dump`, 用 `db.rs` 里现成的执行入口跑: ```sql 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/.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 就能做完**): ```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 换算自证 ```bash # 1. 换算前:取一行,记住 account 与 f_password # 2. 换算后:用**同一个明文**走一遍官方登录链路 # 本仓的等价物:md5(明文) → AES 密文 → POST /api/oauth/Login # 3. 官方侧登录成功 ⇒ 换算正确 ``` ⚠️ 本仓的登录**只比 `md5(明文)`** ⇒ 换算成官方格式后**本仓就登不上了**(预期)。 ⇒ 换算是**单向操作**:迁到官方前做一次,且**先备份**。 --- ## 8. 验证 **迁移前**(本仓基线必须全绿): ```bash bash scripts/perm-smoke.sh # 面 A:32 条 —— 「没把原契约改坏」 bash scripts/perm-smoke-jnpf.sh # 面 B:18 条 —— 「官方形状达标」(打印「面 B 覆盖 N/18」) bash scripts/check-module.sh # 业务模块 9 接触点静态自检 ``` **迁移后**(官方库上): ```bash # 面 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 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单 |