Files
ssw-platform/docs/runbook.md
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

421 lines
25 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-platform
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 无关) |
| `SSW_PROFILE` | `dev` | 部署档位 —— `dev` = 一律不判弱口令;`prod` = 六条弱口令判据生效,违规**拒绝启动** |
| `SEED_ADMIN_PASSWORD` | `123456` | 首启 admin 的**种子口令**(明文)—— **只在空库首启时生效** |
🔴 **`PGLITE_DIR` 只能写绝对路径**。`config.rs` 对它是**原样使用** ⇒ 相对路径会相对**当前工作目录**解析
⇒ 换个 cwd 就换一份库,而且**静默**。要临时库就写 `PGLITE_DIR=memory://`
(pglite-rs 0.2.7 没有真内存模式,走的是系统临时目录里的一次性数据目录,进程退出即销毁)。
---
## 4. 冒烟与自检
### 4.1 权限闭环冒烟(32 条断言)
```bash
bash scripts/perm-smoke.sh # 期望:PASS=32 FAIL=0,退出码 0(**后端不用先起**,见 4.1.1)
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.1.1 尺子自起隔离后端(**默认行为**)
两把契约尺子(`perm-smoke.sh` / `perm-smoke-jnpf.sh`)**默认自己把后端起起来**(助手在
`scripts/smoke_backend.sh`,被两把尺子 `source`)。口径:
| 情况 | 行为 |
|---|---|
| **没给 `B`** + `:30010` **通** | 就用它(保留「跑开发中的后端」这个习惯) |
| **没给 `B`** + `:30010` **不通** | **自起隔离实例**:空闲端口 + `mktemp -d` 临时数据目录 ⇒ 打印「ℹ️ 已自起隔离后端:…」 |
| **显式给了 `B`** + 不可达 | **不自起**(尊重外部后端)⇒ 前置错误,**退出码 2** |
为什么:不自起的话 ① 两把尺子**互相踩**(面 A 改了库里的角色/菜单 ⇒ 面 B 的前置状态被污染);
② 跑完**留脏数据**在 `src/backend/data/lite.pg`;③ **CI 里没法跑**(没人替你起后端)。
⇒ 自起时库里的痕迹**随临时目录一起消失** ⇒ 断言可重复、两把尺子互不污染。
🔴 隔离实例的 `PGLITE_DIR` 是**临时目录下的绝对路径**(契约:只接受绝对路径或 `memory://`),
进程退出即销毁;退出时尺子先 `TERM` 后端(等 6s 再兜底 `KILL`)再删临时目录。
### 4.2 面 B 冒烟(官方 JNPF 形状,18 条断言)
```bash
bash scripts/perm-smoke-jnpf.sh # 期望:PASS=18 FAIL=0 SKIP=0,退出码 0(**后端不用先起**,见 4.1.1)
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 业务模块 10 接触点静态自检
```bash
bash scripts/check-module.sh # 无参 ⇒ 检查契约登记的全部业务模块(期望 PASS=93)
bash scripts/check-module.sh books Book # 只查一个
```
**纯静态**:不启动后端、不发请求、不依赖 node。
每个 `appCode/Entity` 查 10 个接触点(后端路由注册 · spec 定义 · 实体表 · 守卫 `module_key` ·
前端 api 文件 · 前端页面 · 前端路由 · **菜单声明**(`*_MENU: MenuSpec`,与契约 `[MENU]` 逐字对齐)·
**菜单登记**(`modules/mod.rs` 的 `ALL_MENUS`)· **三处一字不差**),
外加两条契约红线(`f_` 前缀 + `f_id VARCHAR(50)` 主键 · 软删契约)。
🔴 **期望值不在脚本里** —— 全部从 `docs/contract.md` **附录 A**(机器可读)读
(`scripts/contract_expect.py` 解析):菜单表 / 业务模块清单 / 各尺子的断言条数。
⇒ 改契约只改一处;代码漂移立刻报。
🔴 **尺子自证**:脚本结尾会比对「本尺子实际跑了多少条断言」与「契约登记的条数」,
对不上 ⇒ **失败**(防止有人删掉断言把尺子改弱)。
退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错(未知参数、app_code/Entity 不在契约清单)。
> 🔴 demo 模块**没有** `api/demoitem.ts`(`views/DemoItem.tsx` 直接 `request.get('/ssw/demo/DemoItem/List')`)
> ⇒ 这一条走「view 直连」分支;两种都查不到才算 ❌。
### 4.4 分层红线静态自检(平台层 / 业务层不许互相渗透)
```bash
bash scripts/check-boundary.sh # 期望:PASS=11 FAIL=0,退出码 0
```
**纯静态**(只需要 `python3`,macOS 自带)。把 `CLAUDE.md` 红线 12
(「加一个业务模块只碰业务层」)变成可执行的尺子:
| 判据 | 内容 |
|---|---|
| **CP1'** | 扫描器**反自证** —— 造一个明知存在的泄漏,必须被抓到(永远返回「干净」的尺子 = 没有尺子) |
| **CP1** | 平台层**零业务标识符**(业务表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code)—— 只扫**字符串字面量**(注释里的举例允许);禁止清单**从业务层自己派生** ⇒ 加模块时这把尺子自动变严 |
| **CP2** | 平台层**不反向依赖**业务层(`platform/**` 不许 `use crate::modules`) |
| **CP3** | 业务层**不直接调**平台层的种子(接线只在装配根 `bootstrap.rs`) |
| **CP4** | 每个业务模块必须声明 `*_MENU: MenuSpec` ⇒ 且被 `modules/mod.rs` 的 `ALL_MENUS` 收编 ⇒ 且声明的菜单 id 与**契约** `[MODULE]` 一致 |
| **CP5** | `platform::seed::ensure_base` 的调用点**只有** `bootstrap.rs`(应用与测试走同一条路 ⇒ 测到的库 == 上线的库) |
| **CP6** | 平台层自带菜单的**条数**(= 契约菜单数 − 业务模块数)与**id 列表**都与契约逐条一致(业务菜单不许混进 `platform/seed.rs`) |
退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错(缺 `python3`)。
🔴 **期望值不在脚本里** —— 菜单数、业务模块数都从 `docs/contract.md` **附录 A** 读
⇒ 加一个业务模块只需在契约里加两行,本脚本的期望值自动跟着变。
🔴 **尺子自证**:结尾比对「实际跑了多少条断言」与「契约登记的条数」,对不上 ⇒ 失败。
### 4.5 契约端点表 ↔ 代码真实路由 对账(静态闸门 3)
```bash
bash scripts/check-contract.sh # 期望:PASS=10 FAIL=0,退出码 0
```
**纯静态**(只需要 `python3`)。把 `docs/contract.md` **附录 A 的 `[ENDPOINT]`**
(机器可读的端点表:face / method / path / guard / owner,一行一条,共 32 行)
与**代码里真实注册的路由**逐条对账 —— **双向**:
| 判据 | 内容 |
|---|---|
| **CC2** | 端点**总数**一致(契约 N 条 == 代码 N 条) |
| **CC3** | 契约 → 代码:每条端点在代码里存在且**方法**一致 |
| **CC4** | 代码 → 契约:代码里没有契约未登记的端点 |
| **CC5** | **归属层**一致(`platform` / 业务模块代号 `demo|shop|books`) |
| **CC6** | **守卫**一致(面A 菜单 key / 面B 点权限编码 / 登录 / 无)—— **静态推导** |
| **CC7** | 钉子测试的字面量清单(`REGISTERED` / `JNPF_REGISTERED`)与平台层路由**双向覆盖** |
| **CC8** | 业务路由**三处**一致(各模块 `ROUTES` 常量 / `router()` 注册 / `ALL_ROUTES`) |
| **CC9** | 契约面计数**自洽**(`[FACE]` 登记的条数 == `[ENDPOINT]` 里各 face 的实际条数) |
| **CC10** | **官方端点台账**(`[OFFICIAL]`)↔ 代码真实路由**双向**:说 `implemented/partial` 的必须真的注册了,说 `absent/oos` 的必须**没有**注册;反向:**面 B / 共用**的每条路由都必须在台账上有账 |
| **CC1'** | **反自证** —— 注入 9 种已知漂移,必须**每一种**都被抓到 |
退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错或前置错误(契约读不出来)。
#### 官方端点覆盖 N/M(CC10 的副产物)
尺子会打印一行进度(**不计入** PASS/FAIL):
```
📊 CC10-COVER:官方端点覆盖 8/47(implemented 3 / partial 5 / absent 39;oos 6 单列,不进分母)
```
N = `implemented` + `partial`(**已落地**的官方端点数);
M = 再加 `absent`(**在范围内**的官方端点总数,官方 JNPF 后台最小可用面这一条线);
`oos`(v1 明确不做:导入导出族、数据权限链接)**单列**,不进分母。
状态词表见 `docs/contract.md` 附录 A `[OFFICIAL]` 的表头注释;
`partial` 的**具体偏差**逐条记在 `JNPF_COMPAT_SURFACE.md` §8 的 B1–B10。
🔴 台账的 `src` 列是官方出处 `文件:行号` ⇒ 由**引文闸门**(`check-citations.sh`)逐条核对
⇒ 台账里的官方出处**不是抄来的**,是**验过的**。
🔴 **守卫对账是静态推导**(`require_module(&state,&headers,CONST)` ⇒ 菜单 key;
`guard(&state,&headers,EN_X)` ⇒ 点权限编码)⇒ 改守卫写法会让扫描器**推不出来**
(报 ⚠️ WARN,**不**判失败,但要人工核对)。
🔴 **尺子自证**:结尾比对「实际跑了多少条断言」与「契约登记的条数」,对不上 ⇒ 失败。
🔴 **改端点要改两处**:契约 §6 的散文表 **+** 附录 A 的 `[ENDPOINT]`。
### 4.6 文档引文(`路径:行号`)核对(静态闸门 4)
```bash
bash scripts/check-citations.sh # 期望:PASS=4 FAIL=0,退出码 0
bash scripts/check-citations.sh --list # 顺带打印每条引文明细
```
**纯静态**(只需要 `python3`)。本仓的文档大量引用源码位置,行号是**会漂移**的:
源码改一行 ⇒ 上游行号整体位移 ⇒ 文档里的引用**静默指向别的行**——不报错,只是悄悄说错话。
本闸门把每条引文**解析到真实文件**并核对行号:
| 判据 | 内容 |
|---|---|
| **CIT1** | 引文**可解析**:每条 `路径:行号` 都能定位到真实文件(当前 141 条) |
| **CIT2** | 引文**行号有效**:行号区间落在该文件的行数范围内(`N` / `N-M` / `N/M` / `N+` 四种写法) |
| **CIT3** | **DDL 行号表**对账:`CLAUDE.md` 里写的建表行号 ↔ 官方 DDL 那一行真的有 `CREATE TABLE <表名>`(7 张 `base_*` 表) |
| **CIT1'** | **反自证** —— 注入 3 类坏引用(行号越界 / 文件不存在 / DDL 行号错位),必须**每一种**都被抓到 |
**解析口径**(三级,先精确后模糊):① `<根>/<路径>` 精确命中 ⇒ ② 相对路径**后缀**命中
(`db/schema.sql` ⇒ `src/backend/db/schema.sql`)⇒ ③ **基名**命中(官方源码文档里
`ActionResult.java:27` 这种写法)。参照根共 4 处:本仓 / 官方 JNPF 源码
(`~/Desktop/workspace/jnpf`)/ react 姊妹技能 / cargo registry(引文指到依赖源码时,如
`pglite-rs 0.2.7` 的 `src/db.rs:444`)。
退出码:**0** 全过 / **1** 有 ❌ / **2** 用法错或前置错误。
🔴 **外部参照根缺失 ⇒ 判「跳过」不判失败**(官方源码 / react 技能 / cargo registry 都不在本机时,
本闸门只校验本仓内的引文,条数照旧、状态记 ⏭)。
🔴 **「无路径的续行行号」(`:NNN`)只报不判失败** —— 那是本仓表格的约定(先写文件名、
下面只写行号),且**相邻两行可能指不同文件** ⇒ 机械继承会大量误报。
本闸门用「上文 40 行内点名的文件里**任意一个**行数够」这种**弱判据**核对,
对不上才报「疑似漂移」。
🔴 **尺子自证**:结尾比对「实际跑了多少条断言」与「契约登记的条数」,对不上 ⇒ 失败。
### 4.7 macOS SysV 信号量回收(`cargo test` 跑多了会攒)
```bash
bash scripts/reap-ipc-leaks.sh # 扫 + 回收本仓的孤儿信号量集
bash scripts/reap-ipc-leaks.sh --dry-run # 只扫不删
```
🔴 **为什么需要**:pglite 的 `initdb` 会 `semget` 一个 `nsems=20` 的信号量集,
而 macOS(XNU)**不回收**进程退出时留下的信号量集(Linux 有 `ipcrm`,macOS 没有)⇒
`cargo test` 跑久了会攒到几千个 ⇒ 撞上 `kern.sysv.semmns`(本机 87381)上限 ⇒
`semget` 失败 ⇒ 测试莫名其妙起不来。
脚本用 `nsems==20` 这个 **PGlite 指纹**定位(零业务内容),只回收**当前用户**的。
### 4.8 生产档弱密钥守卫
```bash
SSW_PROFILE=prod SEED_ADMIN_PASSWORD=123456 ./target/release/ssw-jnpf-lite-rust
# ⇒ [启动失败] 生产档弱密钥守卫未通过(SSW_PROFILE=prod):
# - SEED_ADMIN_PASSWORD:判据③:值等于已知弱值(123456)
# - SEED_ADMIN_PASSWORD:判据⑥:长度 6 < 12
# ⇒ 退出码 1
```
🔴 **六条判据**:① 键不在清单里 ⇒ 跳过 ② 空/空白 ③ 精确等于已知弱值
④ **含**已知弱值(反绕过,`123456x` 也拦)⑤ 命中弱标记词(**整体词**,`administrator` 不误伤)
⑥ 长度 < 12。
🔴 **两道检查**:配置级(本次用的种子口令)+ **库内级**(回读 `base_user` 的 admin 行)——
库内级是必须的:种子口令只对**空库**生效 ⇒ 生产库里那个可能是当初种下的 `123456`,
运维后来才设了 `SEED_ADMIN_PASSWORD` ⇒ 只查配置 = 守卫形同虚设。
🔴 **不做误伤**:管理员**合法改过**口令后,库里那个不再等于任何已知弱值 ⇒ 放行。
---
## 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;无害。