Files
ssw-platform/MIGRATION.md
T
admin acf076df5a refactor: 内核瘦身 —— 示例搬成业务包 + 装配/测试各归其位
- 内核只有 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。
2026-11-04 14:46:12 +08:00

313 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 迁移指南(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/<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` 子命令(推荐)**
在 `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/<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 就能做完**):
```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 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单 |