- 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/:前端接口清单、页面依赖反查、运行时探针
25 KiB
runbook —— ssw-jnpf-lite-rust 怎么起、怎么冒烟、坏了怎么办
契约见
contract.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. 第一次上手
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,用:
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 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 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 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 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 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 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 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 |
| 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 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 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 生产档弱密钥守卫
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 run.sh dev
浏览器打开 http://127.0.0.1:5173:
admin/123456登录 ⇒ 进 Dashboard;- 菜单树正确:系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
- 5 个管理页可增删改(用户 / 角色 / 机构 / 菜单 / 授权);
- 3 个业务页可用(DemoItem / Product / Book);
- 退出再登录 ⇒ 仍正常。
代理自检(不开浏览器也能验):
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 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;无害。