Files
ssw-jnpf-lite-rust/docs/runbook.md
T
adminandClaude Code 8b24bb1aea refactor(name): 项目正式名称统一为 ssw-jnpf-lite-rust
**影响**:仓库/目录/二进制/契约里的项目标识全部换成 `ssw-jnpf-lite-rust`,
旧名 `tds-lite-rs`(曾误写 `tdc-lite-rs`)不再出现在任何代码、脚本或文档里。

**改动**
- Cargo:`package`/`[[bin]]` → `ssw-jnpf-lite-rust`,`[lib]` → `ssw_jnpf_lite_rust`;
  `Cargo.lock` 随之重生成
- 运行期:`jnpf.rs` 的 `SYSTEM_ID`/`SYSTEM_CODE` → `ssw-jnpf-lite-rust`
  (面 B 响应的 `currentSystemId`/`systemCode`/菜单 `systemId` 兜底值随之变化);
  `main.rs` 的 `--help`/`--enc`/启动与停止日志文案
- 脚本:`run.sh` 二进制路径与 `pkill` 模式(**保留旧名兜底 pkill**,收掉改名前起的老进程);
  `perm-smoke.sh`/`perm-smoke-jnpf.sh` 的 `ENC_BIN` 默认路径、`App-Code` 头、提示文案;
  `check-module.sh`;`.env.example`
- 文档:`CLAUDE.md`/`README.md`/`HANDOFF.md`/`docs/*.md` 全文;
  `HANDOFF.md` §1 第 5 条决策改为「正式名称,2026-10-26 改定」,原方案 `tds-lite-rs` 标为已推翻

**验收**:`cargo build --release` 0 error 0 warning · `cargo test` 195 passed / 0 failed ·
面 A 冒烟 PASS=32 FAIL=0 · 面 B 冒烟 PASS=18 FAIL=0 SKIP=0 · 静态自检 PASS=57 FAIL=0 ·
`--enc 123456` 输出与上游检验向量逐字一致

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 12:36:06 +08:00

