From 0aed12a1023fdf669af05be147ca1026eb241bbb Mon Sep 17 00:00:00 2001 From: admin Date: Sun, 25 Oct 2026 17:05:00 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A5=91=E7=BA=A6=E8=A7=84=E6=A0=BC=20?= =?UTF-8?q?+=20=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92=20+=20=E5=AE=98?= =?UTF-8?q?=E6=96=B9=20base=5F*=20DDL=20=E5=8E=9F=E6=96=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/contract.md: 唯一规格来源(信封/cipher/端点/权限/种子/验收门) - docs/ddl/base_ddl_raw.sql: 从官方 JNPF dump 逐字提取的 7 张 base_* DDL - CLAUDE.md / HANDOFF.md: 项目级 agent 指引与交接文档 Co-Authored-By: Claude --- .gitignore | 23 ++ CLAUDE.md | 260 +++++++++++++++ HANDOFF.md | 360 +++++++++++++++++++++ docs/contract.md | 655 ++++++++++++++++++++++++++++++++++++++ docs/ddl/base_ddl_raw.sql | 206 ++++++++++++ 5 files changed, 1504 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 HANDOFF.md create mode 100644 docs/contract.md create mode 100644 docs/ddl/base_ddl_raw.sql diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2a4ab85 --- /dev/null +++ b/.gitignore @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3d3449a --- /dev/null +++ b/CLAUDE.md @@ -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>>`)。同时**一个数据目录只能被一个进程打开** + ⇒ 集成测试要么串行、要么各自用独立数据目录。 +7. **查询结果序列化**:沿用 `tdc-rs` 的手法 + `SELECT row_to_json(q)::text AS _row FROM () 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` 是"还缺什么状态" ⇒ `with_state` 必须是**链条最后一步**。 +11. **`Form` 在 axum 0.8.9 只实现 `FromRequest`**(没有 `OptionalFromRequest`) + ⇒ `Option>` **编译不过** ⇒ 需要"解析失败也走业务信封"的表单端点, + 取**原始 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>` 编译不过 | 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/<子系统>/.md`(本文件表格即其索引)。 +- **工作日志** → `.workbuddy/memory/YYYY-MM-DD.md`。 +- **本文件只留**「原则 + 决定 + 一句话摘要」。改代码后回头核对本文件是否还成立。 diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..5a721e0 --- /dev/null +++ b/HANDOFF.md @@ -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,全部绿了才算完成。 diff --git a/docs/contract.md b/docs/contract.md new file mode 100644 index 0000000..45ebd7f --- /dev/null +++ b/docs/contract.md @@ -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; +/// 失败: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` 兜底)。 diff --git a/docs/ddl/base_ddl_raw.sql b/docs/ddl/base_ddl_raw.sql new file mode 100644 index 0000000..acdf31b --- /dev/null +++ b/docs/ddl/base_ddl_raw.sql @@ -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) +); +