31 KiB
契约规格 —— 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. 统一信封
{ "code": 200, "msg": "成功", "data": null }
code:intmsg:stringdata:任意 JSON(失败时为null)
Rust 侧固定形态(src/backend/src/envelope.rs):
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 逐字节等价)
// 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
算法:
key = md5_hex("EY8WePvjM5GGwQzn")⇒ 32 个 ASCII 字节(不是 16 字节摘要!)src = md5_hex(plaintext)的 32 个 ASCII 字节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):
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 串:
to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creator_time
5.3 pglite 封装(src/backend/src/db.rs)
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):
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 '账号或密码错误'
实现注记: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 归一化:一维数组直接用;历史二维形态 [[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 集合,四个来源:
- 直授:
base_authorize中f_object_type='user' AND f_object_id=<userId> AND f_item_type='module' AND f_delete_mark=0⇒f_item_id - 角色:
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 - 组织:
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 - 岗位:
base_user_relation中f_user_id=<userId> AND f_object_type='position'⇒ 同上,f_object_type='position'
8.2 菜单守卫 has_module(userId, isAdmin, moduleKey)
isAdmin == 1⇒ 放行(不查任何 SQL)- 查
base_module中f_url_address = moduleKey AND f_delete_mark=0;查不到 ⇒ 放行(未映射放行) - 查得到 ⇒ 该菜单
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 导出。
// ---- 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
pub fn new_uuid() -> String; // 36 位 UUID v4(带连字符)
session.rs
#[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
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
/// 三个字段全是 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
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)
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)
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
pub fn build_router(state: AppState) -> Router;
(with_state 由 main.rs 在链尾调用。)
AppState(src/backend/src/lib.rs 或独立 state.rs)
#[derive(Clone)]
pub struct AppState {
pub config: Arc<Config>,
pub db: Arc<Db>,
pub sessions: Arc<SessionStore>,
}
10. 启动装配(main.rs)
顺序:
resolve_project_dir()—— 从可执行文件向上找锚点文件(src/backend/db/schema.sql+ 根Cargo.toml),与 cwd 解耦Config::from_env(project_dir)- 标识符白名单自检(不过 ⇒ 秒退 exit 1),放在开库之前
Db::open/Db::open_temp⇒ensure_schema()seed::ensure_base()⇒ 若用户数为 0 则seed::first_seed()build_router(state)+ 404 兜底 + 405 改写中间件 +with_state(state)(链尾)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 兜底)。