diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..a38e3d6 --- /dev/null +++ b/.env.example @@ -0,0 +1,23 @@ +# tds-lite-rs 环境变量样例 +# +# 用法:cp .env.example .env 后按需修改;run.sh 会把 .env 里的变量导出给子进程。 +# 🔴 本文件里的每一项都必须是「**生效的**」值 —— 注释掉才是「不生效」。 + +# 后端监听端口(缺省 30010)。 +# 🔴 不许改成 30010 以外的端口:兄弟项目 tdc-rs 已经占了它自己的后端端口, +# 两套服务必须彻底分开(不共享端口 / 数据目录 / 代码)。 +PORT=30010 + +# pglite 数据目录。 +# +# 🔴 **留空** ⇒ 用后端的默认值 `<项目根>/src/backend/data/lite.pg` +# (**绝对路径**,由可执行文件向上定位项目根 ⇒ 与 cwd 无关)。 +# +# 🔴 **不要**在这里写一个**相对**的 PGLITE_DIR:config.rs 对 PGLITE_DIR 是**原样使用** +# (相对路径 ⇒ 相对**当前工作目录**解析)⇒ 换个 cwd 就换一份库,而且**静默**。 +# 真要覆盖,只能写**绝对路径**,例如: +# PGLITE_DIR=/Users/xxx/tds-lite-rs/src/backend/data/lite.pg +# +# 临时库(进程退出即销毁)—— pglite-rs 0.2.7 没有真内存模式, +# `memory://` 走的是 `PGlite::open_temp()`(系统临时目录里的一次性数据目录)。 +# PGLITE_DIR=memory:// diff --git a/.gitignore b/.gitignore index 2a4ab85..be52912 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ src/frontend/.vite/ # 运行期 PID / 日志 .run/ +.logs/ *.log # macOS diff --git a/CLAUDE.md b/CLAUDE.md index 3d3449a..2068625 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,7 +37,7 @@ v1 = **全量契约对齐**:登录 / `CurrentUser` / 5 组 `base_*` 管理 CRU |---|---|---| | 后端 | Rust 2021 + axum 0.8 + tokio | 单二进制 | | 数据库 | **`pglite-rs` 0.2**(进程内原生 PostgreSQL) | 零服务/零 Docker/零 WASM;数据落盘 `src/backend/data/lite.pg` | -| 前端 | **react 技能的前端产物,逐字复用**(React + Vite) | **零改前端**;vite 代理 `/api` → 后端 | +| 前端 | **react 技能的前端产物,逐字复用**(React + Vite) | **唯一改动 = vite 代理端口 `30000 → 30010`**;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 | | @@ -45,12 +45,19 @@ v1 = **全量契约对齐**:登录 / `CurrentUser` / 5 组 `base_*` 管理 CRU > 它把 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 # 本文件 / 交接文档 +├── README.md # 项目定位 / 启动方式 / 验收门 +├── run.sh # install / build / dev / backend / frontend / stop / logs +├── .env.example # PORT / PGLITE_DIR(后者只能写绝对路径或 memory://) +├── docs/ +│ ├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型 +│ ├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障 +│ └── ddl/ # 官方 DDL 摘录 ├── src/ │ ├── backend/ # Rust 后端(workspace 唯一成员,crate 名 tds-lite-rs) │ │ ├── Cargo.toml @@ -71,12 +78,11 @@ tds-lite-rs/ │ │ │ └── routes.rs # 路由装配 │ │ ├── db/schema.sql # 完整 DDL(base_* 7 张 + 3 业务表) │ │ └── data/ # 运行期数据(gitignore) -│ └── frontend/ # react 技能前端逐字复制(不改) +│ └── frontend/ # react 技能前端逐字复制(**只改** vite.config.ts 的代理端口 30000→30010) ├── scripts/ -│ ├── perm-smoke.sh # 权限闭环冒烟(22+ 断言) -│ └── check-module.sh # 业务模块 9 接触点静态自检 -├── run.sh # install / build / dev / stop / logs -└── .env.example +│ ├── perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖) +│ └── check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端) +└── .gitignore ``` ## 架构红线 @@ -184,8 +190,12 @@ tds-lite-rs/ ## 端点全表 +🔴 `src/backend/src/routes.rs` 里**逐条注册 27 条**路径(axum 0.8.9 用 matchit 0.8.4, +**不支持** `{a,b}` 这种「一段里多个参数」的写法 ⇒ 必须逐条注册)。 + | 方法 | 路径 | 守卫 | 说明 | |---|---|---|---| +| GET | `/api/health` | 无 | **非契约**探活 ⇒ `{ok, tables, version}`;永远有响应(查不到表也返 200) | | 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` | @@ -200,6 +210,7 @@ tds-lite-rs/ | GET/POST/DELETE | `/api/ssw/books/Book/{List,Save,Delete?id=}` | 登录 + 菜单 `books/Book` | | 其它:未知路由 → **HTTP 404** + `{code:404,msg:'接口不存在',data:null}`。 +(`routes.rs` 的「路由表钉子测试」用「错方法 ⇒ 405」逐条证明这 27 条都注册了。) ## 命令速查 @@ -209,13 +220,29 @@ cargo build # debug cargo build --release # 发布版(release profile 写在根 Cargo.toml) cargo test # 单测 +# 工程脚本(仓库根 run.sh;退出码 0 成功 / 1 运行期失败 / 2 用法错) +bash run.sh install # cargo fetch + npm --prefix src/frontend install +bash run.sh build # cargo build --release + vite build +bash run.sh dev # 后台起后端(30010) + 前端(5173),日志 .logs/、PID .run/ +bash run.sh backend # 前台起后端 +bash run.sh frontend # 前台起前端 +bash run.sh stop # 停后台进程(幂等) +bash run.sh logs # tail .logs/{backend,frontend}.log +bash run.sh # 无参 ⇒ 用法错 ⇒ 退出码 2 + # 运行(后端) PORT=30010 ./target/release/tds-lite-rs -PGLITE_DIR=memory:// PORT=30010 ./target/release/tds-lite-rs # 纯内存 +PGLITE_DIR=memory:// PORT=30010 ./target/release/tds-lite-rs # 临时库(系统临时目录的一次性数据目录,进程退出即销毁;pglite-rs 0.2.7 没有真内存模式) -# 冒烟 -bash scripts/perm-smoke.sh # 默认打 127.0.0.1:30010 +# 前端 +npm --prefix src/frontend install # 或 npm ci(严格按 package-lock.json 装) +npm --prefix src/frontend run build # 产出 src/frontend/dist +npm --prefix src/frontend run dev # http://127.0.0.1:5173(vite 代理 /api → 30010) + +# 冒烟 / 自检 +bash scripts/perm-smoke.sh # 默认打 127.0.0.1:30010(32 条断言) B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh +bash scripts/check-module.sh # 9 接触点静态自检(纯静态,不起后端) ./target/release/tds-lite-rs --enc 123456 # cipher 自证(免 node 依赖) ``` @@ -227,16 +254,16 @@ B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh | 症状 | 根因 | 处理 | |---|---|---| -| 登录必失败(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