- 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/:前端接口清单、页面依赖反查、运行时探针
436 lines
25 KiB
Markdown
436 lines
25 KiB
Markdown
# 面 B:官方 JNPF 契约面(规格书)
|
||
|
||
> **这份文档是「尺子的规格」** —— [`scripts/perm-smoke-jnpf.sh`](scripts/perm-smoke-jnpf.sh) 逐条断言的就是本文的每一条。
|
||
> 官方源码依据见 [`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(每条带 `文件:行号`)。
|
||
|
||
---
|
||
|
||
## 0. 一句话
|
||
|
||
**面 A** = 本仓现有契约(ssw/react 技能那套),**一个字都不动**。
|
||
**面 B** = 官方 JNPF 契约(官方 Vue 前端那套),**与面 A 共用同一个进程、同一个库、同一套 `base_*` 表**。
|
||
|
||
⇒ 官方 JNPF 的 Vue 前端,可以**直接**指着本仓的后端跑;本仓的 React 前端,也**照旧**跑。
|
||
|
||
---
|
||
|
||
## 1. 为什么需要面 B
|
||
|
||
审计结论([`JNPF_SOURCE_AUDIT.md` §3](JNPF_SOURCE_AUDIT.md)):
|
||
|
||
| 差异 | 能否靠「改前端」绕过 | 结论 |
|
||
|---|---|---|
|
||
| D2 列表响应(`PageListVO`) | ❌ 官方前端分页组件要 `pagination.total` | **必须后端出** |
|
||
| D3 `CurrentUser` 形状(`PcUserVO`) | ❌ 官方前端读 `permissionList` / `userInfo.*` | **必须后端出** |
|
||
| D4 码表缺 602 | ❌ 官方前端靠 602 清 token 跳登录 | **必须后端出** |
|
||
| D5 菜单接口(`ModuleBySystem`) | ❌ 官方前端启动就调 | **必须后端出** |
|
||
| D6 点权限(`f_en_code`) | ⚠️ 可前端硬编码,但不可维护 | 后端出更好 |
|
||
| D1 端点风格 | ✅ 官方前端路径写死 | **必须后端出**(新路径) |
|
||
| D7 请求头 | ✅ 忽略即可 | 后端**别拒** |
|
||
| D8 口令存储 | ✅ 换算期处理 | 迁移期一次性 |
|
||
|
||
⇒ 结论:**「官方前端 → Rust 后端能跑」这件事,后端必须有一层官方形状**。这就是面 B。
|
||
|
||
---
|
||
|
||
## 2. 面 A / 面 B 的边界规则
|
||
|
||
### 2.1 路由层:面 B = 新增路径 + 少数共用路径
|
||
|
||
| 情况 | 处理 |
|
||
|---|---|
|
||
| 官方路径与面 A **不冲突**(`/api/permission/*`、`/api/system/*`) | **新增**面 B 路由,与面 A 并存 |
|
||
| 官方路径与面 A **冲突**(`/api/oauth/Login`、`/api/oauth/CurrentUser`、`PUT /api/permission/Authority/Data/{objectId}`) | **共用同一路由**,按规则分流(见 §2.2) |
|
||
| 官方请求体是面 A 请求体的**超集**(授权写) | 直接兼容,**零改动** |
|
||
|
||
### 2.2 共用路由的分流规则:**按请求头 `Vue-Version: 3` 判面**
|
||
|
||
官方前端**必然**带这三个头(`jnpf-web-apps-main/src/api/request.ts:109-112`):
|
||
|
||
```
|
||
App-Code: <应用编码>
|
||
Jnpf-Origin: pc
|
||
Vue-Version: 3
|
||
```
|
||
|
||
🔴 **本仓前端带其中两个**(`src/frontend/src/api/request.ts:35-37`,与官方同款):
|
||
|
||
```ts
|
||
config.headers.set('App-Code', 'sswflow');
|
||
config.headers.set('Jnpf-Origin', 'pc'); // ← 官方也有 ⇒ **不能**用它判别
|
||
if (token) config.headers.set('Authorization', token);
|
||
```
|
||
|
||
⇒ 三个官方头里,**本仓前端唯一不发的是 `Vue-Version`** ⇒ 判别只能用它。
|
||
|
||
⇒ **判定规则(唯一规则,全局生效)**:
|
||
|
||
```
|
||
请求头含 "Vue-Version: 3" ⇒ 走【面 B】官方形状
|
||
否则 ⇒ 走【面 A】ssw 形状
|
||
```
|
||
|
||
**为什么用这个头**:官方前端**无条件**携带 `Vue-Version: 3`,而本仓前端**从不**携带 ⇒ 零歧义、零配置、双方都不需要改。
|
||
(`App-Code` 与 `Jnpf-Origin` **不作**判据 —— 本仓前端也发这两个,判了必错。)
|
||
|
||
🔴 **红线:本仓前端禁止发 `Vue-Version` 头**(一旦发出,面 A 的请求会被误判成面 B ⇒ 契约整体错位)。
|
||
`scripts/check-module.sh` 的「全局红线」段**静态钉住**这一条(查 `src/frontend/src/api/request.ts`),
|
||
面 B 尺子 `scripts/perm-smoke-jnpf.sh` 也**必须**带 `Vue-Version: 3`(否则面 B 请求不会被识别成面 B)—— 同一处静态自检。
|
||
|
||
### 2.3 三个共用路由的逐条结论
|
||
|
||
| 路由 | 面 A 现状 | 面 B 要求 | 判定 |
|
||
|---|---|---|---|
|
||
| `POST /api/oauth/Login` | `{token, expiresIn:7200, tokenTypeName:'bearer'}` | 官方读 `data.token`(`LoginVO.java:17`) | ✅ **零改动**(官方前端忽略多余字段) |
|
||
| `PUT /api/permission/Authority/Data/{objectId}` | body `{objectType, module:[…]}` | 官方 body = `{objectType, module, button, column, resource, form, systemIds}`(`AuthorizeDataUpForm.java:14-38`) | ✅ **零改动**(官方 body 是面 A 的**超集**;面 A 只消费 `objectType`+`module`) |
|
||
| `GET /api/oauth/CurrentUser` | `{userInfo:{4 字段}, menuList:[本仓自定义节点]}` | 官方 `PcUserVO`(`PcUserVO.java:16-34`) | ⚠️ **必须分流**(§3.3) |
|
||
|
||
---
|
||
|
||
## 3. 面 B 端点规格
|
||
|
||
### 3.1 认证
|
||
|
||
#### `POST /api/oauth/Login`
|
||
|
||
- **共用面 A**,零改动。
|
||
- 请求:`application/x-www-form-urlencoded`,`account` / `password`(密文 hex) / `grant_type=password`。
|
||
- 响应:`ActionResult<{token, expiresIn, tokenTypeName}>`。官方前端只读 `data.token` ⇒ 兼容。
|
||
|
||
#### `GET /api/oauth/CurrentUser` ★ **形状分流点**
|
||
|
||
**面 A 形状**(无 `Vue-Version` 头)——**不动**:
|
||
|
||
```json
|
||
{ "code":200, "msg":"操作成功", "data":{
|
||
"userInfo":{ "userId":"…","userAccount":"admin","userName":"admin","isAdministrator":true },
|
||
"menuList":[ …本仓菜单节点… ] } }
|
||
```
|
||
|
||
**面 B 形状**(带 `Vue-Version: 3`)——官方 `PcUserVO`:
|
||
|
||
```json
|
||
{ "code":200, "msg":"操作成功", "data":{
|
||
"menuList":[ { "id":"…","fullName":"系统管理","enCode":"…","parentId":"0","icon":"…",
|
||
"hasChildren":true,"urlAddress":"system/User","pageAddress":"…","linkTarget":null,
|
||
"children":[…],"type":1,"propertyJson":null,"sortCode":0,
|
||
"systemId":"…","isData":false } ],
|
||
"permissionList":[ { "modelId":"…","moduleName":"…","button":[],"column":[],"resource":[],"form":[] } ],
|
||
"userInfo":{ "userId":"…","userAccount":"admin","userName":"…","isAdministrator":true,
|
||
"headIcon":null,"organizeId":"…","organizeName":"…",
|
||
"positionId":"…","positionName":"…","systemId":"…","systemCode":"…",
|
||
"prevLogin":1,"prevLoginTime":…,"prevLoginIPAddress":null,"prevLoginIPAddressName":null },
|
||
"currentSystemId":"…",
|
||
"sysConfigInfo":{ … } } }
|
||
```
|
||
|
||
**字段依据**:
|
||
- `PcUserVO.java`:`:19` menuList / `:22` permissionList / `:25` userInfo / `:27` currentSystemId / `:33` sysConfigInfo
|
||
- `AllMenuSelectVO.java`:`:12` id / `:15` fullName / `:18` enCode / `:21` parentId / `:24` icon / `:27` hasChildren / `:30` urlAddress / `:33` pageAddress / `:36` linkTarget / `:39` children / `:42` type / `:44` propertyJson / `:46` sortCode / `:48` systemId / `:50` isData
|
||
- `PermissionModel.java`:`:10` modelId / `:12` moduleName / `:14` button / `:16` column / `:18` resource / `:20` form
|
||
- `UserCommonInfoVO.java`:`:16` userId / `:19` userAccount / `:22` userName / `:25` headIcon / `:28` organizeId / `:31` organizeName / `:34` positionId / `:37` positionName / `:40` prevLogin / `:43` prevLoginTime / `:47` prevLoginIPAddress / `:51` prevLoginIPAddressName / `:75` isAdministrator / `:83` systemId / `:87` systemCode
|
||
|
||
**硬性要求**:
|
||
1. 五个顶层字段**一个都不能少**(官方前端按 `menuList` + `permissionList` 渲染侧栏与按钮)。
|
||
2. `menuList` 节点的 `type`:`1`=目录 / `2`=页面(与 `base_module.f_type` 语义一致)。
|
||
3. `permissionList` 可为空数组 `[]`(**但不能是 `null`**)—— 官方前端遍历它。
|
||
|
||
> 📌 **不实现** `sysConfigInfo` 的真实内容时,返 `{}`(空对象)而不是 `null` ⇒ 官方前端不炸。
|
||
|
||
#### `POST /api/oauth/Logout` — 可后置
|
||
|
||
官方 `LoginController.java:155`。本仓 v1 无此端点(前端本地清 token)。
|
||
**优先级:低**(官方前端退出时若 404,会在控制台报错但不影响使用)。
|
||
|
||
### 3.2 用户 `/api/permission/Users`
|
||
|
||
**列表** `GET /api/permission/Users`
|
||
|
||
请求参数(`UserPagination.java:11-36` = `Pagination.java:19-29` + 过滤):
|
||
|
||
| 参数 | 类型 | 默认 | 说明 |
|
||
|---|---|---|---|
|
||
| `pageSize` | long | `20` | `Pagination.java:19` |
|
||
| `currentPage` | long | `1` | `Pagination.java:25` |
|
||
| `sort` | string | `"DESC"` | `Pagination.java:21` |
|
||
| `sidx` | string | `""` | `Pagination.java:23` |
|
||
| `keyword` | string | — | 关键字(`Pagination` 父类 `Page`) |
|
||
| `gender` | string | — | `UserPagination.java:14` |
|
||
| `enabledMark` | int | — | `:17`(0 禁用 / 1 启用 / 2 锁定 / 12 启用和锁定) |
|
||
| `groupId` / `organizeId` / `positionId` / `roleId` | string | — | `:20/23/26/29` |
|
||
| `showSubOrganize` | int | — | `:32` |
|
||
| `dataType` | int | — | `:35`(1 = 全部数据) |
|
||
|
||
响应(`UserController.java:295` ⇒ `ActionResult<PageListVO<UserListVO>>`):
|
||
|
||
```json
|
||
{ "code":200, "msg":"操作成功", "data":{
|
||
"pagination":{ "currentPage":1, "pageSize":20, "total":42 },
|
||
"list":[ { "id":"…","account":"admin","realName":"管理员","fullName":"管理员",
|
||
"gender":null,"mobilePhone":null,"email":null,"organize":"…",
|
||
"description":null,"enabledMark":1,"creatorTime":1730000000000,
|
||
"sortCode":0,"lockMark":0,"handoverMark":0,"isAdministrator":1,
|
||
"headIcon":null,"unlockTime":null,"position":"…",
|
||
"isDutyUser":0,"maxRelationId":null } ] } }
|
||
```
|
||
|
||
**列表项字段依据**:`UserListVO.java:19-74`。
|
||
**硬性要求**:
|
||
1. `data` 必须是**对象**(含 `pagination` + `list`),**不是**裸数组。
|
||
2. `list` 项**不得**含 `password` / `secretkey`。
|
||
3. `pagination.total` = **总条数**(不是本页条数)。
|
||
4. `currentPage` / `pageSize` **原样回显**请求值(官方前端会算总页数)。
|
||
5. `creatorTime` 是**毫秒时间戳(数字)**。
|
||
6. `isAdministrator` 是**数字** `0|1`(不是布尔)—— 官方 VO 是 `Integer`(`UserListVO.java:60`)。
|
||
|
||
**单条 / 增 / 改 / 删**(`UserController.java:355/409/429/496`):
|
||
|
||
| 方法 | 路径 | 官方权限码 | 面 B 行为 |
|
||
|---|---|---|---|
|
||
| GET | `/api/permission/Users/{id}` | `permission.user` | 返 `UserListVO` 同构单对象 |
|
||
| POST | `/api/permission/Users` | `permission.user` | 建号;body 用**去前缀名**(`account`/`realName`/`organizeId`/…) |
|
||
| PUT | `/api/permission/Users/{id}` | `permission.user` | 改;body 同上 + `id` 在 path |
|
||
| DELETE | `/api/permission/Users/{id}` | `permission.user` | 删;成功返 `ActionResult.success()` |
|
||
|
||
**权限码语义(面 B)**:官方用 `@SaCheckPermission("permission.user")` ⇒ 判定依据是
|
||
**该用户是否持有 `f_en_code = 'permission.user'` 的菜单授权**(`base_module.f_en_code`)。
|
||
本仓的菜单路径白名单(`system/User`)在面 B **不适用** ⇒ 面 B 用 `f_en_code` 判。
|
||
|
||
> 🔴 **这意味着面 B 必须能读到 `f_en_code` 且种子菜单要带 `f_en_code` 值。**
|
||
> 本仓 `base_module` 表**已有 `f_en_code` 列**(官方 DDL 逐字)⇒ 列在,**值要补种子**。
|
||
|
||
### 3.3 角色 `/api/permission/Role`
|
||
|
||
| 方法 | 路径 | 官方出处 | 权限码 |
|
||
|---|---|---|---|
|
||
| GET | `/api/permission/Role` | `RoleController.java:99-100` | `permission.auth` OR `permission.role` |
|
||
| GET | `/api/permission/Role/{id}` | `:273` | `permission.role` |
|
||
| POST | `/api/permission/Role` | `:122` | `permission.role` |
|
||
| PUT | `/api/permission/Role/{id}` | `:165` | `permission.role` |
|
||
| DELETE | `/api/permission/Role/{id}` | `:298` | `permission.role` |
|
||
| GET | `/api/permission/Role/Selector` | `:327` | 登录即可 |
|
||
|
||
列表响应:`ActionResult<PageListVO<RoleListVO>>`(`RoleController.java:101`)—— 形状同 §3.2 的列表规则。
|
||
|
||
### 3.4 组织 `/api/permission/Organize`
|
||
|
||
| 方法 | 路径 | 官方出处 | 权限码 |
|
||
|---|---|---|---|
|
||
| GET | `/api/permission/Organize/AsyncList/{id}` | `OrganizeController.java:107-110` | `permission.organize` OR `permission.user` OR `permission.role` OR … |
|
||
| GET | `/api/permission/Organize` | 前端 `organize.ts:14` | 登录即可 |
|
||
| GET | `/api/permission/Organize/{id}` | `:290` | `permission.organize` |
|
||
| POST | `/api/permission/Organize` | `:179` | `permission.organize` |
|
||
| PUT | `/api/permission/Organize/{id}` | `:212` | `permission.organize` |
|
||
| DELETE | `/api/permission/Organize/{id}` | `:315` | `permission.organize` |
|
||
| GET | `/api/permission/Organize/Selector` | `:145` | 登录即可 |
|
||
|
||
**注意**:官方组织列表是**按 parentId 逐层取**(`AsyncList/{id}`,`id` = 父节点 id,根为 `0`)⇒ 面 B 必须支持 `AsyncList` 路径,
|
||
**不能**只有"全量列表"。
|
||
|
||
🔴 `AsyncList/{id}` 的响应是 `ActionResult<PageListVO<OrganizeListVO>>`(`OrganizeController.java:110-112`)
|
||
⇒ **`data` 是 `{pagination, list}`(PageListVO)**,不是裸数组。
|
||
|
||
### 3.5 菜单 `/api/system/Menu`
|
||
|
||
| 方法 | 路径 | 官方出处 | 面 B 行为 |
|
||
|---|---|---|---|
|
||
| GET | `/api/system/Menu/ModuleBySystem` | `ModuleController.java:121` | **官方前端启动入口**:返该系统下的菜单**列表(平铺)** |
|
||
| GET | `/api/system/Menu/{systemId}/TreeView` | `:332` | 菜单**树** |
|
||
| GET | `/api/system/Menu/Selector/{id}` | `:267` | 上级菜单下拉 |
|
||
| GET | `/api/system/Menu/Selector/All` | `:444` | 全量下拉 |
|
||
| POST | `/api/system/Menu` | `:169-170` | 新建 |
|
||
| PUT | `/api/system/Menu/{id}` | `:194-195` | 修改 |
|
||
| GET | `/api/system/Menu/{id}` | `:248-249` | 详情 |
|
||
| DELETE | `/api/system/Menu/{id}` | `:228-229` | 删除 |
|
||
|
||
`ModuleBySystem` 的 `systemId` 从哪来?官方前端 `api/system/menu.ts:9` 传 `data`(query)。
|
||
**本仓单系统** ⇒ 忽略入参、返本仓全部菜单(平铺,`parentId` 表达层级)。
|
||
|
||
🔴 **`ModuleBySystem` 的 `data` 不是裸数组** —— 官方返回 `ActionResult<ListVO<MenuListVO>>`
|
||
(`ModuleController.java:121` + `ListVO.java:19-22`)⇒ **线形是 `{ "list": [...] }`**。
|
||
(`ListVO` 全仓只有 `list` 一个字段;`PageListVO` 才是 `pagination` + `list`。)
|
||
⇒ 尺子断言 16 判的是 **`code=200` + `data.list` 是数组**,不是「`data` 是数组」。
|
||
|
||
**菜单项字段**:官方 `base_module` 实体字段(`f_id`/`f_full_name`/`f_en_code`/`f_parent_id`/`f_icon`/`f_url_address`/`f_type`/`f_sort_code`/`f_system_id`/`f_property_json`/`f_link_target`/`f_page_address`)
|
||
⇒ 键名去 `f_` 前缀后 camelCase,与本仓 JSON 键名规则一致。
|
||
|
||
### 3.6 授权 `/api/permission/Authority`
|
||
|
||
| 方法 | 路径 | 官方出处 | 面 B 行为 |
|
||
|---|---|---|---|
|
||
| POST | `/api/permission/Authority/Data/{objectId}/Values` | `AuthorizeController.java:99-100` | 返**权限树 + 已勾选值** |
|
||
| PUT | `/api/permission/Authority/Data/{objectId}` | `:159-160` | ✅ **与面 A 共用,零改动** |
|
||
|
||
**`Values` 的请求体**(`DataValuesQuery.java:14-24`):
|
||
|
||
```json
|
||
{ "type":"module", "objectType":"role", "moduleIds":"" }
|
||
```
|
||
|
||
- `type` = 项目类型:`module`(菜单)/ `button` / `column` / `form` / `resource`
|
||
- `objectType` = `role` / `organize` / `position` / `user`(`PermissionConst.java:8-58`)
|
||
- 🔴 `moduleIds` 是 **`String`**(逗号分隔的菜单 id),**不是数组**(`DataValuesQuery.java:19-20`)
|
||
- 🔴 `type` 为空 ⇒ 官方直接返 `ActionResult.fail(MsgCode.PS012)`(`AuthorizeController.java:112-114`)⇒ **不能省 `type`**
|
||
|
||
**响应**:官方 `AuthorizeDataReturnVO.java:16-27` = `{ list: AuthorizeDataReturnModel[], ids: String[], all: String[] }`
|
||
(`list` = 权限树模型集合 / `ids` = 已勾选 id / `all` = 全部 id,**`all` 不含菜单 id**)。
|
||
|
||
🔴 **面 B v1 降级**:本仓**不实现**完整权限树模型 ⇒ 先只保证 `ids`(已勾选 id)语义正确,
|
||
`list` 可返空数组、`all` 可返本仓全部菜单 id;并在面 B 规格里标注「`list` 未与官方 `AuthorizeDataReturnModel` 逐字对齐」。
|
||
官方前端的「授权弹窗」需要 `list` 才是完整体验 ⇒ 属面 B 后续项。
|
||
|
||
---
|
||
|
||
## 4. 码表(面 B)
|
||
|
||
| 码 | 场景 | 官方行为 |
|
||
|---|---|---|
|
||
| 200 | 成功 | 放行 |
|
||
| 400 | 业务失败 | 提示 `msg` |
|
||
| 401 | 验证错误 | 提示 `msg` |
|
||
| 500 | 异常 | 提示 `msg` |
|
||
| 600 | 登录过期 | 提示 |
|
||
| 601 | 被踢出 | 清 token |
|
||
| **602** | **token 失效** | **清 token 跳登录** ★ 官方前端靠它 |
|
||
| 403 | 权限异常 | 跳无权限页 |
|
||
|
||
**面 B 硬性要求**:
|
||
1. **未登录/无效 token 一律返 `602`(不是 600)** —— 官方前端 `request.ts:78-80` 只对 `TOKEN_ERROR/TOKEN_LOGGED/TOKEN_TIMEOUT` 清 token。
|
||
2. 权限不足返 `403`。
|
||
3. 业务失败返 `400` + `msg`(**HTTP 仍是 200**)。
|
||
|
||
> ⚠️ 这与**面 A 不同**(面 A 用 `600`)⇒ 同一个「未登录」场景,**面 A 返 600、面 B 返 602**。这正是分流规则要处理的地方。
|
||
|
||
---
|
||
|
||
## 5. 请求头
|
||
|
||
面 B **必须接受**(且**不得**因此报错):
|
||
|
||
| 头 | 值 | 作用 |
|
||
|---|---|---|
|
||
| `Jnpf-Origin` | `pc` | 本仓前端也发 ⇒ **不作**判据 |
|
||
| `Vue-Version` | `3` | **面 B 判别依据**(§2.2)——本仓前端唯一不发的一头 |
|
||
| `App-Code` | 应用编码 | 本仓单系统 ⇒ 忽略 |
|
||
| `Authorization` | `Bearer <token>` | 鉴权(面 A 同) |
|
||
|
||
---
|
||
|
||
## 6. 尺子:`scripts/perm-smoke-jnpf.sh`
|
||
|
||
### 6.1 它测什么
|
||
|
||
**第二把尺子**(第一把是 `scripts/perm-smoke.sh`,测面 A 的 32 条断言)。
|
||
本脚本测**官方形状**:同一个后端进程,按官方请求头 + 官方路径 + 官方响应形状断言。
|
||
|
||
### 6.2 断言清单(目标 18 条)
|
||
|
||
| # | 断言 | 判据 |
|
||
|---|---|---|
|
||
| 1 | 面 A 未受影响 | 无 `Vue-Version` 头时 `CurrentUser` 仍是面 A 形状(2 字段) |
|
||
| 2 | 面 A 登录仍通 | 无头登录 → `code=200` + `token` |
|
||
| 3 | 面 B 登录 | 带 `Vue-Version: 3` 登录 → `code=200` + `data.token` |
|
||
| 4 | 面 B `CurrentUser` 顶层 5 字段 | `data` 同时有 `menuList`/`permissionList`/`userInfo`/`currentSystemId`/`sysConfigInfo` |
|
||
| 5 | 面 B `menuList` 节点形状 | **`AllMenuSelectVO` 的 15 个字段齐全**(`id`/`fullName`/`enCode`/`parentId`/`icon`/`hasChildren`/`urlAddress`/`pageAddress`/`linkTarget`/`children`/`type`/`propertyJson`/`sortCode`/`systemId`/`isData`) |
|
||
| 6 | 面 B `permissionList` 是数组 | `[]` 也算过(**不能是 null**) |
|
||
| 7 | 面 B 无 token → `602` | 不是 600、不是 401 |
|
||
| 8 | 面 B 无 token → 未知路由仍 404 | |
|
||
| 9 | 面 B 用户列表是 `PageListVO` | `data` 有 `pagination` + `list` |
|
||
| 10 | `pagination` 三字段 | `currentPage`/`pageSize`/`total` 都在 |
|
||
| 11 | `pagination.total` 是总条数 | ≥ `list.length` |
|
||
| 12 | 列表项**无** `password`/`secretkey` | 逐项检查 |
|
||
| 13 | 列表项 `isAdministrator` 是数字 | 0 或 1,不是 true/false |
|
||
| 14 | 角色列表是 `PageListVO` | 同 #9 |
|
||
| 15 | 组织列表支持 `AsyncList/{id}` | 根节点 `id=0` 能取到一级组织 |
|
||
| 16 | 菜单 `ModuleBySystem` 可达 | `code=200` + `data.list` 是数组(官方是 `ListVO`,**不是裸数组**) |
|
||
| 17 | 授权写(官方 body 超集) | 用官方完整 body 发 `PUT /api/permission/Authority/Data/{id}` → 成功且 `module` 真的写进去 |
|
||
| 18 | 授权读是 **POST** | `POST .../Data/{id}/Values` → `code=200` |
|
||
|
||
### 6.3 进度报告(**关键设计**)
|
||
|
||
脚本**不假装全过**:
|
||
|
||
- 每条断言独立记 `PASS` / `FAIL` / **`SKIP(未实现)`**;
|
||
- 结尾打印 **`面 B 覆盖 N/M`**(M = 18);
|
||
- **退出码**:
|
||
- `0` = 全部 PASS;
|
||
- `1` = 有 FAIL;
|
||
- `2` = 用法错 / 后端不可达(前置错误)。
|
||
|
||
⇒ 在面 B 尚未实现时,它是一把**诚实量进度**的尺子(`SKIP` 计入未覆盖,不算 PASS)。
|
||
|
||
> **2026-10-26 当前状态**:`PASS=18 FAIL=0 SKIP=0` ⇒ **18/18 全覆盖,退出码 0**。
|
||
> `SKIP` 机制**保留**(面 B 尚未落地的端点、或后端还没起时仍如实记 SKIP / 退出码 2)。
|
||
|
||
### 6.4 与面 A 尺子的关系
|
||
|
||
| | `perm-smoke.sh` | `perm-smoke-jnpf.sh` |
|
||
|---|---|---|
|
||
| 测的面 | A(ssw) | B(官方) |
|
||
| 判别 | 无特殊头 | `Vue-Version: 3` |
|
||
| 断言数 | 32 | 18 |
|
||
| 都要跑 | ✅ | ✅(面 B 落地后) |
|
||
|
||
**两把契约尺子必须同时绿**(`perm-smoke.sh` 面 A + `perm-smoke-jnpf.sh` 面 B;本仓另有四道静态闸门,
|
||
合计**六道闸门**)—— 面 A 绿证明「没把原契约改坏」,面 B 绿证明「官方形状达标」。
|
||
|
||
---
|
||
|
||
## 7. 落地顺序(面 B 的实施建议)
|
||
|
||
| 阶段 | 内容 | 产出 | 状态 |
|
||
|---|---|---|---|
|
||
| S1 | 分流机制(`Vue-Version: 3` 判面)+ 码表补 `602` | 面 A 零影响;面 B 未登录返 602 | ✅ 已落地 |
|
||
| S2 | `CurrentUser` 面 B 形状(`PcUserVO`) | 官方前端能登录并渲染侧栏 | ✅ 已落地 |
|
||
| S3 | 分页列表引擎(`PageListVO`) | 官方用户/角色/组织列表能翻页 | ✅ 已落地 |
|
||
| S4 | 菜单 `ModuleBySystem` + `f_en_code` 种子 | 官方前端能拿到菜单树 | ✅ 已落地 |
|
||
| S5 | `f_en_code` 判权 + `permissionList` | 官方前端按钮显隐正确 | ✅ 已落地(**按钮级除外,见 B4**) |
|
||
| S6 | 授权 `Values` 读取 + 完整树 | 授权弹窗可用 | ✅ 已落地(**树模型除外,见 B1**) |
|
||
|
||
> 每阶段结束跑 `bash scripts/perm-smoke-jnpf.sh` ⇒ 覆盖数从 `0/18` 逐步爬到 `18/18`。
|
||
>
|
||
> **2026-10-26:S1–S6 一次性落地完毕** ⇒ `bash scripts/perm-smoke-jnpf.sh` = **PASS=18 FAIL=0 SKIP=0**(18/18)。
|
||
> **面 A 零改动** ⇒ `bash scripts/perm-smoke.sh` 仍为 **PASS=32 FAIL=0**,`cargo test` = **195 passed / 0 failed**。
|
||
>
|
||
> 落地对照:
|
||
> | 阶段 | 落在哪 |
|
||
> |---|---|
|
||
> | S1 | `src/backend/src/platform/jnpf.rs`(`is_jnpf` / `require_login_jnpf`)、`src/backend/src/platform/envelope.rs`(`code::*` 官方码表)、`src/backend/src/platform/auth.rs`(`require_login_any`) |
|
||
> | S2 | `src/backend/src/platform/jnpf.rs`(`current_user` / `build_user_info` / `build_menu_tree` / `build_permission_list`) |
|
||
> | S3 | `src/backend/src/platform/jnpf.rs`(`Paging` / `page_list` / `list_vo`) |
|
||
> | S4 | `src/backend/src/platform/jnpf.rs`(`module_by_system`)、`src/backend/src/platform/seed.rs`(`BuiltinMenu.en_code` + 存量库 **NULL 回填**) |
|
||
> | S5 | `src/backend/src/platform/permission.rs`(`has_en_code_permission` —— **第二套判据**) |
|
||
> | S6 | `src/backend/src/platform/jnpf.rs`(`authority_values`)、`src/backend/src/routes.rs`(`POST .../Values`) |
|
||
|
||
---
|
||
|
||
## 8. 已知不对齐项(如实记录)
|
||
|
||
| # | 项 | 状态 | 影响 |
|
||
|---|---|---|---|
|
||
| B1 | `AuthorizeDataReturnVO` 的 `list`(权限树模型) | **未逐字对齐**(面 B 只保证 `ids`/`all` 语义,`list` 返空数组) | 官方授权弹窗需二次适配 |
|
||
| B2 | `sysConfigInfo` | 返 `{}` 空对象 | 官方前端不读关键字段 |
|
||
| B3 | `currentSystemId` | 返本仓固定系统 id | 单系统场景等价 |
|
||
| B4 | 按钮级权限(`btn_*`) | 未实现(`permissionList` 的 `button`/`column`/`resource`/`form` **恒空数组**) | 官方前端按钮恒显(不隐藏) |
|
||
| B5 | 数据权限方案(`ModuleDataAuthorizeLink`) | 不做 | 官方前端相关页面 404 |
|
||
| B6 | 导入导出(`ImportData`/`ExportData`/…) | 不做 | 官方前端相关按钮报错 |
|
||
| B7 | 官方 `password` 存储格式(secretkey) | 见 `JNPF_SOURCE_AUDIT.md` §6.3 | 迁官方时一次性换算 |
|
||
| **B8** | **业务菜单的 `f_en_code`** | **本仓自定占位**(`permission.demo` / `permission.shop.product` / `permission.books.book`)—— 官方没有这三个模块 | 迁官方时要改成官方编码;当前占位不与官方 `permission.*` 冲突 |
|
||
| **B9** | **`permissionList` 的粒度** | 本仓按「**每个可见菜单一条**、`modelId` = **菜单 id**」给(对齐官方前端 `permissionList.find(o => o.modelId === menuId)` 的用法) | 官方动态模型页的**按钮**仍恒显(并入 B4) |
|
||
| **B10** | **组织列表 `AsyncList/{id}` 的分页** | 本仓按父 id **逐层**取,**不分页**(`pageSize` = 本层条数) | 官方前端逐层展开可用;机构极多时需自行加 `pageSize` 过滤 |
|
||
|
||
🔴 **本表就是官方端点台账的「偏差来源」**:`docs/contract.md` 附录 A 的 `[OFFICIAL]` 区段里,
|
||
每条官方端点的 `status` = `partial` 时,其 `note` 列指的就是这里的一条 B#
|
||
(B1 → 两个授权端点;B2/B3/B4/B9 → `CurrentUser`;B10 → `Organize/AsyncList/{id}`)。
|
||
⇒ **改了本表 ⇒ `[OFFICIAL]` 的 `note` 也要跟着改**(否则两边说法不一致)。
|
||
🔴 覆盖进度由 `bash scripts/check-contract.sh` 的 **CC10** 打印(当前 **8/47**)—— **算出来的**。
|
||
|
||
---
|
||
|
||
## 9. 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|---|---|
|
||
| 2026-10-26 | 首版。确立「面 A 不动 + 面 B 新增」的边界规则、请求头分流规则、18 条断言清单、6 阶段落地顺序、7 条已知不对齐项。 |
|
||
| 2026-10-26 | **S1–S6 全部落地**。新增 `src/backend/src/platform/jnpf.rs`(面 B 全部端点与响应形状);`routes.rs` 增 5 条面 B 路由(面 A 的 27 条**一字未动**);`seed.rs` 增 `f_en_code` 种子 + 存量库 NULL 回填;`permission.rs` 增 `has_en_code_permission`(第二套点权限判据);`envelope.rs` 补齐官方码表(含 `602`)。**尺子**:面 B `PASS=18 FAIL=0 SKIP=0`(18/18),面 A `PASS=32 FAIL=0`,`cargo test` 195/0。新增不对齐项 B8–B10。 |
|