Files
ssw-jnpf-lite-rust/docs/runbook.md
T
adminandClaude Code 8edcd3507d feat: 前端逐字复制(仅代理端口改 30010)+ run.sh + check-module.sh + 文档
前端:从 ssw-jnpf-lite-react/src/frontend 逐字复制(package-lock.json 一并复制),
唯一改动 = vite.config.ts 的代理目标 30000 → 30010(含紧邻注释行的端口);
src/api/request.ts 的注释与 axios timeout: 30000 逐字节保留。

脚本:run.sh(install/build/dev/backend/frontend/stop/logs,退出码 0/1/2,
kill_ports 只清 30010 与 5173);scripts/check-module.sh(9 接触点静态自检,
纯静态零 node 依赖)。

文档:README.md、docs/runbook.md、.env.example;CLAUDE.md 逐条核对并与代码同步,
HANDOFF.md §0 状态表与 §9 交接话术改为交付态。

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 03:26:22 +08:00

9.0 KiB
Raw Blame History

runbook —— tds-lite-rs 怎么起、怎么冒烟、坏了怎么办

契约见 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/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,用:

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 加密后提交)
  • 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.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 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 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 run.sh dev

浏览器打开 http://127.0.0.1:5173:

  1. admin / 123456 登录 ⇒ 进 Dashboard;
  2. 菜单树正确:系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
  3. 5 个管理页可增删改(用户 / 角色 / 机构 / 菜单 / 授权);
  4. 3 个业务页可用(DemoItem / Product / Book);
  5. 退出再登录 ⇒ 仍正常。

代理自检(不开浏览器也能验):

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 的代理端口 30000 → 30010(连注释行一起改;src/api/request.ts 的 注释与 axios 的 timeout: 30000 刻意逐字节不动)。
  • src/backend/**、docs/contract.md、scripts/perm-smoke.sh:已定稿,改动需走评审。