- 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/:前端接口清单、页面依赖反查、运行时探针
421 lines
25 KiB
Markdown
421 lines
25 KiB
Markdown
# 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;无害。
|