Files
ssw-platform/docs/contract.md
T
admin ce30c5b2f6 feat(pack): 框架固定包 + 加模块一条命令(批次 12 + 12.5)
把「内核怎么知道有这个包」从手写改成生成,漏接直接报错而不是静默 404。

- crates/sspf-plugin:load_static() 收掉装配样板,bootstrap 的 load_packs 缩成一行

- 包统一出口:pub struct Pack + pub const DDLS(生成器不必理解各包常量命名)

- 业务 DDL 跟包走(packs/*/schema/*.sql 经 include_str! 编进二进制)

- packs_gen.rs / modules/mod.rs 5 段 / Cargo.toml / contract.md 三段改由 pack-sync.py 生成

- scripts/new-pack.sh:一条命令产出 5 个后端文件 + 接线 + 可选前端三件套

- scripts/verify.sh 静态闸门一键跑;.workbuddy 记忆与 HANDOFF 见下一提交
2026-11-01 23:04:53 +08:00

1956 lines
150 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` | 四把尺子全绿(**123** / **11** / **10** / **4** 条断言,FAIL=0)——纯静态,不起后端。🔴 批次 12 起本仓有 `src/frontend`(React MVP 模板)⇒ check-module 的前端接触点是**真检查**,不再是 `⏭`,见附录 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
<!-- PACK:BEGIN -->
# 🔴 以下由 `scripts/pack-sync.py` 从 `packs/*` 生成 —— **不许手改**
# (下次同步会被覆盖;改包就够)
m_resource 数据资源 permission.asset.dataResource asset/DataResource 0 2 app 9
<!-- PACK:END -->
[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
<!-- PACK:BEGIN -->
# 🔴 以下由 `scripts/pack-sync.py` 从 `packs/*` 生成 —— **不许手改**
# (下次同步会被覆盖;改包就够)
asset DataResource asset_data_resource asset/DataResource asset/DataResource m_resource 有 asset.rs
<!-- PACK:END -->
[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 GET /api/system/System 登录 platform
B POST /api/system/System appCenter platform
B GET /api/system/System/Selector 登录 platform
B GET /api/system/System/userAuthList 登录 platform
B POST /api/system/System/actionTop 登录 platform
B GET /api/system/System/getAppAuthorization/{id} 登录 platform
B POST /api/system/System/saveAppAuthorization appConfig.baseConfig platform
B POST /api/system/System/changeAppAuthorization appConfig.baseConfig platform
B GET /api/system/System/{id} 登录 platform
B PUT /api/system/System/{id} appConfig.baseConfig platform
B DELETE /api/system/System/{id} appCenter platform
B POST /api/system/System/{id}/Actions/Copy appCenter platform
B POST /api/system/System/preferenceSave/{id} appConfig.baseConfig platform
B GET /api/system/SysConfig sysConfig.parameter platform
B PUT /api/system/SysConfig sysConfig.parameter platform
B GET /api/system/SysConfig/socials sysConfig.parameter platform
B PUT /api/system/SysConfig/socials sysConfig.parameter platform
B GET /api/system/SysConfig/getAdminList sysConfig.parameter platform
B PUT /api/system/SysConfig/setAdminList sysConfig.parameter platform
B POST /api/system/SysConfig/{type}/testQyWebChatConnect sysConfig.parameter platform
B POST /api/system/SysConfig/testDingTalkConnect sysConfig.parameter platform
B GET /api/system/Tag 登录 platform
B POST /api/system/Tag 登录 platform
B GET /api/system/Tag/selector 登录 platform
B GET /api/system/Tag/{id} 登录 platform
B PUT /api/system/Tag/{id} 登录 platform
B DELETE /api/system/Tag/{id} 登录 platform
B POST /api/system/SynThirdInfo sysConfig.parameter platform
B GET /api/system/SynThirdInfo/getSynThirdTotal/{type} sysConfig.parameter platform
B GET /api/system/SynThirdInfo/clearAllSyn sysConfig.parameter platform
B GET /api/system/SynThirdInfo/getHandleNum sysConfig.parameter platform
B GET /api/system/BusinessCategory 登录 platform
B POST /api/system/BusinessCategory 登录 platform
B GET /api/system/BusinessCategory/treeList 登录 platform
B GET /api/system/BusinessCategory/selector 登录 platform
B GET /api/system/BusinessCategory/{id} 登录 platform
B PUT /api/system/BusinessCategory/{id} 登录 platform
B DELETE /api/system/BusinessCategory/{id} 登录 platform
B GET /api/message 登录 platform
B POST /api/message/Actions/ReadAll 登录 platform
B GET /api/message/ReadInfo/{id} 登录 platform
B DELETE /api/message/Record 登录 platform
B POST /api/message/Reply/{id} 登录 platform
B POST /api/message/Notice/List msgCenter.notice platform
B POST /api/message/Notice msgCenter.notice platform
B GET /api/message/Notice/{id} msgCenter.notice platform
B PUT /api/message/Notice/{id} msgCenter.notice platform
B DELETE /api/message/Notice/{id} msgCenter.notice platform
B PUT /api/message/Notice/{id}/Actions/Release msgCenter.notice platform
B GET /api/message/Notice/{id}/ReplyUserList msgCenter.notice 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
B GET /api/permission/Standing permission.identity platform
B POST /api/permission/Standing permission.identity platform
B GET /api/permission/Standing/list permission.identity platform
B GET /api/permission/Standing/{id} permission.identity platform
B PUT /api/permission/Standing/{id} permission.identity platform
B DELETE /api/permission/Standing/{id} permission.identity platform
B POST /api/permission/Standing/{id}/Actions/AddObject permission.identity platform
B POST /api/permission/Standing/{id}/Actions/DeleteObject permission.identity platform
B GET /api/permission/PermissionGroup permission.authGroup platform
B POST /api/permission/PermissionGroup permission.authGroup platform
B GET /api/permission/PermissionGroup/{id} permission.authGroup platform
B PUT /api/permission/PermissionGroup/{id} permission.authGroup platform
B DELETE /api/permission/PermissionGroup/{id} permission.authGroup platform
B POST /api/permission/PermissionGroup/{id}/Actions/Copy permission.authGroup platform
B GET /api/permission/PermissionGroup/PermissionMember/{id} permission.authGroup platform
B POST /api/permission/PermissionGroup/PermissionMember/{id} permission.authGroup platform
B GET /api/permission/Action permission.action platform
B POST /api/permission/Action permission.action platform
B GET /api/permission/Action/{id} permission.action platform
B PUT /api/permission/Action/{id} permission.action platform
B DELETE /api/permission/Action/{id} permission.action platform
B GET /api/system/Log sysLog.loginLog platform
B DELETE /api/system/Log sysLog.loginLog platform
B DELETE /api/system/Log/deleteLoginLog 登录 platform
B GET /api/system/Log/ModuleName sysLog.loginLog platform
B GET /api/system/Log/{id} sysLog.loginLog platform
B DELETE /api/system/Log/{id} sysLog.loginLog platform
B GET /api/system/CommonWords 登录 platform
B POST /api/system/CommonWords 登录 platform
B GET /api/system/CommonWords/Selector 登录 platform
B POST /api/system/CommonWords/UsesNum 登录 platform
B GET /api/system/CommonWords/{id} 登录 platform
B PUT /api/system/CommonWords/{id} 登录 platform
B DELETE /api/system/CommonWords/{id} 登录 platform
B GET /api/system/BillRule templateCenter.billRule platform
B POST /api/system/BillRule templateCenter.billRule platform
B GET /api/system/BillRule/Selector templateCenter.billRule platform
B GET /api/system/BillRule/BillNumber/{enCode} 登录 platform
B POST /api/system/BillRule/Actions/Import templateCenter.billRule platform
B GET /api/system/BillRule/{id} templateCenter.billRule platform
B PUT /api/system/BillRule/{id} templateCenter.billRule platform
B DELETE /api/system/BillRule/{id} templateCenter.billRule platform
B PUT /api/system/BillRule/{id}/Actions/State templateCenter.billRule platform
B GET /api/system/BillRule/{id}/Actions/Export templateCenter.billRule platform
B GET /api/system/DataSource dataCenter.dataSource platform
B POST /api/system/DataSource dataCenter.dataSource platform
B GET /api/system/DataSource/Selector 登录 platform
B GET /api/system/DataSource/getGroup 登录 platform
B POST /api/system/DataSource/Actions/Test dataCenter.dataSource platform
B GET /api/system/DataSource/{id} dataCenter.dataSource platform
B PUT /api/system/DataSource/{id} dataCenter.dataSource platform
B DELETE /api/system/DataSource/{id} dataCenter.dataSource platform
B GET /api/system/BasicDataType 登录 platform
B GET /api/system/CommonFields 登录 platform
B GET /api/system/DataModel/{linkId}/Tables 登录 platform
B GET /api/system/DataModel/{linkId}/TableAll 登录 platform
B GET /api/system/DataModel/{linkId}/Table/{tableName} dataCenter.dataModel|onlineDev.formDesign platform
B GET /api/system/DataModel/{linkId}/Tables/{tableName}/Fields 登录 platform
B GET /api/system/DataModel/{linkId}/Tables/{tableName}/Fields/Selector 登录 platform
B GET /api/system/DataModel/{linkId}/Table/{tableName}/Preview dataCenter.dataModel platform
B POST /api/system/DataModel/{linkId}/Table dataCenter.dataModel platform
B PUT /api/system/DataModel/{linkId}/Table dataCenter.dataModel platform
B PUT /api/system/DataModel/{linkId}/addFields dataCenter.dataModel|onlineDev.formDesign platform
B DELETE /api/system/DataModel/{linkId}/Table/{tableName} dataCenter.dataModel platform
B DELETE /api/system/DataModel/{linkId}/deleteAllTable dataCenter.dataModel platform
B POST /api/system/DataModel/{linkId}/Table/{tableName}/Actions/Copy dataCenter.dataModel platform
B GET /api/system/DataModel/{linkId}/Table/{tableName}/Actions/Export dataCenter.dataModel platform
B POST /api/system/DataModel/{linkId}/Actions/Import dataCenter.dataModel platform
B GET /api/system/Dataset dataCenter.dataset platform
B POST /api/system/Dataset dataCenter.dataset platform
B GET /api/system/Dataset/getList 登录 platform
B POST /api/system/Dataset/previewSql dataCenter.dataset platform
B POST /api/system/Dataset/fields 登录 platform
B POST /api/system/Dataset/Actions/Import dataCenter.dataset platform
B GET /api/system/Dataset/GetParam/{id} 登录 platform
B GET /api/system/Dataset/{id} dataCenter.dataset platform
B PUT /api/system/Dataset/{id} dataCenter.dataset platform
B DELETE /api/system/Dataset/{id} dataCenter.dataset platform
B GET /api/system/Dataset/{id}/get 登录 platform
B POST /api/system/Dataset/{id}/save dataCenter.dataset platform
B GET /api/system/Dataset/{id}/Actions/Export dataCenter.dataset platform
B POST /api/system/Dataset/{id}/Actions/Copy dataCenter.dataset platform
B POST /api/system/Dataset/{id}/Actions/Preview 登录 platform
B POST /api/system/Dataset/{id}/Actions/List 登录 platform
B POST /api/system/Dataset/{id}/Actions/InfoByIds 登录 platform
B POST /api/system/Dataset/{id}/Actions/getRes dataCenter.dataset platform
B GET /api/system/DataInterface dataCenter.dataService platform
B POST /api/system/DataInterface dataCenter.dataService platform
B GET /api/system/DataInterface/getList 登录 platform
B GET /api/system/DataInterface/GetParam/{id} 登录 platform
B GET /api/system/DataInterface/{id} dataCenter.dataService platform
B PUT /api/system/DataInterface/{id} dataCenter.dataService platform
B DELETE /api/system/DataInterface/{id} dataCenter.dataService platform
B GET /api/system/DataInterface/{id}/get dataCenter.dataService platform
B POST /api/system/DataInterface/{id}/save dataCenter.dataService platform
B POST /api/system/DataInterface/{id}/Actions/Copy dataCenter.dataService platform
B GET /api/system/DataInterface/{id}/Actions/Export dataCenter.dataService platform
B POST /api/system/DataInterface/{id}/Actions/Preview 登录 platform
B GET /api/system/InterfaceOauth integrationCenter.openApi platform
B POST /api/system/InterfaceOauth integrationCenter.openApi platform
B GET /api/system/InterfaceOauth/getAppId integrationCenter.openApi platform
B POST /api/system/InterfaceOauth/getInterfaceList integrationCenter.openApi platform
B GET /api/system/InterfaceOauth/dataInterfaceLog/{id} integrationCenter.openApi platform
B GET /api/system/InterfaceOauth/interfaceSelector integrationCenter.openApi platform
B POST /api/system/InterfaceOauth/SaveUserList integrationCenter.openApi platform
B GET /api/system/InterfaceOauth/{id} integrationCenter.openApi platform
B PUT /api/system/InterfaceOauth/{id} integrationCenter.openApi platform
B DELETE /api/system/InterfaceOauth/{id} integrationCenter.openApi platform
B GET /api/system/printDev onlineDev.printDev platform
B POST /api/system/printDev onlineDev.printDev platform
B GET /api/system/printDev/Selector 登录 platform
B GET /api/system/printDev/WorkSelector 登录 platform
B POST /api/system/printDev/getListOptions 登录 platform
B GET /api/system/printDev/{id} onlineDev.printDev platform
B PUT /api/system/printDev/{id} onlineDev.printDev platform
B DELETE /api/system/printDev/{id} onlineDev.printDev platform
B POST /api/system/printDev/{id}/Actions/Copy onlineDev.printDev platform
B GET /api/system/printDev/{id}/Actions/Export onlineDev.printDev platform
B GET /api/system/printDev/{id}/Actions/Preview onlineDev.printDev platform
B POST /api/system/printDev/BatchData 登录 platform
B POST /api/system/printDev/Save onlineDev.printDev platform
B GET /api/system/printDev/Info/{id} onlineDev.printDev platform
B GET /api/system/printDev/Version/{id} onlineDev.printDev platform
B POST /api/system/printDev/Info/{id} onlineDev.printDev platform
B DELETE /api/system/printDev/Info/{id} onlineDev.printDev platform
B GET /api/system/Signature 登录 platform
B POST /api/system/Signature 登录 platform
B GET /api/system/Signature/Selector 登录 platform
B POST /api/system/Signature/ListByIds 登录 platform
B GET /api/system/Signature/{id} 登录 platform
B PUT /api/system/Signature/{id} 登录 platform
B DELETE /api/system/Signature/{id} 登录 platform
B POST /api/system/ModuleButton permission.resource|appConfig.appResource platform
B POST /api/system/ModuleButton/selectActions/{menuId} permission.resource|appConfig.appResource platform
B GET /api/system/ModuleButton/{menuId}/List permission.resource|appConfig.appResource platform
B GET /api/system/ModuleButton/{menuId}/Selector permission.resource|appConfig.appResource platform
B GET /api/system/ModuleButton/{id} permission.resource|appConfig.appResource platform
B PUT /api/system/ModuleButton/{id} permission.resource|appConfig.appResource platform
B DELETE /api/system/ModuleButton/{id} permission.resource|appConfig.appResource platform
B POST /api/system/ModuleColumn permission.resource|appConfig.appResource platform
B POST /api/system/ModuleColumn/Actions/Batch permission.resource|appConfig.appResource platform
B GET /api/system/ModuleColumn/{moduleId}/Fields permission.resource|appConfig.appResource platform
B GET /api/system/ModuleColumn/{id} permission.resource|appConfig.appResource platform
B PUT /api/system/ModuleColumn/{id} permission.resource|appConfig.appResource platform
B DELETE /api/system/ModuleColumn/{id} permission.resource|appConfig.appResource platform
B POST /api/system/ModuleForm permission.resource|appConfig.appResource platform
B POST /api/system/ModuleForm/Actions/Batch permission.resource|appConfig.appResource platform
B GET /api/system/ModuleForm/{moduleId}/Fields permission.resource|appConfig.appResource platform
B GET /api/system/ModuleForm/{id} permission.resource|appConfig.appResource platform
B PUT /api/system/ModuleForm/{id} permission.resource|appConfig.appResource platform
B DELETE /api/system/ModuleForm/{id} permission.resource|appConfig.appResource platform
B POST /api/system/AdvancedQuery 登录 platform
B GET /api/system/AdvancedQuery/{moduleId}/List 登录 platform
B GET /api/system/AdvancedQuery/{id} 登录 platform
B PUT /api/system/AdvancedQuery/{id} 登录 platform
B DELETE /api/system/AdvancedQuery/{id} 登录 platform
B POST /api/system/ModuleDataAuthorize permission.resource|appConfig.appResource platform
B GET /api/system/ModuleDataAuthorize/{moduleId}/List permission.resource|appConfig.appResource platform
B GET /api/system/ModuleDataAuthorize/{moduleId}/FieldList permission.resource|appConfig.appResource platform
B GET /api/system/ModuleDataAuthorize/{id} permission.resource|appConfig.appResource platform
B PUT /api/system/ModuleDataAuthorize/{id} permission.resource|appConfig.appResource platform
B DELETE /api/system/ModuleDataAuthorize/{id} permission.resource|appConfig.appResource platform
B POST /api/system/ModuleDataAuthorizeScheme permission.resource|appConfig.appResource platform
B GET /api/system/ModuleDataAuthorizeScheme/{moduleId}/List 登录 platform
B GET /api/system/ModuleDataAuthorizeScheme/{id} permission.resource|appConfig.appResource platform
B PUT /api/system/ModuleDataAuthorizeScheme/{id} permission.resource|appConfig.appResource platform
B DELETE /api/system/ModuleDataAuthorizeScheme/{id} permission.resource|appConfig.appResource platform
B POST /api/system/ModuleDataAuthorizeLink/saveLinkData permission.resource|appConfig.appResource platform
B GET /api/system/ModuleDataAuthorizeLink/getVisualTables/{menuId}/{type} permission.resource|appConfig.appResource platform
B GET /api/system/ModuleDataAuthorizeLink/getInfo/{menudId}/{type} permission.resource|appConfig.appResource platform
B GET /api/system/ModuleDataAuthorizeLink/{linkId}/Tables/{tableName}/Fields/{menuType}/{dataType} permission.resource|appConfig.appResource platform
<!-- PACK:BEGIN -->
# 🔴 以下由 `scripts/pack-sync.py` 从 `packs/*` 生成 —— **不许手改**
# (下次同步会被覆盖;改包就够)
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
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/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
B GET /api/asset/DataResource permission.asset.dataResource asset
B POST /api/asset/DataResource permission.asset.dataResource asset
B DELETE /api/asset/DataResource/{id} permission.asset.dataResource asset
<!-- PACK:END -->
[FACE]
# face 条数 说明
A 28 面 A 专属(+ 2 条共用 ⇒ 面 A 合计 30 条)
B 349 面 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;无「开发者」列 ⇒ 退化为全体用户(管理员优先)
GET /api/system/System implemented SystemController.java:153 面 B 已落地:ListVO<SystemListVO>;`filterMain` 默认排除主系统,`type` 1/2/3 已按创建者/授权过滤
POST /api/system/System implemented SystemController.java:318 面 B 已落地:`enCode` 唯一校验,`enCode` 为空时服务端生成;返回 `data=enCode`(官方行为)
GET /api/system/System/Selector implemented SystemController.java:430 面 B 已落地:裸数组,排除主系统;`keyword` 过滤
GET /api/system/System/userAuthList implemented SystemController.java:415 面 B 已落地:裸数组;管理员=全部,普通用户按 `f_user_id`/`f_authorize_id` 过滤
POST /api/system/System/actionTop implemented SystemController.java:445 面 B 已落地:按 `f_user_id + f_type + f_object_id` 记账(base_system_top),取消置顶走软删
GET /api/system/System/getAppAuthorization/{id} partial SystemController.java:179 面 B 已落地:AppAuthorizeVo 形状(isAllDevUser/fullName/createUserId/devUsers);devUsers 来自 `f_user_id` 逗号串,不读 base_authorize
POST /api/system/System/saveAppAuthorization partial SystemController.java:235 面 B 已落地:只落 `f_user_id`(逗号串);不写 base_authorize 关系(本仓无应用级授权表)
POST /api/system/System/changeAppAuthorization partial SystemController.java:243 面 B 已落地:`changeAppAuthorization` = 改 `f_creator_user_id` + `f_user_id`
GET /api/system/System/{id} implemented SystemController.java:291 面 B 已落地:SystemVO 13 字段
PUT /api/system/System/{id} implemented SystemController.java:332 面 B 已落地:只 SET body 出现的键;`f_is_main` 不可改
DELETE /api/system/System/{id} implemented SystemController.java:355 面 B 已落地:主系统禁删、有菜单的应用禁删(官方 SYS040),软删
POST /api/system/System/{id}/Actions/Copy partial SystemController.java:603 面 B 已落地:复制应用行(新 id + `{编码}_copy`);菜单/表单等资源不复制(官方 importCopy 会连 visualdev/portal/report 一起复制)
POST /api/system/System/preferenceSave/{id} implemented SystemController.java:304 面 B 已落地:只写 `f_preference_json`
GET /api/system/SysConfig implemented SysConfigController.java:87 面 B 已落地:`base_sys_config`(category=SysConfig)键值行拼回对象,库为空时给完整默认值(前端直接 `.logCleanPeriod` ⇒ 不能返 null)
PUT /api/system/SysConfig implemented SysConfigController.java:108 面 B 已落地:逐键 upsert;数字/布尔按文本存、读回时还原类型
GET /api/system/SysConfig/socials implemented SysConfigController.java:152 面 B 已落地:category=SocialsConfig,默认值 ∪ 库值
PUT /api/system/SysConfig/socials implemented SysConfigController.java:177 面 B 已落地:逐键 upsert
GET /api/system/SysConfig/getAdminList implemented SysConfigController.java:274 面 B 已落地:`f_is_administrator=1` 的用户,UserAdminVO = id/account/realName
PUT /api/system/SysConfig/setAdminList implemented SysConfigController.java:288 面 B 已落地:`adminIds` 追加为超级管理员(不清除既有)
POST /api/system/SysConfig/{type}/testQyWebChatConnect implemented SysConfigController.java:227 面 B 已落地:未接企业微信 SDK ⇒ 恒 `400` + 人话(不假装成功)
POST /api/system/SysConfig/testDingTalkConnect implemented SysConfigController.java:254 面 B 已落地:未接钉钉 SDK ⇒ 恒 `400` + 人话
POST /api/system/SynThirdInfo partial SynThirdInfoController.java:243 面 B 已落地:未启用第三方同步 ⇒ 恒 `400`;不写同步记录
GET /api/system/SynThirdInfo/getSynThirdTotal/{type} implemented SynThirdInfoController.java:165 面 B 已落地:SynThirdTotal 两条(组织/用户),统计恒零
GET /api/system/SynThirdInfo/clearAllSyn implemented SynThirdInfoController.java:230 面 B 已落地:无同步记录可清 ⇒ 恒成功
GET /api/system/SynThirdInfo/getHandleNum implemented SynThirdInfoController.java:192 面 B 已落地:PageListVO,恒空列表
GET /api/system/Tag implemented TagController.java:56 面 B 已落地:ListVO(无 pagination);支持 `keyword` 过滤
POST /api/system/Tag implemented TagController.java:66 面 B 已落地:名称/编码唯一校验,`f_type` 强制 1(自定义)
GET /api/system/Tag/selector implemented TagController.java:116 面 B 已落地:`enCode` 为空 ⇒ 全部;应用中心页启动即调(404 会闪红条)
GET /api/system/Tag/{id} implemented TagController.java:109 面 B 已落地:详情
PUT /api/system/Tag/{id} implemented TagController.java:84 面 B 已落地:只 SET body 出现的键;名称判重
DELETE /api/system/Tag/{id} implemented TagController.java:102 面 B 已落地:软删
GET /api/system/BusinessCategory implemented BusinessCategoryController.java:43 面 B 已落地:ListVO,`list` 是**树**(根节点带 `children`),不是平铺数组
POST /api/system/BusinessCategory implemented BusinessCategoryController.java:53 面 B 已落地:`f_type` 强制 1(自定义);同层级重名 / 编码重复 ⇒ `400`
PUT /api/system/BusinessCategory/{id} implemented BusinessCategoryController.java:73 面 B 已落地:只 SET body 出现的键;判重带上「同父级」
DELETE /api/system/BusinessCategory/{id} implemented BusinessCategoryController.java:91 面 B 已落地:软删(官方是物理删 ⇒ 本仓偏保守)
GET /api/system/BusinessCategory/{id} implemented BusinessCategoryController.java:98 面 B 已落地:软删后返 `400`(不是空对象)
GET /api/system/BusinessCategory/treeList implemented BusinessCategoryController.java:105 面 B 已落地:`type` = 1/2/3 ⇒ 按层数裁剪(1 只剩一级,2 带一层子级)
GET /api/system/BusinessCategory/selector implemented BusinessCategoryController.java:114 面 B 已落地:`parentId=-1` = **所有一级的子级**(官方两段式语义,不是根列表)
GET /api/message implemented NoticeController.java:273 面 B 已落地:PageListVO;**按 `f_user_id = 当前用户`** 过滤,漏了等于串号
POST /api/message/Actions/ReadAll implemented NoticeController.java:386 面 B 已落地:`ids` / `category` 可选收窄;只动自己的未读行
GET /api/message/ReadInfo/{id} implemented NoticeController.java:332 面 B 已落地:**会写库**(`f_is_read` 0⇒1,已回执 2 不回退);公告快照 JSON 摊平到 VO
DELETE /api/message/Record implemented NoticeController.java:433 面 B 已落地:软删**自己的**消息;`ids` 为空 ⇒ `400`
POST /api/message/Reply/{id} implemented NoticeController.java:310 面 B 已落地:手动回执 ⇒ `f_is_read = 2`(官方同款)
POST /api/message/Notice/List implemented NoticeController.java:94 partial:`keyword`/`type`/`enabledMark`/`releaseUser` 已实现,**时间区间过滤未做**
POST /api/message/Notice implemented NoticeController.java:143 面 B 已落地:只建草稿(`f_enabled_mark = 0`),不发消息
GET /api/message/Notice/{id} implemented NoticeController.java:186 面 B 已落地:详情 + `excerpt` 现算(官方 `getExcerpt()` 是 getter,不落列)
PUT /api/message/Notice/{id} implemented NoticeController.java:167 面 B 已落地:只 SET body 出现的键
DELETE /api/message/Notice/{id} implemented NoticeController.java:221 面 B 已落地:软删 + `f_enabled_mark = -1`(同官方语义)
PUT /api/message/Notice/{id}/Actions/Release implemented NoticeController.java:239 面 B 已落地:置已发送 + **逐收件人落 `base_message`**(收件人为空 ⇒ 全体用户)
GET /api/message/Notice/{id}/ReplyUserList implemented NoticeController.java:317 面 B 已落地:ListVO;按 `f_body_text LIKE %noticeId%` + `f_is_read = 2` 去重成人
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:[{id,enCode,isTree,dictionaryList}]}`(`isTree=1` 的类型里 dictionaryList 是树);前端 `store/base.ts:48` 取 `res.data.list` ⇒ 不能是裸数组;`businessType` 字典由 `seed.rs` 灌 1 分类 + 13 数据行
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 本仓单租户 ⇒ **明确失败**(同上)
GET /api/permission/Standing implemented identity.ts:9 身份列表(PageListVO);新表 `base_standing`(官方 `JNPF-PostgreSQL.sql:4071`,15 列逐字);`isSystem` 归一化成 1/0
POST /api/permission/Standing implemented identity.ts:13 `f_is_system` 默认写 **2**(自定义;官方 1=系统/2=自定义)+ 白名单写库 + 名称非空校验
GET /api/permission/Standing/list implemented identity.ts:29 身份关联列表:`type=position` ⇒ 岗位,否则 ⇒ 角色;关系在 `base_authorize`(`f_item_type='standing'`)
GET /api/permission/Standing/{id} implemented identity.ts:21 身份详情(`StandingInfoVO`)
PUT /api/permission/Standing/{id} implemented identity.ts:17 **只 SET body 里出现的键**
DELETE /api/permission/Standing/{id} implemented identity.ts:25 软删 + 同步软删 `base_authorize` 的关联行
POST /api/permission/Standing/{id}/Actions/AddObject implemented identity.ts:33 body `{ids, type}` ⇒ 写 `base_authorize`(`f_item_type='standing'`);幂等
POST /api/permission/Standing/{id}/Actions/DeleteObject implemented identity.ts:37 body `{ids, type}` ⇒ 关联行软删
GET /api/permission/PermissionGroup implemented authGroup.ts:9 权限组列表(PageListVO);新表 `base_permission_group`(官方 `JNPF-PostgreSQL.sql:3278`,16 列逐字)
POST /api/permission/PermissionGroup implemented authGroup.ts:25 `f_type` 默认 1(自定义)+ 白名单写库 + 名称非空校验
GET /api/permission/PermissionGroup/{id} implemented authGroup.ts:13 权限组详情
PUT /api/permission/PermissionGroup/{id} implemented authGroup.ts:21 **只 SET body 里出现的键**
DELETE /api/permission/PermissionGroup/{id} implemented authGroup.ts:17 软删 + 同步软删该组的 `base_authorize` 行
POST /api/permission/PermissionGroup/{id}/Actions/Copy implemented authGroup.ts:29 `fullName` 加 `.副本<5 位>`、`enCode` 加同 5 位、**清空** `f_permission_member`、复制授权关系
GET /api/permission/PermissionGroup/PermissionMember/{id} implemented authGroup.ts:33 成员列表(ListVO);`f_permission_member` 是**逗号分隔 id 串**
POST /api/permission/PermissionGroup/PermissionMember/{id} implemented authGroup.ts:37 body `{ids}` ⇒ 逗号串写回 `f_permission_member`
GET /api/permission/Action implemented action.ts:9 动作列表(PageListVO);新表 `base_action`(官方 `JNPF-PostgreSQL.sql:1`,15 列逐字);`type` 1=自定义/其它=系统
POST /api/permission/Action implemented action.ts:13 `f_type` 强制 1(自定义,官方 `insertOrUpdate`);🔴 `f_enabled_mark` 是 **VARCHAR(11)**(官方陷阱)
GET /api/permission/Action/{id} implemented action.ts:21 动作详情
PUT /api/permission/Action/{id} implemented action.ts:17 **只 SET body 里出现的键**;`f_enabled_mark` 不加 CAST(VARCHAR)
DELETE /api/permission/Action/{id} implemented action.ts:25 软删
GET /api/system/Log implemented LogController.java:62 面 B 已落地:PageListVO;`category` 1登录/3操作/4异常/5请求,其余(含 2 访问)按官方 `default` 返 `400`;`creatorTime` 是**毫秒数**(官方 `LoginLogVO.creatorTime` 是 `Long`)
DELETE /api/system/Log implemented LogController.java:115 面 B 已落地:body `{ids}`(数组或逗号串都收)⇒ 物理删;空 ids 返 `400`
GET /api/system/Log/{id} implemented LogController.java:96 面 B 已落地:详情(四个 VO 字段的并集)
DELETE /api/system/Log/{id} partial LogController.java:133 面 B 已落地:`{id}` 在官方是**分类号**(一键清空该分类),不是日志 id;`dataInterfaceId` 收窄未做
DELETE /api/system/Log/deleteLoginLog implemented LogController.java:144 面 B 已落地:只删**当前用户**的登录日志(官方 `deleteHandleLog("1", 1, null)`);登录即可用(无点权限码)
GET /api/system/Log/ModuleName implemented LogController.java:156 面 B 已落地:裸数组 `[{moduleName}]`(不是 ListVO)
GET /api/system/CommonWords implemented CommonWordsController.java:61 面 B 已落地:PageListVO;`commonWordsType=1`(个人)时**额外**加 `f_creator_user_id=当前用户` 并按 `f_uses_num` 倒序
GET /api/system/CommonWords/{id} implemented CommonWordsController.java:76 面 B 已落地:详情并补 `systemNames`(本仓无多应用授权 ⇒ 空串)
GET /api/system/CommonWords/Selector implemented CommonWordsController.java:105 面 B 已落地:ListVO;`type` 空 ⇒ 全部启用项
POST /api/system/CommonWords implemented CommonWordsController.java:119 面 B 已落地:`text + type` 同档判重 ⇒ `400 常用语已存在`(`SYS105`)
PUT /api/system/CommonWords/{id} implemented CommonWordsController.java:139 面 B 已落地:只 SET body 出现的键;判重排除自身
DELETE /api/system/CommonWords/{id} implemented CommonWordsController.java:159 面 B 已落地:软删
POST /api/system/CommonWords/UsesNum implemented CommonWordsController.java:172 面 B 已落地:按**文本**累加 `f_uses_num`(官方就是按文本,不是按 id)
GET /api/system/BillRule implemented BillRuleController.java:84 面 B 已落地:PageListVO;`category` 用 `base_dictionary_data` 换成中文名,`creatorUser` = `姓名/账号`
GET /api/system/BillRule/Selector implemented BillRuleController.java:112 面 B 已落地:**也是 PageListVO**(官方 `ActionResult.page`),只给 `enabledMark=1`
PUT /api/system/BillRule/{id}/Actions/State implemented BillRuleController.java:143 面 B 已落地:`f_enabled_mark` 1↔0 来回切
PUT /api/system/BillRule/{id} implemented BillRuleController.java:170 面 B 已落地:只 SET body 出现的键;**生成规则变了(前缀/后缀长度、位数、日期格式)⇒ 清空 `f_this_number`/`f_output_number`**
GET /api/system/BillRule/{id} implemented BillRuleController.java:211 面 B 已落地:详情(`category` 原样返 **id**,表单回填要用)
GET /api/system/BillRule/BillNumber/{enCode} implemented BillRuleController.java:227 面 B 已落地:三分支(时间格式/随机数/UUID)+ **跨天归零** + 回写流水号;登录即可用(官方无点权限码)
POST /api/system/BillRule implemented BillRuleController.java:243 面 B 已落地:名称/编码各自判重 ⇒ `400 名称不能重复` / `400 编码不能重复`
DELETE /api/system/BillRule/{id} implemented BillRuleController.java:267 面 B 已落地:`f_output_number` 非空 ⇒ `400 单据已经被使用,不允许被删除`(`SYS003`);否则软删
GET /api/system/BillRule/{id}/Actions/Export partial BillRuleController.java:291 面 B 已落地但**恒失败**:官方走 `DataFileExport` 写文件服务,本仓无文件服务 ⇒ `400` + 人话(不假装成功)
POST /api/system/BillRule/Actions/Import partial BillRuleController.java:310 面 B 已落地但**恒失败**:同上,multipart 导入依赖文件服务 ⇒ `400` + 人话
GET /api/system/DataSource/Selector partial DbLinkController.java:81 面 B 已落地:第一组是**合成**「默认数据库」(`id="0"`、`dbType=PostgreSQL`)—— 前端 `dataModel/index.vue:158` 靠 `list[0].children[0]` 取默认连接;真实连接按 `dbType` 分组(官方按「系统数据连接」字典目录分组,本仓没灌那本字典)
GET /api/system/DataSource partial DbLinkController.java:135 面 B 已落地:PageListVO + `creatorUser`=`姓名/账号` + `port` 字符串 + `creatorTime` 毫秒;`dbType` 保持**编码原样**(官方换字典中文名,本仓查不到就是空串 ⇒ 原样更有信息量)
GET /api/system/DataSource/getGroup implemented DbLinkController.java:183 面 B 已落地:按 `host` 分组 `[{host, options:[…]}]`
GET /api/system/DataSource/{id} partial DbLinkController.java:210 面 B 已落地;**`password` 恒空串**:官方回 AES 密文,本仓存明文 ⇒ 绝不外吐
POST /api/system/DataSource implemented DbLinkController.java:224 面 B 已落地:名称判重(`名称已存在`);`enabledMark` 接受但不落库(`base_db_link` 没这列)
PUT /api/system/DataSource/{id} implemented DbLinkController.java:244 面 B 已落地:只 SET body 出现的键;**`password` 空串 = 不改**
DELETE /api/system/DataSource/{id} implemented DbLinkController.java:268 面 B 已落地:软删(官方物理删,本仓保守)
POST /api/system/DataSource/Actions/Test partial DbLinkController.java:288 面 B 已落地但**恒失败**:本仓只有内嵌 PG,没有驱动层 ⇒ `400` + 人话(不假装连上了)
GET /api/system/BasicDataType implemented DataTypeController.java:46 面 B 已落地:`base_data_type` 官方初始库 7 行(`seed.rs::DATA_TYPES` 逐字灌),`ListVO`
GET /api/system/CommonFields partial ComFieldsController.java:64 面 B 已落地:`base_common_fields` 官方 10 行 + `dataTypeName` 联查;官方要求 `dataCenter.dataModel|dataCenter.basicField`,本仓后者未登记成点权限 ⇒ **只校验登录**
GET /api/system/DataModel/{linkId}/Tables implemented DbTableController.java:124 面 B 已落地:真读 `pg_class`(`current_schema()`)+ `obj_description` 注释,PageListVO + keyword/分页;`linkId` **忽略**(本仓只有一个库)
GET /api/system/DataModel/{linkId}/TableAll implemented DbTableController.java:147 面 B 已落地:表 + 视图 + 物化视图(`relkind IN r,v,m`),裸 `ListVO`
GET /api/system/DataModel/{linkId}/Tables/{tableName}/Fields implemented DbTableController.java:212 面 B 已落地:`information_schema.columns` + 主键子查询;`dataType` 归一成官方 7 编码,`dataTypeReal` 保留 `udt_name`
GET /api/system/DataModel/{linkId}/Tables/{tableName}/Fields/Selector implemented DbTableController.java:186 面 B 已落地:与 `Fields` 同源同形(官方也是同一个 `getFieldList`)
GET /api/system/DataModel/{linkId}/Table/{tableName} implemented DbTableController.java:251 面 B 已落地:`DbTableInfoVO`;`hasTableData` 用 `EXISTS` 真探测(判错会让前端在**有数据**的表上删列)
GET /api/system/DataModel/{linkId}/Table/{tableName}/Preview implemented DbTableController.java:168 面 B 已落地:逐列 `"col" AS "col"` 投影 —— **不能用 `SELECT *`**(`f_*` 会被归一成 camelCase,前端按原样列名取值 ⇒ 整表空白)
POST /api/system/DataModel/{linkId}/Table implemented DbTableController.java:271 面 B 已落地:真 `CREATE TABLE` + `COMMENT ON`;表名/列名过 `db_ident` 白名单,撞 `schema.sql` 里的表报「名称不能重复」(官方 `EXIST001`);自增/主键三条规矩照抄 `checkPrimary`
PUT /api/system/DataModel/{linkId}/Table implemented DbTableController.java:295 面 B 已落地:**重建表**(`DROP`+`CREATE` 同一批 ⇒ simple protocol 隐式事务,比官方的「临时表→删旧→改名」少一个中间态);内置表 `DB102`、有数据 `DB202`
PUT /api/system/DataModel/{linkId}/addFields implemented DbTableController.java:341 面 B 已落地:只 `ADD COLUMN IF NOT EXISTS`(**不删列、不要求主键**);新列一律可空 —— 给非空表加 `NOT NULL` 列必然失败
DELETE /api/system/DataModel/{linkId}/Table/{tableName} implemented DbTableController.java:361 面 B 已落地:内置表 `DB101`、有数据 `DB201`;`DROP TABLE`
DELETE /api/system/DataModel/{linkId}/deleteAllTable partial DbTableController.java:378 面 B 已落地但**有意收窄**:官方删 `getTableList` 的**全部**表(含系统表,等于把平台自己拆了)⇒ 本仓只删「不在 `schema.sql` 里」的表
POST /api/system/DataModel/{linkId}/Table/{tableName}/Actions/Copy implemented DbTableController.java:455 面 B 已落地:`CREATE TABLE … (LIKE … INCLUDING ALL)` ⇒ 主键/NOT NULL/DEFAULT/IDENTITY 一起带过去(官方按字段清单重建会**丢自增**);`type=1` 追加 `INSERT … SELECT *`
GET /api/system/DataModel/{linkId}/Table/{tableName}/Actions/Export partial DbTableController.java:433 面 B 已落地但**恒失败**:官方返 `DownloadVO`(文件服务)⇒ 本仓 `400` + 人话,不返假下载地址
POST /api/system/DataModel/{linkId}/Actions/Import partial DbTableController.java:388 面 B 已落地但**恒失败**:官方读 multipart 的 `.json`;本仓没启 `axum/multipart` ⇒ 明说不支持(前端建模页也没有导入按钮)
GET /api/system/Dataset implemented DataSetController.java:96 面 B 已落地:PageListVO + `type`/`returnType` 换成**中文名**(`SQL语句`/`列表数据`,官方枚举 `getNameByCode`);`creatorTime` 毫秒;keyword/category/type/returnType/enabledMark 五个过滤全支持
POST /api/system/Dataset implemented DataSetController.java:116 面 B 已落地:`action` 恒 `3`(查询,官方 `create` 也强制);`enCode` 只收字母数字(官方 `^[a-zA-Z0-9]+$`);名称/编码双判重
PUT /api/system/Dataset/{id} implemented DataSetController.java:136 面 B 已落地:只 SET body 出现的键;**只改名称时用库里原编码补齐再判重**(否则会把自己判成重复)
DELETE /api/system/Dataset/{id} implemented DataSetController.java:155 面 B 已落地:软删(官方物理删,本仓保守)
GET /api/system/Dataset/{id} implemented DataSetController.java:171 面 B 已落地:`DataSetForm` 形状(`type`/`returnType` 是**数字**,与列表的中文名不同)
GET /api/system/Dataset/{id}/get implemented DataSetController.java:183 面 B 已落地:`DataSetDesVo` = 详情 + `variateJson`(恒 `"[]"`,官方来自变量表)+ `fields`(`fieldJson` 解析)
POST /api/system/Dataset/{id}/save implemented DataSetController.java:200 面 B 已落地:只存设计器字段;`variateJson` 收下**不落库**(本仓没有 `base_data_interface_variate`)
GET /api/system/Dataset/getList implemented DataSetController.java:309 面 B 已落地:`DataSetSelectVO`;多 `hasPage`/`fields`;`parameterJson` 是**字符串**且已剔掉 `isSystem=1` 的项(官方原地改写)
POST /api/system/Dataset/previewSql partial DataSetController.java:333 面 B 已落地但只支持 `sqlType=1`:原样回 SQL;`sqlType=2`(图形化配置式)⇒ `400` + 人话(官方走 `CallAssembleUtil.getPreviewSql` 拼 SQL)
POST /api/system/Dataset/fields implemented DataSetController.java:373 面 B 已落地:`TableTreeModel` 裸数组;`{id:enCode, interfaceId, label:fullName, fullName:"enCode(fullName)", children:[…]}`(官方 `getFields` 逐字)
GET /api/system/Dataset/GetParam/{id} implemented DataSetController.java:381 面 B 已落地:**裸数组**(不是 `ListVO`),内容就是 `parameterJson` 原样解析
POST /api/system/Dataset/{id}/Actions/Preview implemented DataSetController.java:349 面 B 已落地:**真执行 SQL**(只读)。`${xxx}`/`@xxx` ⇒ `$N` 绑定不拼文本;`${}` 里的值来自 `paramList.defaultValue`;`required=1` 为空 ⇒ `400 x不能为空`;`enabledMark≠1` ⇒ `400 数据集已禁用`
POST /api/system/Dataset/{id}/Actions/List implemented DataSetController.java:360 面 B 已落地:`hasPage=1` 走真分页;`hasPage=0` 先取窗口再**内存**按 `keyword`+`columnOptions` 过滤并切页(官方 `actionsList` 同法)
POST /api/system/Dataset/{id}/Actions/InfoByIds implemented DataSetController.java:367 面 B 已落地:输出**按请求 ids 顺序**对齐,缺项给 `{}`;`propsValue` 过 `db_ident` 白名单(它要拼进 SQL 的列名位)
POST /api/system/Dataset/{id}/Actions/getRes implemented DataSetController.java:341 面 B 已落地:用的是 **body 里**的 `dataConfigJson`(设计器边改边试跑);返回 `FieldJsonModel`。⚠️ 列名靠「执行 1 行」反推 —— **空结果集拿不到列名 ⇒ `fields:[]`**(官方走 JDBC 元数据,本仓 `row_to_json` 没行就没有键)
POST /api/system/Dataset/{id}/Actions/Copy implemented DataSetController.java:290 面 B 已落地:名称加「副本」、编码加 6 位 uuid 后缀,撞名/撞码最多重试 5 轮
GET /api/system/Dataset/{id}/Actions/Export partial DataSetController.java:217 面 B 已落地但**恒失败**:官方返 `DownloadVO`(文件服务)⇒ 本仓 `400` + 人话,不返假下载地址
POST /api/system/Dataset/Actions/Import partial DataSetController.java:231 面 B 已落地但**恒失败**:官方读 multipart 的 `.json`;本仓没启 `axum/multipart` ⇒ 明说不支持
GET /api/system/DataInterface implemented DataInterfaceController.java:96 面 B 已落地:PageListVO 形状,列表项含接口查询配置
POST /api/system/DataInterface implemented DataInterfaceController.java:129 面 B 已落地:白名单写库 + 编码校验,返 {id}
GET /api/system/DataInterface/getList implemented DataInterfaceController.java:113 面 B 已落地:DataSetSelectVO 裸数组
GET /api/system/DataInterface/GetParam/{id} implemented DataInterfaceController.java:266 面 B 已落地:裸数组(即 parameterJson 解析)
GET /api/system/DataInterface/{id} implemented DataInterfaceController.java:190 面 B 已落地:DataInterfaceInfoVO 形状
PUT /api/system/DataInterface/{id} implemented DataInterfaceController.java:146 面 B 已落地:只 SET body 出现的键
DELETE /api/system/DataInterface/{id} implemented DataInterfaceController.java:178 面 B 已落地:软删
GET /api/system/DataInterface/{id}/get implemented DataInterfaceController.java:201 面 B 已落地:详情 + 字段
POST /api/system/DataInterface/{id}/save implemented DataInterfaceController.java:211 面 B 已落地:只存设计器字段
POST /api/system/DataInterface/{id}/Actions/Copy implemented DataInterfaceController.java:352 面 B 已落地:副本化(编码加后缀)
GET /api/system/DataInterface/{id}/Actions/Export partial DataInterfaceController.java:281 面 B 已落地但**恒失败**:官方返 DownloadVO(文件服务)⇒ 本仓 400 + 人话
POST /api/system/DataInterface/{id}/Actions/Preview implemented DataInterfaceController.java:367 面 B 已落地:按配置执行接口(SQL/HTTP,只读)
GET /api/system/InterfaceOauth implemented InterfaceOauthController.java:95 面 B 已落地:分页列表
POST /api/system/InterfaceOauth implemented InterfaceOauthController.java:118 面 B 已落地:白名单写库 + 应用校验,返 {id}
GET /api/system/InterfaceOauth/getAppId implemented InterfaceOauthController.java:232 面 B 已落地:返回第三方 appId/appSecret(脱敏)
POST /api/system/InterfaceOauth/getInterfaceList implemented InterfaceOauthController.java:240 面 B 已落地:接口清单(base_data_interface 列表)
GET /api/system/InterfaceOauth/dataInterfaceLog/{id} implemented InterfaceOauthController.java:248 面 B 已落地:调用日志分页
GET /api/system/InterfaceOauth/interfaceSelector implemented InterfaceOauthController.java:263 面 B 已落地:接口下拉(ListVO)
POST /api/system/InterfaceOauth/SaveUserList implemented InterfaceOauthController.java:125 面 B 已落地:官方在 create/update 内联保存用户清单,本仓拆成独立端点(等价语义)
GET /api/system/InterfaceOauth/{id} implemented InterfaceOauthController.java:163 面 B 已落地:详情
PUT /api/system/InterfaceOauth/{id} implemented InterfaceOauthController.java:133 面 B 已落地:只 SET body 出现的键
DELETE /api/system/InterfaceOauth/{id} implemented InterfaceOauthController.java:151 面 B 已落地:软删
GET /api/system/printDev implemented PrintDevController.java:208 面 B 已落地:分页列表
POST /api/system/printDev implemented PrintDevController.java:256 面 B 已落地:建模板 + 首版本(v1 未发布)
GET /api/system/printDev/Selector implemented PrintDevController.java:443 面 B 已落地:按分类树 + 模板叶子(仅 state=1)
GET /api/system/printDev/WorkSelector implemented PrintDevController.java:525 面 B 已落地:常用模板分页(state=1 & commonUse=1)
POST /api/system/printDev/getListOptions implemented PrintDevController.java:499 面 B 已落地:按 ids 返 {id,fullName,enCode}
GET /api/system/printDev/{id} implemented PrintDevController.java:267 面 B 已落地:PrintDevInfoVO 形状(含版本信息)
PUT /api/system/printDev/{id} implemented PrintDevController.java:277 面 B 已落地:只 SET body 出现的键
DELETE /api/system/printDev/{id} implemented PrintDevController.java:298 面 B 已落地:软删模板 + 清版本
POST /api/system/printDev/{id}/Actions/Copy implemented PrintDevController.java:383 面 B 已落地:副本模板(副本前缀)+ 复制所有版本
GET /api/system/printDev/{id}/Actions/Export partial PrintDevController.java:392 面 B 已落地但**恒失败**:官方返 DownloadVO(文件服务)⇒ 本仓 400 + 人话
GET /api/system/printDev/{id}/Actions/Preview implemented PrintDevController.java:513 面 B 已落地:JOIN 取首版本 PrintDevInfoVO
POST /api/system/printDev/BatchData partial PrintDevController.java:451 面 B 已落地但**恒失败**:本仓无打印渲染引擎 ⇒ 400 + 人话(不返回批量打印数据)
POST /api/system/printDev/Save implemented PrintDevController.java:369 面 B 已落地:update 模板 + upsert 版本(type=1 即发布,归档旧已发布版本)
GET /api/system/printDev/Info/{id} implemented PrintDevController.java:313 面 B 已落地:版本详情(PrintDevInfoVO)
GET /api/system/printDev/Version/{id} implemented PrintDevController.java:353 面 B 已落地:版本列表(裸数组,fullName=打印版本V{n})
POST /api/system/printDev/Info/{id} implemented PrintDevController.java:322 面 B 已落地:版本复制
DELETE /api/system/printDev/Info/{id} implemented PrintDevController.java:331 面 B 已落地:版本删除(至少留 1 个;已发布/已归档不可删)
GET /api/system/Signature implemented SignatureController.java:55 面 B 已落地:PageListVO;userIds = 「真实名/账号」用「;」连接;支持 userId 过滤
POST /api/system/Signature implemented SignatureController.java:112 面 B 已落地:名称/编码判重(EXIST001/EXIST002 分开报)+ 写签章 + 写授权人
GET /api/system/Signature/Selector implemented SignatureController.java:67 面 B 已落地:ListVO
POST /api/system/Signature/ListByIds implemented SignatureController.java:81 面 B 已落地:ListVO(按 ids 取)
GET /api/system/Signature/{id} implemented SignatureController.java:96 面 B 已落地:SignatureInfoVO(userIds 是数组)
PUT /api/system/Signature/{id} implemented SignatureController.java:134 面 B 已落地:只 SET body 出现的键;userIds 变化时全量重建授权人
DELETE /api/system/Signature/{id} implemented SignatureController.java:158 面 B 已落地:软删
POST /api/system/ModuleButton implemented ModuleButtonController.java:123 面 B 已落地:同菜单内编码判重;parentId 缺省 -1
GET /api/system/ModuleButton/{menuId}/List implemented ModuleButtonController.java:71 面 B 已落地:PageListVO(按 menuId 过滤 + 关键词)
GET /api/system/ModuleButton/{menuId}/Selector implemented ModuleButtonController.java:87 面 B 已落地:ListVO + **树**(parentId=-1 视为根)
GET /api/system/ModuleButton/{id} implemented ModuleButtonController.java:107 面 B 已落地:ModuleButtonInfoVO
PUT /api/system/ModuleButton/{id} implemented ModuleButtonController.java:144 面 B 已落地:只 SET body 出现的键
DELETE /api/system/ModuleButton/{id} implemented ModuleButtonController.java:167 面 B 已落地:软删
POST /api/system/ModuleButton/selectActions/{menuId} implemented ModuleButtonController.java:204 面 B 已落地:从动作管理批量选入(逐条判重;任一撞 ⇒ 整体失败不落库)
POST /api/system/ModuleColumn implemented ModuleColumnController.java:180 面 B 已落地:enCode 前缀化(fieldRule=1 ⇒ jnpf_<bindTable>_jnpf_;=2 ⇒ <childTableKey>-)
GET /api/system/ModuleColumn/{moduleId}/Fields implemented ModuleColumnController.java:79 面 B 已落地:PageListVO;读时剥掉 enCode 前缀
GET /api/system/ModuleColumn/{id} implemented ModuleColumnController.java:153 面 B 已落地:ModuleColumnInfoVO(childTableKey 默认 tableField)
PUT /api/system/ModuleColumn/{id} implemented ModuleColumnController.java:215 面 B 已落地:同 create 的前缀化规则
DELETE /api/system/ModuleColumn/{id} implemented ModuleColumnController.java:251 面 B 已落地:软删
POST /api/system/ModuleColumn/Actions/Batch implemented ModuleColumnController.java:294 面 B 已落地:columnJson 批量;库内撞码与**批内撞码**都判失败
POST /api/system/ModuleForm implemented ModuleFormController.java:201 面 B 已落地:同 ModuleColumn 的前缀化规则
GET /api/system/ModuleForm/{moduleId}/Fields implemented ModuleFormController.java:83 面 B 已落地:PageListVO;读时剥掉 enCode 前缀
GET /api/system/ModuleForm/{id} implemented ModuleFormController.java:174 面 B 已落地:ModuleFormInfoVO(childTableKey 默认 tableField)
PUT /api/system/ModuleForm/{id} implemented ModuleFormController.java:237 面 B 已落地:同 create 的前缀化规则
DELETE /api/system/ModuleForm/{id} implemented ModuleFormController.java:272 面 B 已落地:软删
POST /api/system/ModuleForm/Actions/Batch implemented ModuleFormController.java:290 面 B 已落地:formJson 批量;库内撞码与批内撞码都判失败
POST /api/system/AdvancedQuery implemented AdvancedQueryController.java:54 面 B 已落地:必填校验(fullName/conditionJson/matchLogic/moduleId)
GET /api/system/AdvancedQuery/{moduleId}/List implemented AdvancedQueryController.java:106 面 B 已落地:ListVO;**只返当前用户自己**的方案
GET /api/system/AdvancedQuery/{id} implemented AdvancedQueryController.java:125 面 B 已落地:只看自己的方案(他人 ⇒ 数据不存在)
PUT /api/system/AdvancedQuery/{id} implemented AdvancedQueryController.java:70 面 B 已落地:只 SET body 出现的键
DELETE /api/system/AdvancedQuery/{id} implemented AdvancedQueryController.java:87 面 B 已落地:软删;只删自己的方案
POST /api/system/ModuleDataAuthorize implemented ModuleDataAuthorizeController.java:229 面 B 已落地:type==3 && fieldRule!=0 && bindTable 非空 ⇒ enCode 加 bindTable. 前缀;propertyJson=childTableKey
GET /api/system/ModuleDataAuthorize/{moduleId}/List implemented ModuleDataAuthorizeController.java:91 面 B 已落地:ListVO;conditionSymbol/conditionText 解码中文名;读时剥 bindTable. 前缀
GET /api/system/ModuleDataAuthorize/{moduleId}/FieldList implemented ModuleDataAuthorizeController.java:137 面 B 已落地:返回空数组(依赖低代码表单字段解析,本仓无该能力)
GET /api/system/ModuleDataAuthorize/{id} implemented ModuleDataAuthorizeController.java:208 面 B 已落地:ModuleDataAuthorizeInfoVO;读时剥 bindTable. 前缀
PUT /api/system/ModuleDataAuthorize/{id} implemented ModuleDataAuthorizeController.java:254 面 B 已落地:type==3 && fieldRule==1 && bindTable 非空 ⇒ enCode 加前缀
DELETE /api/system/ModuleDataAuthorize/{id} implemented ModuleDataAuthorizeController.java:281 面 B 已落地:删前遍历方案 conditionJson 比对 enCode(带前缀,equalsIgnoreCase)命中 ⇒ SYS020
POST /api/system/ModuleDataAuthorizeScheme implemented ModuleDataAuthorizeSchemeController.java:98 面 B 已落地:EXIST001/EXIST002 判重
GET /api/system/ModuleDataAuthorizeScheme/{moduleId}/List implemented ModuleDataAuthorizeSchemeController.java:62 面 B 已落地:PageListVO;仅需登录(无 @SaCheckPermission)
GET /api/system/ModuleDataAuthorizeScheme/{id} implemented ModuleDataAuthorizeSchemeController.java:81 面 B 已落地:ModuleDataAuthorizeSchemeInfoVO
PUT /api/system/ModuleDataAuthorizeScheme/{id} implemented ModuleDataAuthorizeSchemeController.java:126 面 B 已落地:allData==1 ⇒ SYS021;EXIST001/EXIST002;FA002/SU004
DELETE /api/system/ModuleDataAuthorizeScheme/{id} implemented ModuleDataAuthorizeSchemeController.java:160 面 B 已落地:软删;FA003/SU003
POST /api/system/ModuleDataAuthorizeLink/saveLinkData implemented ModuleDataAuthorizeLinkController.java:79 面 B 已落地:新建(SU002)/更新(SU004)
GET /api/system/ModuleDataAuthorizeLink/getVisualTables/{menuId}/{type} implemented ModuleDataAuthorizeLinkController.java:103 面 B 已落地:低代码(type 3/9/11)返回空;其余按 menuId+type 查 base_module_link
GET /api/system/ModuleDataAuthorizeLink/getInfo/{menudId}/{type} implemented ModuleDataAuthorizeLinkController.java:154 面 B 已落地:按 menuId+type 查 base_module_link ⇒ DataAuthorizeLinkForm
GET /api/system/ModuleDataAuthorizeLink/{linkId}/Tables/{tableName}/Fields/{menuType}/{dataType} implemented ModuleDataAuthorizeLinkController.java:176 面 B 已落地:返回空 PageListVO(依赖 dbTableService.getFieldList 内省,本仓无该能力)
[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
# 🔴 **本仓现在有前端**(批次 12 起 `src/frontend` = React MVP 模板,
# 见 HANDOFF §0-ter)⇒ check-module 的前端接触点从 `⏭` 变成**真检查**,条数随之增加:
# 123 = demo 31 + shop 30 + books 30 + asset 30 + 全局面 A / 面 B 判别头 2
# 前端那几条的构成:demo 走「view 直连」4 条(契约 apiFile=无,本来就没有 api 层);
# 其余三个走「api 三导出(listX/saveX/deleteX)」3 条 + views 页面 1 条 + App.tsx 路由 1 条。
# (更早的 114 = 4 模块 × 28 + 2,那时本仓后端-only,前端 4×4 处全打 `⏭` 但仍计入条数。)
check-module.sh 123
check-boundary.sh 11
check-contract.sh 10
check-citations.sh 4
```
<!-- END CONTRACT-EXPECT -->