Files
ssw-platform/docs/contract.md
T
admin 5601a667f3 feat(面B): 个人设置 Users/Current/* 23 端点 + 2 张官方表
- 新表 base_user_extra(官方 DDL:4637,18 列)/ base_sign_img(官方 DDL:3937,14 列),tables 16→18
- 23 条面 B 端点(个人资料/改密码/主题/语言/头像/签名/密钥/saas/岗位切换)
- 修 3 个真 bug:占位符与参数顺序错 ×2(BaseInfo / upsert_user_extra)、$N::integer 绑定协议错 ×1(SignImg)
- 新增 self_it.rs 5 条回归测试(反自证已验:注入 bug 必红)
- 六闸全绿:module 114 / boundary 11 / contract 10 / citations 4 / smoke 43 / smoke-jnpf 23;cargo test 226
2026-10-31 07:56:12 +08:00

1491 lines
98 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.
# 契约规格 —— ssw-jnpf-lite-rust
> **本文件是唯一规格来源(binding spec)。** 所有实现任务、代码评审、最终评审都以此为准。
> 与 `HANDOFF.md` 冲突时,以本文件为准;与本文件冲突的**计划文字**由控制者裁决并记入 ledger。
>
> 🔴 **本文件 = 面 A(ssw/react 契约)的规格,冻结不动。**
> 面 B(官方 JNPF 契约面)的规格在 **[`JNPF_COMPAT_SURFACE.md`](../JNPF_COMPAT_SURFACE.md)**(已落地 18/18),
> 两面共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径、面 B 按 `f_en_code`)。
---
## 0. 术语与参照物
| 参照物 | 路径 | 地位 |
|---|---|---|
| 官方 JNPF DDL | `~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql` | **数据模型真源**(`base_*` 表名/列名逐字) |
| `ssw-jnpf-lite-react` | `~/Desktop/workspace/skills/ssw-jnpf-lite-react/` | **行为真源**(NestJS 版把契约跑起来了) |
| `tdc-rs` | `~/Desktop/workspace/tdc-rs/` | **工程手法参考**(只读;不共享代码/端口/数据目录) |
---
## 1. 全局红线(每个任务都必须满足)
### R1.1 契约优先于实现
端点路径、入参、返回形状、错误码**逐字**对齐 `ssw-jnpf-lite-react`。不确定时读 react 源码,不凭印象。
### R1.2 业务失败一律 HTTP 200 + `{code,msg,data}`
- 成功:`code=200, msg='成功'`
- 业务失败:`code=400`,`data=null`,`msg` 透传业务提示
- 未登录:`code=600`,`msg='未登录'`
- 无菜单权限:`code=403`,`msg='无菜单权限'`
- 未捕获异常(panic / DB 报错)⇒ 同样 **HTTP 200** + `{code:400,msg:'系统异常,请联系管理员',data:null}`
(对齐 react 的全局 `ActionResultFilter` 兜底分支:真实堆栈只进服务端日志,不外泄)
- **唯一例外**:未知路由 → **HTTP 404**,body 仍是 `{code:404,msg:'接口不存在',data:null}`
(404 是**传输层**例外,不是业务失败;同理 **405 保留 HTTP 405**,见 §6.5)
### R1.3 `base_*` 表名/列名逐字对齐官方 DDL
不得自创表名/列名。迁移期靠 `--data-only` 导数据,列名差一个字符就导不进去。
### R1.4 不得用 `SELECT *`
所有 SELECT **必须显式列出列名**。原因:react 版库(TypeORM `synchronize`)只有 entity 里的列,
官方 DDL 有 30~60 列。显式投影让本仓后端**能开 react 建出来的库**,且响应 JSON 与 react 逐字相同。
🔴 **每列还要显式 `AS "<JSON键>"`**(camelCase + **双引号**,见 §4)——`row_to_json` 用**列的输出名**当 JSON 键。
写成 `AS creator_time` 会得到 `"creator_time"`,react 是 `"creatorTime"` ⇒ 前端读不到字段。
🔴🔴 **别名必须加双引号**(2026-10-25 修订,Ruling P23)——
**PostgreSQL 会把未加双引号的标识符折叠成小写**:`AS realName` 的输出列名是 `realname`
⇒ `row_to_json` 出来的键是 `"realname"`,**不是** `"realName"` ⇒ 前端读不到字段,**且静默**。
实测:`SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q` ⇒ `{"realname":1}`;
写成 `AS "realName"` 才是 `{"realName":1}`。
⇒ **规范写法:`f_real_name AS "realName"`、`f_price::text AS "price"`。**
(`db.rs` 另有一层键归一兜底,见 §5.4 —— 它是**安全网**,不是本规范;规范写法本身不依赖它。)
### R1.5 numeric 列必须序列化成 JSON 字符串
`f_price` 回显 `"9.90"`,不是 `9.9`。手段:**在 SQL 投影里就 cast 成 text**(`f_price::text AS price`)。
`int` 列(`f_delete_mark` / `f_stock` / `f_is_administrator`)**保持数字**。
### R1.6 口令不得外泄
库内存 `md5(明文)` 小写 hex。对外响应**手工挑字段**(用户列表去掉 `password`)。密文只在请求体里出现,永不回显。
### R1.7 四源权限合并 + 管理员短路 + 未映射放行
- 管理员(`f_is_administrator=1`)**在任何 SQL 之前**短路放行;
- 权限 = 用户直授 + 角色 + 组织 + 岗位,**只查角色会漏授权**;
- 菜单**未映射**到 `base_module` ⇒ **放行**(对齐 `SswPermissionGuard` 的 warn 路径),不是拒绝。
这条最容易写反且**静默**,必须有测试钉住。
### R1.8 前端不直接持有数据库
一切访问经 `/api/**`。
### R1.9 schema DDL 绝不可从 HTTP 下载
`db/schema.sql` **不在 web root**。后端若托管静态产物,只能托管前端 `dist/`。
### R1.10 标识符白名单
任何拼进 SQL 的表名/列名都要过白名单(`[A-Za-z][A-Za-z0-9_]*`),启动时自检全部拼接点,不过白名单 ⇒ 秒退。
### R1.11 同一文件的多个 Edit 必须串行
并行 Edit 同一文件 = last-writer-wins 静默覆盖。改完必须 grep 复核全部改动点。
### R1.12 bash 变量后紧跟中文必须写 `${VAR}`
`"$RC里已有"` 会把中文字节并入变量名,`set -u` 下直接 `unbound variable`。写中文提示的 shell 脚本一律用 `${VAR}` 包裹。
---
## 2. 统一信封
```json
{ "code": 200, "msg": "成功", "data": null }
```
- `code`:`int`
- `msg`:`string`
- `data`:任意 JSON(失败时为 `null`)
**Rust 侧固定形态**(`src/backend/src/platform/envelope.rs`):
```rust
use axum::Json;
use serde_json::Value;
#[derive(serde::Serialize)]
pub struct ActionResult {
pub code: i32,
pub msg: String,
pub data: Value,
}
/// 成功:code=200, msg='成功'
pub fn ok(data: Value) -> Json<ActionResult>;
/// 失败:code=<code>, msg=<msg>, data=null(**恒 HTTP 200**)
pub fn fail(code: i32, msg: impl Into<String>) -> Json<ActionResult>;
```
**没有第三种形状。** 禁止 `{"success":false,...}`、禁止 401/403 裸 body(那是 `tdc-rs` 的形状,**不要抄**)。
---
## 3. cipher(与 `cipher.ts` 逐字节等价)
```rust
// src/backend/src/platform/cipher.rs
pub fn md5_hex(s: &str) -> String;
pub fn encrypt_password(plain: &str) -> String; // hex 输出
pub fn decrypt_to_md5(encrypted_hex: &str) -> Option<String>; // 解出 md5(明文);非法 hex ⇒ None
```
算法:
1. `key = md5_hex("EY8WePvjM5GGwQzn")` ⇒ **32 个 ASCII 字节**(不是 16 字节摘要!)
2. `src = md5_hex(plaintext)` 的 **32 个 ASCII 字节**
3. `AES-256-ECB-PKCS7`,输出 hex
🔴 **key 当成 hex 串当 ASCII 用** ⇒ 32 字节 ⇒ AES-256。若当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂。
**上游检验向量(必须逐字节相等)**:
```
encrypt_password("123456")
== "d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b"
```
**中间值(已用 openssl 独立验算通过,2026-10-25)**:
```
md5_hex("EY8WePvjM5GGwQzn") = "05b0175907a859751f57a04d5a5ee9ac" ← 32 字符,当 32 个 ASCII 字节用
md5_hex("123456") = "e10adc3949ba59abbe56e057f20f883e" ← 32 字符,当 32 个 ASCII 字节用
```
🔴 **输出长度**:输入是 32 字节(= 16 的整数倍)⇒ PKCS7 **补满一整块 16 字节** ⇒
密文 48 字节 ⇒ hex **96 个字符**(不是 64)。
自查:若你的实现输出 64 个 hex 字符 ⇒ 漏了 PKCS7 填充。
解密时必须**去掉 PKCS7 填充**;填充非法 ⇒ 返回 `None`。
**口令比对**:库内存 `md5(明文)`;登录时 `decrypt_to_md5(密文)` 得到 `md5(明文)` ⇒ **大小写不敏感**比较。
🔴 **解密失败(`None`)⇒ 登录端点返回 `400 '账号或密码错误'`,与 react 完全同形。**
react 的 `decryptToMd5` 遇非法 hex / 非法填充返回**空串** ⇒ 与库里的 md5 比对不等 ⇒ 抛 `账号或密码错误`。
⇒ 本仓的 `None` 必须**映射到同一条消息**,**不要**另造「密文格式错误」之类的新提示。
(也别再加「解密结果长度必须 == 32」这类额外校验 —— react 没有,额外校验只会让行为与 react 不一致。)
**依赖版本组合(别混用)**:`aes 0.8` + `ecb 0.1`(cipher 0.4 家族);`md-5 0.10`(crate 名 `md5`,`use md5::{Digest, Md5};`)。
`aes 0.9`/`ecb 0.2` 是 cipher 0.5 家族,两套泛型不通用。
---
## 4. JSON 键名映射(列名 ↔ JSON 键)
**规则**:列名去 `f_` 前缀 → 剩余部分按 `_` 拆 → camelCase。
🔴 **投影时别名一律写 `AS "<JSON键>"`(带双引号)** —— PG 会把未加引号的标识符折叠成小写
(`AS realName` ⇒ 键 `"realname"` ⇒ 前端读不到,**且静默**)。详见 §R1.4。
| 列 | JSON 键 |
|---|---|
| `f_id` | `id` |
| `f_tenant_id` | `tenantId` |
| `f_account` | `account` |
| `f_real_name` | `realName` |
| `f_password` | `password` |
| `f_secretkey` | `secretkey` |
| `f_is_administrator` | `isAdministrator` |
| `f_role_id` | `roleId` |
| `f_organize_id` | `organizeId` |
| `f_creator_user_id` | `creatorUserId` |
| `f_creator_time` | `creatorTime` |
| `f_enabled_mark` | `enabledMark` |
| `f_delete_mark` | `deleteMark` |
| `f_full_name` | `fullName` |
| `f_en_code` | `enCode` |
| `f_url_address` | `urlAddress` |
| `f_parent_id` | `parentId` |
| `f_sort_code` | `sortCode` |
| `f_type` | `type` |
| `f_category` | `category` |
| `f_icon` | `icon` |
| `f_object_type` | `objectType` |
| `f_object_id` | `objectId` |
| `f_item_type` | `itemType` |
| `f_item_id` | `itemId` |
| `f_role_id` | `roleId` |
| `f_user_id` | `userId` |
| `f_org_id` | `orgId` |
| `f_title` | `title` |
| `f_status` | `status` |
| `f_price` | `price` |
| `f_stock` | `stock` |
| `f_author` | `author` |
| `f_isbn` | `isbn` |
**Rust 侧固定形态**(`src/backend/src/platform/db.rs`):
```rust
pub fn column_to_json_key(col: &str) -> String;
pub fn json_key_to_column(key: &str) -> String; // 逆规则
pub fn valid_table(name: &str) -> Option<String>;
pub fn valid_column(name: &str) -> Option<String>;
```
**请求体键名 = JSON 键名**(去前缀名):`title` 不是 `fTitle`,`realName` 不是 `fRealName`。
---
## 5. 数据库
### 5.1 表清单(10 张)
`base_*` 7 张 —— **官方 DDL 逐字**(源行号见括号):
`base_authorize`(812) · `base_module`(2209) · `base_organize`(3178) · `base_role`(3686) ·
`base_role_relation`(3729) · `base_user`(4479) · `base_user_relation`(4707)
> 官方 DDL 原文已提取到 `.tmp/base_ddl_raw.sql`(**逐字,未改写**)。
> 复合主键一律 `(f_id, f_tenant_id)`;`f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL`。
> 除 `f_id` 外**没有**其它 NOT NULL 列 ⇒ 插入只需给业务列 + `f_tenant_id`。
> 唯一性(`f_account` / `f_en_code`)**无 DB 约束**,应用层保证。
> 🔴 **「两版后端可开同一个库」这句话的适用范围 = 下面那 3 张业务表**(本节的措辞如此)。
> `base_*` 7 张是**官方 DDL 逐字**(本仓的「契约」),而 react 的 `base_*` entity 只是它的**子集**
> (react 的 `base_module` 没有 `f_creator_user_id`;`base_authorize` 没有 `f_creator_time` /
> `f_creator_user_id`;`base_role_relation` 这两列都没有)⇒ **react 后端本来就打不开本仓的库**
> (它的 TypeORM `synchronize: true` 会 `ALTER` 掉官方 DDL 的多余列)。
> ⇒ 本仓真正复用的是 react 的**前端产物**,**不是** react 的**后端**。
> 两个方向的依据分开:**写**以**官方 DDL** 为准(本仓的种子会写 `f_creator_user_id` /
> `f_creator_time`);**读**以 **react 的 entity 列集**为准(见 §5.3 的投影规则)。
业务表 3 张 —— 表名与 react 版同名(两版后端可开同一个库):
| 表 | 列 |
|---|---|
| `demo_item` | `f_id` / `f_title` / `f_status` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` |
| `shop_product` | `f_id` / `f_title` / `f_price numeric(12,2)` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` |
| `book_shop_book` | `f_id` / `f_title` / `f_author` / `f_isbn` / `f_category` / `f_price numeric(12,2)` / `f_stock int` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` |
业务表主键 `f_id VARCHAR(50) PRIMARY KEY`,时间列 `TIMESTAMP(0) WITHOUT TIME ZONE`。
🔴 **业务表的列宽与默认值必须逐字对齐 react 的 TypeORM entity**
(`demo-item.entity.ts` / `product.entity.ts` / `book.entity.ts`)——
这是「两版后端可开同一个库」能成立的**前提**:TypeORM `synchronize` 建的库与我们的 `schema.sql`
必须是同一张表,否则一边 `synchronize` 会 `ALTER` 掉另一边建好的列。
| 表 | 逐字 DDL |
|---|---|
| `demo_item` | `f_id VARCHAR(50) PRIMARY KEY` / `f_title VARCHAR(255)` / **`f_status VARCHAR(32)`** / `f_creator_user_id VARCHAR(50)` / `f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE` / `f_delete_mark INTEGER DEFAULT 0` |
| `shop_product` | `f_id VARCHAR(50) PRIMARY KEY` / `f_title VARCHAR(255)` / `f_price NUMERIC(12,2)` / `f_creator_user_id VARCHAR(50)` / `f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE` / `f_delete_mark INTEGER DEFAULT 0` |
| `book_shop_book` | `f_id VARCHAR(50) PRIMARY KEY` / `f_title VARCHAR(255)` / `f_author VARCHAR(100)` / **`f_isbn VARCHAR(32)`** / `f_category VARCHAR(50)` / `f_price NUMERIC(12,2)` / **`f_stock INTEGER DEFAULT 0`** / `f_creator_user_id VARCHAR(50)` / `f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE` / `f_delete_mark INTEGER DEFAULT 0` |
| `asset_data_resource` | `f_id VARCHAR(50) PRIMARY KEY` / `f_name VARCHAR(200)` / `f_category VARCHAR(50)` / `f_scenario VARCHAR(500)` / `f_provider VARCHAR(200)` / `f_format VARCHAR(50)` / `f_scale VARCHAR(50)` / `f_source VARCHAR(50)` / **`f_register_time TIMESTAMP(0) WITHOUT TIME ZONE`** / `f_creator_user_id VARCHAR(50)` / `f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE` / `f_delete_mark INTEGER DEFAULT 0` |
> 🔴 `asset_data_resource` 是**尚数网真实业务表**(不是脚手架示例):列名逐字取自公司本体
> `DataResource`(`数据资源`)。它**没有 react 版对应表** ⇒ §5.1 那条「两版同库」不适用;
> 但它同样遵守**全部** DDL 红线(`f_` 前缀 / `f_id VARCHAR(50)` / 软删 / 业务列无 DB 默认值)。
🔴 **有 DB 默认值的只有两处**:`f_delete_mark`(三张表都有)与 **`book_shop_book.f_stock`**。
react 的 `book.entity.ts` 上 `stock` 也有 `default: 0` ⇒ TypeORM 建的库同样带这个默认值。
§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)依赖它们补出 `0`。
其余业务列(`f_title` / `f_status` / `f_price` / `f_author` / `f_isbn` / `f_category` /
`f_creator_user_id` / `f_creator_time`)**不得**有 DB 默认值(§7.6 路径 2 要求"没给就是 NULL")。
### 5.2 时间列口径
官方 DDL 是 `TIMESTAMP(0) WITHOUT TIME ZONE`(秒精度、无时区)。
**写入一律 UTC 朴素时间**;**读出投影成 JS ISO 串**:
```sql
to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime
```
🔴 **投影的 `AS` 别名必须就是 §4 的 JSON 键(camelCase),且必须加双引号** ——
`row_to_json` 用的是**列的输出名**当 JSON 键。别名写成 `AS creator_time` 会得到 `"creator_time"`,
与 react 的 `"creatorTime"` **对不上** ⇒ 前端所有字段读不到。
**每一列**都要显式 `AS "<JSON键>"`(**带双引号** —— PG 折叠未加引号的标识符,见 §R1.4)。
### 5.3 精确列清单(**投影真源**)
🔴 **SELECT 的列必须逐字取自下表** —— 这是 react 版 entity 的**精确列集**(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/src/backend/src/**/*.entity.ts`),
**不是**官方 DDL 的全列。官方 DDL 有 30~60 列,react entity 只有 8~13 列。
取下表的列 ⇒ ① 响应 JSON 与 react **逐字相同**;② 本仓后端能打开 react 建出来的库。
格式:`列名 → JSON 键`。列顺序 = react entity 的声明顺序。
🔴 **投影写法**:每列都写成 `f_xxx AS "<JSON键>"`(**别名 = 右边的 JSON 键,camelCase,且带双引号**)。
`row_to_json` 用的就是别名当 JSON 键 —— 别名写错 ⇒ 响应键名对不上 react;
**双引号漏了 ⇒ PG 折叠成小写 ⇒ 键名对不上且静默**(见 §R1.4)。
例:`f_real_name AS "realName"`、`f_is_administrator AS "isAdministrator"`、
`f_creator_time` ⇒ `to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS "creatorTime"`、
`f_price` ⇒ `f_price::text AS "price"`(numeric 必须是字符串)。
**base_authorize**(9 列)
```
f_id → id f_tenant_id → tenantId f_object_type → objectType
f_object_id → objectId f_item_type → itemType f_item_id → itemId
f_org_id → orgId f_sort_code → sortCode f_delete_mark → deleteMark
```
⚠️ react 的 `base_authorize` entity **没有** `f_creator_time` / `f_creator_user_id`(官方 DDL 有)⇒ 投影里**不要**它们。
**base_module**(13 列)
```
f_id → id f_tenant_id → tenantId f_full_name → fullName
f_url_address → urlAddress f_parent_id → parentId f_type → type
f_category → category f_en_code → enCode f_icon → icon
f_sort_code → sortCode f_enabled_mark → enabledMark
f_creator_time → creatorTime f_delete_mark → deleteMark
```
⚠️ 没有 `f_creator_user_id`。
**base_organize**(11 列)
```
f_id → id f_tenant_id → tenantId f_full_name → fullName
f_parent_id → parentId f_category → category f_en_code → enCode
f_manager_id → managerId f_sort_code → sortCode f_enabled_mark → enabledMark
f_creator_time → creatorTime f_delete_mark → deleteMark
```
⚠️ 没有 `f_creator_user_id`。
**base_role**(11 列)
```
f_id → id f_tenant_id → tenantId f_full_name → fullName
f_en_code → enCode f_type → type f_description → description
f_enabled_mark → enabledMark f_sort_code → sortCode
f_creator_user_id → creatorUserId f_creator_time → creatorTime
f_delete_mark → deleteMark
```
**base_role_relation**(8 列)
```
f_id → id f_tenant_id → tenantId f_object_type → objectType
f_object_id → objectId f_role_id → roleId f_sort_code → sortCode
f_delete_mark → deleteMark
```
⚠️ 没有 `f_creator_time` / `f_creator_user_id`。
**base_user**(13 列)
```
f_id → id f_tenant_id → tenantId f_account → account
f_real_name → realName f_password → password f_secretkey → secretkey
f_is_administrator → isAdministrator f_role_id → roleId
f_organize_id → organizeId f_creator_user_id → creatorUserId
f_creator_time → creatorTime f_enabled_mark → enabledMark
f_delete_mark → deleteMark
```
🔴 **没有 `f_manager_id` / `f_position_id` / `f_gender` / `f_email` 等** —— 官方 DDL 有,react entity 没有 ⇒ 不投影。
**base_user_relation**(8 列)
```
f_id → id f_tenant_id → tenantId f_user_id → userId
f_object_type → objectType f_object_id → objectId
f_sort_code → sortCode f_delete_mark → deleteMark
```
**demo_item**(6 列)/ **shop_product**(6 列)/ **book_shop_book**(10 列)
```
demo_item: f_id → id, f_title → title, f_status → status,
f_creator_user_id → creatorUserId, f_creator_time → creatorTime,
f_delete_mark → deleteMark
shop_product: f_id → id, f_title → title, f_price → price,
f_creator_user_id → creatorUserId, f_creator_time → creatorTime,
f_delete_mark → deleteMark
book_shop_book: f_id → id, f_title → title, f_author → author, f_isbn → isbn,
f_category → category, f_price → price, f_stock → stock,
f_creator_user_id → creatorUserId, f_creator_time → creatorTime,
f_delete_mark → deleteMark
```
**已知无害偏离**(记入 ledger,不必对齐):
- `f_sort_code` 是 `BIGINT`,直投影为 JSON **数字**;react 因 `pg` 驱动把 int8 返回成**字符串**。
前端只在 `<td>` 里原样渲染(`MenuManage.tsx:75`)⇒ 显示一致。
- 时间列:react 返回 JS Date ⇒ JSON `"2026-01-01T00:00:00.000Z"`;我们投影 `"2026-01-01T00:00:00Z"`(秒精度)。
前端**完全不用** `creatorTime` ⇒ 无影响。
### 5.4 pglite 封装(`src/backend/src/platform/db.rs`)
```rust
pub const SCHEMA_SQL: &str = include_str!("../db/schema.sql");
pub struct Db { /* PGlite + 进程级 Mutex */ }
impl Db {
pub async fn open(dir: &Path) -> Result<Db, pglite::Error>;
pub async fn open_temp() -> Result<Db, pglite::Error>;
pub async fn ensure_schema(&self) -> Result<(), pglite::Error>;
pub async fn query_json(&self, sql: &str) -> Result<Vec<serde_json::Value>, pglite::Error>;
pub async fn query_json_params(&self, sql: &str, params: &[&(dyn pglite::ToSql + Sync)])
-> Result<Vec<serde_json::Value>, pglite::Error>;
pub async fn exec(&self, sql: &str) -> Result<(), pglite::Error>;
pub async fn exec_params(&self, sql: &str, params: &[&(dyn pglite::ToSql + Sync)])
-> Result<(), pglite::Error>;
pub async fn scalar_text(&self, sql: &str) -> Result<Option<String>, pglite::Error>;
}
/// 字面量感知 SQL 切分(单引号串 / dollar-quote / 行注释 / 块注释内的 `;` 不切)
pub fn split_sql_statements(sql: &str) -> Vec<String>;
```
**序列化手法**(沿用 `tdc-rs`):
```sql
SELECT row_to_json(q)::text AS _row FROM (<sql>) AS q
```
⇒ 取单列文本 ⇒ `serde_json::from_str`。**不要另起逐列类型映射分支。**
🔴 **键归一安全网**(`db.rs` 内建,Ruling P23):`query_json` 返回前会把 JSON 键还原成 camelCase ——
① 内层 SQL 里 `AS <别名>`(**含大写字母**)的别名 ⇒ 按作者原样还原(`AS realName` ⇒ `"realName"`);
② 键以 `f_` 开头 ⇒ 走 `column_to_json_key`(`f_real_name` ⇒ `realName`,与 `tdc-rs` 同思路)。
已加双引号的别名(`AS "realName"`)PG 原样保留 ⇒ 两条规则都不动它。
⇒ **两种写法都能出正确键**;但**规范写法是加双引号**(原生 PG 行为,不依赖这层解析)。
安全网存在的意义是:万一某处漏了双引号,**不会静默产出小写键**。
**绑定参数一律按 text 传**(`&str` / `Option<&str>` 都实现了 `ToSql`);
类型转换由 SQL 里的 `CAST` / 列上下文负责(PG 从目标列推断参数类型)。
**单 backend 独占**:pglite-rs 每进程只允许一个 `PGlite` 实例 ⇒ 集成测试必须**共用一个实例**,
且各自用独立数据目录的多个测试二进制不能并行跑。
### 5.5 schema 初始化
启动时探测 `base_user` 是否存在;不存在才按 `;` 拆分执行 `schema.sql`(拆分要**字面量感知**)。
🔴 **`schema.sql` 只在「`base_user` 不存在」时整体执行一次**,不是「每次启动都跑」。
- 改了 schema(加列/改类型)⇒ 必须**清空数据目录**(`src/backend/data/`)重建,否则旧库仍是老结构。
- 7 张 `base_*` 的 `CREATE TABLE` 块与 `docs/ddl/base_ddl_raw.sql` **逐字相同**;
文件尾部另有 4 条官方索引(`i_ba_foi` / `i_brr_fri` / `i_bu_fa` / `i_bur_fui`),
官方全部**非唯一** ⇒ 账号唯一性仍由**应用层**保证(不会有 23505)。
- 4 条索引都带 `IF NOT EXISTS` ⇒ `schema.sql` 重复执行不会报 42P07。
---
## 6. 端点全表
> 🔴 **本节是「人读」版;机器可读版在附录 A 的 `[ENDPOINT]` 区段**
> (列:`face` / `method` / `path` / `guard` / `owner`,一行一条端点,**132** 条;
> 外加 `[FACE]` 区段登记各契约面的条数)。
> 由 **`scripts/check-contract.sh`** 把它与**代码里真实注册的路由**逐条对账
> (总数 / 存在性 / 方法 / 归属层 / 守卫,**双向**)⇒
> 改契约忘了改代码(或反之)**立刻报**。
> 🔴 **改端点时两处都要改**:本节的散文表 + 附录 A 的 `[ENDPOINT]`。
>
> 📊 **本仓对「官方 JNPF 契约面」的覆盖**是另一本账:附录 A 的 **`[OFFICIAL]`** 区段
> (53 行 = 官方端点全表 + 每个端点的 `status` 四态 + 官方出处 `文件:行号`)⇒
> 由 `check-contract.sh` 的 **CC10** 与代码真实路由**双向**对账 ⇒
> 打印「官方端点覆盖 N/M」。官方端点全表的人读版在 `JNPF_SOURCE_AUDIT.md` §4。
### 6.1 认证
| 方法 | 路径 | 守卫 | 说明 |
|---|---|---|---|
| POST | `/api/oauth/Login` | 无 | **form-urlencoded**:`account` / `password`(密文 hex) / `grant_type=password` |
| GET | `/api/oauth/CurrentUser` | 登录 | `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` |
| POST | `/api/oauth/Logout` | 登录 | **恒成功** `{data:null}`(前端忽略返回值,但 404 会弹红条 ⇒ 必须得是 200) |
| GET | `/api/system/BaseLang/LangJson` | 登录 | i18n 远端词条包;恒 `{data:null}` ⇒ 前端不 merge |
**登录失败文案**(逐字):
- 缺 `account` 或 `password` ⇒ `400 '缺少 account / password'`
- `grant_type` **非空**且 ≠ `password` ⇒ `400 '不支持的 grant_type'`
- 口令错 / 账号不存在 ⇒ `400 '账号或密码错误'`
- **密文非法(非法 hex / 非法 PKCS7 填充 ⇒ `decrypt_to_md5` 返回 `None`)⇒ 同一条 `400 '账号或密码错误'`**
(react 的 `decryptToMd5` 失败返空串 ⇒ 比对不等 ⇒ 同一条消息。**不要**另造提示文案。)
**实现注记**:axum 0.8.9 的 `Form<T>` **没有** `OptionalFromRequest` ⇒ `Option<Form<T>>` 编译不过。
⇒ handler 取**原始 body**(`Bytes`),自己 `serde_urlencoded::from_bytes::<LoginForm>(&body)`;
**解析失败也走业务信封**(`fail(400, "缺少 account / password")`),不要 axum 默认的 400 文本。
**登录成功体**:`{token, expiresIn: 7200, tokenTypeName: 'bearer'}`
**token 形态**:`lite-` + 32 位小写 hex(`lite-` 前缀 + md5)。进程重启即失效(内存表)。
**Authorization 头**:`bearer <token>`(大小写不敏感前缀)。
**CurrentUser 的 `userName` = 账号**(react 版 `userName: u.account`,不是 `realName`)。
`isAdministrator` 是 **JSON 布尔**(`isAdmin === 1`)。
### 6.2 系统管理(5 组)
| 方法 | 路径 | 守卫菜单 key |
|---|---|---|
| GET/POST/DELETE | `/api/ssw/sys/User/{List,Save,Delete?id=}` | `system/User` |
| GET/POST/DELETE | `/api/ssw/sys/Role/{List,Save,Delete?id=}` | `system/Role` |
| GET | `/api/ssw/sys/Role/Modules?roleId=` | **仅登录** |
| GET/POST/DELETE | `/api/ssw/sys/Organize/{List,Save,Delete?id=}` | `system/Organize` |
| GET/POST/DELETE | `/api/ssw/sys/Module/{List,Save,Delete?id=}` | `system/Module` |
### 6.3 授权
| 方法 | 路径 | 守卫 | 说明 |
|---|---|---|---|
| PUT | `/api/permission/Authority/Data/{objectId}` | 仅登录 | body `{objectType:'role', module:['m1','m2']}`(**一维**) |
| GET | `/api/permission/Authority/RoleModules?roleId=` | 仅登录 | 返 `string[]`(菜单 id) |
**`module` 归一化**(react `normalizeModule`):一维数组直接用;历史二维形态 `[[checked],[halfChecked]]` **展平**后同样落库;
非数组 ⇒ 视作空数组;只保留**非空字符串**元素。
⚠️ body 里的 **`objectType` 被完全忽略**(react 只读 `body.module`,落库的 `f_object_type` 硬编码为 `'role'`)⇒
**不要**因为 body 传了 `'Role'` 就拒绝。详见 §7.5 与 §7.7。
### 6.4 业务模块(3 组)
| 方法 | 路径 | 守卫菜单 key |
|---|---|---|
| GET/POST/DELETE | `/api/ssw/demo/DemoItem/{List,Save,Delete?id=}` | **仅登录**(无菜单守卫) |
| GET/POST/DELETE | `/api/ssw/shop/Product/{List,Save,Delete?id=}` | `shop/Product` |
| GET/POST/DELETE | `/api/ssw/books/Book/{List,Save,Delete?id=}` | `books/Book` |
### 6.5 其它
- 未知路由 ⇒ **HTTP 404** + `{code:404,msg:'接口不存在',data:null}`
- 405(路径存在、方法不对)⇒ **HTTP 405** + `{code:405,msg:'方法不被允许',data:null}`,**保留 `Allow` 头**
(react 侧 Express 路由对错误方法其实返 404,但**前端从不发错方法** ⇒ 这条不在契约面上,
按「传输层状态码保留」处理,别让它掉进 R1.2 的 HTTP 200 规则。)
- 未捕获异常(panic / DB 报错)⇒ **HTTP 200** + `{code:400,msg:'系统异常,请联系管理员',data:null}`
(必须装 catch-all 中间件,**不能**让 axum 的默认 500 空 body 漏出去)
- `GET /api/health` ⇒ `{ok, tables, version}`(**非契约**,探活用)
---
## 7. 各端点语义(逐字对齐 react 版)
> 本节每一条都**逐字核对过** react 源码
> (`~/Desktop/workspace/skills/ssw-jnpf-lite-react/src/backend/src/{auth,sys,demo,shop,books}/`)。
> 括号里的 `react:` 行号是出处。凡与 react 有**故意**偏离的(只有一条:User Save 的 `password`),
> 都标了 🔴 **刻意偏离** 并在 §7.7 记录原因。
> 🔴 **全局覆盖规则(§7.1–§7.4 通用)**:后文所有「覆盖 `f_xxx`」默认指
> **只 SET body 里出现的键**(body 里没出现 ⇒ 该列**不动原值**)——
> 这就是 react / TypeORM `save` 的 `undefined` 语义(`save` 跳过 `undefined` 的列)。
> body 里出现了但值为 `null` ⇒ 写 NULL;出现了且值为 `''` ⇒ 写空串。
> **例外**:凡是本节显式写出兜底表达式的列(`?? 原值` / `|| '0'` / `? 1 : 0`),
> **一律按该表达式求值** —— body 缺该键时取**兜底值**(`?? 原值` ⇒ 原值、
> `|| '0'` ⇒ `'0'`),**不是**「不动原值」。
> 🔴 **承重之处**:§7.4 的 `f_url_address` 是 §8.2 权限守卫的比对键。
> 把它清成 NULL ⇒ 该菜单变成「**未映射**」⇒ 守卫走「未映射放行」
> ⇒ **任何登录用户都能访问该模块**(静默越权)。⇒ 更新菜单时**绝不可**把
> `f_url_address` 写成本仓未提供的值。
### 7.1 User(`/api/ssw/sys/User/*`)
- **List**
- `base_user`:`f_delete_mark=0`,`f_creator_time DESC`。
- 关联:`base_role_relation` 取 `f_object_type='user'` 的**全部**行(**不按 `f_delete_mark` 过滤**),
再按 `f_object_id == 用户 id` 过滤 ⇒ `roleIds` = 命中行的 `f_role_id` 数组(保持库里顺序)。
- `roleNames` = `base_role` 中 `f_delete_mark=0` 的行按 id 查 `f_full_name`;
**查不到就跳过**(不是填空串、不是 null)⇒ 数组长度可能小于 `roleIds`。
- 输出去掉 `password`,追加 `roleIds` / `roleNames`(两个都是**一维** `string[]`)。
- **Save**(`POST /api/ssw/sys/User/Save`,body 是 JSON)
1. `account` 为空 ⇒ `400 '账号不能为空'`。
2. **查重**(新建和更新**都查**):`base_user` 中 `f_account = <account> AND f_delete_mark = 0`。
⚠️ 官方 DDL 对 `f_account` **无 UNIQUE**,唯一性只在应用层。
3. **无 `id`** ⇒ 新建:
- `f_id` = 36 位 UUID v4(带连字符),`f_tenant_id='0'`;
- `f_account` = body.account;
- `f_real_name` = body.realName(body 没有 ⇒ NULL);
- `f_password` = `md5(body.password)`;body.password 为空 ⇒ `md5('123456')`;
- `f_is_administrator` = body.isAdministrator **真值 ⇒ 1,否则 0**(缺省即 0,不是「保持原值」);
- `f_organize_id` = body.organizeId || `'0'`;
- `f_creator_user_id` = `'admin'`,`f_creator_time` = now(UTC),
`f_enabled_mark=1`,`f_delete_mark=0`。
- `f_secretkey` / `f_role_id` 不写(NULL)。
- 若 `dup` 存在 ⇒ `400 '账号已存在:<account>'`(**HTTP 200,不是 500**)。
4. **有 `id`** ⇒ 更新:
- 先按 `f_id = <id>` 查(**不按 `f_delete_mark` 过滤** ⇒ 软删过的行也算存在),
查不到 ⇒ `400 '用户不存在'`;
- 若 `dup` 存在**且** `dup.f_id != <id>` ⇒ `400 '账号已存在:<account>'`;
- 覆盖规则(**只覆盖 body 里出现的键**,`undefined` ⇒ 不动原值):
`f_account`(必覆盖)、`f_real_name`(body 有才覆盖)、
`f_is_administrator`(**总是**覆盖为 body 真值 ? 1 : 0)、
`f_organize_id`(**总是**覆盖为 body.organizeId || `'0'`)、
`f_password`(**body.password 非空才**覆盖为 `md5(body.password)`)。
- ⚠️ 更新**不**碰 `f_creator_time` / `f_enabled_mark` / `f_delete_mark`。
5. `roleIds` 是数组 ⇒ **先硬删**该用户的 `base_role_relation` 旧行
(`f_object_type='user' AND f_object_id=<id>`),再每个 roleId 插一行
(`f_id`=UUID v4、`f_tenant_id='0'`、`f_object_type='user'`、`f_object_id=<id>`、
`f_role_id=<rid>`、`f_sort_code=0`、`f_delete_mark=0`)。空数组 ⇒ 只删不插。
6. **响应** = 落库后该用户行(**去掉 `password`**)+ `roleIds` + `roleNames`。
🔴 **刻意偏离**:react 的 Save 响应**带着 `password` 的 md5 摘要**(可被重新加密成合法登录密文)。
本仓按 R1.6 **剥掉 `password`**(List 与 Save 都剥)。前端从不读该字段 ⇒ 无影响。
- **Delete**(`DELETE /api/ssw/sys/User/Delete?id=`)
- 软删 `base_user`:`f_delete_mark=1`(按 id,**不按 `f_delete_mark` 过滤** ⇒ 幂等);
- 硬删 `base_role_relation`:`f_object_type='user' AND f_object_id=<id>`;
- **不检查用户是否存在** ⇒ 不存在也返回成功。
### 7.2 Role(`/api/ssw/sys/Role/*`)
- **List**:`f_delete_mark=0`,`f_sort_code ASC`。
- **Save**
1. `fullName` 为空 ⇒ `400 '角色名称不能为空'`。
2. **无 `id`** ⇒ 新建:
- **先查重** `base_role` 中 `f_en_code = <enCode> AND f_delete_mark = 0`;
命中 ⇒ `400 '角色编码已存在:<enCode>'`;
- `f_id`=UUID v4、`f_tenant_id='0'`、`f_full_name`=body.fullName、`f_en_code`=body.enCode、
`f_type` = body.type ?? `'user'`、`f_description`=body.description、
`f_enabled_mark=1`、`f_sort_code` = body.sortCode ?? 0、
`f_creator_user_id='admin'`、`f_creator_time`=now、`f_delete_mark=0`。
3. **有 `id`** ⇒ 更新:
- 按 `f_id` 查(**不带 `f_delete_mark` 过滤**),查不到 ⇒ `400 '角色不存在'`;
- 覆盖(**body 有才覆盖**,见本节全局规则):`f_full_name`、`f_en_code`、
`f_type` = body.type ?? **原值**、`f_description`;
- ⚠️ 更新**不做** `f_en_code` 查重;**不碰** `f_sort_code` / `f_enabled_mark`。
- **Delete**
- 软删 `base_role`(`f_delete_mark=1`,按 id);
- 软删 `base_authorize`:`f_object_type='role' AND f_object_id=<id>` ⇒ `f_delete_mark=1`
(⚠️ **不带 `f_item_type` 过滤**);
- **硬删** `base_role_relation`:`f_role_id=<id>`(⚠️ **不带 `f_object_type` 过滤**)。
- **`GET /api/ssw/sys/Role/Modules?roleId=`**
⇒ `base_authorize` 中 `f_object_type='role' AND f_item_type='module' AND f_object_id=<roleId> AND f_delete_mark=0`
的 `f_item_id` 数组(`string[]`)。
### 7.3 Organize(`/api/ssw/sys/Organize/*`)
- **List**:`f_delete_mark=0`,`f_sort_code ASC`。
- **Save**
1. `fullName` 为空 ⇒ `400 '机构名称不能为空'`。
2. **无 `id`** ⇒ 新建:`f_id`=UUID v4、`f_tenant_id='0'`、`f_full_name`=body.fullName、
`f_parent_id` = body.parentId || `'0'`、`f_category` = body.category ?? NULL、
`f_sort_code` = body.sortCode ?? 0、`f_enabled_mark=1`、`f_creator_time`=now、`f_delete_mark=0`。
⚠️ **不写 `f_creator_user_id`**(react 的 `base_organize` entity 没有该列)⇒ NULL。
3. **有 `id`** ⇒ 更新:按 `f_id` 查(不带 `f_delete_mark` 过滤),查不到 ⇒ `400 '机构不存在'`;
覆盖(**body 有才覆盖**,见本节全局规则):`f_full_name`、
`f_parent_id` = body.parentId || `'0'`、`f_category` = body.category ?? **原值**。
⚠️ 更新**不碰** `f_sort_code` / `f_enabled_mark`。
- **Delete**
- 先查子机构:`base_organize` 中 `f_parent_id=<id> AND f_delete_mark=0`;
非空 ⇒ `400 '该机构下还有子机构,先删除子机构'`;
- 否则软删(`f_delete_mark=1`,按 id)。
### 7.4 Module(`/api/ssw/sys/Module/*`)
- **List**:`f_delete_mark=0`,`f_sort_code ASC`。
- **Save**
1. `fullName` 为空 ⇒ `400 '菜单名称不能为空'`。
2. **无 `id`** ⇒ 新建:`f_id`=UUID v4、`f_tenant_id='0'`、`f_full_name`=body.fullName、
`f_url_address`=body.urlAddress、`f_parent_id` = body.parentId || `'0'`、
`f_type` = body.type ?? **2**(**INTEGER**:1=目录 2=页面)、
`f_category` = body.category ?? NULL(**VARCHAR 分类**)、
`f_icon`=body.icon、`f_sort_code` = body.sortCode ?? 0、
`f_enabled_mark=1`、`f_creator_time`=now、`f_delete_mark=0`。
⚠️ **不写 `f_creator_user_id`** ⇒ NULL。
3. **有 `id`** ⇒ 更新:按 `f_id` 查(不带 `f_delete_mark` 过滤),查不到 ⇒ `400 '菜单不存在'`;
覆盖(**body 有才覆盖**,见本节全局规则):`f_full_name`、`f_url_address`、
`f_parent_id` = body.parentId || `'0'`、`f_type` = body.type ?? **原值**、
`f_category` = body.category ?? **原值**、`f_icon`、`f_sort_code` = body.sortCode ?? 0。
- **Delete**
- 软删 `base_module`(`f_delete_mark=1`,按 id);
- 软删 `base_authorize`:`f_item_type='module' AND f_item_id=<id>` ⇒ `f_delete_mark=1`
(⚠️ **不带 `f_object_type` 过滤**)。
### 7.5 授权(`/api/permission/Authority/*`)
- **`PUT /api/permission/Authority/Data/{objectId}`**,body `{objectType, module}`:
1. **守卫**:未登录 ⇒ `600 '未登录'`。
2. **归一化 `module`**(react `normalizeModule`):
- body 里没有 `module` 或不是数组 ⇒ `[]`;
- 若 `module[0]` 是数组 ⇒ **展平一层**(兼容官方前端的 `[checked, halfChecked]` 二维形态);
- 只保留**非空字符串**。
3. ⚠️ **body 里的 `objectType` 被完全忽略**(react 只读 `body.module`)⇒
落库一律 `f_object_type='role'`、`f_item_type='module'`、`f_object_id=<objectId>`。
(不要因为 body 传了 `'Role'` 而拒绝 —— react 不校验,本仓也不校验。)
4. **先软删**旧行:`base_authorize` 中 `f_object_type='role' AND f_item_type='module' AND f_object_id=<objectId>`
⇒ `f_delete_mark=1`(⚠️ **不带 `f_delete_mark` 过滤**)。
5. 再**插新行**(每个 moduleId 一行):`f_id`=UUID v4、`f_tenant_id='0'`、
`f_object_type='role'`、`f_item_type='module'`、`f_item_id`=<moduleId>、
`f_sort_code=0`、`f_delete_mark=0`。空数组 ⇒ 只软删不插。
6. 成功 ⇒ `{code:200,msg:'成功',data:null}`。
- **`GET /api/permission/Authority/RoleModules?roleId=`** ⇒ 同 §7.2 的 `Role/Modules`
(`string[]`)。未登录 ⇒ `600 '未登录'`。
### 7.6 业务模块(spec 引擎,3 组同构)
- **List**:`f_delete_mark=0`,`f_creator_time DESC`。
- **Save** —— **三条互不相同的路径**,按 body 里有没有 `id`、以及该 `id` 存不存在分流:
1. **无 `id`** ⇒ 新建(**只写下列字段,不多写**):
- `demo_item`:`f_id`=UUID v4、`f_title`=body.title、`f_status` = body.status ?? `'草稿'`、
`f_creator_user_id` = **`'admin'`(硬编码,不取 body)**、`f_creator_time`=now、`f_delete_mark`=0;
- `shop_product`:`f_id`=UUID v4、`f_title`=body.title、`f_price` = body.price ?? `'0.00'`、
`f_creator_user_id` = body.creatorUserId || `'admin'`、`f_creator_time`=now、`f_delete_mark`=0;
- `book_shop_book`:`f_id`=UUID v4、`f_title`=body.title、`f_author`=body.author、
`f_isbn`=body.isbn、`f_category`=body.category、`f_price` = body.price ?? `'0.00'`、
`f_stock` = body.stock ?? 0、`f_creator_user_id` = body.creatorUserId || `'admin'`、
`f_creator_time`=now、`f_delete_mark`=0。
2. **有 `id` 但库里查不到该行** ⇒ **用这个 id 新建**:
- 写入 body 里**该实体的已知列**(§5.3 的列集),**不加任何默认值**:
没有 `f_creator_time` ⇒ NULL;没有 `f_status` / `f_price` ⇒ NULL;
- `f_delete_mark`:body 没给 ⇒ **0**(业务表该列 DDL 带 `DEFAULT 0`);
- `f_stock`(**仅 `book_shop_book`**):body 没给 ⇒ **0**(该列 DDL 也带 `DEFAULT 0`,
与 react 的 `book.entity.ts` 一致 ⇒ 两版后端开同一个库时结果相同)。
3. **有 `id` 且库里查得到** ⇒ 覆盖更新:**只覆盖 body 里出现的该实体已知列**(`Object.assign` 语义),
body 没出现的列保持原值。
- 三个模块**共用**一条规则:**body 里不属于该实体列集的键一律忽略**(不建列、不报错)。
- **响应体 = 落库后重新读回的那一行**(这样 numeric 的 `"9.90"` 由投影 `::text` 保证)。
- **Delete**(`DELETE .../Delete?id=`):软删 `f_delete_mark=1`(按 id,**不检查是否存在** ⇒ 幂等)。
### 7.7 与 react 的唯一刻意偏离
| 项 | react 行为 | 本仓行为 | 理由 |
|---|---|---|---|
| User **Save** 响应 | 带 `password` 字段(md5 摘要) | **剥掉 `password`** | R1.6 口令不得外泄。md5 摘要可被前端用 `cipher.ts` 重新加密成**合法登录密文** ⇒ 泄露即等于泄露凭据。前端从不读该字段 ⇒ 无功能影响。List 响应两版都剥。 |
---
## 8. 权限与菜单树
### 8.1 四源合并
`resolve_user_module_ids(userId)` 返回菜单 id 集合,四个来源:
1. **直授**:`base_authorize` 中 `f_object_type='user' AND f_object_id=<userId> AND f_item_type='module' AND f_delete_mark=0` ⇒ `f_item_id`
2. **角色**:`base_role_relation` 中 `f_object_type='user' AND f_object_id=<userId>` ⇒ 每行的 `f_role_id`
⇒ 对每个 roleId 取 `base_authorize` 中 `f_object_type='role' AND f_object_id=<roleId> AND f_item_type='module' AND f_delete_mark=0` ⇒ `f_item_id`
3. **组织**:`base_user_relation` 中 `f_user_id=<userId> AND f_object_type='organize'` ⇒ 每行的 `f_object_id`
⇒ 对每个 objectId 取 `base_authorize` 中 `f_object_type='organize' AND f_object_id=<objectId> ...` ⇒ `f_item_id`
4. **岗位**:`base_user_relation` 中 `f_user_id=<userId> AND f_object_type='position'` ⇒ 同上,`f_object_type='position'`
### 8.2 菜单守卫 `has_module(userId, isAdmin, moduleKey)`
1. `isAdmin == 1` ⇒ **放行**(不查任何 SQL)
2. 查 `base_module` 中 `f_url_address = moduleKey AND f_delete_mark=0`(取**第一条**);
**查不到 ⇒ 放行**(未映射放行)
3. 查得到 ⇒ 该菜单 `f_id` 是否在四源合并集合里;在 ⇒ 放行,否则 ⇒ `403`
### 8.3 菜单树 `build_menu_list(userId, isAdmin)`
- 取 `base_module` 中 `f_delete_mark=0` 的行,按 `f_sort_code ASC`
- 非管理员:过滤成「id 在四源集合里」的子集
- 建树:`f_parent_id` 为空或 `'0'` 或父节点不在集合内 ⇒ 该节点是根;否则挂到父节点 `children`
- 节点形状:`{id, fullName, urlAddress, icon, parentId, children}`
(`urlAddress` / `icon` 库里是 NULL ⇒ JSON 里就是 `null`,**不要**省略这两个键;
`parentId` 取 `f_parent_id`,为 NULL/空 ⇒ `'0'`)
- 根按 `f_sort_code` 升序;同层 children 按 `f_sort_code` 升序
### 8.4 种子菜单(8 行,`f_tenant_id='0'`,`f_enabled_mark=1`,`f_delete_mark=0`)
| id | fullName | urlAddress | parentId | type | icon | sortCode |
|---|---|---|---|---|---|---|
| `m_sys` | 系统管理 | `system` | `0` | 1 | `setting` | 1 |
| `m_user` | 用户管理 | `system/User` | `m_sys` | 2 | — | 2 |
| `m_role` | 角色管理 | `system/Role` | `m_sys` | 2 | — | 3 |
| `m_org` | 机构管理 | `system/Organize` | `m_sys` | 2 | — | 4 |
| `m_menu` | 菜单管理 | `system/Module` | `m_sys` | 2 | — | 5 |
| `m_demo` | Demo 示例 | `demo-item` | `0` | 2 | `app` | 6 |
| `m_product` | 产品管理 | `shop/Product` | `0` | 2 | `app` | 7 |
| `m_book` | 图书超市 | `books/Book` | `0` | 2 | `app` | 8 |
**期望菜单树字符串**(冒烟断言用;值在**附录 A 的 `[MENU_TREE]` 区段**,脚本从那里读):
```
系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:
```
🔴 **这 8 行的值住在哪(分层红线 12)**:
- 前 5 行(系统管理 + 4 个系统页)= **平台层**的种子,值在 `platform/seed.rs` 的 `BUILTIN_MENUS`;
- 后 3 行(Demo / 产品 / 图书)= **业务层**的菜单,值在各自 `modules/<app>.rs` 的 `*_MENU: MenuSpec`,
经 `modules::ALL_MENUS` 交给装配根 `src/bootstrap.rs` 回灌。
⇒ **加一个业务模块只碰 `modules/`**(平台层一个字都不改),但**菜单行数会变** ⇒
本节表格与 `modules::ALL_MENUS` 必须同步;`scripts/check-boundary.sh` 的 CP4/CP6 静态钉住这两处一致。
### 8.5 种子角色(2 行)
| id | enCode | fullName | sortCode |
|---|---|---|---|
| `role_admin` | `admin` | 管理员 | 1 |
| `role_user` | `user` | 使用者 | 2 |
其它列:`f_tenant_id='0'`、`f_type='user'`、`f_enabled_mark=1`、`f_delete_mark=0`。
### 8.6 两段式种子
**`ensure_base()`(每次启动都跑,幂等)**
- 补内置角色:查 `base_role` 的**全部行**(🔴 **不按 `f_delete_mark` 过滤**),
凡 `f_en_code` 命中内置清单(`admin` / `user`)的**一律视为已存在** ⇒ 不补、不覆盖。
缺的行按 §8.5 的值插入。
- 补内置菜单:查 `base_module` 的**全部行**(🔴 **含软删行**),
凡 `f_url_address` 命中内置清单的**一律视为已存在** ⇒ **不复活**软删的菜单。
缺的行按 §8.4 的值插入(`f_tenant_id='0'`、`f_enabled_mark=1`、`f_delete_mark=0`)。
- 补 admin 授权:
- 取 `base_role` 中 `f_en_code='admin'` 的行(🔴 **不按 `f_delete_mark` 过滤**,取到软删行也用它);
- 取 `base_module` 中 `f_delete_mark=0` **且** `f_url_address` 命中内置清单的行(`builtin_live`);
- 查 `base_authorize` 中 `f_object_type='role' AND f_object_id=<adminRoleId> AND f_item_type='module'`
的**全部行**(🔴 **不按 `f_delete_mark` 过滤** ⇒ 软删的授权行也算「已授权」⇒ 不补);
- `builtin_live` 里没出现在上述集合中的行 ⇒ 补一条授权
(`f_id`=UUID v4、`f_tenant_id='0'`、`f_object_type='role'`、`f_object_id=<adminRoleId>`、
`f_item_type='module'`、`f_item_id=<menuId>`、`f_sort_code=0`、`f_delete_mark=0`)
- **只补缺项**:不覆盖已改值(人工改名/调序会被保留)
**`first_seed()`(仅 `base_user` 行数为 0 时跑一次)**
- 建 `admin` 用户:`f_id`=UUID v4、`f_account='admin'`、`f_real_name='管理员'`、
`f_password=md5_hex('123456')`、`f_is_administrator=1`、`f_organize_id='0'`、
`f_creator_user_id='admin'`、`f_creator_time`=now、`f_enabled_mark=1`、`f_delete_mark=0`、`f_tenant_id='0'`
- 建一条 `base_role_relation`:`f_object_type='user'`、🔴 **`f_object_id='admin'`(账号名,不是 UUID!)**、
`f_role_id='role_admin'`、`f_sort_code=0`、`f_delete_mark=0`、`f_tenant_id='0'`、`f_id`=UUID v4
(react 源码里就是 `'admin'`,**逐字照抄**;admin 本人是管理员,不靠这条授权吃饭)
---
## 9. Rust 模块接口契约
🔴 **代码分两层**(对齐 react 版的 `common`+`auth`+`sys` / `demo`+`shop`+`books`,
以及官方 JNPF 的 `jnpf-common`+`jnpf-system` / `jnpf-admin`):
| 层 | 目录 | 职责 | 加业务模块 |
|---|---|---|---|
| **平台层** | `src/backend/src/platform/` | 契约实现(信封 / cipher / 登录 / 权限 / `base_*` 管理 / 面 B / CRUD 引擎) | **不动** |
| **业务层** | `src/backend/src/modules/` | 业务 spec + 各自的 handler 与路由 | **只动这里** |
所有模块由 `src/backend/src/lib.rs` 统一 `pub mod` 导出。
```rust
// ---- lib.rs ----
pub mod modules; // 业务层:demo / shop / books
pub mod platform; // 平台层:契约实现
pub mod routes; // 路由装配
```
### ids.rs
```rust
pub fn new_uuid() -> String; // 36 位 UUID v4(带连字符)
```
### session.rs
```rust
#[derive(Clone)]
pub struct TokenUser { pub user_id: String, pub account: String, pub is_admin: i32 }
#[derive(Clone, Default)]
pub struct SessionStore { /* Arc<RwLock<HashMap<String, TokenUser>>> */ }
impl SessionStore {
pub fn new() -> Self;
pub fn issue(&self, account: &str, user_id: &str, is_admin: i32) -> String; // "lite-" + 32 hex
pub fn resolve(&self, auth_header: Option<&str>) -> Option<TokenUser>; // 去 bearer 前缀(大小写不敏感)
}
```
### config.rs
```rust
pub struct Config {
pub port: u16, // 默认 30010,env PORT
pub pg_dir: PathBuf, // env PGLITE_DIR;"memory://" ⇒ open_temp()
pub project_dir: PathBuf,
pub static_dir: Option<PathBuf>, // src/frontend/dist 存在才有
}
impl Config { pub fn from_env(project_dir: PathBuf) -> Config; }
```
### auth.rs
```rust
/// 三个字段全是 Option:缺字段也要走业务信封(code=400),不能落到 axum 默认的 400 文本。
/// `grant_type` 是 snake_case 字面量,**不能**改名为 camelCase。
#[derive(serde::Deserialize)]
pub struct LoginForm {
pub account: Option<String>,
pub password: Option<String>,
pub grant_type: Option<String>,
}
pub async fn login(state: &AppState, body: LoginForm) -> Json<ActionResult>;
pub async fn current_user(state: &AppState, headers: HeaderMap) -> Json<ActionResult>;
/// 守卫:未登录 ⇒ `fail(600, "未登录")`;无菜单权限 ⇒ `fail(403, "无菜单权限")`
pub async fn require_login(state: &AppState, headers: &HeaderMap) -> Result<TokenUser, Json<ActionResult>>;
pub async fn require_module(state: &AppState, headers: &HeaderMap, module_key: &str)
-> Result<TokenUser, Json<ActionResult>>;
```
### permission.rs
```rust
pub async fn resolve_user_module_ids(db: &Db, user_id: &str) -> HashSet<String>;
pub async fn has_module(db: &Db, user_id: &str, is_admin: i32, module_key: &str) -> bool;
pub async fn build_menu_list(db: &Db, user_id: &str, is_admin: i32) -> Vec<MenuNode>;
#[derive(serde::Serialize)]
pub struct MenuNode {
pub id: String, pub full_name: String, // #[serde(rename="fullName")]
pub url_address: Option<String>, // #[serde(rename="urlAddress")]
pub icon: Option<String>,
pub parent_id: String, // #[serde(rename="parentId")]
pub children: Vec<MenuNode>,
}
```
### `platform/entity.rs`(业务实体 spec 的**类型**)+ `modules/`(业务 spec 本体)
🔴 **类型在平台层、spec 在业务层**(加业务模块只碰业务层)。
`platform/entity.rs`:
```rust
pub struct EntitySpec {
pub app_code: &'static str, // "demo" / "shop" / "books"
pub entity: &'static str, // "DemoItem" / "Product" / "Book"
pub table: &'static str, // "demo_item" / "shop_product" / "book_shop_book"
pub module_key: Option<&'static str>, // None = 仅登录守卫;Some("shop/Product")
pub columns: &'static [ColumnSpec],
pub numeric_columns: &'static [&'static str], // 需要 ::text 投影的列
// 🔴 `f_creator_user_id` 的写死值(裁决 S22):
// Some("admin") ⇒ 恒写 admin(demo);None ⇒ `body.creatorUserId || 'admin'`。
// 平台层**不认 app_code** ⇒ 加新表不必改引擎。
pub creator_fixed: Option<&'static str>,
}
pub struct ColumnSpec {
pub column: &'static str, // "f_title"
pub json_key: &'static str, // "title"
pub default: Option<&'static str>, // 新建时的默认值
pub numeric: bool, // true ⇒ 投影 ::text
}
```
`modules/mod.rs`(业务层登记表):
```rust
pub fn all_specs() -> &'static [EntitySpec];
pub fn find_spec(app_code: &str, entity: &str) -> Option<&'static EntitySpec>;
pub const ALL_ROUTES: &[&str]; // 全部业务路由(业务层的路由表)
pub fn router() -> Router<AppState>; // 全部业务模块的路由
```
### `platform/crud.rs`(spec 驱动的通用 CRUD 引擎)
```rust
pub(crate) async fn handle_list(state: &AppState, headers: &HeaderMap, spec: &EntitySpec) -> Json<ActionResult>;
pub(crate) async fn handle_save(state: &AppState, headers: &HeaderMap, spec: &EntitySpec, body: &Bytes) -> Json<ActionResult>;
pub(crate) async fn handle_delete(state: &AppState, headers: &HeaderMap, spec: &EntitySpec, raw: &RawQuery) -> Json<ActionResult>;
```
🔴 **平台层不含任何业务表名 / app_code** ⇒ 加业务表**不用改本文件**。
### routes.rs
```rust
pub fn build_router(state: AppState) -> Router;
```
(`with_state` 由 `main.rs` 在**链尾**调用;
业务路由由 `routes.rs` 的 `.merge(modules::router())` 一次并入 ⇒ **加业务模块不动平台层**。)
### AppState(`src/backend/src/platform/state.rs`)
```rust
#[derive(Clone)]
pub struct AppState {
pub config: Arc<Config>,
pub db: Arc<Db>,
pub sessions: Arc<SessionStore>,
}
```
🔴 **`src/backend/src/lib.rs` 现在只声明三层**:`pub mod platform;` / `pub mod modules;` / `pub mod routes;`
—— 平台层的模块清单在 `platform/mod.rs` 里,业务层的在 `modules/mod.rs` 里。
(`AppState` 在 `platform/state.rs`。)
---
## 10. 启动装配(main.rs)
顺序:
1. `resolve_project_dir()` —— 从可执行文件向上找锚点文件(`src/backend/db/schema.sql` + 根 `Cargo.toml`),**与 cwd 解耦**
2. `Config::from_env(project_dir)`
3. **标识符白名单自检**(不过 ⇒ 秒退 exit 1),放在开库**之前**
4. `Db::open` / `Db::open_temp` ⇒ `ensure_schema()`
5. `seed::ensure_base()` ⇒ 若用户数为 0 则 `seed::first_seed()`
🔴 **种子失败 ⇒ 打印人话错误 + `exit 1`(启动期不变量破了就立刻退出)**,
与第 3 步的白名单自检同一处置。react 的 `onModuleInit` 是 try/catch + `logger.warn` 后**继续跑**,
本仓**刻意不同**(react 那边是 NestJS 容器里已挂载的应用,退出不了;本仓是单二进制,退出更干净)。
这条**不在 HTTP 契约面上**(服务要么正常起来,要么根本不起来)。
6. `build_router(state)` + 404 兜底 + 405 改写中间件 + **catch-all(panic/未捕获异常 ⇒ HTTP 200 + `code=400`)** + `with_state(state)`(**链尾**)
7. `TcpListener::bind` ⇒ 绑定失败打印人话 + exit 1(**不 panic**)
**子命令**:`--enc <明文>` ⇒ 打印 hex 到 stdout,退出码 0(冒烟脚本用它自证 cipher,不依赖 node)。
`--help` / 未知参数 ⇒ 打印用法,退出码 0 或 2。
**`PGLITE_DIR=memory://`** ⇒ `Db::open_temp()`(pglite-rs 0.2.7 **没有**真正的内存模式,`open()` 只接受路径)。
---
## 11. 验收门(六道,全绿才算完成)
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error **0 warning**;release profile:根 `Cargo.toml` 写 `opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`;🔴 **不要**写 `panic="abort"`(Ruling P19:abort 下 `catch_unwind` 抓不到 panic,与 §6.5 的「panic ⇒ HTTP 200 + code=400」冲突 ⇒ 必须用默认的 `unwind`) |
| ② 单测 | `cargo test` | 见 §12 |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **全部断言全绿**(FAIL=0),断言集与 react 版**逐条对应**;🔴 **后端不用先起** —— 尺子默认自起隔离实例(见下) |
| ④ 前端手验 | `cd src/frontend && npm run dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → 3 个业务页可用 → 退出再登录 |
| ⑤ 静态闸门 | `bash scripts/check-module.sh` + `bash scripts/check-boundary.sh` + `bash scripts/check-contract.sh` + `bash scripts/check-citations.sh` | 四把尺子全绿(**86** / **11** / **10** / **4** 条断言,FAIL=0)——纯静态,不起后端。🔴 本仓后端-only:check-module 的 10 个前端接触点打 `⏭`(仍计入条数),见附录 A `[RULER]` |
**脚本退出码约定**(各入口一致):
`run.sh` 0=成功 / 1=运行期失败 / 2=用法错;
`check-module.sh` 0=全过 / 1=有 ❌ / 2=用法错;
`check-boundary.sh` 0=全过 / 1=有 ❌ / 2=用法错;
`check-contract.sh` 0=全过 / 1=有 ❌ / 2=用法错或前置错误(契约读不出来);
`check-citations.sh` 0=全过 / 1=有 ❌ / 2=用法错或前置错误;
`perm-smoke.sh` 0=全绿 / 1=有断言失败 / 2=前置错误(后端不可达且**显式指定了 `B`** ⇒ 不自起)。
🔴 **两把契约尺子默认自起隔离后端**(`scripts/smoke_backend.sh`):
没给 `B` ⇒ 先探 `:30010`;**通** ⇒ 用它;**不通** ⇒ 自起隔离实例(空闲端口 + `mktemp -d` 临时
`PGLITE_DIR`),跑完即删 ⇒ 两把尺子**互不污染**、不留脏数据、**CI 可跑**。
**显式给了 `B`** ⇒ **不自起**,不可达即退出码 2(尊重外部后端)。
🔴 **官方端点覆盖是一本「账」**(附录 A 的 `[OFFICIAL]` 区段,机器可读):
官方 JNPF 契约面的**端点全表**在 `JNPF_SOURCE_AUDIT.md` §4(**散文表格**),
本仓的**覆盖账本**在附录 A `[OFFICIAL]`(**机器可读**)⇒
`check-contract.sh` 的 **CC10** 与代码真实路由**双向**对账,并打印
**「官方端点覆盖 N/M」**(N = implemented + partial;M = 再加 absent;`oos` 单列不进分母)。
状态词表:`implemented`(已落地且形状对齐)/ `partial`(已落地但**形状有偏差**,
偏差逐条记在 `JNPF_COMPAT_SURFACE.md` §8 的 B1–B10)/ `absent`(未实现,可后置)/
`oos`(v1 明确不做)。🔴 **面 B / 共用的每条路由都必须在账上**(防止"实现了但没记账")。
🔴 **尺子的期望值只有一处**:**附录 A**(机器可读)。
菜单表 / 菜单树 / 业务模块清单 / **端点表(路径 / 方法 / 守卫 / 归属)** /
各尺子的断言条数**都不写在脚本里**,
一律由 `scripts/contract_expect.py` 从附录 A 读 ⇒
① 改契约只改附录 A 一处;② 代码漂移尺子立刻报;③ 加模块不用改脚本。
🔴 **每把尺子都自证**:结尾比对「本尺子实际跑了多少条断言」与附录 A `[RULER]` 登记的条数,
对不上 ⇒ **失败** ⇒ 尺子不会被人悄悄改弱(这条是**故意的**:加断言必须同步契约)。
---
## 12. 单测覆盖清单(门② 必须全过)
- **cipher**:上游向量逐字节相等;`md5_hex` ↔ `decrypt_to_md5` 往返;非法 hex ⇒ `None`
- **envelope**:业务失败 HTTP **200** + `code=400`;`code=600`/`403` 同形;成功 `code=200`+`msg='成功'`
- **db**:`split_sql_statements` 字面量感知(单引号 / dollar-quote / 注释内的 `;` 不切);
`column_to_json_key` / `json_key_to_column` 互逆;`valid_table` 只收 `[A-Za-z][A-Za-z0-9_]*`
- **ids**:UUID 36 位带连字符、格式合法
- **session**:登录后可查回;错误 token 查不到;`bearer` 前缀大小写不敏感
- **permission**:四源合并**各源单独可注入**;管理员短路**不查 SQL**(无授权记录的管理员仍放行);未映射菜单放行
- **seed**:空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;**再启动一次库内容不变**;不复活软删行
- **CRUD 往返**:36 位 UUID;numeric ⇒ `"9.90"`;int ⇒ `100`;软删过滤生效;账号重复返 **400**(不是 500)
---
## 13. 冒烟断言集(门③,逐条对应 react 版)
react 版 `scripts/perm-smoke.sh` 实际有 **32 条断言**。移植后一条不落,另加
**9 条真实业务模块断言**(33–41,asset/DataResource)+ **2 条多应用断言**(42/43)⇒ 本仓共 **43 条**:
| # | 断言 | 期望 |
|---|---|---|
| 1 | 无 token 访问 `User/List` | `code=600` |
| 2 | admin 加密登录 | `code=200` |
| 3 | token 非空 | 真 |
| 4 | `CurrentUser` | `code=200` |
| 5 | 菜单树 | `系统管理:用户管理,角色管理,机构管理,菜单管理\|Demo 示例:\|产品管理:\|图书超市:` |
| 6 | 新建 `smoke_user` | `code=200` |
| 7 | 重复账号 HTTP 状态 | **200**(不是 500) |
| 8 | 重复账号业务码 | `code=400` |
| 9 | 重复账号 msg | `账号已存在:smoke_user` |
| 10 | 写授权(一维数组) | `code=200` |
| 11 | 写授权(二维兼容) | `code=200` |
| 12 | `smoke_user` 登录 | `code=200` |
| 13 | `smoke_user` 菜单收窄 | `Demo 示例:` |
| 14 | `smoke_user` 访问 `User/List` | `code=403` |
| 15 | `smoke_user` 访问 `DemoItem/List` | `code=200` |
| 16 | 未知路由 | **HTTP 404** |
| 17 | admin 访问 `Product/List` | `code=200`(管理员短路) |
| 18 | Product 新建 | `code=200` |
| 19 | Product 主键长度 | `36` |
| 20 | Product numeric 往返 | `"9.90"` |
| 21 | Product 无 token | `code=600` |
| 22 | Product 未授权非管理员 | `code=403` |
| 23 | Book 列表(admin 短路) | `code=200` |
| 24 | Book 新建(6 字段) | `code=200` |
| 25 | Book 主键长度 | `36` |
| 26 | Book title 往返 | `三体` |
| 27 | Book author 往返 | `刘慈欣` |
| 28 | Book numeric 往返 | `"58.00"` |
| 29 | Book int 库存往返 | `100` |
| 30 | Book 列表含新建项 | 长度 ≥ 1 |
| 31 | Book 无 token | `code=600` |
| 32 | Book 未授权非管理员 | `code=403` |
| 33 | 数据资源列表(admin 短路) | `code=200` |
| 34 | 数据资源新建(6 字段) | `code=200` |
| 35 | 数据资源主键长度 | `36` |
| 36 | 数据资源 `name` 往返 | `全国企业工商登记数据` |
| 37 | 数据资源 `category` 往返 | `结构化` |
| 38 | 数据资源 `provider` 往返 | `尚数网` |
| 39 | 数据资源列表含新建项 | 长度 ≥ 1 |
| 40 | 数据资源无 token | `code=600` |
| 41 | 数据资源未授权非管理员 | `code=403` |
| 42 | 多应用:`CurrentUser` 无 `App-Code` 头 | `data.currentSystemId = "mainSystem"`(官方 `JnpfConst.MAIN_SYSTEM_CODE`,回落主系统) |
| 43 | 多应用:`CurrentUser` 带 `App-Code: app-b` | `data.currentSystemId = "app-b"`(应用路由生效) |
**脚本不得依赖 node**(react 版依赖 `node` + `crypto-js` + `src/backend/node_modules`,本仓一律不用):
- **cipher 加密** ⇒ 调用后端自证:`./target/release/ssw-platform --enc '<明文>'` 输出 hex(退出码 0)。
(冒烟脚本自带 `--enc` 的向量自检,**不**假设 node 存在。)
- **JSON 取值** ⇒ `jq`(若已装)或 `python3`(macOS 自带)写的取字段小工具;**不得**用 node。
- **期望菜单树** ⇒ **从附录 A 的 `[MENU_TREE]` 区段读**(不是写死在脚本里)——
值仍是 §8.4 的 `系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:`。
react 版是从 `src/backend/src/sys/seed.service.ts` 里 grep 菜单数组动态算的 ——
本仓是 Rust,没有那个文件 ⇒ 直接用字面量(§8.4 的表就是它的来源)。
- **后端地址** ⇒ `B` 环境变量,默认 **`http://127.0.0.1:30010`**(本仓端口,**不是** react 的 30000)。
- 所有 curl 都要带 `--noproxy '*'`(本机 curl 走系统代理,不加会打不通 loopback)。
<!-- BEGIN CONTRACT-EXPECT(机器可读期望值) -->
```text
# 契约期望值 —— **唯一真源**。
#
# 🔴 下面这段是**机器可读**的(`scripts/contract_expect.py` 解析),
# 所有尺子(check-module.sh / check-boundary.sh / check-contract.sh /
# perm-smoke.sh / perm-smoke-jnpf.sh)
# 的**期望值都从这里读** ⇒
# ① 改契约 ⇒ 改这一处,尺子自动跟着走;
# ② 代码漂移 ⇒ 尺子立刻报「与契约不一致」(不是默默放过)。
#
# 格式:区段 `[NAME]` + **制表符**分隔的列;`#` 开头是注释行(忽略)。
# 列名以各区段的表头注释为准。空字段 = 空值(NULL)。
#
# 区段:
# [MENU] 种子菜单 8 行(id / fullName / enCode / urlAddress / parentId / type / icon / sortCode)
# [MENU_TREE] 期望菜单树字符串(面 A 的 CurrentUser 对账用)
# [MODULE] 业务模块清单(app / entity / table / urlAddress / moduleKey / menuId / apiFile / rsFile)
# [ENDPOINT] **端点表**(face / method / path / guard / owner)—— 由 `scripts/check-contract.sh`
# 与**代码里真实注册的路由**逐条对账(总数 / 存在性 / 方法 / 归属层 / 守卫,双向)
# [FACE] 各契约面的条数(自洽对账用)
# [OFFICIAL] **官方端点台账**(method / path / status / src / note)—— 官方 JNPF 契约面的
# 覆盖账本;由 `scripts/check-contract.sh` 的 CC10 与代码真实路由**双向**对账
# [RULER] 各尺子的期望断言条数(尺子自证用)
[MENU]
# id fullName enCode urlAddress parentId type icon sortCode
m_sys 系统管理 permission system 0 1 setting 1
m_user 用户管理 permission.user system/User m_sys 2 2
m_role 角色管理 permission.role system/Role m_sys 2 3
m_org 机构管理 permission.organize system/Organize m_sys 2 4
m_menu 菜单管理 permission.menu system/Module m_sys 2 5
m_demo Demo 示例 permission.demo demo-item 0 2 app 6
m_product 产品管理 permission.shop.product shop/Product 0 2 app 7
m_book 图书超市 permission.books.book books/Book 0 2 app 8
m_resource 数据资源 permission.asset.dataResource asset/DataResource 0 2 app 9
[MENU_TREE]
系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:|数据资源:
[MODULE]
# app entity table urlAddress moduleKey menuId apiFile rsFile
# moduleKey = 该模块的守卫菜单 key;`None` = 仅需登录(无菜单权限要求)
# apiFile = 前端**应不应该**有 `src/frontend/src/api/<name>.ts`(`有` / `无`)
# rsFile = 业务模块源文件 `src/backend/src/modules/<name>.rs`
demo DemoItem demo_item demo-item None m_demo 无 demo.rs
shop Product shop_product shop/Product shop/Product m_product 有 shop.rs
books Book book_shop_book books/Book books/Book m_book 有 books.rs
asset DataResource asset_data_resource asset/DataResource asset/DataResource m_resource 有 asset.rs
[ENDPOINT]
# face method path guard owner
# face = A(面A 专属) / B(面B 专属) / AB(两面共用,按判别头 `Vue-Version: 3` 分流)
# guard = 无 / 登录 / 面A 的菜单路径 key / 面B 的点权限编码 `f_en_code`
# owner = platform(平台层) / 业务模块代号(demo|shop|books) ⇒ 路由注册在哪个文件
# path = 与代码**逐字**一致(axum 0.8 的 `{param}` 花括号语法)
A GET /api/health 无 platform
A POST /api/oauth/Login 无 platform
AB GET /api/oauth/CurrentUser 登录 platform
A GET /api/ssw/sys/User/List system/User platform
A POST /api/ssw/sys/User/Save system/User platform
A DELETE /api/ssw/sys/User/Delete system/User platform
A GET /api/ssw/sys/Role/List system/Role platform
A POST /api/ssw/sys/Role/Save system/Role platform
A DELETE /api/ssw/sys/Role/Delete system/Role platform
A GET /api/ssw/sys/Role/Modules 登录 platform
A GET /api/ssw/sys/Organize/List system/Organize platform
A POST /api/ssw/sys/Organize/Save system/Organize platform
A DELETE /api/ssw/sys/Organize/Delete system/Organize platform
A GET /api/ssw/sys/Module/List system/Module platform
A POST /api/ssw/sys/Module/Save system/Module platform
A DELETE /api/ssw/sys/Module/Delete system/Module platform
AB PUT /api/permission/Authority/Data/{objectId} 登录 platform
A GET /api/permission/Authority/RoleModules 登录 platform
B GET /api/permission/Users permission.user platform
B POST /api/permission/Users permission.user platform
B GET /api/permission/Users/{id} permission.user platform
B PUT /api/permission/Users/{id} permission.user platform
B DELETE /api/permission/Users/{id} permission.user platform
B POST /api/permission/Users/BatchDelete permission.user platform
B POST /api/permission/Users/BatchUpdateState permission.user platform
B GET /api/permission/Users/{id}/GetPosition permission.user platform
B POST /api/permission/Users/{id}/Actions/ResetPassword permission.user platform
B PUT /api/permission/Users/{id}/Actions/unlock permission.user platform
B GET /api/permission/Group permission.user platform
B POST /api/permission/Group permission.user platform
B GET /api/permission/Group/{id} permission.user platform
B PUT /api/permission/Group/{id} permission.user platform
B DELETE /api/permission/Group/{id} permission.user platform
B POST /api/permission/Group/{id}/Actions/AddUser permission.user platform
B POST /api/permission/Group/{id}/Actions/DeleteUser permission.user platform
B POST /api/permission/Users/{id}/SetPosition permission.user platform
B POST /api/permission/Users/SetPositionBatch permission.user platform
B POST /api/permission/Users/workHandover permission.user platform
B GET /api/permission/Users/{id}/SelectorByUserPosId permission.user platform
B GET /api/system/System/getDevUser permission.user platform
B DELETE /api/permission/socials/{id} permission.user platform
B GET /api/system/DictionaryData/All 登录 platform
B GET /api/system/HomeData 登录 platform
B POST /api/system/MenuData/useModuleNum/{id} 登录 platform
B GET /api/oauth/getLoginConfig 无 platform
B GET /api/oauth/getConfig/{account} 无 platform
B GET /api/permission/Organize permission.organize platform
B POST /api/permission/Organize permission.organize platform
B GET /api/permission/Organize/{id} permission.organize platform
B PUT /api/permission/Organize/{id} permission.organize platform
B DELETE /api/permission/Organize/{id} permission.organize platform
B GET /api/permission/Organize/Selector permission.organize platform
B POST /api/permission/Role permission.role platform
B GET /api/permission/Role/{id} permission.role platform
B PUT /api/permission/Role/{id} permission.role platform
B DELETE /api/permission/Role/{id} permission.role platform
B GET /api/permission/Role/Selector permission.role platform
B POST /api/permission/Role/RoleCondition permission.role platform
B GET /api/permission/Position permission.position platform
B POST /api/permission/Position permission.position platform
B GET /api/permission/Position/{id} permission.position platform
B PUT /api/permission/Position/{id} permission.position platform
B DELETE /api/permission/Position/{id} permission.position platform
B GET /api/permission/Position/Selector permission.position platform
B GET /api/permission/Position/SelectorTree permission.position platform
B POST /api/permission/Position/PositionCondition permission.position platform
B POST /api/permission/Position/SelectedList permission.position platform
B POST /api/permission/Position/{id}/Actions/DutyPosition permission.position platform
B POST /api/permission/Position/{id}/Actions/DutyUser permission.position platform
B GET /api/permission/Group/Selector permission.user platform
B GET /api/permission/Organize/AsyncPosList permission.organize platform
B POST /api/system/Menu permission.menu platform
B GET /api/system/Menu/{id} permission.menu platform
B PUT /api/system/Menu/{id} permission.menu platform
B DELETE /api/system/Menu/{id} permission.menu platform
B GET /api/system/Menu/Selector/{id} permission.menu platform
B GET /api/system/Menu/Selector/All permission.menu platform
B GET /api/system/Menu/Selector/Form permission.menu platform
B GET /api/system/Menu/Selector/Page permission.menu platform
B GET /api/system/Menu/SelectorFilter/{id} permission.menu platform
B GET /api/system/Menu/getSystemMenu permission.menu platform
B GET /api/system/Menu/{id}/Actions/Export permission.menu platform
B GET /api/system/Menu/getPermissionGroup/{id} permission.menu platform
B GET /api/system/Menu/getPermission/{id}/{permissionId} permission.menu platform
B GET /api/system/DictionaryType permission.dictionary platform
B POST /api/system/DictionaryType permission.dictionary platform
B GET /api/system/DictionaryType/{id} permission.dictionary platform
B PUT /api/system/DictionaryType/{id} permission.dictionary platform
B DELETE /api/system/DictionaryType/{id} permission.dictionary platform
B GET /api/system/DictionaryType/Selector/{id} permission.dictionary platform
B POST /api/system/DictionaryData permission.dictionary platform
B GET /api/system/DictionaryData/{id} permission.dictionary platform
B GET /api/system/DictionaryData/{id}/Info permission.dictionary platform
B PUT /api/system/DictionaryData/{id} permission.dictionary platform
B DELETE /api/system/DictionaryData/{id} permission.dictionary platform
B GET /api/system/DictionaryData/{id}/Data/Selector permission.dictionary platform
B GET /api/system/DictionaryData/{id}/Selector/{pid} permission.dictionary platform
B GET /api/system/DictionaryData/{id}/Actions/Export permission.dictionary platform
B GET /api/permission/Users/Selector permission.user platform
B POST /api/permission/Users/getUserList permission.user platform
B POST /api/permission/Users/getSelectedList permission.user platform
B POST /api/permission/Users/getSelectedUserList permission.user platform
B GET /api/permission/Users/ReceiveUserList permission.user platform
B GET /api/permission/Users/getAllPermission permission.user platform
B GET /api/permission/Users/Authorize permission.user platform
B GET /api/permission/Authority/{kind}/{objectId} permission.role platform
B POST /api/permission/Authority/{kind}/{objectId} permission.role platform
B GET /api/permission/RoleRelation/roleList permission.role platform
B POST /api/permission/RoleRelation/addRoles permission.role platform
B POST /api/permission/RoleRelation/deleteRoles permission.role platform
B POST /api/permission/RoleRelation/delete permission.role platform
B POST /api/permission/UserRelation permission.user platform
B POST /api/permission/UserRelation/delete permission.user platform
B GET /api/permission/UserRelation/userList permission.user platform
B GET /api/permission/Role permission.role platform
B POST /api/oauth/Logout 登录 platform
B GET /api/system/BaseLang/LangJson 登录 platform
B GET /api/permission/Organize/AsyncList/{id} permission.organize platform
B GET /api/system/Menu/ModuleBySystem permission.menu platform
B POST /api/permission/Authority/Data/{objectId}/Values 登录 platform
B GET /api/permission/Users/Current/BaseInfo 登录 platform
B PUT /api/permission/Users/Current/BaseInfo 登录 platform
B PUT /api/permission/Users/Current/Avatar 登录 platform
B PUT /api/permission/Users/Current/SystemTheme 登录 platform
B PUT /api/permission/Users/Current/SystemLanguage 登录 platform
B POST /api/permission/Users/Current/Actions/ModifyPassword 登录 platform
B GET /api/permission/Users/Current/Subordinate/{id} 登录 platform
B GET /api/permission/Users/Current/SystemLog 登录 platform
B GET /api/permission/Users/Current/getUserOrganizes 登录 platform
B GET /api/permission/Users/Current/getUserPositions 登录 platform
B GET /api/permission/Users/Current/getUserRoles 登录 platform
B PUT /api/permission/Users/Current/major 登录 platform
B GET /api/permission/Users/Current/SignImg 登录 platform
B POST /api/permission/Users/Current/SignImg 登录 platform
B DELETE /api/permission/Users/Current/{id}/SignImg 登录 platform
B PUT /api/permission/Users/Current/{id}/SignImg 登录 platform
B GET /api/permission/Users/Current/getAppSecret 登录 platform
B PUT /api/permission/Users/Current/saveAppSecret 登录 platform
B GET /api/permission/Users/Current/saasList 登录 platform
B GET /api/permission/Users/Current/saasinfo 登录 platform
B GET /api/permission/Users/Current/saasTenantName/{id} 登录 platform
B POST /api/permission/Users/Current/saasjoin 登录 platform
B DELETE /api/permission/Users/Current/{id}/saas 登录 platform
A GET /api/ssw/demo/DemoItem/List 登录 demo
A POST /api/ssw/demo/DemoItem/Save 登录 demo
A DELETE /api/ssw/demo/DemoItem/Delete 登录 demo
A GET /api/ssw/shop/Product/List shop/Product shop
A POST /api/ssw/shop/Product/Save shop/Product shop
A DELETE /api/ssw/shop/Product/Delete shop/Product shop
A GET /api/ssw/books/Book/List books/Book books
A POST /api/ssw/books/Book/Save books/Book books
A DELETE /api/ssw/books/Book/Delete books/Book books
A GET /api/ssw/asset/DataResource/List asset/DataResource asset
A POST /api/ssw/asset/DataResource/Save asset/DataResource asset
A DELETE /api/ssw/asset/DataResource/Delete asset/DataResource asset
[FACE]
# face 条数 说明
A 28 面 A 专属(+ 2 条共用 ⇒ 面 A 合计 30 条)
B 125 面 B 专属(官方 JNPF 形状)
AB 2 两面共用(CurrentUser / Authority Data —— 按判别头分流)
[OFFICIAL]
# 官方端点台账 —— 本仓对**官方 JNPF 契约面**的覆盖账本(机器可读)
# method = HTTP 方法;`*` = 端点**一族**(范围声明,不做存在性对账)
# path = 官方路径(axum 0.8 的 `{param}` 花括号语法)
# status = implemented(已落地且形状对齐) / partial(已落地但**形状有偏差**,见 note)
# / absent(未实现,可后置) / oos(v1 明确不做,不进覆盖分母)
# src = 官方出处(`文件:行号` ⇒ 由 `scripts/check-citations.sh` 逐条核对)
# note = 偏差/取舍说明
#
# 🔴 由 `scripts/check-contract.sh` 的 **CC10** 与代码真实路由**双向**对账:
# implemented/partial 的必须真的注册了;absent/oos 的必须**没有**注册;
# 反向:代码里**面 B / 共用**的每条路由都必须在本台账里**有账**。
# 覆盖 N/M = (implemented + partial) / (implemented + partial + absent)。
POST /api/oauth/Login partial LoginController.java:117 路径与入参逐字一致;返回的是面 A 形状(token 同名同义),官方 LoginVO 的 theme/wlQrcode/isSaas/saasList 未返
POST /api/oauth/Logout implemented LoginController.java:155 面 B 已落地:恒 `{data:null}`(前端 try/catch 丢弃返回值,但 404 会弹红条);服务端不撤销 token(进程内内存表无 revoke,已知限制 B5)
GET /api/system/BaseLang/LangJson implemented baseLang.ts:28-30 面 B 已落地:恒 `{data:null}` ⇒ 前端 `locales/index.ts:114` 走 `!res.data` 早退,不 merge 远端词条(本仓无 base_language 表)
GET /api/oauth/CurrentUser partial LoginController.java:192 面 B 返 PcUserVO 5 字段;sysConfigInfo 返空对象、currentSystemId 固定、按钮级权限恒空、permissionList 按菜单给
GET /api/permission/Users implemented UserController.java:293 面 B 已落地:PageListVO 形状、列表项无 password/secretkey、isAdministrator 是数字
GET /api/permission/Users/{id} implemented UserController.java:355 面 B 已落地:UserInfoVO 形状(Form.vue 的 field 逐字对齐),无 password/secretkey
POST /api/permission/Users implemented UserController.java:409 面 B 已落地:白名单写库 + 账号查重 + 默认口令 md5(123456),返回 `{id}`
PUT /api/permission/Users/{id} implemented UserController.java:429 面 B 已落地:**只 SET body 里出现的键**(未出现的列保持原值)
DELETE /api/permission/Users/{id} implemented UserController.java:496 面 B 已落地:软删(f_delete_mark=1),幂等
POST /api/permission/Users/BatchDelete implemented UserController.java:592 面 B 已落地:一条 UPDATE … IN ⇒ 原子;空集合返成功
POST /api/permission/Users/BatchUpdateState implemented UserController.java:694 面 B 已落地:批量改 f_enabled_mark
GET /api/permission/Users/All absent UserController.java:729 全量用户未做
GET /api/permission/Users/Selector implemented UserController.java:769 用户下拉未做
POST /api/permission/Users/UserCondition absent UserController.java:806 用户条件查询未做
GET /api/permission/Users/{id}/GetPosition implemented UserController.java:273 面 B 已落地:无 base_position 表 ⇒ 由 f_position_id 反推,包成 `[{id}]`
POST /api/permission/Users/{id}/Actions/ResetPassword implemented user.ts:37 面 B 已落地:body.password ⇒ md5;兼容 newPassword
PUT /api/permission/Users/{id}/Actions/unlock implemented user.ts:45 面 B 已落地:清 f_lock_mark / f_unlock_time / f_log_error_count
GET /api/permission/Users/ExportData oos user.ts:53 导入导出族(官方前端按需)—— v1 明确不做
GET /api/permission/Users/TemplateDownload oos user.ts:57-69 导入导出族 —— v1 明确不做
POST /api/permission/Users/ImportData oos user.ts:57-69 导入导出族 —— v1 明确不做
POST /api/permission/Users/ImportPreview oos user.ts:57-69 导入导出族 —— v1 明确不做
GET /api/permission/Users/ExportExceptionData oos user.ts:57-69 导入导出族 —— v1 明确不做
POST /api/permission/Users/getUserList implemented user.ts:49 批量选择族(可后置,未列入 v1 范围也未明确排除)
POST /api/permission/Users/getSelectedList implemented user.ts:73 批量选择族(可后置)
POST /api/permission/Users/getSelectedUserList implemented user.ts:77 批量选择族(可后置)
GET /api/permission/Group implemented group.ts:9 面 B 已落地:ListVO `{list}`(前端 `user/index.vue:340` 取 `res.data.list`);新表 `base_group`(官方 `JNPF-PostgreSQL.sql:1758`,14 列逐字)
POST /api/permission/Group implemented group.ts:17 面 B 已落地:白名单写库 + 名称非空校验,返 `{id}`;成员关系**不在**本表
GET /api/permission/Group/{id} implemented group.ts:25 面 B 已落地:`GroupForm.vue:64` 直接 `setFieldsValue(res.data)`
PUT /api/permission/Group/{id} implemented group.ts:21 面 B 已落地:**只 SET body 里出现的键**
DELETE /api/permission/Group/{id} implemented group.ts:29 面 B 已落地:软删分组 + 同步软删 `base_user_relation` 的 Group 关系行
POST /api/permission/Group/{id}/Actions/AddUser implemented group.ts:37 面 B 已落地:`base_user_relation`(f_object_type='Group'),幂等插;空集合返成功
POST /api/permission/Group/{id}/Actions/DeleteUser implemented group.ts:41 面 B 已落地:关系行软删;空集合返成功
POST /api/permission/Users/{id}/SetPosition implemented user.ts:101 面 B 已落地:岗位写 `base_user.f_position_id`(逗号分隔);无 base_position 表
POST /api/permission/Users/SetPositionBatch implemented user.ts:105 面 B 已落地:body `{userIds, ids}`,一条 UPDATE … ANY(string_to_array) 原子完成
POST /api/permission/Users/workHandover implemented user.ts:85 面 B 已落地:置 `f_handover_mark=1`;工作流/流程任务不迁 ⇒ 只落能落的部分
GET /api/permission/Users/{id}/SelectorByUserPosId implemented user.ts:93 面 B 已落地:同 `f_position_id` 的其它用户(ListVO)
GET /api/system/System/getDevUser implemented system.ts:53 面 B 已落地:`QueryUserSelect` 的 `:api` ⇒ ListVO;无「开发者」列 ⇒ 退化为全体用户(管理员优先)
DELETE /api/permission/socials/{id} implemented socialsUser.ts:21 面 B 已落地:本仓无 `base_socials_users` 表 ⇒ 无绑可解,恒成功(只返 msg)
GET /api/system/DictionaryData/All implemented dictionary.ts:38-40 面 B 已落地:恒 `{list:[]}`(无 base_dictionary 表);前端 `store/base.ts:48` 取 `res.data.list` ⇒ 不能是裸数组
GET /api/system/HomeData implemented homeData.ts:8 面 B 已落地:恒 `[]`(前端 `dashboard/index.vue:104` 读 `res.data.length` ⇒ 必须是数组)
POST /api/system/MenuData/useModuleNum/{id} implemented collectMenu.ts:21 面 B 已落地:常用菜单计数**无表可记** ⇒ 恒成功(每页 afterEach 都调,404 会弹红条)
GET /api/oauth/getLoginConfig implemented user.ts:33 面 B 已落地:恒 `{}`(**登录前**调用 ⇒ 无守卫;前端读 `res.data.redirect` ⇒ 必须是对象)
GET /api/oauth/getConfig/{account} implemented user.ts:31 面 B 已落地:恒 `{}`(同登录前,无守卫)
GET /api/permission/Organize implemented organize.ts:13 面 B 已落地:ListVO `{list}`(`organize/index.vue:280` 取 `res.data.list`);树本身走 `AsyncList/{parentId}`
POST /api/permission/Organize implemented organize.ts:17 面 B 已落地:白名单写库 + 名称非空校验;`f_organize_id_tree`/`f_org_name_tree` 按「父树+自己」拼
GET /api/permission/Organize/{id} implemented organize.ts:25 面 B 已落地:`OrganizeForm.vue:103` 直接 `setFieldsValue(res.data)`
PUT /api/permission/Organize/{id} implemented organize.ts:21 面 B 已落地:**只 SET body 里出现的键**(表单提交 parentId/category/fullName/enCode/sortCode/description)
DELETE /api/permission/Organize/{id} implemented organize.ts:29 面 B 已落地:软删本行;**不级联**子机构(已知限制)
GET /api/permission/Organize/Selector implemented organize.ts:53 面 B 已落地:ListVO 全树(不做 parentId 剪枝 ⇒ 权限页选择器一次看到全树)
GET /api/permission/Position implemented position.ts:9 面 B 已落地:ListVO `{list}`;新表 `base_position`(官方 DDL 逐字)
POST /api/permission/Position implemented position.ts:13 面 B 已落地:`POSITION_WRITE_FIELDS` 白名单 + 名称非空;`f_position_id_tree` 恒为自己(本仓岗位无层级)
GET /api/permission/Position/{id} implemented position.ts:21 面 B 已落地:岗位详情
PUT /api/permission/Position/{id} implemented position.ts:17 面 B 已落地:**只 SET body 里出现的键**
DELETE /api/permission/Position/{id} implemented position.ts:25 面 B 已落地:软删本行
GET /api/permission/Position/Selector implemented position.ts:45 面 B 已落地:ListVO 全量岗位
GET /api/permission/Position/SelectorTree implemented position.ts:41 面 B 已落地:`organizeId` 命中就只返该机构岗位;本仓岗位无层级 ⇒ 平铺
POST /api/permission/Position/PositionCondition implemented position.ts:37 面 B 已落地:body `{ids}` ⇒ `ANY(string_to_array(...))`
POST /api/permission/Position/SelectedList implemented position.ts:49 面 B 已落地:同 PositionCondition(**刻意不复用**,委托会让契约扫描器推不出守卫)
POST /api/permission/Position/{id}/Actions/DutyPosition implemented position.ts:29 面 B 已落地:写 `base_organize.f_duty_position`;`organizeId` 缺失 ⇒ 400
POST /api/permission/Position/{id}/Actions/DutyUser implemented position.ts:33 面 B 已落地:写 `base_position.f_duty_user`;`userId` 缺失 ⇒ 400
GET /api/permission/Organize/AsyncPosList implemented organize.ts:68 面 B 已落地:按 `type` 分流(position ⇒ 岗位表,否则按 parentId 取机构)
GET /api/permission/Group/Selector implemented group.ts:13 面 B 已落地:ListVO 全量分组
POST /api/system/Menu implemented menu.ts:22 面 B 已落地:`MENU_WRITE_FIELDS` 白名单 + 名称非空;`f_system_id` 不传就落当前 App-Code 解析出的系统
GET /api/system/Menu/{id} implemented menu.ts:31 面 B 已落地:菜单详情
PUT /api/system/Menu/{id} implemented menu.ts:26 面 B 已落地:**只 SET body 里出现的键**
DELETE /api/system/Menu/{id} implemented menu.ts:35 面 B 已落地:软删本行;**不级联**子菜单(已知限制)
GET /api/system/Menu/Selector/{id} implemented menu.ts:15 面 B 已落地:上级菜单下拉,**排除自己及其直接子级**(防树成环)
GET /api/system/Menu/Selector/All implemented menu.ts:19 面 B 已落地:ListVO 当前系统全量菜单
GET /api/system/Menu/Selector/Form implemented menu.ts:56 面 B 已落地:同 Selector/All
GET /api/system/Menu/Selector/Page implemented menu.ts:60 面 B 已落地:PageListVO;`type` 有值就按 `f_type` 过滤
GET /api/system/Menu/SelectorFilter/{id} implemented menu.ts:52 面 B 已落地:同 Selector/{id}(本仓无「发布」概念,退化等价)
GET /api/system/Menu/getSystemMenu implemented menu.ts:60 面 B 已落地:同 Selector/All
GET /api/system/Menu/{id}/Actions/Export implemented menu.ts:38 面 B 已落地:**恒 `data:null`**(无导出文件服务);前端 `if (!res.data.url) return;` 静默跳过
GET /api/system/Menu/getPermissionGroup/{id} implemented menu.ts:42 面 B 已落地:恒 `{list:[]}`(按钮/列/表单级权限不做,见已知限制 (ag))
GET /api/system/Menu/getPermission/{id}/{permissionId} implemented menu.ts:46 面 B 已落地:恒 `{list:[]}`,同上
GET /api/system/DictionaryType implemented dictionary.ts:8 面 B 已落地:ListVO;新表 `base_dictionary_type`(官方 DDL 逐字)
POST /api/system/DictionaryType implemented dictionary.ts:16 面 B 已落地:`DICT_TYPE_WRITE_FIELDS` 白名单 + 名称非空
GET /api/system/DictionaryType/{id} implemented dictionary.ts:28 面 B 已落地:字典分类详情
PUT /api/system/DictionaryType/{id} implemented dictionary.ts:20 面 B 已落地:**只 SET body 里出现的键**
DELETE /api/system/DictionaryType/{id} implemented dictionary.ts:32 面 B 已落地:软删本行;**不级联**字典数据
GET /api/system/DictionaryType/Selector/{id} implemented dictionary.ts:12 面 B 已落地:ListVO 全量分类(本仓分类只有一层 ⇒ 忽略 id)
POST /api/system/DictionaryData implemented dictionary.ts:50 面 B 已落地:`DICT_DATA_WRITE_FIELDS` 白名单 + 名称非空
GET /api/system/DictionaryData/{id} implemented dictionary.ts:36 面 B 已落地:ListVO 按 `f_dictionary_type_id` 过滤
GET /api/system/DictionaryData/{id}/Info implemented dictionary.ts:58 面 B 已落地:字典数据详情
PUT /api/system/DictionaryData/{id} implemented dictionary.ts:54 面 B 已落地:**只 SET body 里出现的键**
DELETE /api/system/DictionaryData/{id} implemented dictionary.ts:62 面 B 已落地:软删本行
GET /api/system/DictionaryData/{id}/Data/Selector implemented dictionary.ts:44 面 B 已落地:按分类过滤的下拉
GET /api/system/DictionaryData/{id}/Selector/{pid} implemented dictionary.ts:40 面 B 已落地:同分类下拉树(本仓字典数据无层级 ⇒ 平铺)
GET /api/system/DictionaryData/{id}/Actions/Export implemented dictionary.ts:66 面 B 已落地:**恒 `data:null`**(无导出服务);前端 `if (!res.data.url) return;` 静默跳过
GET /api/permission/Users/Selector implemented user.ts:13 面 B 已落地:用户选择器 ListVO;`keyword` 命中 `f_account`/`f_real_name`
POST /api/permission/Users/getUserList implemented user.ts:49 面 B 已落地:body `{ids}` ⇒ `ANY(string_to_array(...))`
POST /api/permission/Users/getSelectedList implemented user.ts:73 面 B 已落地:**刻意不复用** getUserList(委托会让契约扫描器推不出守卫)
POST /api/permission/Users/getSelectedUserList implemented user.ts:77 面 B 已落地:组织维度已选用户,同 getSelectedList
GET /api/permission/Users/ReceiveUserList implemented user.ts:89 面 B 已落地:交接接收人候选,同 Selector(**先自己判守卫再委托**)
GET /api/permission/Users/getAllPermission implemented user.ts:109 面 B 已落地:点权限集合 = 可见菜单的 `f_en_code`(本仓只做菜单级,见限制 (ag))
GET /api/permission/Users/Authorize implemented user.ts:113 面 B 已落地:同 getAllPermission(授权只到菜单级)
GET /api/permission/Authority/{kind}/{objectId} implemented auth.ts:17 面 B 已落地:**恒 `{ids:[], all:false, list:[]}`**(本仓无 Portal/流程/打印模板三类对象)
POST /api/permission/Authority/{kind}/{objectId} implemented auth.ts:21 面 B 已落地:恒成功(同上,无对象可授权)
GET /api/permission/RoleRelation/roleList implemented roleRelation.ts:29 面 B 已落地:`base_role_relation` 只记用户↔角色 ⇒ `objectId` 当**用户 id** 用
POST /api/permission/RoleRelation/addRoles implemented roleRelation.ts:21 面 B 已落地:body `{objectId, roleIds}`;幂等插(`ON CONFLICT DO NOTHING`)
POST /api/permission/RoleRelation/deleteRoles implemented roleRelation.ts:25 面 B 已落地:body `{objectId, roleIds}` ⇒ 软删关系行
POST /api/permission/RoleRelation/delete implemented roleRelation.ts:17 面 B 已落地:body `{objectId, ids}`,等价 deleteRoles
POST /api/permission/UserRelation implemented userRelation.ts:13 面 B 已落地:body `{objectType, objectId, userIds}`,写 `base_user_relation`
POST /api/permission/UserRelation/delete implemented userRelation.ts:17 面 B 已落地:软删关系行
GET /api/permission/UserRelation/userList implemented userRelation.ts:9 面 B 已落地:`objectId` 下的用户 ListVO
GET /api/permission/Role implemented RoleController.java:99-100 面 B 已落地:PageListVO 形状
GET /api/permission/Role/{id} implemented role.ts:25 面 B 已落地:表单直接 `setFieldsValue(res.data)`
POST /api/permission/Role implemented role.ts:17 面 B 已落地:`ROLE_WRITE_FIELDS` 白名单写库 + 名称非空校验,返 `{id}`
PUT /api/permission/Role/{id} implemented role.ts:21 面 B 已落地:**只 SET body 里出现的键**
DELETE /api/permission/Role/{id} implemented role.ts:29 面 B 已落地:软删本行;不级联解绑 `base_role_relation`
GET /api/permission/Role/Selector implemented role.ts:13 面 B 已落地:ListVO;`type` 有值就按 `f_type` 过滤
POST /api/permission/Role/RoleCondition implemented role.ts:33 面 B 已落地:body `{ids}`,`ANY(string_to_array(...))` 一次取回
GET /api/permission/Organize/AsyncList/{id} partial OrganizeController.java:107-110 面 B 已落地:按父 id 逐层取,但**不分页**(pageSize = 本层条数)
GET /api/permission/Organize implemented organize.ts:13 面 B 已落地:ListVO `{list}`(`organize/index.vue:280` 取 `res.data.list`);逐层树走 `AsyncList/{parentId}`
GET /api/permission/Organize/{id} implemented organize.ts:25 面 B 已落地:`OrganizeForm.vue:103` 直接 `setFieldsValue(res.data)`
POST /api/permission/Organize implemented organize.ts:17 面 B 已落地:白名单写库 + 名称非空;`f_organize_id_tree`/`f_org_name_tree` 按「父树+自己」拼
PUT /api/permission/Organize/{id} implemented organize.ts:21 面 B 已落地:**只 SET body 里出现的键**
DELETE /api/permission/Organize/{id} implemented organize.ts:29 面 B 已落地:软删本行;**不级联**子机构(已知限制)
GET /api/permission/Organize/Selector implemented organize.ts:53 面 B 已落地:ListVO 全树(不做 parentId 剪枝 ⇒ 权限页选择器一次看到全树)
POST /api/permission/Organize/SelectedList absent OrganizeController.java:341 机构已选列表未做
GET /api/system/Menu/ModuleBySystem implemented ModuleController.java:121 面 B 已落地:ListVO 形状(不是裸数组)、节点 15 字段
GET /api/system/Menu/{systemId}/TreeView absent ModuleController.java:332 管理端菜单树未做
GET /api/system/Menu/Selector/{id} implemented menu.ts:15 面 B 已落地:上级菜单下拉,**排除自己及直接子级**(防树成环)
GET /api/system/Menu/Selector/All implemented menu.ts:19 面 B 已落地:ListVO 当前系统全量菜单
POST /api/system/Menu implemented menu.ts:22 面 B 已落地:`MENU_WRITE_FIELDS` 白名单 + 名称非空;`f_system_id` 不传就落当前 App-Code 解析出的系统
PUT /api/system/Menu/{id} implemented menu.ts:26 面 B 已落地:**只 SET body 里出现的键**
GET /api/system/Menu/{id} implemented menu.ts:31 面 B 已落地:菜单详情
DELETE /api/system/Menu/{id} implemented menu.ts:35 面 B 已落地:软删本行;**不级联**子菜单(已知限制)
PUT /api/system/Menu/{id}/Actions/State absent ModuleController.java:498-499 菜单启停未做
POST /api/permission/Authority/Data/{objectId}/Values partial AuthorizeController.java:99-100 面 B 已落地:官方完整 body 真落库、读是 POST;但 list(权限树模型)返空数组
PUT /api/permission/Authority/Data/{objectId} partial AuthorizeController.java:159-160 两面共用(按判别头分流);list(权限树模型)返空数组
GET /api/permission/Authority/Model/{itemId}/{objectType} absent AuthorizeController.java:124-125 权限树模型读取未做
PUT /api/permission/Authority/Model/{portalManageId} absent AuthorizeController.java:138-139 权限树模型保存未做
* /api/system/ModuleDataAuthorizeLink/** oos authorize.ts:4 低代码数据权限方案(表/字段级)—— v1 明确不碰
GET /api/permission/Users/Current/BaseInfo implemented userSetting.ts:13 个人资料:新表 `base_user_extra`(官方 `JNPF-PostgreSQL.sql:4637`,18 列逐字);`preferenceJson` 是**字符串**;`avatar` 与 `headIcon` 同值
PUT /api/permission/Users/Current/BaseInfo implemented userSetting.ts:17 `SELF_WRITE_FIELDS` 白名单(**不含** account/organizeId/enabledMark)+ 只 SET body 里出现的键
PUT /api/permission/Users/Current/Avatar implemented userSetting.ts:9 写 `base_user.f_head_icon`
PUT /api/permission/Users/Current/SystemTheme implemented userSetting.ts:25 写 `base_user.f_theme`
PUT /api/permission/Users/Current/SystemLanguage implemented userSetting.ts:29 写 `base_user.f_language`
POST /api/permission/Users/Current/Actions/ModifyPassword implemented userSetting.ts:21 旧口令校验 + 新口令走官方 cipher;**不回显口令**
GET /api/permission/Users/Current/Subordinate/{id} implemented userSetting.ts:33 查 `f_manager_id` 指向自己的下级
GET /api/permission/Users/Current/SystemLog implemented userSetting.ts:37 本仓无登录日志表 ⇒ 恒空列表
GET /api/permission/Users/Current/getUserOrganizes implemented userSetting.ts:41 `base_user_relation`(f_object_type='Organize')+ 祖先链
GET /api/permission/Users/Current/getUserPositions implemented userSetting.ts:45 `f_position_id` 逗号串拆开 + 查 `base_position`
GET /api/permission/Users/Current/getUserRoles implemented userSetting.ts:49 `f_role_id` 逗号串拆开 + 查 `base_role`
PUT /api/permission/Users/Current/major implemented userSetting.ts:53 设默认岗位 / 切换身份 / 切换系统(`f_position_id`/`f_role_id`/`f_app_system_id`)
GET /api/permission/Users/Current/SignImg implemented userSetting.ts:57 新表 `base_sign_img`(官方 `JNPF-PostgreSQL.sql:3937`,14 列逐字);`f_creator_user_id` 存**登录账号**
POST /api/permission/Users/Current/SignImg implemented userSetting.ts:61 `signImg` 非空校验 + 默认签名落库
DELETE /api/permission/Users/Current/{id}/SignImg implemented userSetting.ts:65 软删;**只能删自己的**(`f_creator_user_id` 匹配当前账号)
PUT /api/permission/Users/Current/{id}/SignImg implemented userSetting.ts:69 设默认 ⇒ 同用户其余置 `f_is_default=0`
GET /api/permission/Users/Current/getAppSecret implemented userSetting.ts:97 读 `base_user_extra.f_property_json`;没有 ⇒ 空串
PUT /api/permission/Users/Current/saveAppSecret implemented userSetting.ts:101 重新生成 AppSecret 写回 `f_property_json`
GET /api/permission/Users/Current/saasList implemented userSetting.ts:85 本仓单租户(§2.2 不做多租户)⇒ 恒空列表
GET /api/permission/Users/Current/saasinfo implemented userSetting.ts:89 本仓单租户 ⇒ 恒空对象
GET /api/permission/Users/Current/saasTenantName/{id} implemented userSetting.ts:93 本仓单租户 ⇒ 恒空串
POST /api/permission/Users/Current/saasjoin implemented userSetting.ts:77 本仓单租户 ⇒ **明确失败**(不做静默假成功)
DELETE /api/permission/Users/Current/{id}/saas implemented userSetting.ts:81 本仓单租户 ⇒ **明确失败**(同上)
[RULER]
# name 期望断言数(尺子**自己**断言的条数;跑出来的条数对不上 ⇒ 失败)
# 43 = react 版对齐的 32 条 + 真实业务模块 asset/DataResource 9 条 + 多应用 2 条
# (无 App-Code ⇒ 主系统 / App-Code: app-b ⇒ app-b)
perm-smoke.sh 43
# 23 = 原 18 条 + 多应用 1 条(App-Code: app-b ⇒ currentSystemId = app-b,与面 A 同一口径)
# + 用户 CRUD 4 条(详情无口令 / 改档只 SET 出现的键 / 批量启停 + 软删)
perm-smoke-jnpf.sh 23
# 🔴 本仓是**后端-only**(CLAUDE.md §2.2:前端/移动端本期不动,沿用 Java 版)⇒
# check-module 的「前端接触点」(4 模块 × 4 处 + 全局面 A 判别头)按 N/A 打 `⏭`
# 且**仍计入条数**;114 = 4 模块 × 28 条 + 全局面 B 判别头 1 条 + 全局面 A 判别头 1 条。
# (脚手架原版口径 93 = 3 模块含真实前端的条数,本仓无 src/frontend,不适用。)
check-module.sh 114
check-boundary.sh 11
check-contract.sh 10
check-citations.sh 4
```
<!-- END CONTRACT-EXPECT -->