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]>
This commit is contained in:
adminandClaude committed 2026-10-25 17:05:00 +08:00
commit 0aed12a102
5 files changed
+1504

No files matched your search

+23
View File
@@ -0,0 +1,23 @@
# Rust / cargo
target/
**/target/
# 运行期数据(pglite 数据目录)
src/backend/data/
*.pg/
# 前端
src/frontend/node_modules/
src/frontend/dist/
src/frontend/.vite/
# SDD 工作区(git-ignored 草稿)
.superpowers/
.tmp/
# 运行期 PID / 日志
.run/
*.log
# macOS
.DS_Store
+260
View File
@@ -0,0 +1,260 @@
# AGENTS.md
本文件是 `tds-lite-rs` 的**项目级 agent 指引**。内容必须与代码**同步**;改代码后回头核对本文件是否还成立。
> 详细设计、决策记录、实施顺序、验收门 ⇒ 见 [`HANDOFF.md`](HANDOFF.md)。
## 项目定位
**tds-lite-rs** = **JNPF 兼容契约的 Rust 实现**(单二进制、零外部服务)。
它的存在意义只有一条:**让"用 Rust 写业务"和"迁回官方 JNPF(Java)"之间是机械翻译,而不是重写。**
为此本仓的**数据模型(表名/列名/语义)与 HTTP 契约**从第一天就锁死成官方 JNPF 的形状。
命名沿用用户指定的 `tds-lite-rs`(与 `ssw-jnpf-lite` / `ssw-jnpf-lite-react` 同族的轻量垫片),
**不要**把它理解成 `tdc-rs` 那个「数据接入连接器」——两者无继承关系。
### 三个参照物(各司其职,别混)
| 参照物 | 路径 | 地位 |
|---|---|---|
| **官方 JNPF 源码 + DDL** | `~/Desktop/workspace/jnpf/` | **数据模型真源**:`base_*` 表名/列名/陷阱以官方 DDL 为准 |
| **`ssw-jnpf-lite-react` 技能** | `~/Desktop/workspace/skills/ssw-jnpf-lite-react/` | **行为真源**:NestJS 版把契约"跑起来了",本仓逐条对齐它 |
| **`tdc-rs` 兄弟项目** | `~/Desktop/workspace/tdc-rs/` | **只抄工程手法**(pglite 单实例、row_to_json 投影、axum 0.8 坑位)。**不共享代码、不共享端口、不共享数据目录** |
🔴 **`tdc-rs` 与本仓无依赖关系**。别 import 它的代码、别改它、别把两边的数据目录指到同一处。
它已经占了 `:30000`,**本仓后端默认 `:30010`**。
### 交付形态
v1 = **全量契约对齐**:登录 / `CurrentUser` / 5 组 `base_*` 管理 CRUD / 统一授权 /
四源权限合并 / 两段式种子 / 3 个业务模块(demo · shop · books)/ 权限闭环冒烟。
先做**真实项目**,跑通验收门之后**再抽成技能**(技能资产形态 = 本仓 1:1 复制)。
## 技术栈
| 层 | 选型 | 说明 |
|---|---|---|
| 后端 | Rust 2021 + axum 0.8 + tokio | 单二进制 |
| 数据库 | **`pglite-rs` 0.2**(进程内原生 PostgreSQL) | 零服务/零 Docker/零 WASM;数据落盘 `src/backend/data/lite.pg` |
| 前端 | **react 技能的前端产物,逐字复用**(React + Vite) | **零改前端**;vite 代理 `/api` → 后端 |
| 密码学 | `aes` 0.8 + `ecb` 0.1 + `md-5` 0.10 | 与 react 技能 `cipher.ts` **逐字节等价** |
| 其它 | `serde` / `serde_json` / `serde_urlencoded` 0.7 / `uuid` v4 / `rand` 0.8 | |
> 🔴 **`pglite-rs` ≠ 浏览器 PGlite**。crate 名 `pglite-rs`、import 名 `pglite`;
> 它把 postgres-pglite 编译成原生静态库链进二进制 ⇒ **真实 PostgreSQL 语义**(类型/MVCC/事务/扩展/线协议),
> 进程内单 backend。**不是** `@electric-sql/pglite`(那是 WASM + IndexedDB,本仓禁止引入)。
## 目录速览(目标形态)
```
tds-lite-rs/
├── Cargo.toml # 【workspace 根】members = ["src/backend"];release profile 写在这里
├── CLAUDE.md / HANDOFF.md # 本文件 / 交接文档
├── src/
│ ├── backend/ # Rust 后端(workspace 唯一成员,crate 名 tds-lite-rs)
│ │ ├── Cargo.toml
│ │ ├── src/
│ │ │ ├── main.rs # 启动装配
│ │ │ ├── config.rs # 环境变量
│ │ │ ├── db.rs # pglite 封装 + schema 初始化
│ │ │ ├── cipher.rs # md5 + AES-256-ECB(对齐 cipher.ts)
│ │ │ ├── envelope.rs # ActionResult{code,msg,data}
│ │ │ ├── ids.rs # 36 位 UUID v4
│ │ │ ├── session.rs # 内存 token 表
│ │ │ ├── auth.rs # 登录 / CurrentUser / 鉴权守卫
│ │ │ ├── permission.rs# 四源合并 + 管理员短路 + 菜单树
│ │ │ ├── seed.rs # ensureBase + firstSeed
│ │ │ ├── sys.rs # 5 组 base_* 显式 handler
│ │ │ ├── crud.rs # 业务实体 spec 驱动 CRUD 引擎
│ │ │ ├── entities.rs # 业务实体 spec 表
│ │ │ └── routes.rs # 路由装配
│ │ ├── db/schema.sql # 完整 DDL(base_* 7 张 + 3 业务表)
│ │ └── data/ # 运行期数据(gitignore)
│ └── frontend/ # react 技能前端逐字复制(不改)
├── scripts/
│ ├── perm-smoke.sh # 权限闭环冒烟(22+ 断言)
│ └── check-module.sh # 业务模块 9 接触点静态自检
├── run.sh # install / build / dev / stop / logs
└── .env.example
```
## 架构红线
1. 🔴 **契约优先于实现。** 任何端点的路径、入参、返回形状、错误码,必须与
`ssw-jnpf-lite-react` **逐字一致**。不确定时先读 react 技能源码,别凭印象。
2. 🔴 **业务失败一律 HTTP 200 + `{code,msg,data}`。** 成败只看 body 的 `code`。
例外只有一个:**未知路由保留 HTTP 404**(body 仍是 `ActionResult` 形状)。
🔴 **鉴权失败也是 HTTP 200**(`code=600` 未登录 / `code=403` 无菜单权限)——
**与 `tdc-rs` 的 401/403 裸 body 相反**,别把 tdc-rs 的形状抄过来。
3. 🔴 **`base_*` 表名与列名逐字对齐官方 DDL**(含两个官方陷阱,见下)。
**不允许自创表名/列名**——迁移期靠 `--data-only` 导数据,列名差一个字符就导不进去。
4. 🔴 **四源权限合并 + 管理员短路 + 未映射放行。**
- 管理员(`f_is_administrator=1`)**在任何 SQL 之前**短路放行;
- 权限 = 用户直授 + 角色 + 组织 + 岗位,**只查角色会漏授权**;
- 菜单**未映射**到 `base_module` ⇒ **放行**(对齐 `SswPermissionGuard` 的 warn 路径),
不是拒绝。这条最容易写反,且**静默**(不报错),所以必须有测试钉住。
5. 🔴 **口令不得外泄。** 库内存 `md5(明文)`;对外响应**手工挑字段**(用户列表要**去掉 `password`**)。
密文只在请求体里出现,永不回显。
6. 🔴 **前端不直接持有数据库。** 一切访问经 `/api/**`。
7. 🔴 **schema DDL 绝不可从 HTTP 下载。** `db/schema.sql` **不在 web root**,
且要有兜底守卫(`/api/**` 之外的静态托管只放前端产物)。
8. 🔴 **同一文件的多个 Edit 必须串行**(并行 Edit = last-writer-wins 静默覆盖)。
改完**必须 grep 复核**全部改动点。
### 官方 DDL 的两个"故意不修正"的陷阱
| 陷阱 | 事实 | 后果 |
|---|---|---|
| `base_role_relation` | 用户 id 存在 **`f_object_id`**(配 `f_object_type='user'`),**没有 `f_user_id`** | 写错列 ⇒ 角色授权永远不生效 |
| `base_user_relation` | 组织/岗位关系在**另一张表**,那里**才有 `f_user_id`** | 写错表 ⇒ 组织/岗位授权永远不生效 |
另:`base_module.f_type` 是 **INTEGER**(1-目录 2-页面),`f_category` 是 **VARCHAR**(分类)——
早期 MVP 曾写反,本仓以官方 DDL 为准。
## 关键实现细节(改代码前必读)
1. **cipher 的 key 是"hex 串当 ASCII 用"**:
`md5_hex("EY8WePvjM5GGwQzn")` 得到 32 个 hex 字符 ⇒ 把这 **32 个 ASCII 字节**当 key
⇒ **AES-256**(不是 AES-128)。src 同理 = `md5_hex(明文)` 的 32 个 ASCII 字节。
输出 hex。**上游检验向量**:`encryptPassword('123456')` ==
`d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`。
`tdc-rs/src/cipher.rs` 有逐字对齐的 Rust 实现**可读作参考**(但**不共享代码**)。
2. **口令比对**:`base_user.f_password` 存 `md5(明文)` 的小写 hex;
登录时 `decrypt(密文)` 得到 `md5(明文)` ⇒ **大小写不敏感**比较。
3. **numeric 列必须序列化成 JSON 字符串**(`"9.90"`,不是 `9.9`)。
手段:**在 SQL 投影里就 cast 成 text**(`f_price::text AS price`)——
`row_to_json` 直接给数字会被 serde_json 变成 f64 再输出 `9.9` ⇒ 契约破。
`int` 列(`f_delete_mark` / `f_stock` / `f_is_administrator`)**保持数字**。
4. **主键是 36 位 UUID v4**(带连字符),列 `varchar(50)` 装得下。**不是** `tdc-rs` 的雪花十进制。
5. **JSON 键名 = 列名去 `f_` 前缀后 camelCase**:`f_id→id`、`f_real_name→realName`、
`f_url_address→urlAddress`、`f_is_administrator→isAdministrator`、`f_delete_mark→deleteMark`、
`f_creator_time→creatorTime`。请求体**去前缀名**(`title` 不是 `fTitle`)。
6. **pglite 单 backend 串行化**:所有 DB 访问必须持**进程级** `db_lock`
(`OnceLock<Arc<tokio::Mutex<()>>>`)。同时**一个数据目录只能被一个进程打开**
⇒ 集成测试要么串行、要么各自用独立数据目录。
7. **查询结果序列化**:沿用 `tdc-rs` 的手法
`SELECT row_to_json(q)::text AS _row FROM (<sql>) q` ⇒ 取单列文本 ⇒ `serde_json::from_str`。
**不要另起逐列类型映射分支。**
8. **标识符白名单**:任何拼进 SQL 的表名/列名都要过白名单
(`[A-Za-z][A-Za-z0-9_]*`),并在**启动时自检**全部拼接点,不过白名单 ⇒ 秒退。
9. **`include_str!` 路径相对 `src/db.rs`**:写 `../db/schema.sql`。
10. **axum 0.8 语义**:`Router<S>` 的 `S` 是"还缺什么状态" ⇒ `with_state` 必须是**链条最后一步**。
11. **`Form<T>` 在 axum 0.8.9 只实现 `FromRequest`**(没有 `OptionalFromRequest`)
⇒ `Option<Form<T>>` **编译不过** ⇒ 需要"解析失败也走业务信封"的表单端点,
取**原始 body** 自己用 `serde_urlencoded::from_bytes` 解析。
(`/api/oauth/Login` 正是这种端点,且 `grant_type` **不能**加 camelCase。)
12. **405 的 JSON 兜底**用**响应改写中间件**(挂在链尾),不要用 axum 的
`method_not_allowed_fallback`(后者只对调用那一刻已注册的路由生效,且丢 `Allow` 头)。
13. **schema 初始化**:启动时探测 `base_user` 是否存在,不存在才按 `;` 拆分执行 `schema.sql`
(拆分要**字面量感知**,别把字符串里的 `;` 当语句边界)。
14. **路径与 cwd 解耦**:`resolve_project_dir()` 从可执行文件向上找锚点文件,
`static/` 与 `data/` 都基于它 —— 后台启动时 cwd 会漂移,改成相对 cwd ⇒ 500。
15. **未知路由 = HTTP 404**(body 仍是 `{code:404,msg:'接口不存在',data:null}`)。
**不要**用"全局 404 兜底"把它变成 200。
## 数据模型
`src/backend/db/schema.sql` —— **10 张表**。
### `base_*` 7 张(官方 DDL 逐字,复合主键 `(f_id, f_tenant_id)`,单租户固定 `'0'`)
| 表 | 官方 DDL 行号 | 用途 |
|---|---|---|
| `base_authorize` | 812 | 授权(`f_object_type`/`f_object_id`/`f_item_type`/`f_item_id`) |
| `base_module` | 2209 | 菜单(`f_url_address` = 前端 Route path 去前导斜杠) |
| `base_organize` | 3178 | 机构(`f_parent_id` 树) |
| `base_role` | 3686 | 角色(`f_en_code` 唯一性应用层保证) |
| `base_role_relation` | 3729 | 用户↔角色(⚠️ 用户 id 在 `f_object_id`) |
| `base_user` | 4479 | 用户(`f_password`=md5,`f_is_administrator`,**`f_account` 无 UNIQUE**) |
| `base_user_relation` | 4707 | 用户↔组织/岗位(⚠️ 这里才有 `f_user_id`) |
行号出处:`~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql`
(同目录还有 `jnpf_db_init.sql` 等 9 个 init 文件,**只读**)。
### 业务表 3 张(与 react 技能同名 ⇒ 两版后端可开同一个库)
| 表 | 实体 | 列 |
|---|---|---|
| `demo_item` | DemoItem | `f_id` / `f_title` / `f_status` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` |
| `shop_product` | Product | `f_id` / `f_title` / `f_price numeric(12,2)` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` |
| `book_shop_book` | 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` |
> 🔴 **只有 `base_*` 的表名/列名是契约**;业务表名只是**为了数据模型可移植**(两版后端能开同一个库)才故意对齐。
## 端点全表
| 方法 | 路径 | 守卫 | 说明 |
|---|---|---|---|
| POST | `/api/oauth/Login` | 无 | form-urlencoded:`account` / `password`(密文 hex) / `grant_type=password`;成功返回 `{token, expiresIn:7200, tokenTypeName:'bearer'}` |
| GET | `/api/oauth/CurrentUser` | 登录 | `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}`;未登录 `code=600` |
| GET/POST/DELETE | `/api/ssw/sys/User/{List,Save,Delete?id=}` | 登录 + 菜单 `system/User` | 列表**去掉 `password`**,附 `roleIds`/`roleNames` |
| GET/POST/DELETE | `/api/ssw/sys/Role/{List,Save,Delete?id=}` | 登录 + 菜单 `system/Role` | |
| GET | `/api/ssw/sys/Role/Modules?roleId=` | 登录 | 返 `string[]`(菜单 id) |
| GET/POST/DELETE | `/api/ssw/sys/Organize/{List,Save,Delete?id=}` | 登录 + 菜单 `system/Organize` | 有子机构时拒删(`code=400`) |
| GET/POST/DELETE | `/api/ssw/sys/Module/{List,Save,Delete?id=}` | 登录 + 菜单 `system/Module` | |
| PUT | `/api/permission/Authority/Data/{objectId}` | 登录 | body `{objectType:'role', module:['m1','m2']}` —— **`objectType` 必须小写**、**`module` 是一维数组** |
| GET | `/api/permission/Authority/RoleModules?roleId=` | 登录 | 返 `string[]` |
| 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` | |
其它:未知路由 → **HTTP 404** + `{code:404,msg:'接口不存在',data:null}`。
## 命令速查
```bash
# 编译(仓库根是 cargo workspace,成员 = src/backend)
cargo build # debug
cargo build --release # 发布版(release profile 写在根 Cargo.toml)
cargo test # 单测
# 运行(后端)
PORT=30010 ./target/release/tds-lite-rs
PGLITE_DIR=memory:// PORT=30010 ./target/release/tds-lite-rs # 纯内存
# 冒烟
bash scripts/perm-smoke.sh # 默认打 127.0.0.1:30010
B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh
./target/release/tds-lite-rs --enc 123456 # cipher 自证(免 node 依赖)
```
> 本机 curl 走系统代理,**测 localhost 必须加 `--noproxy '*'`**。
> 后台常驻进程用 Bash 工具的 `run_in_background` 托管;`nohup … &` 在工具返回后会被回收。
> 起服务时 stdout **不要**指向 `/dev/null`(进程会以 100 退出)。
## 已知踩坑清单
| 症状 | 根因 | 处理 |
|---|---|---|
| 登录必失败(400 账号或密码错误) | cipher key 当成了 16 字节原始摘要 ⇒ AES-128 | key = md5_hex 的 **32 个 ASCII 字节** ⇒ AES-256 |
| `f_price` 回显 `9.9` 而不是 `"9.90"` | `row_to_json` 把 numeric 给了数字 | 投影里 `f_price::text AS price` |
| 角色授权写了不生效 | 写进 `base_role_relation.f_user_id`(**不存在此列**) | 用户 id 写 `f_object_id` + `f_object_type='user'` |
| 组织/岗位授权不生效 | 写进 `base_role_relation` | 写 `base_user_relation`(有 `f_user_id`) |
| 授权接口返 200 但一行没写 | `objectType` 传了 `'Role'`(大写) | 必须小写 `'role'`;`module` 传一维数组 |
| 非管理员拿到了全部菜单 | 只查了角色授权 | 四源合并(直授+角色+组织+岗位) |
| 菜单授权没生效但接口放行 | 菜单 `f_url_address` ≠ 前端 Route path | 三处(urlAddress / Route path / 守卫 key)必须一字不差 |
| `Option<Form<T>>` 编译不过 | axum 0.8.9 的 `Form` 无 `OptionalFromRequest` | 取原始 body 自己 `serde_urlencoded` 解析 |
| 405 返回 HTML / 丢 `Allow` 头 | 用了 axum 的 `method_not_allowed_fallback` | 用响应改写中间件(链尾) |
| DDL 能从 HTTP 下载 | DDL 落在 web root | 移到 `db/` + 兜底守卫 |
| 第二个实例起不来 | pglite 单实例独占数据目录 | 换数据目录/端口 |
| 集成测试互相撞车 | pglite 独占 + 种子账号唯一 | 串行跑 或 各用独立数据目录 |
| 账号能建重复 | 官方 `f_account` **无 UNIQUE**(故意的) | 唯一性**应用层**保证;只比 `delete_mark=0` 的行 |
| `data/` 里的库改了不生效 | schema 只在**首次**建表时执行 | 改 schema ⇒ 清空 `data/` 重建 |
## 明确不在 v1 范围
- **低代码引擎**(JNPF 的表单/流程/代码生成)—— 官方能力,本仓不碰。
- **多租户**(`jnpf-tenant*`)—— 单租户固定 `f_tenant_id='0'`。
- **按钮/列/表单/数据范围级授权**(`base_module_button` / `_column` / `_form` / `_data`)——
官方 DDL 里都有,但 v1 只做 `item_type='module'`(菜单)一类。
- **Redis / Sa-Token** —— 内存 token 表即可(进程重启即失效,与 JNPF 的 Sa-Token 内存模式同代)。
- **分页** —— 契约里的 `List` 就是**全量**(前端不分页)。要分页是 JNPF 稳定期的 `SuperServiceImpl.page`。
- **`base_user.secretkey` / `f_role_id` 的 JNPF 真实算法**(官方是 `md5(md5(raw)+secretkey)`)——
本仓留位待迁移补;本仓用 `md5(明文)` 即可(登录比的是同一个值)。
## 记忆约定
- **踩坑清单与长 traceback** → `docs/<子系统>/<topic>.md`(本文件表格即其索引)。
- **工作日志** → `.workbuddy/memory/YYYY-MM-DD.md`。
- **本文件只留**「原则 + 决定 + 一句话摘要」。改代码后回头核对本文件是否还成立。
+360
View File
@@ -0,0 +1,360 @@
# HANDOFF.md —— tds-lite-rs 交接文档
> **给下一个会话的你**:本文件 + `CLAUDE.md` 两份读完就能直接开工,**不需要**重新推导任何设计。
> 目标:把「JNPF 兼容契约的 Rust 实现」从零写到**验收全绿**。
---
## 0. 当前状态
| 项 | 状态 |
|---|---|
| 目录 `~/Desktop/workspace/tds-lite-rs/` | ✅ 已建(`git init` 已做,**未 commit**) |
| `CLAUDE.md` | ✅ 已写(项目级 agent 指引:红线 / 坑位 / 端点全表 / 数据模型) |
| `HANDOFF.md`(本文件) | ✅ 已写 |
| 代码 | ⬜ **零行**。`src/` `scripts/` `Cargo.toml` `schema.sql` 都还没有 |
| 前端 | ⬜ 还没复制(`ssw-jnpf-lite-react/src/frontend` → 本仓 `src/frontend`) |
| 设计 | ✅ 已定稿(见 §3),**不要再重新设计** |
**开工前先读**:`CLAUDE.md`(红线与坑位)→ 本文件 §3(设计)→ §5(实施顺序)。
§4 的四道验收门是"什么算做完"的唯一判据。
---
## 1. 决策记录(本轮问答全过程,含被推翻的方案)
> 保留被推翻的方案,是为了避免下个会话"重新考虑"已经讨论过的问题。
| # | 问题 | 决定 | 理由 |
|---|---|---|---|
| 1 | Rust 版做成什么形态? | **先做真实项目,验证后再抽技能** | 技能是模板;没跑通的模板没有价值 |
| 2 | v1 做多大? | **全量契约对齐**(auth + 5 组 `base_*` + 四源权限 + 两段种子 + 3 业务模块 + 冒烟) | 迁移价值全在权限与数据模型这两块,缺一块就不成立 |
| 3 | 落在哪个仓? | **独立仓** `tds-lite-rs` | ~~原方案:tdc-rs 开分支~~(已被 #4 推翻) |
| 4 | 运行时拓扑? | **先不碰 tdc-rs,独立仓做** | tdc-rs 已占 `:30000` 且已有自己的 `/api/oauth/Login`(JSON 账号库),两套同路径不同语义会打架 |
| 5 | 目录名? | **`tds-lite-rs`**(用户指定) | ~~原方案:`ssw-jnpf-lite-rust`~~ |
| 6 | 数据库? | **pglite-rs 0.2**(进程内原生 PG) | 沿用 tdc-rs 已验证的形态;零服务零 Docker |
| 7 | 后端端口? | **`:30010`**(前端 vite `:5173`) | 避开 tdc-rs 的 `:30000` |
| 8 | 前端怎么办? | **逐字复制** react 技能的前端,**零改动** | 前端零改 = 契约真的对齐了(改了就说明后端在迁就前端) |
| 9 | 业务实体怎么实现? | **spec 驱动 CRUD 引擎**;5 组 `base_*` 走**显式 handler** | 业务模块语义简单可声明化;`base_*` 的语义(一维授权数组 / 用户↔角色 / 机构树防环)塞不进通用引擎 |
| 10 | 冒烟脚本的 node 依赖? | Rust 二进制加 `--enc <明文>` 模式,脚本**自证 cipher**,不依赖 node | 去掉 node 依赖 = 冒烟可在任何装了 Rust 的机器上跑 |
| 11 | 抽技能的时机? | **验收门全绿之后**再抽 | 目录结构现在就和 react 技能对齐(`src/backend` + `src/frontend` + `scripts/` + `run.sh`),届时 1:1 复制即可 |
**关键约束**:`tdc-rs` **只读**。本仓不 import 它的代码、不共享数据目录、不共享端口。
可以**读**它的 `src/cipher.rs` / `src/db.rs` / `src/envelope.rs` 作工程手法参考。
---
## 2. 目标与非目标
**目标(v1 做完的样子)**:
1. 用 **Rust** 起一个**单二进制、零外部服务**的后端,行为与 `ssw-jnpf-lite-react`(NestJS)**逐条一致**。
2. 前端**一行不改**就能跑通(直接复用 react 技能的 `src/frontend`)。
3. `base_*` 表结构与官方 DDL **逐字一致** ⇒ 迁 JNPF 时**导数据即可**(`--data-only`)。
4. 权限闭环(登录 → 菜单树 → 建用户 → 授权 → 收窄 → 403)**有自动化冒烟钉住**。
5. 跑通之后,1:1 复制成技能(`ssw-jnpf-lite-rust`)。
**非目标(明确不做)**:低代码引擎 / 多租户 / 按钮·列·表单·数据范围级授权 /
Redis+Sa-Token / 分页 / `secretkey` 的官方双层 md5 算法。理由见 `CLAUDE.md`「明确不在 v1 范围」。
---
## 3. 设计(已定稿)
### 3.1 落点与边界
```
tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
├── Cargo.toml ← 【workspace 根】members=["src/backend"] + [profile.release]
├── src/backend/ ← 名字保留是为了将来抽技能时目录与 react 版对齐
│ ├── src/*.rs ← 14 个模块(见 §3.3)
│ ├── db/schema.sql ← 10 张表完整 DDL
│ └── data/ ← 运行期(gitignore)
├── src/frontend/ ← react 技能前端逐字复制(零改)
├── scripts/{perm-smoke.sh,check-module.sh}
├── run.sh ← install/build/dev/stop/logs
└── .env.example
```
**端口**:后端 `30010`(`PORT` 可覆盖)· 前端 `5173`(vite)· vite proxy `/api` → `http://127.0.0.1:30010`。
**数据库**:`pglite-rs`,默认落盘 `src/backend/data/lite.pg`;`PGLITE_DIR=memory://` ⇒ 纯内存。
### 3.2 契约逐字对齐表(对着 react 技能源码抄)
| 契约点 | 精确口径 | react 源码位置 |
|---|---|---|
| 统一返回 | `{code,msg,data}`;成功 `code=200,msg='成功'`;失败 `data=null` | `src/backend/src/common/action-result.ts` |
| HTTP 状态 | 业务失败/鉴权失败 **HTTP 200**;**未知路由 HTTP 404**(body 仍是 ActionResult) | `common/action-result.filter.ts` |
| 错误码 | 未登录 `600` · 无菜单权限 `403` · 业务失败 `400`(msg 透传) | 同上 + 各 controller |
| 登录 | `POST /api/oauth/Login`,form-urlencoded `account`/`password`(密文 hex)/`grant_type=password` | `auth/auth.controller.ts:19` |
| 登录失败文案 | 缺参 → `400 '缺少 account / password'`;grant_type 不支持 → `400`;口令错 → `400 '账号或密码错误'` | `auth/auth.controller.ts` |
| 登录成功体 | `{token, expiresIn:7200, tokenTypeName:'bearer'}` | `auth/auth.service.ts` |
| CurrentUser | `GET /api/oauth/CurrentUser` → `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` | `auth/auth.controller.ts:34` |
| cipher | `md5(明文)` → AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")` 的 32 ASCII 字节)→ hex | `common/cipher.ts` |
| 检验向量 | `encryptPassword('123456')` = `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b` | `common/cipher.ts` 注释 |
| 口令比对 | 库内存 `md5(明文)` 小写 hex;登录解出 `md5(明文)` ⇒ **大小写不敏感**比较 | `auth/auth.service.ts` |
| 权限四源 | 直授 + 角色 + 组织 + 岗位;**管理员短路在 SQL 之前**;**菜单未映射 ⇒ 放行** | `sys/permission.service.ts` |
| 菜单树 | `parentId||'0'` 为根;按 `sortCode` 升序;节点 `{id,fullName,urlAddress,icon,parentId,children}` | `sys/permission.service.ts:toTree` |
| 授权写入 | `PUT /api/permission/Authority/Data/{objectId}`,body `{objectType:'role'(小写), module:[...]}`(**一维**) | `sys/authorize.controller.ts:39` |
| 授权读取 | `GET /api/permission/Authority/RoleModules?roleId=` → `string[]` | `sys/authorize.controller.ts:52` |
| 角色授权写 | 旧行**软删**(`delete_mark=1`)后插新行 | `sys/sys.service.ts:saveRoleModules` |
| 用户↔角色 | `setUserRoles` = 先 `delete` 旧 `base_role_relation` 行再插新行 | `sys/sys.service.ts` |
| 用户列表 | 去掉 `password`,追加 `roleIds` / `roleNames` | `sys/sys.service.ts:listUsers` |
| 账号唯一 | 应用层保证,**只比 `delete_mark=0`**(官方 DDL 无 UNIQUE) | `sys/sys.service.ts:saveUser` |
| 机构删除 | 有子机构 ⇒ `400 '该机构下还有子机构,先删除子机构'` | `sys/sys.service.ts:deleteOrganize` |
| 业务 List | 软删过滤 + `creatorTime DESC` | `shop/product.service.ts` |
| 业务 Save | 无 id ⇒ 新 36 位 UUID + `creatorUserId='admin'` + `creatorTime=now` + `deleteMark=0`;有 id ⇒ 覆盖更新 | `shop/product.service.ts` |
| 业务 Delete | **软删**(`f_delete_mark=1`) | `shop/product.service.ts` |
| numeric 列 | JSON **字符串**(`"9.90"`) | `shop/product.entity.ts` + TypeORM numeric→string |
| int 列 | JSON 数字 | `books/book.entity.ts` |
| 端点命名 | `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` | 各 controller |
**种子里必须逐字保留的常量**(`sys/seed.service.ts` 的字面量数组):
- 角色:`role_admin`/enCode `admin`/管理员/sort 1;`role_user`/enCode `user`/使用者/sort 2
- 菜单(`f_type`:1=目录 2=页面):
| 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 |
> ⚠️ `perm-smoke.sh` 在 react 版里是**从 `seed.service.ts` 的字面量动态算期望菜单树**的。
> Rust 版没有那个文件 ⇒ **两种做法二选一**:
> (a) 把上表搬进冒烟脚本作为字面量;或 (b) 后端暴露一个只读端点/二进制子命令打印期望树。
> **推荐 (a)**:脚本自包含、离线可跑。菜单增删时同步改脚本(这是**刻意的耦合**,不是缺陷)。
**两段式种子**(`sys/seed.service.ts`):
- `ensureBase`(**每次启动都跑**,幂等):按 `enCode` 补内置角色、按 `urlAddress` 补内置菜单、
补齐 admin 角色对内置菜单的授权(取库里**真实行 id**)。
**只补缺项**:不覆盖已改值;**同 urlAddress 已有行(含软删)不复活**。
- `firstSeed`(**仅 users==0 时跑一次**):`admin/123456`(`f_is_administrator=1`, `f_organize_id='0'`)
+ 一条 `base_role_relation`(`object_type='user'`, `object_id='admin'`, `role_id='role_admin'`)。
角色/菜单/授权行已由 `ensureBase` 建出,**不重复写**。
### 3.3 后端模块划分
| 模块 | 职责 | 备注 |
|---|---|---|
| `main.rs` | 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听 | `with_state` 必须是最后一步 |
| `config.rs` | `PORT` / `PGLITE_DIR` / 静态目录 / 种子开关 | 环境变量 |
| `db.rs` | pglite 封装:`query_json()` / `query_rows()` / `exec()` / `ensure_schema()` / `valid_table()` | 单 backend ⇒ 进程级 `db_lock` |
| `cipher.rs` | `md5_hex()` / `encrypt_password()` / `decrypt_to_md5()` | **逐字对齐 `cipher.ts`** + 上游向量单测 |
| `envelope.rs` | `ActionResult{code,msg,data}` + `ok/fail/fail_code` | 业务失败恒 HTTP 200 |
| `ids.rs` | `new_uuid()` → 36 位 UUID v4 | **不是** tdc-rs 的雪花 |
| `session.rs` | 内存 token 表(`lite-` 前缀 + 32 hex) | 进程重启即失效 |
| `auth.rs` | 登录 / CurrentUser / `require_login()` / `require_module()` | 守卫返回 `ActionResult`(600 / 403) |
| `permission.rs` | `resolve_user_module_ids()` 四源合并 / `has_module()` 管理员短路+未映射放行 / `build_menu_list()` | **四源 + 两条放行路径都要有测试** |
| `seed.rs` | `ensure_base()` + `first_seed()` | 幂等 + 只补缺项 |
| `sys.rs` | 5 组 `base_*` 的显式 handler 语义 | 用户/角色/机构/菜单/授权 |
| `crud.rs` | spec 驱动的通用 CRUD(List/Save/Delete) | 业务实体用 |
| `entities.rs` | 业务实体 spec 表(表名 / 列 / 类型 / 数值列 / 守卫菜单 key) | 加业务模块 = 加一条 spec |
| `routes.rs` | 路由装配 | |
### 3.4 三个关键取舍
1. **业务实体走 spec 引擎,`base_*` 走显式 handler。**
理由:业务模块语义同构(列表/保存/软删/守卫),声明化后"加一个模块 = 加一条 spec";
而 `base_*` 的语义(一维授权数组、用户↔角色关系、机构树防环、账号唯一性)**塞不进通用引擎**,
硬塞会得到一个既不懂 JNPF 又难懂的框架。
2. **numeric 列在 SQL 投影里就 cast 成 text。**
理由:`row_to_json` 直接给数字 ⇒ serde_json 解析成 f64 ⇒ 回显 `9.9` ⇒ 契约破。
在投影层 `f_price::text AS price` 才是"一次解决、处处一致"。
3. **HTTP 状态语义**刻意**不同于** `tdc-rs`(那边是 401/403 裸 body,这边是 200 + code 600/403)。
理由:react 前端的拦截器只认 `body.code`;两边同时跑时更不能混形状,否则冒烟脚本得写两套。
### 3.5 前端
- **逐字复制** `ssw-jnpf-lite-react/src/frontend` → `src/frontend`(`package.json` / `vite.config.ts` / `src/**`)。
- **唯一允许的改动**:vite 的 proxy 目标端口 `30000 → 30010`(以及 `baseURL` 仍是 `/api`,不变)。
- 前端 `utils/cipher.ts` **保持不变**(它是浏览器侧算法;后端 Rust 侧必须与它**逐字节等价**——由上游向量钉住)。
- 路由 path(`App.tsx`):`/login` `/demo-item` `/shop/Product` `/books/Book`
`/system/User` `/system/Role` `/system/Organize` `/system/Module`
⇒ **去掉前导斜杠**就是 `base_module.f_url_address` ⇒ 也是后端守卫的 module key。**三处一字不差。**
### 3.6 目录/文件对照(react 技能 → 本仓)
| react 技能 | 本仓 |
|---|---|
| `src/backend/src/common/cipher.ts` | `src/backend/src/cipher.rs` |
| `src/backend/src/common/action-result.ts` + `.filter.ts` | `src/backend/src/envelope.rs` |
| `src/backend/src/auth/*` | `src/backend/src/auth.rs` |
| `src/backend/src/sys/permission.service.ts` | `src/backend/src/permission.rs` |
| `src/backend/src/sys/seed.service.ts` | `src/backend/src/seed.rs` |
| `src/backend/src/sys/sys.service.ts` | `src/backend/src/sys.rs` |
| `src/backend/src/{demo,shop,books}/*` | `src/backend/src/entities.rs` + `crud.rs` |
| `src/backend/db/schema.sql` | `src/backend/db/schema.sql`(**本仓要写全 10 张表**) |
| `src/frontend/**` | `src/frontend/**`(逐字复制) |
| `scripts/perm-smoke.sh` | `scripts/perm-smoke.sh`(移植,cipher 改用 `--enc`) |
| `scripts/check-module.sh` | `scripts/check-module.sh`(移植,grep 模式按 Rust 调整) |
| `run.sh` | `run.sh`(改成 cargo 版本) |
---
## 4. 四道验收门("做完"的唯一判据)
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error 0 warning;release 配置照 tdc-rs(`opt-level=2` / `lto="thin"` / `strip="symbols"` / `panic="abort"` / `codegen-units=16`) |
| ② 单测 | `cargo test` | 覆盖:cipher 上游向量 · 信封形状(200/400/600/403)· 四源合并 · 管理员短路 · 未映射放行 · 种子幂等(跑两次结果一致 + 不复活软删行)· CRUD 往返(36 位 UUID / numeric→`"9.90"` / int→`100`)· 账号重复返 400 而非 500 |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **22+ 条断言全绿**(FAIL=0),与 react 版断言集**逐条对应**(见 §5 步骤 11 的清单) |
| ④ 前端手验 | `cd src/frontend && npm run dev` | 浏览器 `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
**外加**:`scripts/check-module.sh`(9 接触点静态自检)的 Rust 版移植,作为"加模块后立刻跑"的前置闸门。
---
## 5. 建议实施顺序(step 0–12)
> 每步都带**完成判据**。做完一步先跑该步的判据,再进下一步。
| step | 内容 | 完成判据 |
|---|---|---|
| **0** | 建 **cargo workspace**(根 `Cargo.toml`:`[workspace] members=["src/backend"]` + `[profile.release]`)+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / tower-http 0.6 / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) | 根目录 `cargo build` 通过(哪怕是空 main) |
| **1** | `src/cipher.rs` + 单测 | 上游向量**逐字节**相等;`md5_hex` 与 `decrypt_to_md5` 往返一致 |
| **2** | `src/envelope.rs` + 单测 | 业务失败 HTTP 200 + `code=400`;`code=600/403` 同形 |
| **3** | `src/db.rs` + `src/config.rs` + `db/schema.sql`(10 张表) | 进程能开库并建表;`query_json()` 能取回 JSON |
| **4** | `src/ids.rs` + `src/session.rs` | UUID 36 位带连字符;token 登录后可查回 |
| **5** | `src/seed.rs`(`ensure_base` + `first_seed`) | 空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;**再启动一次库内容不变** |
| **6** | `src/permission.rs` + 单测 | 四源合并各源单独可注入;管理员短路**不查 SQL**(可用「无授权记录的管理员仍放行」验证);未映射菜单放行 |
| **7** | `src/auth.rs` + `/api/oauth/*` | 登录返 `{token,expiresIn:7200,tokenTypeName:'bearer'}`;CurrentUser 返 `{userInfo,menuList}`;无 token ⇒ `code=600` |
| **8** | `src/sys.rs` + `/api/ssw/sys/*` + `/api/permission/Authority/*` | 5 组 CRUD 语义对齐;**重复账号返 `code=400` + msg `'账号已存在:xxx'`**(不是 500);授权写 `objectType='role'` 小写 + 一维数组 |
| **9** | `src/entities.rs` + `src/crud.rs` + 3 个业务模块端点 | demo/shop/books 三个模块端点可用;numeric 往返 `"9.90"`;未授权非管理员访问 shop/books ⇒ `code=403` |
| **10** | `src/routes.rs` + `main.rs` 装配 + 404/405 兜底 | 未知路由 **HTTP 404** + `code=404`;405 返回 JSON;`with_state` 在链尾 |
| **11** | `scripts/perm-smoke.sh` 移植(**逐条对应 react 版**) | 22+ 断言全绿 |
| **12** | 前端复制 + `run.sh` + `.env.example` + 文档 | 门④ 手验全过;`run.sh install/build/dev/stop/logs` 可用 |
**step 11 的断言清单**(照 react 版 `scripts/perm-smoke.sh` 逐条移植):
1. 无 token 访问 `User/List` ⇒ `code=600`
2. 加密登录 ⇒ `code=200`;3. 拿到 token(非空)
4. `CurrentUser` ⇒ `code=200`
5. 菜单树与种子表**逐字相等**(推荐做法:把 §3.2 的菜单表搬进脚本作字面量)
6. 建用户 ⇒ `code=200`
7. **重复账号** ⇒ HTTP **200**(不是 500)且 `code=400` 且 msg `'账号已存在:smoke_user'`
8. 写授权(一维数组)⇒ `code=200`;9. 写授权(二维兼容)⇒ `code=200`
10. 非管理员登录 ⇒ `code=200`
11. 非管理员菜单**已收窄**(字符串比对)
12. 非管理员访问 `User/List` ⇒ `code=403`
13. 已授权业务(demo)⇒ `code=200`
14. 未知路由 ⇒ **HTTP 404**(不被吞掉)
15. admin 短路 ⇒ Product 列表 `code=200`
16. Product 新建 ⇒ `code=200`;17. 主键 **36 位**;18. numeric 往返 **`"9.90"`**
19. Product 无 token ⇒ `code=600`;20. 未授权非管理员 ⇒ `code=403`
(react 版共 22+ 条,上表是主干;移植时以 react 脚本为准逐条对齐,**一条不落**。)
**另外**:`scripts/check-module.sh`(9 接触点静态自检)移植为 Rust 版——
把「grep TS 文件里的字符串」换成「grep Rust 源 + 检查 spec 注册」,保持同样的 ❌ 判定与退出码约定
(0 全过 / 1 有 ❌ / 2 用法错)。
**脚本退出码约定**(三个入口一致,照抄 react 技能):
| 入口 | 0 | 1 | 2 |
|---|---|---|---|
| `run.sh` | 执行成功 | 运行期失败 | 用法错 |
| `scripts/check-module.sh` | 接触点全过 | 有 ❌ 项 | 用法错 |
| `scripts/perm-smoke.sh` | 全绿(FAIL=0) | 有断言失败 | 前置错误(后端不可达) |
---
## 6. 必读参考文件(绝对路径)
### 契约真源(react 技能,**只读**)
```
~/Desktop/workspace/skills/ssw-jnpf-lite-react/
├── src/backend/src/common/cipher.ts ← cipher 算法 + 检验向量
├── src/backend/src/common/action-result.ts ← {code,msg,data}
├── src/backend/src/common/action-result.filter.ts ← HTTP 状态映射(200/404 的来源)
├── src/backend/src/auth/auth.controller.ts ← 登录 / CurrentUser 端点与文案
├── src/backend/src/auth/auth.service.ts ← 口令比对、token 生成
├── src/backend/src/sys/permission.service.ts ← 四源合并 + 管理员短路 + 未映射放行 + 菜单树
├── src/backend/src/sys/seed.service.ts ← roles/menus 字面量 + 两段式种子
├── src/backend/src/sys/sys.service.ts ← 5 组 base_* CRUD 语义
├── src/backend/src/sys/authorize.controller.ts ← 授权写/读 + 一维 module 归一化
├── src/backend/src/sys/base-*.entity.ts ← 7 张表的列 ↔ JSON 键映射
├── src/backend/src/{demo,shop,books}/* ← 业务模块参照实现
├── src/frontend/src/api/{request,auth,sys,product,book}.ts ← 前端实际调用的端点
├── src/frontend/src/App.tsx ← 前端路由 path(= urlAddress)
├── src/frontend/src/utils/cipher.ts ← 浏览器侧 cipher(后端必须等价)
├── scripts/perm-smoke.sh ← 断言集(逐条移植)
├── scripts/check-module.sh ← 9 接触点静态自检
└── run.sh ← 脚本骨架(改成 cargo 版)
```
### 官方 JNPF(数据模型真源,**只读**)
```
~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql
base_authorize :812
base_module :2209
base_organize :3178
base_role :3686
base_role_relation :3729
base_user :4479
base_user_relation :4707
(另有 base_module_{authorize,button,column,data,form,link,scheme,use_num}、
base_organize_administrator、base_user_{device,extra,old_password} —— v1 不做)
同目录还有 jnpf_db_init.sql(base_user 的 INSERT 可二次确证列名)等 9 个 init 文件
```
### 工程手法参考(tdc-rs,**只读**、不共享代码)
```
~/Desktop/workspace/tdc-rs/src/cipher.rs ← cipher 的 Rust 版逐字实现 + 坑位注释
~/Desktop/workspace/tdc-rs/src/envelope.rs ← 信封形状
~/Desktop/workspace/tdc-rs/src/db.rs ← pglite 封装 / query_json / valid_table
~/Desktop/workspace/tdc-rs/src/main.rs ← resolve_project_dir / 404 兜底 / with_state 收口
~/Desktop/workspace/tdc-rs/src/routes/mw.rs ← 405 JSON 兜底中间件
~/Desktop/workspace/tdc-rs/Cargo.toml ← release 配置
```
---
## 7. 风险与坑(开工前先知道)
| 风险 | 表现 | 处置 |
|---|---|---|
| **pglite 单实例独占数据目录** | 第二个进程起不来(`postmaster.pid` 锁) | 换数据目录/端口;集成测试串行或各用独立目录 |
| **pglite 体积** | debug 二进制 ~35 MB(内嵌 PG 引擎) | 与 tdc-rs 同量级,可接受 |
| **cipher 的 ASCII-hex key 坑** | 一旦当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂 | 单测钉死上游向量(步骤 1) |
| **numeric 变 9.9** | 前端金额显示错、冒烟第 18 条红 | 投影层 `::text`(步骤 9) |
| **`base_role_relation` 无 `f_user_id`** | 角色授权不生效 | 建表时逐字照官方 DDL(步骤 3) |
| **npm 装 esbuild 被拦** | vite 起不来 / 端口 000 且报错不指根因 | `npm install-scripts approve esbuild` 后在 `src/frontend` 重跑 `npm install` |
| **前端端口** | macOS 上 `localhost:5173` 失败 | 用 `127.0.0.1:5173`(vite 模板固定 bind IPv4) |
| **冒烟脚本依赖 node** | 换机器跑不了 | Rust 侧 `--enc` 自证(步骤 11) |
| **权限"看起来生效"其实没测到** | 返回了数据 ≠ 权限生效(管理员短路/菜单没映射/未清缓存/异常降级放行,**四条路径全是放行**) | 必须以「**菜单收窄 + 403 拦截**」为判据 |
---
## 8. 开放问题(开工时按需裁决,不阻塞)
1. **`git` 首个 commit 何时做** —— 目录已 `git init` 但**未 commit**。建议步骤 0 结束就 commit 一次骨架。
2. ~~**Cargo workspace 还是单 crate**~~ —— ✅ **已定:workspace**。
根 `Cargo.toml` = `[workspace] members = ["src/backend"] resolver = "2"` + `[workspace.dependencies]` +
`[profile.release]`(**release profile 只在 workspace 根生效**,别写到成员里);
`src/backend/Cargo.toml` = 成员 crate(crate 名 `tds-lite-rs`,`src/main.rs` 在 `src/backend/src/main.rs`)。
理由:保持目录与 react 版对齐 ⇒ 抽技能时 1:1 复制。
3. **`--enc` 子命令的参数形式** —— 建议 `./tds-lite-rs --enc 123456`(打印 hex 到 stdout,退出码 0);
未知参数按 `--help` 处理。
4. **是否需要 `/api/health`** —— react 版没有。**建议加**(`{ok, tables, version}`),便于冒烟探活,但**不是契约**。
5. **抽技能的目标目录名** —— 建议 `ssw-jnpf-lite-rust`,落在 `~/Desktop/workspace/skills/`,
与 `ssw-jnpf-lite-react` 并列。**验收全绿后再做。**
---
## 9. 会话交接话术(给下一个会话的提示词)
> 读 `CLAUDE.md` + `HANDOFF.md`(本文件)。设计已定稿,**不要重新设计**。
> 从 **step 0** 开始按 §5 顺序实施,每步先跑该步的完成判据。
> 参照物:`ssw-jnpf-lite-react`(契约真源,只读)、`jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql`(数据模型真源,只读)、
> `tdc-rs`(工程手法参考,只读,**不改**)。四道验收门见 §4,全部绿了才算完成。
+655
View File
@@ -0,0 +1,655 @@
# 契约规格 —— 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` 兜底)。
+206
View File
@@ -0,0 +1,206 @@
-- ===== base_authorize ===== (source lines 812-829)
CREATE TABLE base_authorize (
f_id VARCHAR(50) NOT NULL,
f_item_type VARCHAR(50),
f_item_id VARCHAR(50),
f_object_type VARCHAR(50),
f_object_id VARCHAR(50),
f_sort_code BIGINT,
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_creator_user_id VARCHAR(50),
f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_modify_user_id VARCHAR(50),
f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_user_id VARCHAR(50),
f_delete_mark INTEGER,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
f_org_id VARCHAR(50),
PRIMARY KEY (f_id, f_tenant_id)
);
-- ===== base_module ===== (source lines 2209-2240)
CREATE TABLE base_module (
f_id VARCHAR(50) NOT NULL,
f_parent_id VARCHAR(50),
f_type INTEGER,
f_full_name VARCHAR(200),
f_en_code VARCHAR(200),
f_category VARCHAR(50),
f_url_address VARCHAR(500),
f_icon VARCHAR(500),
f_link_target VARCHAR(50),
f_is_button_authorize INTEGER,
f_is_column_authorize INTEGER,
f_is_data_authorize INTEGER,
f_is_form_authorize INTEGER,
f_module_id VARCHAR(50),
f_system_id VARCHAR(50),
f_property_json TEXT,
f_description VARCHAR(500),
f_enabled_mark INTEGER,
f_sort_code BIGINT,
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_creator_user_id VARCHAR(50),
f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_modify_user_id VARCHAR(50),
f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_user_id VARCHAR(50),
f_delete_mark INTEGER,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
f_page_address VARCHAR(500),
f_no_show INTEGER DEFAULT 0,
PRIMARY KEY (f_id, f_tenant_id)
);
-- ===== base_organize ===== (source lines 3178-3201)
CREATE TABLE base_organize (
f_id VARCHAR(50) NOT NULL,
f_parent_id VARCHAR(50),
f_category VARCHAR(50),
f_en_code VARCHAR(200),
f_full_name VARCHAR(200),
f_manager_id VARCHAR(50),
f_property_json TEXT,
f_organize_id_tree TEXT,
f_description VARCHAR(500),
f_enabled_mark INTEGER,
f_sort_code BIGINT,
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_creator_user_id VARCHAR(50),
f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_modify_user_id VARCHAR(50),
f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_user_id VARCHAR(50),
f_delete_mark INTEGER,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
f_duty_position VARCHAR(50),
f_org_name_tree TEXT,
PRIMARY KEY (f_id, f_tenant_id)
);
-- ===== base_role ===== (source lines 3686-3707)
CREATE TABLE base_role (
f_id VARCHAR(50) NOT NULL,
f_full_name VARCHAR(200),
f_en_code VARCHAR(200),
f_type VARCHAR(50),
f_property_json TEXT,
f_global_mark INTEGER,
f_description VARCHAR(500),
f_enabled_mark INTEGER,
f_sort_code BIGINT,
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_creator_user_id VARCHAR(50),
f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_modify_user_id VARCHAR(50),
f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_user_id VARCHAR(50),
f_delete_mark INTEGER,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
f_is_condition INTEGER,
f_condition_json TEXT,
PRIMARY KEY (f_id, f_tenant_id)
);
-- ===== base_role_relation ===== (source lines 3729-3744)
CREATE TABLE base_role_relation (
f_id VARCHAR(50) NOT NULL,
f_role_id VARCHAR(50),
f_object_type VARCHAR(50),
f_object_id VARCHAR(50),
f_sort_code BIGINT,
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_creator_user_id VARCHAR(50),
f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_modify_user_id VARCHAR(50),
f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_user_id VARCHAR(50),
f_delete_mark INTEGER,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
PRIMARY KEY (f_id, f_tenant_id)
);
-- ===== base_user ===== (source lines 4479-4542)
CREATE TABLE base_user (
f_id VARCHAR(50) NOT NULL,
f_account VARCHAR(50),
f_real_name VARCHAR(50),
f_quick_query VARCHAR(100),
f_nick_name VARCHAR(50),
f_head_icon TEXT,
f_gender VARCHAR(50),
f_birthday TIMESTAMP(0) WITHOUT TIME ZONE,
f_mobile_phone VARCHAR(20),
f_tele_phone VARCHAR(20),
f_landline VARCHAR(50),
f_email VARCHAR(50),
f_nation VARCHAR(50),
f_native_place VARCHAR(50),
f_entry_date TIMESTAMP(0) WITHOUT TIME ZONE,
f_certificates_type VARCHAR(50),
f_certificates_number VARCHAR(50),
f_education VARCHAR(50),
f_urgent_contacts VARCHAR(50),
f_urgent_tele_phone VARCHAR(50),
f_postal_address VARCHAR(500),
f_signature VARCHAR(500),
f_password VARCHAR(50),
f_secretkey VARCHAR(50),
f_first_log_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_first_log_ip VARCHAR(50),
f_prev_log_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_prev_log_ip VARCHAR(50),
f_last_log_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_log_ip VARCHAR(50),
f_log_success_count INTEGER,
f_log_error_count INTEGER,
f_change_password_date TIMESTAMP(0) WITHOUT TIME ZONE,
f_language VARCHAR(50),
f_theme VARCHAR(50),
f_is_administrator INTEGER,
f_manager_id VARCHAR(50),
f_organize_id VARCHAR(50),
f_position_id VARCHAR(50),
f_role_id TEXT,
f_portal_id TEXT,
f_lock_mark INTEGER,
f_unlock_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_group_id VARCHAR(50),
f_handover_mark INTEGER,
f_app_system_id VARCHAR(50),
f_description VARCHAR(500),
f_enabled_mark INTEGER,
f_sort_code BIGINT,
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_creator_user_id VARCHAR(50),
f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_modify_user_id VARCHAR(50),
f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_user_id VARCHAR(50),
f_delete_mark INTEGER,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
f_handover_userid VARCHAR(100),
f_rank VARCHAR(50),
f_standing VARCHAR(50),
f_app_standing VARCHAR(50),
PRIMARY KEY (f_id, f_tenant_id)
);
-- ===== base_user_relation ===== (source lines 4707-4722)
CREATE TABLE base_user_relation (
f_id VARCHAR(50) NOT NULL,
f_user_id VARCHAR(50),
f_object_type VARCHAR(50),
f_object_id VARCHAR(50),
f_sort_code BIGINT,
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_creator_user_id VARCHAR(50),
f_last_modify_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_last_modify_user_id VARCHAR(50),
f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_user_id VARCHAR(50),
f_delete_mark INTEGER,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
PRIMARY KEY (f_id, f_tenant_id)
);