Files
ssw-platform/JNPF_COMPAT_SURFACE.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

436 lines
25 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.
# 面 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。 |