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]>
This commit is contained in:
adminandClaude Code committed 2026-10-26 03:26:22 +08:00
1 parent 8366a3745f
commit 8edcd3507d
31 files changed
+4536 -33

No files matched your search

+195
View File
@@ -0,0 +1,195 @@
# runbook —— tds-lite-rs 怎么起、怎么冒烟、坏了怎么办
> 契约见 [`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/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,用:
```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` 加密后提交)
- 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.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
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
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` 的代理端口 `30000 → 30010`(连注释行一起改;`src/api/request.ts` 的
注释与 axios 的 `timeout: 30000` **刻意逐字节不动**)。
- `src/backend/**`、`docs/contract.md`、`scripts/perm-smoke.sh`:**已定稿**,改动需走评审。