§6.5 要求 panic ⇒ HTTP 200 + code=400,而 panic="abort" 下 catch_unwind 抓不到 panic(进程直接 abort ⇒ 客户端连接重置)。Ruling P19 已决定保留默认 unwind,但 §11 的表格里仍写着 panic="abort",与 Cargo.toml 现状矛盾 —— 按契约写的实现者会把 panic="abort" 加回去。此处消除矛盾。 Co-Authored-By: Claude Code <[email protected]>
981 lines
52 KiB
Markdown
981 lines
52 KiB
Markdown
# 契约规格 —— tds-lite-rs
|
||
|
||
> **本文件是唯一规格来源(binding spec)。** 所有实现任务、代码评审、最终评审都以此为准。
|
||
> 与 `HANDOFF.md` 冲突时,以本文件为准;与本文件冲突的**计划文字**由控制者裁决并记入 ledger。
|
||
|
||
---
|
||
|
||
## 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/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/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/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 张 —— 表名与 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` |
|
||
|
||
🔴 **有 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/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. 端点全表
|
||
|
||
### 6.1 认证
|
||
|
||
| 方法 | 路径 | 守卫 | 说明 |
|
||
|---|---|---|---|
|
||
| POST | `/api/oauth/Login` | 无 | **form-urlencoded**:`account` / `password`(密文 hex) / `grant_type=password` |
|
||
| GET | `/api/oauth/CurrentUser` | 登录 | `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` |
|
||
|
||
**登录失败文案**(逐字):
|
||
- 缺 `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 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 '角色不存在'`;
|
||
- 覆盖:`f_full_name`、`f_en_code`、`f_type` = body.type ?? **原值**、
|
||
`f_description`(body 有才覆盖);
|
||
- ⚠️ 更新**不做** `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 '机构不存在'`;
|
||
覆盖 `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 '菜单不存在'`;
|
||
覆盖 `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 |
|
||
|
||
**期望菜单树字符串**(冒烟断言用,冒烟脚本里作字面量):
|
||
```
|
||
系统管理:用户管理,角色管理,机构管理,菜单管理|Demo 示例:|产品管理:|图书超市:
|
||
```
|
||
|
||
### 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 模块接口契约
|
||
|
||
所有模块在 `src/backend/src/`,由 `src/backend/src/lib.rs` 统一 `pub mod` 导出。
|
||
|
||
```rust
|
||
// ---- lib.rs ----
|
||
pub mod auth;
|
||
pub mod cipher;
|
||
pub mod config;
|
||
pub mod crud;
|
||
pub mod db;
|
||
pub mod entities;
|
||
pub mod envelope;
|
||
pub mod ids;
|
||
pub mod permission;
|
||
pub mod routes;
|
||
pub mod seed;
|
||
pub mod session;
|
||
pub mod state; // 🔴 由 Task 4 追加(全仓只有 Task 4 能改 lib.rs)
|
||
pub mod sys;
|
||
```
|
||
|
||
### 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>,
|
||
}
|
||
```
|
||
|
||
### entities.rs(业务实体 spec)
|
||
```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 投影的列
|
||
}
|
||
|
||
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
|
||
}
|
||
|
||
pub fn all_specs() -> &'static [EntitySpec];
|
||
pub fn find_spec(app_code: &str, entity: &str) -> Option<&'static EntitySpec>;
|
||
```
|
||
|
||
### crud.rs(spec 驱动的通用 CRUD)
|
||
```rust
|
||
pub async fn list(db: &Db, spec: &EntitySpec) -> Result<Vec<Value>, pglite::Error>;
|
||
pub async fn save(db: &Db, spec: &EntitySpec, body: &Value) -> Result<Value, pglite::Error>;
|
||
pub async fn remove(db: &Db, spec: &EntitySpec, id: &str) -> Result<(), pglite::Error>;
|
||
```
|
||
|
||
### routes.rs
|
||
```rust
|
||
pub fn build_router(state: AppState) -> Router;
|
||
```
|
||
(`with_state` 由 `main.rs` 在**链尾**调用。)
|
||
|
||
### AppState(`src/backend/src/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` 的唯一 owner 是「建 `state.rs` 的那个任务」**(Task 4)。
|
||
`lib.rs` 里加**一行** `pub mod state;` 即可 —— **其它任务一律不许改 `lib.rs`**。
|
||
(`AppState` 需要 `Config`(Task 3)+ `Db`(Task 3)+ `SessionStore`(Task 4)
|
||
⇒ Task 4 是最后一个依赖就位的人,由它一次性把 `state.rs` 和那行 `pub mod state;` 落地。)
|
||
|
||
---
|
||
|
||
## 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 个业务页可用 → 退出再登录 |
|
||
|
||
**脚本退出码约定**(三个入口一致):
|
||
`run.sh` 0=成功 / 1=运行期失败 / 2=用法错;
|
||
`check-module.sh` 0=全过 / 1=有 ❌ / 2=用法错;
|
||
`perm-smoke.sh` 0=全绿 / 1=有断言失败 / 2=前置错误(后端不可达)。
|
||
|
||
---
|
||
|
||
## 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 条断言**。移植后一条不落:
|
||
|
||
| # | 断言 | 期望 |
|
||
|---|---|---|
|
||
| 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` |
|
||
|
||
**脚本不得依赖 node**(react 版依赖 `node` + `crypto-js` + `src/backend/node_modules`,本仓一律不用):
|
||
- **cipher 加密** ⇒ 调用后端自证:`./target/release/tds-lite-rs --enc '<明文>'` 输出 hex(退出码 0)。
|
||
(冒烟脚本自带 `--enc` 的向量自检,**不**假设 node 存在。)
|
||
- **JSON 取值** ⇒ `jq`(若已装)或 `python3`(macOS 自带)写的取字段小工具;**不得**用 node。
|
||
- **期望菜单树** ⇒ **写字面量**(§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)。
|