Files
ssw-jnpf-lite-rust/docs/contract.md
T
adminandClaude 0aed12a102 docs: 契约规格 + 实施计划 + 官方 base_* DDL 原文
- docs/contract.md: 唯一规格来源(信封/cipher/端点/权限/种子/验收门)
- docs/ddl/base_ddl_raw.sql: 从官方 JNPF dump 逐字提取的 7 张 base_* DDL
- CLAUDE.md / HANDOFF.md: 项目级 agent 指引与交接文档

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

656 lines
29 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 逐字相同。
### 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"
```
**口令比对**:库内存 `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`。
### 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 creator_time
```
### 5.3 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.4 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 '账号或密码错误'`
**登录成功体**:`{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` 归一化**:一维数组直接用;历史二维形态 `[[checked],[halfChecked]]` **展平**后同样落库。
非数组 ⇒ 视作空数组。
### 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 版)
### 7.1 User
- **List**:`f_delete_mark=0`,`f_creator_time DESC`。去掉 `password`,追加 `roleIds`(数组)与 `roleNames`(数组)。
`roleIds` 取自 `base_role_relation` 中 `f_object_type='user' AND f_object_id=<userId>` 的 `f_role_id`。
`roleNames` = 这些 roleId 对应的 `base_role.f_full_name`(`f_delete_mark=0` 的角色),查不到则跳过。
- **Save**:
- `account` 为空 ⇒ `400 '账号不能为空'`
- **重复账号** ⇒ `400 '账号已存在:<account>'`(**HTTP 200,不是 500**)。只比 `f_delete_mark=0` 的行。
- 无 `id` ⇒ 新建:`f_id` = 36 位 UUID v4,`f_tenant_id='0'`,`f_password` = `md5(明文)`,
`f_is_administrator` = 1/0,`f_organize_id` 默认 `'0'`,`f_creator_user_id='admin'`,
`f_creator_time` = now(UTC),`f_enabled_mark=1`,`f_delete_mark=0`。
口令缺省 = `md5('123456')`。
- 有 `id` ⇒ 更新:`account`/`realName`/`isAdministrator`/`organizeId` 覆盖;
`password` 非空才覆盖;`f_delete_mark=1` 的行**也算存在**(react 的 `findOne({id})` 不带 deleteMark 过滤)。
- `roleIds` 是数组 ⇒ 先删该用户的 `base_role_relation` 旧行,再插新行。
- **Delete**:软删 `f_delete_mark=1`;并**删除**该用户的 `base_role_relation` 行。
### 7.2 Role
- **List**:`f_delete_mark=0`,`f_sort_code ASC`
- **Save**:`fullName` 为空 ⇒ `400 '角色名称不能为空'`。
无 `id` 时 `f_en_code` 重复(且 `f_delete_mark=0`)⇒ `400 '角色编码已存在:<enCode>'`。
有 `id` 但行不存在 ⇒ `400 '角色不存在'`。
新建:`f_id`=UUID v4,`f_tenant_id='0'`,`f_type` 默认 `'user'`,`f_enabled_mark=1`,
`f_sort_code` 默认 0,`f_creator_user_id='admin'`,`f_creator_time`=now,`f_delete_mark=0`。
- **Delete**:软删角色;`base_authorize` 里 `f_object_type='role' AND f_object_id=<id>` 的行**软删**(`f_delete_mark=1`);
`base_role_relation` 里 `f_role_id=<id>` 的行**物理删除**。
- **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` 数组。
### 7.3 Organize
- **List**:`f_delete_mark=0`,`f_sort_code ASC`
- **Save**:`fullName` 为空 ⇒ `400 '机构名称不能为空'`。无 `id`/`f_parent_id` 默认 `'0'`、`f_sort_code` 默认 0。
有 `id` 但行不存在 ⇒ `400 '机构不存在'`。
- **Delete**:**有子机构**(`f_parent_id=<id>` 且 `f_delete_mark=0`)⇒ `400 '该机构下还有子机构,先删除子机构'`;否则软删。
### 7.4 Module
- **List**:`f_delete_mark=0`,`f_sort_code ASC`
- **Save**:`fullName` 为空 ⇒ `400 '菜单名称不能为空'`。
`f_type` 默认 2(**INTEGER**:1=目录 2=页面);`f_category` 是 **VARCHAR 分类**。
无 `id`:`f_id`=UUID v4、`f_tenant_id='0'`、`f_parent_id` 默认 `'0'`、`f_enabled_mark=1`、
`f_creator_time`=now、`f_delete_mark=0`。
有 `id` 但行不存在 ⇒ `400 '菜单不存在'`。
- **Delete**:软删菜单;`base_authorize` 里 `f_item_type='module' AND f_item_id=<id>` 的行**软删**。
### 7.5 授权写入(`saveRoleModules`)
旧行**软删**(`f_delete_mark=1`,条件 `f_object_type='role' AND f_item_type='module' AND f_object_id=<roleId>`),
再插新行(`f_id`=UUID v4、`f_tenant_id='0'`、`f_object_type='role'`、`f_item_type='module'`、
`f_item_id`=<菜单 id>、`f_sort_code=0`、`f_delete_mark=0`)。
### 7.6 业务模块(spec 引擎)
三个模块语义同构:
- **List**:`f_delete_mark=0`,`f_creator_time DESC`
- **Save**:
- 无 `id` ⇒ 新建:`f_id`=36 位 UUID v4,`f_creator_user_id` 默认 `'admin'`(业务模块取请求值,缺省 `'admin'`),
`f_creator_time`=now,`f_delete_mark=0`;
**字段默认值**:`demo_item.f_status` 默认 `'草稿'`;`shop_product.f_price` / `book_shop_book.f_price` 默认 `'0.00'`;
`book_shop_book.f_stock` 默认 `0`。
- 有 `id` ⇒ 覆盖更新(`Object.assign(existing, item)` 语义)。
- **响应体 = 落库后重新读回的那一行**(这样 numeric 的 `"9.90"` 由投影 `::text` 保证)。
- **Delete**:软删 `f_delete_mark=1`
---
## 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
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**:cipher 用后端 `--enc` 自证。JSON 取值用 `grep`/`sed` 或 `jq`(若系统无 `jq`,用 `sed`/`python3` 兜底)。