Files
ssw-jnpf-lite-rust/docs/contract.md
T
adminandClaude Code 1db2f0a1db docs: 修正投影别名铁律(AS 必须用 camelCase JSON 键)
row_to_json 用列的输出名当 JSON 键。原 §5.2 示例写的是 `AS creator_time`,
照抄会得到 `"creator_time"` 而 react 是 `"creatorTime"` ⇒ 前端字段全读不到。
§5.2/§5.3/R1.4 补上「每列显式 AS <JSON键>」并给出正确示例。

Co-Authored-By: Claude Code <[email protected]>
2026-10-25 17:21:08 +08:00

901 lines
44 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.
# 契约规格 —— 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='无菜单权限'`
- **唯一例外**:未知路由 → **HTTP 404**,body 仍是 `{code:404,msg:'接口不存在',data:null}`
### 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"` ⇒ 前端读不到字段。
### 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(明文)` ⇒ **大小写不敏感**比较。
**依赖版本组合(别混用)**:`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。
| 列 | 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`。
🔴 **`f_delete_mark INT DEFAULT 0`** —— react entity 上有 `default: 0`,
§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)依赖这个 DB 默认值补出 `0`。
其余业务列**不得**有 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键>`。
### 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。
例:`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`。**不要另起逐列类型映射分支。**
**绑定参数一律按 text 传**(`&str` / `Option<&str>` 都实现了 `ToSql`);
类型转换由 SQL 里的 `CAST` / 列上下文负责(PG 从目标列推断参数类型)。
**单 backend 独占**:pglite-rs 每进程只允许一个 `PGlite` 实例 ⇒ 集成测试必须**共用一个实例**,
且各自用独立数据目录的多个测试二进制不能并行跑。
### 5.5 schema 初始化
启动时探测 `base_user` 是否存在;不存在才按 `;` 拆分执行 `schema.sql`(拆分要**字面量感知**)。
---
## 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 '账号或密码错误'`
**实现注记**: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 ⇒ JSON `{code:405,msg:'方法不被允许',data:null}`,**保留 `Allow` 头**
- `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` / `f_stock` ⇒ NULL;
- `f_delete_mark`:body 没给 ⇒ **0**(业务表该列 DDL 带 `DEFAULT 0`)。
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)
- 根按 `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()`(每次启动都跑,幂等)**
- 按 `f_en_code` 补内置角色(**已存在的不覆盖**)
- 按 `f_url_address` 补内置菜单(**含软删行也不复活**)
- 取库里 `f_en_code='admin'` 的真实角色行;取所有 `f_delete_mark=0` 且 urlAddress 命中内置菜单清单的行;
对其中尚未在 `base_authorize`(`f_object_type='role' AND f_object_id=<adminRoleId> AND f_item_type='module'`)里的行补授权
- **只补缺项**:不覆盖已改值
**`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'`、`f_role_id='role_admin'`、
`f_sort_code=0`、`f_delete_mark=0`、`f_tenant_id='0'`、`f_id`=UUID v4
---
## 9. Rust 模块接口契约
所有模块在 `src/backend/src/`,由 `src/backend/src/lib.rs` 统一 `pub mod` 导出。
```rust
// ---- lib.rs ----
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 sys;
pub mod auth;
```
### 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>, DbError>;
pub async fn save(db: &Db, spec: &EntitySpec, body: &Value) -> Result<Value, DbError>;
pub async fn remove(db: &Db, spec: &EntitySpec, id: &str) -> Result<(), DbError>;
```
### routes.rs
```rust
pub fn build_router(state: AppState) -> Router;
```
(`with_state` 由 `main.rs` 在**链尾**调用。)
### AppState(`src/backend/src/lib.rs` 或独立 `state.rs`)
```rust
#[derive(Clone)]
pub struct AppState {
pub config: Arc<Config>,
pub db: Arc<Db>,
pub sessions: Arc<SessionStore>,
}
```
---
## 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()`
6. `build_router(state)` + 404 兜底 + 405 改写中间件 + `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"` / `panic="abort"` / `codegen-units=16` |
| ② 单测 | `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)。