# runbook —— tds-lite-rs 怎么起、怎么冒烟、坏了怎么办 > 契约见 [`contract.md`](contract.md);红线与坑位清单见 [`../CLAUDE.md`](../CLAUDE.md)。 --- ## 0. 前置 | 工具 | 版本(本机实测) | 用途 | |---|---|---| | Rust | ≥ 1.85(edition 2021;本机实测 rustc 1.95.0) | 后端 | | Node / npm | node v26.8.1 · npm 11.19.0 | 前端(vite 5) | | jq | 1.7.1(`/usr/bin/jq`) | 冒烟脚本的 JSON 取值(无则 python3 兜底) | | python3 | 3.14.5 | 冒烟脚本的 JSON 取值兜底 | 🔴 **后端与 `scripts/perm-smoke.sh` 零 node 依赖** —— 冒烟脚本用后端自己的 `--enc` 子命令自证 cipher。 前端用 npm/vite 是它本来的工具链,允许。 --- ## 1. 第一次上手 ```bash cd ~/Desktop/workspace/tdc-lite-rs bash run.sh install # cargo fetch + npm --prefix src/frontend install bash run.sh build # cargo build --release + vite build(产出 src/frontend/dist) ``` `install` 用的是 `npm install`(**可能更新 `package-lock.json`**)。想严格按 lock 装、不碰 lock,用: ```bash npm --prefix src/frontend ci ``` > ⚠️ 本机 npm 11 会打印 `install-scripts 2 packages have install scripts not yet covered by allowScripts` > (`esbuild` / `fsevents`)。**不影响构建** —— vite 用的二进制来自平台包 `@esbuild/darwin-*`。 > 万一 vite 报「esbuild binary not found」,再执行: > `npm --prefix src/frontend install-scripts approve esbuild && npm --prefix src/frontend install`。 --- ## 2. 日常启动 ```bash bash run.sh dev # 后台起后端(30010) + 前端(5173) bash run.sh logs # 看 .logs/backend.log + .logs/frontend.log 尾部 bash run.sh stop # 停(幂等:无进程时也不报错,退出码 0) ``` - 前端:**http://127.0.0.1:5173** - 后端:**http://127.0.0.1:30010** - 账号:**`admin` / `123456`**(首次启动自动种;密码用浏览器侧 `utils/cipher.ts` 加密后提交) - PID 在 `.run/{backend,frontend}.pid`,日志在 `.logs/{backend,frontend}.log`(两者都在 `.gitignore` 里) 单起一半: ```bash bash run.sh backend # 前台跑后端(Ctrl-C 停) bash run.sh frontend # 前台跑 vite ``` `run.sh` 退出码:**0** 成功 / **1** 运行期失败 / **2** 用法错(无参、未知子命令)。 `bash run.sh --help` 打印用法并退出 **0**。 🔴 **`run.sh` 的 `kill_ports` 是 `kill -9`** ⇒ 它只会清 **30010** 和 **5173** 两个端口。 **兄弟项目 `tdc-rs` 的端口不在列表里**(打死它就是破坏兄弟项目)。 --- ## 3. 环境变量(`.env`) `run.sh` 会把仓库根的 `.env` 导出给子进程(`set -a; . .env; set +a`)。样例见 `.env.example`。 | 变量 | 默认 | 说明 | |---|---|---| | `PORT` | `30010` | 后端监听端口 | | `PGLITE_DIR` | `<项目根>/src/backend/data/lite.pg` | 数据目录(**绝对路径**,与 cwd 无关) | 🔴 **`PGLITE_DIR` 只能写绝对路径**。`config.rs` 对它是**原样使用** ⇒ 相对路径会相对**当前工作目录**解析 ⇒ 换个 cwd 就换一份库,而且**静默**。要临时库就写 `PGLITE_DIR=memory://` (pglite-rs 0.2.7 没有真内存模式,走的是系统临时目录里的一次性数据目录,进程退出即销毁)。 --- ## 4. 冒烟与自检 ### 4.1 权限闭环冒烟(32 条断言) ```bash bash run.sh dev # 后端得先起来 bash scripts/perm-smoke.sh # 期望:PASS=32 FAIL=0,退出码 0 B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh # 打别的地址 JQ_BIN="" bash scripts/perm-smoke.sh # 强制走 python3 兜底路径(两条路径判据一致) ``` 退出码:**0** 全绿 / **1** 有断言失败 / **2** 前置错误(后端不可达、缺 jq+python3、缺 `--enc` 二进制)。 断言覆盖:未登录 `600` → 加密登录 → 菜单树分组 → 建用户 → 重复账号 `400`(不是 500)→ 一维/二维授权写入 → 非管理员菜单收窄 → `403` → 未知路由 `404` → 管理员短路 → Product/Book 往返(36 位 UUID、numeric 是 JSON 字符串 `"9.90"`、int 是 JSON 数字 `100`)。 ### 4.2 业务模块 9 接触点静态自检 ```bash bash scripts/check-module.sh # 无参 ⇒ 检查全部三个业务模块 bash scripts/check-module.sh books Book # 只查一个 ``` **纯静态**:不启动后端、不发请求、不依赖 node。 每个 `appCode/Entity` 查 9 个接触点(后端路由注册 · spec 定义 · 实体表 · 守卫 `module_key` · 前端 api 文件 · 前端页面 · 前端路由 · 菜单种子 · **授权 key 三处一字不差**), 外加两条契约红线(`f_` 前缀 + `f_id VARCHAR(50)` 主键 · 软删契约)。 退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错(未知参数、app_code/Entity 不在本仓已知清单)。 > 🔴 demo 模块**没有** `api/demoitem.ts`(`views/DemoItem.tsx` 直接 `request.get('/ssw/demo/DemoItem/List')`) > ⇒ 这一条走「view 直连」分支;两种都查不到才算 ❌。 --- ## 5. 前端手验清单(验收门④) ```bash bash run.sh dev ``` 浏览器打开 **http://127.0.0.1:5173**: 1. `admin` / `123456` 登录 ⇒ 进 Dashboard; 2. 菜单树正确:系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市; 3. 5 个管理页可增删改(用户 / 角色 / 机构 / 菜单 / 授权); 4. 3 个业务页可用(DemoItem / Product / Book); 5. 退出再登录 ⇒ 仍正常。 **代理自检**(不开浏览器也能验): ```bash curl --noproxy '*' -s http://127.0.0.1:5173/ | grep '