257 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# runbook —— ssw-jnpf-lite-rust 怎么起、怎么冒烟、坏了怎么办
> 契约见 [`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/ssw-jnpf-lite-rust
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` 加密后提交)
—— 登录后的 **token 寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**);
响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**。
- 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/` `.logs/` 目录 —— 目录只在真正要写日志/PID 的分支里建)。
🔴 **端口是本仓硬约定**:后端固定 **30010**、前端固定 **5173**。
守卫**只对 `dev` / `backend` 生效**(这两个子命令真的会起后端,后端会继承 `PORT` 并真的绑那个端口):
`PORT` 被设成别的值 ⇒ `run.sh dev` / `run.sh backend` **明确报错并退出 2**
(不会去清别的端口、也不会打印错的 URL)。
其它子命令(`--help` / 无参 / `logs` / `install` / `build` / `stop` / `frontend`)**不碰端口**
⇒ **完全不受 `PORT` 影响**(环境里恰好有个 `PORT` 不会让它们失败)。
要用别的端口请直接跑二进制:`PORT=xxxx ./target/release/ssw-jnpf-lite-rust`。
🔴 **后端默认只监听 `127.0.0.1`**(`BIND_ADDR` 可覆盖)—— 本仓的种子口令是 `admin/123456`、
token 永不过期 ⇒ 默认不监听所有网卡;要在容器 / 反代里对外暴露才设 `BIND_ADDR=0.0.0.0`。
🔴 **`run.sh` 的 `kill_ports` 是 `kill -9`** ⇒ 它只会清 **30010** 和 **5173** 两个端口。
**兄弟项目 `tdc-rs` 的端口不在列表里**(打死它就是破坏兄弟项目)。
🔴 **`dev` 会等后端与前端都真的就绪**(后端轮询 `/api/health`,最长 30 秒;前端轮询 vite 根路径,最长 60 秒)
⇒ 任一没真正起来(数据库路径写错 / 依赖没装 / 端口被占 / `npm run dev` 立刻报错退出)时,
**脚本退出码 1** 并打印对应日志尾部(后端失败 ⇒ `.logs/backend.log`;前端失败 ⇒ `.logs/frontend.log`),
**不会**「报成功但其实没有服务」。
此时**本次刚起的前端进程会被一并收掉**(**PID 文件 SIGTERM → SIGKILL** + **按端口 `kill -9` 兜底**)⇒
**不会在 5173 上留残进程**(`stop_pid` 依赖 npm 把 SIGTERM 转发给 vite —— 那是 npm 的内部实现细节、
不是保证 ⇒ 必须有 `kill_ports` 兜底)。
🔴 前端没就绪时**不收后端**(后端可能只是慢;下一次 `dev` / `stop` 的 `kill_ports 30010` 会自愈),
脚本会明确提示「后端仍在 30010 上运行,要停请执行 `./run.sh stop`」。
🔴 **`stop` 的实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ `kill_ports`(按端口 `kill -9`)**;
`pkill` 只是最后兜底,且模式收窄到**后端本体的完整路径**
(macOS/BSD 的 `pkill -f` 匹配**完整命令行**,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉)。
vite 由 `kill_ports 5173` 按**端口**收 ⇒ 不会误杀别的项目的 vite dev server。
🔴 **后端收到 SIGTERM / SIGINT 会优雅关闭**嵌入式 PostgreSQL(先收完在途请求,再正常关库)
⇒ 不再被 SIGKILL 打断(以前每次停机都是 SIGKILL 掉嵌入式 PG ⇒ 下次启动要 crash recovery、
数据目录里还留 `postmaster.pid`);`./run.sh stop` 的 1 秒宽限期对优雅停机足够(实测 < 200ms)。
> ℹ️ 停机瞬间 `.logs/backend.log` 里可能出现**几十行**
> `FATAL: terminating connection because protocol synchronization was lost` ——
> 那是 **pglite-rs 0.2.7 的收尾噪音**(PG 收到 Terminate 后 postmaster 反复拉起后端),
> **无害**:PG 本身是干净关库的(`postmaster.pid` 会被清掉)。
> 后端会在 PG 干净关库后**立刻**退出(日志尾行 `ssw-jnpf-lite-rust 已停止(嵌入式 PostgreSQL 已优雅关闭)。`)。
🔴 **`backend` 子命令用 `exec`** ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是 1)。
---
## 3. 环境变量(`.env`)
`run.sh` 会把仓库根的 `.env` 导出给子进程(`set -a; . .env; set +a`)。样例见 `.env.example`。
| 变量 | 默认 | 说明 |
|---|---|---|
| `PORT` | `30010` | 后端监听端口(**非法值回落 30010**) |
| `BIND_ADDR` | `127.0.0.1` | 后端监听地址 —— 🔴 **默认只监听本机**;要在容器 / 反代里对外暴露才设 `0.0.0.0`(只接受**字面 IP**,主机名会被判非法 ⇒ 回落 127.0.0.1) |
| `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 面 B 冒烟(官方 JNPF 形状,18 条断言)
```bash
bash run.sh dev # 后端得先起来
bash scripts/perm-smoke-jnpf.sh # 期望:PASS=18 FAIL=0 SKIP=0,退出码 0
B=http://127.0.0.1:30010 bash scripts/perm-smoke-jnpf.sh
```
退出码:**0** 全绿 / **1** 有断言失败或未全覆盖 / **2** 前置错误(后端不可达等)。
🔴 **它打的是面 B**(官方 JNPF 形状)⇒ 请求必须带判别头 **`Vue-Version: 3`**(脚本自带)。
断言覆盖:面 A 未受影响 · 两面登录 · 面 B `CurrentUser` 5 字段 · `menuList` 节点 15 字段 ·
`permissionList` 是数组 · 未登录 `602` · 未知路由仍 `404` · 用户/角色列表是 `PageListVO` ·
列表项无 `password`/`secretkey` 且 `isAdministrator` 是**数字** · `ModuleBySystem` 返 `ListVO` ·
授权写(官方完整 body)真落库 · 授权读是 **POST**。
### 4.3 业务模块 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 '<div id="root">'
curl --noproxy '*' -s http://127.0.0.1:5173/api/health
# => {"ok":true,"tables":10,"version":"0.1.0"} ← 说明 vite 代理把 /api 转到了 30010
```
---
## 6. 常见故障
### 6.1 本机特有
| 症状 | 根因 | 处理 |
|---|---|---|
| `curl http://127.0.0.1:5173` 连不上 / 502 | 本机 curl 走**系统代理** | 加 `--noproxy '*'` |
| `localhost:5173` 连不上 | macOS 上 vite 默认只 bind `::1` | 用 `127.0.0.1:5173`(`vite.config.ts` 已强制 IPv4) |
| 起后台进程后工具一返回就没了 | `nohup … &` 会被回收 | 用 Bash 工具的 `run_in_background`;stdout **不要**指向 `/dev/null`(进程会以 100 退出) |
| vite 报端口被占 | `strictPort: true`(故意不自动换端口) | `lsof -ti:5173` 看清是谁;或 `bash run.sh stop` |
| `npm install` 卡在 esbuild | npm 11 的 `allowScripts` 闸门 | `npm --prefix src/frontend install-scripts approve esbuild && npm --prefix src/frontend install` |
| 第二个后端实例起不来 | **pglite 单实例独占数据目录** | 换 `PGLITE_DIR` 或换端口 |
### 6.2 契约层(与 `CLAUDE.md` 的踩坑清单一一对应)
| 症状 | 根因 | 处理 |
|---|---|---|
| 登录必失败(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)必须一字不差 |
| 405 返回 HTML / 丢 `Allow` 头 | 用了 axum 的 `method_not_allowed_fallback` | 用响应改写中间件(链尾) |
| DDL 能从 HTTP 下载 | DDL 落在 web root | 移到 `db/` + 兜底守卫 |
---
## 7. 数据重置
库是**嵌入式 pglite 数据目录**(默认 `src/backend/data/lite.pg`),**没有独立的 PG 服务**。
```bash
bash run.sh stop
mv src/backend/data src/backend/data.bak-$(date +%s) # 改名备份(可恢复),下次启动重建空库
bash run.sh dev # 空库 ⇒ 重新种子(admin/123456)
```
🔴 **schema 只在首次建表时执行** ⇒ 改了 `src/backend/db/schema.sql` 之后**必须**走这一步,否则改动不生效。
---
## 8. 边界(别越界)
- `tdc-rs` 兄弟项目:**不共享**代码 / 端口 / 数据目录。`run.sh` 的 `kill_ports` 只清 30010 与 5173。
- `~/Desktop/workspace/skills/ssw-jnpf-lite-react/`(参照物):**只读**。本仓 `src/frontend/` 是它的逐字复制,
唯一改动是 `vite.config.ts` 的代理端口**改成 30010**(连注释行一起改);
`src/api/request.ts` 的**陈旧端口注释**(写的仍是旧端口号)与 `:31` 的 axios **30 秒超时**
(`timeout` 毫秒数,**不是**端口)**刻意逐字节不动**。
`vite.config.ts:11` 的注释里仍写着「NestJS 后端」(本仓是 Rust)—— 同样**刻意逐字保留**,只记档。
- `src/backend/**`、`docs/contract.md`、`scripts/perm-smoke.sh`:**已定稿**,改动需走评审。
- **前端 Dashboard 只渲染「目录的子项」**(`node.children`)⇒ `Demo 示例` / `产品管理` / `图书超市`
是**顶层页面型菜单**(`parent_id='0'`、无子项)⇒ **Dashboard 里没有它们的按钮**,
只能按 URL 直达(`/demo-item`、`/shop/Product`、`/books/Book`)。
这是**参照物原样行为**且与契约 §8.4 一致 ⇒ **不改**,只记档。
- `/favicon.ico` 在 vite dev server 上返 **404**(`index.html` 没有 favicon 引用)⇒ 浏览器 console 两条 404;无害。