# 契约规格 —— 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; /// 失败:code=, msg=, data=null(**恒 HTTP 200**) pub fn fail(code: i32, msg: impl Into) -> Json; ``` **没有第三种形状。** 禁止 `{"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; // 解出 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; pub fn valid_column(name: &str) -> Option; ``` **请求体键名 = 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; pub async fn open_temp() -> Result; pub async fn ensure_schema(&self) -> Result<(), pglite::Error>; pub async fn query_json(&self, sql: &str) -> Result, pglite::Error>; pub async fn query_json_params(&self, sql: &str, params: &[&(dyn pglite::ToSql + Sync)]) -> Result, 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, pglite::Error>; } /// 字面量感知 SQL 切分(单引号串 / dollar-quote / 行注释 / 块注释内的 `;` 不切) pub fn split_sql_statements(sql: &str) -> Vec; ``` **序列化手法**(沿用 `tdc-rs`): ```sql SELECT row_to_json(q)::text AS _row FROM () 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 `(大小写不敏感前缀)。 **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=` 的 `f_role_id`。 `roleNames` = 这些 roleId 对应的 `base_role.f_full_name`(`f_delete_mark=0` 的角色),查不到则跳过。 - **Save**: - `account` 为空 ⇒ `400 '账号不能为空'` - **重复账号** ⇒ `400 '账号已存在:'`(**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 '角色编码已存在:'`。 有 `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=` 的行**软删**(`f_delete_mark=1`); `base_role_relation` 里 `f_role_id=` 的行**物理删除**。 - **Modules?roleId=**:`base_authorize` 中 `f_object_type='role' AND f_item_type='module' AND f_object_id= 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=` 且 `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=` 的行**软删**。 ### 7.5 授权写入(`saveRoleModules`) 旧行**软删**(`f_delete_mark=1`,条件 `f_object_type='role' AND f_item_type='module' AND f_object_id=`), 再插新行(`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= 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=` ⇒ 每行的 `f_role_id` ⇒ 对每个 roleId 取 `base_authorize` 中 `f_object_type='role' AND f_object_id= AND f_item_type='module' AND f_delete_mark=0` ⇒ `f_item_id` 3. **组织**:`base_user_relation` 中 `f_user_id= AND f_object_type='organize'` ⇒ 每行的 `f_object_id` ⇒ 对每个 objectId 取 `base_authorize` 中 `f_object_type='organize' AND f_object_id= ...` ⇒ `f_item_id` 4. **岗位**:`base_user_relation` 中 `f_user_id= 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= 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>> */ } 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; // 去 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, // 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; pub async fn current_user(state: &AppState, headers: HeaderMap) -> Json; /// 守卫:未登录 ⇒ `fail(600, "未登录")`;无菜单权限 ⇒ `fail(403, "无菜单权限")` pub async fn require_login(state: &AppState, headers: &HeaderMap) -> Result>; pub async fn require_module(state: &AppState, headers: &HeaderMap, module_key: &str) -> Result>; ``` ### permission.rs ```rust pub async fn resolve_user_module_ids(db: &Db, user_id: &str) -> HashSet; 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; #[derive(serde::Serialize)] pub struct MenuNode { pub id: String, pub full_name: String, // #[serde(rename="fullName")] pub url_address: Option, // #[serde(rename="urlAddress")] pub icon: Option, pub parent_id: String, // #[serde(rename="parentId")] pub children: Vec, } ``` ### 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, DbError>; pub async fn save(db: &Db, spec: &EntitySpec, body: &Value) -> Result; 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, pub db: Arc, pub sessions: Arc, } ``` --- ## 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` 兜底)。