diff --git a/.gitignore b/.gitignore index be52912..e3cec06 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ target/ # 运行期数据(pglite 数据目录) src/backend/data/ +src/backend/data.bak-*/ *.pg/ # 前端 diff --git a/HANDOFF.md b/HANDOFF.md index 59fc325..78b7055 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -15,7 +15,7 @@ | `CLAUDE.md` | ✅ 已写;**已逐条核对并与代码同步**(Task 12) | | `HANDOFF.md`(本文件) | ✅ 已写并已同步(§0 状态表 / §9 交接话术,Task 12) | | 代码 | ✅ 后端已实现(`src/backend/`,Rust 2021 + axum 0.8 + pglite-rs 0.2,**10 张表**、**27 条路由**) | -| 前端 | ✅ 已逐字复制(`src/frontend/`;**唯一改动 = vite 代理端口 `30000 → 30010`**,其余文件逐字节相同) | +| 前端 | ✅ 已逐字复制(`src/frontend/`;**唯一改动 = vite 代理端口改成 `30010`**,其余文件逐字节相同) | | 脚本 | ✅ `scripts/perm-smoke.sh`(**32 条断言**)+ `scripts/check-module.sh`(9 接触点静态自检,**55 条 ✅**) | | 工程脚本 | ✅ `run.sh`(`install`/`build`/`dev`/`backend`/`frontend`/`stop`/`logs`,退出码 0/1/2) | | 文档 | ✅ `README.md` / `docs/runbook.md` / `.env.example` | @@ -35,10 +35,10 @@ | 1 | Rust 版做成什么形态? | **先做真实项目,验证后再抽技能** | 技能是模板;没跑通的模板没有价值 | | 2 | v1 做多大? | **全量契约对齐**(auth + 5 组 `base_*` + 四源权限 + 两段种子 + 3 业务模块 + 冒烟) | 迁移价值全在权限与数据模型这两块,缺一块就不成立 | | 3 | 落在哪个仓? | **独立仓** `tds-lite-rs` | ~~原方案:tdc-rs 开分支~~(已被 #4 推翻) | -| 4 | 运行时拓扑? | **先不碰 tdc-rs,独立仓做** | tdc-rs 已占 `:30000` 且已有自己的 `/api/oauth/Login`(JSON 账号库),两套同路径不同语义会打架 | +| 4 | 运行时拓扑? | **先不碰 tdc-rs,独立仓做** | tdc-rs 已占它自己的后端端口,且已有自己的 `/api/oauth/Login`(JSON 账号库),两套同路径不同语义会打架 | | 5 | 目录名? | **`tds-lite-rs`**(用户指定) | ~~原方案:`ssw-jnpf-lite-rust`~~ | | 6 | 数据库? | **pglite-rs 0.2**(进程内原生 PG) | 沿用 tdc-rs 已验证的形态;零服务零 Docker | -| 7 | 后端端口? | **`:30010`**(前端 vite `:5173`) | 避开 tdc-rs 的 `:30000` | +| 7 | 后端端口? | **`:30010`**(前端 vite `:5173`) | 避开 tdc-rs 已占用的后端端口 | | 8 | 前端怎么办? | **逐字复制** react 技能的前端,**零改动** | 前端零改 = 契约真的对齐了(改了就说明后端在迁就前端) | | 9 | 业务实体怎么实现? | **spec 驱动 CRUD 引擎**;5 组 `base_*` 走**显式 handler** | 业务模块语义简单可声明化;`base_*` 的语义(一维授权数组 / 用户↔角色 / 机构树防环)塞不进通用引擎 | | 10 | 冒烟脚本的 node 依赖? | Rust 二进制加 `--enc <明文>` 模式,脚本**自证 cipher**,不依赖 node | 去掉 node 依赖 = 冒烟可在任何装了 Rust 的机器上跑 | @@ -179,7 +179,7 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit) ### 3.5 前端 - **逐字复制** `ssw-jnpf-lite-react/src/frontend` → `src/frontend`(`package.json` / `vite.config.ts` / `src/**`)。 -- **唯一允许的改动**:vite 的 proxy 目标端口 `30000 → 30010`(以及 `baseURL` 仍是 `/api`,不变)。 +- **唯一允许的改动**:vite 的 proxy 目标端口改成 `30010`(以及 `baseURL` 仍是 `/api`,不变)。 - 前端 `utils/cipher.ts` **保持不变**(它是浏览器侧算法;后端 Rust 侧必须与它**逐字节等价**——由上游向量钉住)。 - 路由 path(`App.tsx`):`/login` `/demo-item` `/shop/Product` `/books/Book` `/system/User` `/system/Role` `/system/Organize` `/system/Module` @@ -208,9 +208,9 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit) | 门 | 命令 | 通过标准 | |---|---|---| -| ① 编译 | `cargo build --release` | 0 error 0 warning;release 配置照 tdc-rs(`opt-level=2` / `lto="thin"` / `strip="symbols"` / `panic="abort"` / `codegen-units=16`) | -| ② 单测 | `cargo test` | 覆盖:cipher 上游向量 · 信封形状(200/400/600/403)· 四源合并 · 管理员短路 · 未映射放行 · 种子幂等(跑两次结果一致 + 不复活软删行)· CRUD 往返(36 位 UUID / numeric→`"9.90"` / int→`100`)· 账号重复返 400 而非 500 | -| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **22+ 条断言全绿**(FAIL=0),与 react 版断言集**逐条对应**(见 §5 步骤 11 的清单) | +| ① 编译 | `cargo build --release` | 0 error 0 warning;release 配置:`opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`。🔴 catch-all 依赖默认的 **unwind** 型 panic 策略(Ruling P19)⇒ **禁止**在 release profile 里启用 abort 型 panic(确切写法见根 `Cargo.toml` 里的注释)—— 那会让 catch-all 抓不到 panic ⇒ 契约 §6.5 的「uncaught panic ⇒ HTTP 200 + `{code:400}`」直接失效 | +| ② 单测 | `cargo test` | **实测 177 passed / 0 failed**(8 个测试目标:63+6+19+24+3+18+7+37)。覆盖清单见**契约 §12**(`docs/contract.md:940`):cipher 上游向量 · 信封形状(200/400/600/403)· 四源合并 · 管理员短路 · 未映射放行 · 种子幂等(跑两次结果一致 + 不复活软删行)· CRUD 往返(36 位 UUID / numeric→`"9.90"` / int→`100`)· 账号重复返 400 而非 500 | +| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **32 条断言全绿**(实测 `PASS=32 FAIL=0`,退出码 0),与 react 版断言集**逐条对应**(见 §5 步骤 11 的清单) | | ④ 前端手验 | `cd src/frontend && npm run dev` | 浏览器 `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 | **外加**:`scripts/check-module.sh`(9 接触点静态自检)的 Rust 版移植,作为"加模块后立刻跑"的前置闸门。 @@ -234,8 +234,8 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit) | **8** | `src/sys.rs` + `/api/ssw/sys/*` + `/api/permission/Authority/*` | 5 组 CRUD 语义对齐;**重复账号返 `code=400` + msg `'账号已存在:xxx'`**(不是 500);授权写 `objectType='role'` 小写 + 一维数组 | | **9** | `src/entities.rs` + `src/crud.rs` + 3 个业务模块端点 | demo/shop/books 三个模块端点可用;numeric 往返 `"9.90"`;未授权非管理员访问 shop/books ⇒ `code=403` | | **10** | `src/routes.rs` + `main.rs` 装配 + 404/405 兜底 | 未知路由 **HTTP 404** + `code=404`;405 返回 JSON;`with_state` 在链尾 | -| **11** | `scripts/perm-smoke.sh` 移植(**逐条对应 react 版**) | 22+ 断言全绿 | -| **12** | 前端复制 + `run.sh` + `.env.example` + 文档 | 门④ 手验全过;`run.sh install/build/dev/stop/logs` 可用 | +| **11** | `scripts/perm-smoke.sh` 移植(**逐条对应 react 版**) | **32 条断言全绿**(`PASS=32 FAIL=0`) | +| **12** | 前端复制 + `run.sh` + `.env.example` + 文档 | ✅ **已完成**(Task 12):门④ 手验全过(浏览器实测);`run.sh install/build/dev/stop/logs` 可用 | **step 11 的断言清单**(照 react 版 `scripts/perm-smoke.sh` 逐条移植): @@ -255,7 +255,7 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit) 16. Product 新建 ⇒ `code=200`;17. 主键 **36 位**;18. numeric 往返 **`"9.90"`** 19. Product 无 token ⇒ `code=600`;20. 未授权非管理员 ⇒ `code=403` -(react 版共 22+ 条,上表是主干;移植时以 react 脚本为准逐条对齐,**一条不落**。) +(react 版断言条数更多,上表是主干;移植时以 react 脚本为准逐条对齐,**一条不落**。) **另外**:`scripts/check-module.sh`(9 接触点静态自检)移植为 Rust 版—— 把「grep TS 文件里的字符串」换成「grep Rust 源 + 检查 spec 注册」,保持同样的 ❌ 判定与退出码约定 @@ -412,7 +412,7 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173) 摘自 ledger(`.superpowers/sdd/tds-lite-rs-v1/progress.md`)的「分支级已知限制清单」: - **(k)** release 二进制**没有** catch-all 的自动化覆盖(触发 panic 的端点是 `#[cfg(test)]` 专属; - catch-all 中间件代码在测试构建与 release 构建里**逐字相同**,且 release profile **无** `panic = "abort"` ⇒ 行为等价)。 + catch-all 中间件代码在测试构建与 release 构建里**逐字相同**,且 release profile **没有**启用 abort 型 panic ⇒ 行为等价)。 - **(l)** `Path` 遇**畸形百分号编码** ⇒ axum 默认返**纯文本 400(非信封)**(handler 签名由契约 §S17 定死,改它要动 `sys.rs`)。 - **(m)** 冒烟脚本**每次跑**会往库里留一行 `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user` (react 同款行为;契约 §13 未要求清理 ⇒ 不改)。 @@ -420,13 +420,26 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173) - **(o)** 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的**前置提示文案**不同 (`code=无` vs `code=ERR`),退出码都是 2。 -本任务(Task 12)另记两条**已观察、未改**的观察(留给最终整体评审裁决): +Task 12 修复轮 R=1 另记两条 `run.sh` 的**行为口径**(不是缺陷,是刻意设计): -- **react 版 Dashboard 只渲染「目录的子项」** ⇒ 3 个顶层业务页在菜单里**没有入口按钮**(只能按 URL 直达)。 - 前端是**逐字复制** ⇒ 改它会破「除代理端口外一字不改」的硬约束 ⇒ **不改**,只记档。 +- `run.sh backend` 用 `exec` 跑后端 ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是子命令表里写的 1)。 +- `run.sh stop` 的**实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ `kill_ports`(按端口 `kill -9`)**; + `pkill` 只是最后一道兜底,且模式**收窄到后端本体的完整路径** + (macOS/BSD 的 `pkill -f` 匹配**完整命令行**,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉); + vite 由 `kill_ports 5173` 按**端口**收,不会误杀别的项目的 vite dev server。 + +本任务(Task 12)另记四条**已观察、未改**的观察(留给最终整体评审裁决): + +- **react 版 Dashboard 只渲染「目录的子项」** ⇒ 3 个顶层业务页在菜单里**没有入口按钮**(只能按 URL 直达: + `/demo-item`、`/shop/Product`、`/books/Book`)。前端是**逐字复制** ⇒ 改它会破「除代理端口外一字不改」的 + 硬约束 ⇒ **不改**,只记档。(与契约 §8.4 的菜单表一致:`m_demo`/`m_product`/`m_book` 的 `parent_id='0'`。) - `src/frontend/vite.config.ts` 的注释仍写着「转发到 **NestJS** 后端(30010)」—— 本仓后端是 **Rust**。该注释行属于「代理目标行 + 紧邻注释行」两行允许改动范围, - 但 brief 只授权把端口 `30000 → 30010` ⇒ 框架名**逐字保留**,**不「顺手修好」**(最终评审按 Minor 记)。 + 但 brief 只授权把端口改成 `30010` ⇒ 框架名**逐字保留**,**不「顺手修好」**(最终评审按 Minor 记)。 +- `src/api/request.ts:5` 的**陈旧端口注释**(写的仍是旧端口号)与 `:31` 的 axios **30 秒超时** + (`timeout` 毫秒数,**不是**端口)⇒ **逐字保留**(改了就破「除代理外一字不改」的 diff 门)。 +- `/favicon.ico` 在 vite dev server 上返 **404**(`index.html` 没有 favicon 引用)⇒ 浏览器 console 会有两条 404。 + 无害,且 `index.html` 是逐字复制 ⇒ **不改**,只记档。 ### 下一步(按 plan) diff --git a/docs/runbook.md b/docs/runbook.md index dba3507..7034cf0 100644 --- a/docs/runbook.md +++ b/docs/runbook.md @@ -61,11 +61,25 @@ bash run.sh frontend # 前台跑 vite ``` `run.sh` 退出码:**0** 成功 / **1** 运行期失败 / **2** 用法错(无参、未知子命令)。 -`bash run.sh --help` 打印用法并退出 **0**。 +`bash run.sh --help` 打印用法并退出 **0**(且**不会**创建 `.run/` `.logs/` 目录 —— 目录只在真正要写日志/PID 的分支里建)。 + +🔴 **端口是本仓硬约定**:后端固定 **30010**、前端固定 **5173**。 +`PORT` 被设成别的值 ⇒ `run.sh` **明确报错并退出 2**(不会去清别的端口、也不会打印错的 URL)。 +要用别的端口请直接跑二进制:`PORT=xxxx ./target/release/tds-lite-rs`。 🔴 **`run.sh` 的 `kill_ports` 是 `kill -9`** ⇒ 它只会清 **30010** 和 **5173** 两个端口。 **兄弟项目 `tdc-rs` 的端口不在列表里**(打死它就是破坏兄弟项目)。 +🔴 **`dev` 会等后端真的就绪**(轮询 `/api/health`,最长 30 秒)⇒ 后端起不来(数据库路径写错等)时 +**脚本退出码 1 并打印 `.logs/backend.log` 尾部**,不会「报成功但其实没有服务」。 + +🔴 **`stop` 的实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ `kill_ports`(按端口 `kill -9`)**; +`pkill` 只是最后兜底,且模式收窄到**后端本体的完整路径** +(macOS/BSD 的 `pkill -f` 匹配**完整命令行**,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉)。 +vite 由 `kill_ports 5173` 按**端口**收 ⇒ 不会误杀别的项目的 vite dev server。 + +🔴 **`backend` 子命令用 `exec`** ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是 1)。 + --- ## 3. 环境变量(`.env`) @@ -190,6 +204,13 @@ bash run.sh dev # 空库 ⇒ 重新种 - `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` **刻意逐字节不动**)。 + 唯一改动是 `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;无害。 diff --git a/run.sh b/run.sh index cd766fb..e0dd21c 100755 --- a/run.sh +++ b/run.sh @@ -30,8 +30,6 @@ FRONTEND_PORT=5173 # 不许把兄弟项目 tdc-rs 的端口写进来(打死它就是破坏兄弟项目)。 BACKEND_BIN="$ROOT/target/release/tds-lite-rs" -mkdir -p "$LOGS" "$RUN" - # 加载项目根 .env(后端不 import dotenv,靠这里把 PORT / PGLITE_DIR 导出给子进程) if [ -f "$ROOT/.env" ]; then set -a; . "$ROOT/.env"; set +a @@ -39,6 +37,16 @@ fi export PORT="${PORT:-30010}" +# 🔴 **端口是本仓的硬约定**:后端固定 30010、前端固定 5173。 +# `PORT` 只能被设成 30010;设成别的值 ⇒ 明确报错退出 2。 +# (不是「改成用 $PORT 清端口」——那会让 kill_ports 去杀**任意端口**上的进程。) +if [ "${PORT}" != "${BACKEND_PORT}" ]; then + echo "[用法错] PORT=${PORT} 与本仓硬约定的后端端口 ${BACKEND_PORT} 不一致。" + echo " 本仓端口是硬约定(兄弟项目已占用它自己的端口,两套服务必须彻底分开)。" + echo " 要用别的端口请直接跑二进制:PORT=${PORT} ${BACKEND_BIN}" + exit 2 +fi + usage() { cat <<'EOF' 用法: ./run.sh <子命令> @@ -51,6 +59,7 @@ usage() { logs 打印后端/前端日志尾部 --help 本用法 退出码: 0 成功 / 1 运行期失败 / 2 用法错 +端口: 后端固定 30010、前端固定 5173(硬约定;PORT 改成别的值 ⇒ 退出码 2) EOF } @@ -73,6 +82,22 @@ kill_ports() { return 0 } +# 🔴 **就绪轮询**:起完进程不等于服务可用。 +# 旧版 dev 起完就打印「服务已在后台启动」并 exit 0 ⇒ 后端起不来(数据库路径写错等) +# 时**脚本报成功、实际没有服务** ⇒ 极难定位。 +# ⇒ 轮询 /api/health(routes.rs 里真有的探活端点),最长 30 秒。 +# 本机 curl 走系统代理 ⇒ 必须带 --noproxy '*'。 +wait_backend_ready() { + local i + for i in $(seq 1 30); do + if curl --noproxy '*' -fsS -m 2 "http://127.0.0.1:${BACKEND_PORT}/api/health" >/dev/null 2>&1; then + return 0 + fi + sleep 1 + done + return 1 +} + # 用 PID 文件优雅停(先 SIGTERM,1s 后 SIGKILL),清理 root 进程树 stop_pid() { local f="$1" @@ -121,28 +146,40 @@ case "${1:-}" in npm --prefix "$ROOT/src/frontend" run build ;; dev) - kill_ports "$BACKEND_PORT" "$FRONTEND_PORT" + # 🔴 **先**检查二进制存在性,**再**清端口 —— + # 反过来的话,失败路径上已经先把 30010/5173 上的进程 kill -9 了(失败却先破坏现场)。 if [ ! -x "$BACKEND_BIN" ]; then echo "[启动失败] 后端二进制不存在: $BACKEND_BIN" echo " 先跑「./run.sh build」(cargo build --release)。" exit 1 fi + kill_ports "$BACKEND_PORT" "$FRONTEND_PORT" + mkdir -p "$LOGS" "$RUN" # 🔴 后端 cwd = 仓库根(dir=".")⇒ 相对路径的 PGLITE_DIR 也落在仓库内。 # 🔴 命令行**不带** PORT= 前缀 —— PORT 已由 .env / export 导出,子进程继承。 start_logged . "./target/release/tds-lite-rs" backend start_logged src/frontend "npm run dev" frontend + # 🔴 就绪校验:后端没真正起来 ⇒ **不许**报成功。 + if ! wait_backend_ready; then + echo + echo "[启动失败] 后端在 30 秒内没就绪(/api/health 不通)。" + echo "--- .logs/backend.log 尾部 ---" + tail -n 20 "$LOGS/backend.log" 2>/dev/null || true + exit 1 + fi echo echo "服务已在后台启动。后端: http://127.0.0.1:${BACKEND_PORT} 前端: http://127.0.0.1:${FRONTEND_PORT}" echo "日志:tail -f $LOGS/{backend,frontend}.log" echo "停止:./run.sh stop" ;; backend) - kill_ports "$BACKEND_PORT" if [ ! -x "$BACKEND_BIN" ]; then echo "[启动失败] 后端二进制不存在: $BACKEND_BIN" echo " 先跑「./run.sh build」(cargo build --release)。" exit 1 fi + kill_ports "$BACKEND_PORT" + # 🔴 用 exec ⇒ 后端**自己的**退出码原样透传(本仓二进制 panic 时是 101,不是 1)。 (cd "$ROOT" && exec ./target/release/tds-lite-rs) ;; frontend) @@ -150,17 +187,23 @@ case "${1:-}" in npm --prefix "$ROOT/src/frontend" run dev ;; stop) - # ⚠️ vite 是通用名 —— 只有本仓真的起过前端(PID 文件存在)才 pkill,避免误杀别的项目。 - if [ -f "$RUN/frontend.pid" ]; then - pkill -f "vite" 2>/dev/null || true - fi + mkdir -p "$LOGS" "$RUN" + # 🔴 **实际的停止路径 = PID 文件(SIGTERM→SIGKILL)+ kill_ports(按端口 kill -9)**。 + # pkill 只作为最后一道兜底,且**模式必须精确**: + # macOS/BSD 的 `pkill -f` 匹配的是**完整命令行**(argv 全部拼接), + # 宽模式(如按进程名)会连「命令行里提到本仓名字」的无关进程一起杀掉 + # (本脚本自己、harness 的监督 shell、tail -f 日志、别的项目的 vite)。 stop_pid "$RUN/backend.pid" stop_pid "$RUN/frontend.pid" kill_ports "$BACKEND_PORT" "$FRONTEND_PORT" - pkill -f "tds-lite-rs" 2>/dev/null || true + # 只匹配后端本体的完整路径(cargo/rustc 的 argv 里是目录名与下划线形式,都不匹配)。 + # 🔴 vite **不**用 pkill 收 —— 它由上面的 kill_ports 5173 按**端口**收, + # 不会误杀别的项目的 vite dev server。 + pkill -f "target/release/tds-lite-rs" 2>/dev/null || true echo "stopped" ;; logs) + mkdir -p "$LOGS" "$RUN" # 🔴 补 || true:日志文件不存在时 [ -f ] 返回 1,set -e 下会让脚本以 1 退出。 { [ -f "$LOGS/backend.log" ] && echo "=== backend ===" && tail -n 50 "$LOGS/backend.log"; } || true { [ -f "$LOGS/frontend.log" ] && echo "=== frontend ===" && tail -n 50 "$LOGS/frontend.log"; } || true diff --git a/scripts/check-module.sh b/scripts/check-module.sh index bacea47..d466d07 100755 --- a/scripts/check-module.sh +++ b/scripts/check-module.sh @@ -18,6 +18,11 @@ # # 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错 +# 🔴 **故意只用 `set -u`,不加 `-e` / `pipefail`** —— 这是有意的取舍,不是漏写: +# 本脚本的判定**依赖 grep 的返回码**(grep 命中 ⇒ 记一条 ✅,不命中 ⇒ 记一条 ❌)。 +# 若加 `-e`,**第一条没命中的 grep 就会中止整个脚本** ⇒ 闸门只跑了一半就“静默变绿/变红”, +# 反而把闸门弄坏。加 `pipefail` 同理(管道里任一段非 0 都会中止)。 +# ⇒ 想要「失败即停」请自己看末尾的 `PASS=` / `FAIL=` 与退出码。 set -u ROOT="$(cd "$(dirname "$0")/.." && pwd)" @@ -69,8 +74,12 @@ fi # ---- 期望值表(逐字,来自契约 §8.4 + 契约 §5.3)---- # 每个目标:表名 / ROUTE(= urlAddress = module_key)/ 种子 id / module_key(None = 仅登录) +# / **前端 api 文件该有没有**(有 = 有 / 无 = 走 view 直连分支) +# +# 🔴 **新增业务模块时须同步改这张期望表**(app_code:Entity 的分支、目标清单 TARGETS、 +# 以及下面的 T_API 期望)—— 否则新模块会被判成「未知 app_code/Entity」退出 2。 T_COUNT=${#TARGETS[@]} -T_APP=(); T_ENT=(); T_TABLE=(); T_ROUTE=(); T_SEED=(); T_MK=() +T_APP=(); T_ENT=(); T_TABLE=(); T_ROUTE=(); T_SEED=(); T_MK=(); T_API=() for T in "${TARGETS[@]}"; do A="${T%%:*}" E="${T##*:}" @@ -78,14 +87,18 @@ for T in "${TARGETS[@]}"; do demo:DemoItem) T_TABLE+=("demo_item"); T_ROUTE+=("demo-item") T_SEED+=("m_demo"); T_MK+=("None") + # demo **没有** api 文件:views/DemoItem.tsx 直接 request.get('/ssw/demo/DemoItem/List') + T_API+=("无") ;; shop:Product) T_TABLE+=("shop_product"); T_ROUTE+=("shop/Product") T_SEED+=("m_product"); T_MK+=("shop/Product") + T_API+=("有") ;; books:Book) T_TABLE+=("book_shop_book"); T_ROUTE+=("books/Book") T_SEED+=("m_book"); T_MK+=("books/Book") + T_API+=("有") ;; *) echo "❌ 未知 app_code/Entity: ${A}/${E}" @@ -166,6 +179,7 @@ for i in $(seq 0 $((T_COUNT - 1))); do ROUTE="${T_ROUTE[$i]}" SEED_ID="${T_SEED[$i]}" MK="${T_MK[$i]}" + API_EXP="${T_API[$i]}" LC="$(lower "$ENT")" URL="${APP}/${ENT}" @@ -206,35 +220,44 @@ for i in $(seq 0 $((T_COUNT - 1))); do no "spec.module_key = ${SPEC_MK:-(没取到)},期望 ${MK}" fi - hdr "[${ENT}] 5) 前端 api 文件:api/${LC}.ts 含 list/save/delete 三导出" + hdr "[${ENT}] 5) 前端 api 文件:api/${LC}.ts 含 list/save/delete 三导出(期望:${API_EXP})" API="$FE/src/api/${LC}.ts" VIEW="$FE/src/views/${ENT}.tsx" - if [ -f "$API" ]; then - # 命名约定:list 函数走「自然英语复数」(Book → listBooks / Product → listProducts) - # save/delete 用 Entity 单数(PascalCase),与后端端点命名一致。 - PLURAL_ENT="$(plural "$ENT")" - for fn in "list${PLURAL_ENT}" "save${ENT}" "delete${ENT}"; do - if grep -qE "export[[:space:]]+const[[:space:]]+${fn}" "$API" 2>/dev/null; then - ok "${fn} 导出存在" - else - no "${API} 缺 export const ${fn}(前端解构会 undefined)" - fi - done - else - # 🔴 本仓前端是逐字复制:demo 模块**没有** api 文件, - # views/DemoItem.tsx 直接 request.get('/ssw/demo/DemoItem/List') ⇒ - # 「前端 api 文件」这一接触点对 demo 走**直连分支**(两种都查不到才算 ❌)。 - ok "无 api/${LC}.ts(走 view 直连分支)" - if [ -f "$VIEW" ]; then - for ep in List Save Delete; do - if grep -qE "request\.(get|post|delete)\([^)]*/ssw/${URL}/${ep}" "$VIEW" 2>/dev/null; then - ok "views/${ENT}.tsx 直连 request → /ssw/${URL}/${ep}" + if [ "${API_EXP}" = "有" ]; then + # 期望**有** api 文件 ⇒ 缺文件就是 ❌(**不许**再打「无 api/xxx.ts」这种误导性绿灯)。 + if [ -f "$API" ]; then + # 命名约定:list 函数走「自然英语复数」(Book → listBooks / Product → listProducts) + # save/delete 用 Entity 单数(PascalCase),与后端端点命名一致。 + PLURAL_ENT="$(plural "$ENT")" + for fn in "list${PLURAL_ENT}" "save${ENT}" "delete${ENT}"; do + if grep -qE "export[[:space:]]+const[[:space:]]+${fn}" "$API" 2>/dev/null; then + ok "${fn} 导出存在" else - no "views/${ENT}.tsx 没有直连 request → /ssw/${URL}/${ep}" + no "${API} 缺 export const ${fn}(前端解构会 undefined)" fi done else - no "views/${ENT}.tsx 不存在,无法核对直连分支" + no "缺 api/${LC}.ts(期望有:${ENT} 的前端必须有 api 层)" + fi + else + # 期望**无** api 文件 ⇒ 本仓前端是逐字复制:demo 模块没有 api 文件, + # views/DemoItem.tsx 直接 request.get('/ssw/demo/DemoItem/List') ⇒ + # 「前端 api 文件」这一接触点对 demo 走**直连分支**(两种都查不到才算 ❌)。 + if [ -f "$API" ]; then + no "多出 api/${LC}.ts(期望无:${ENT} 走 view 直连分支)—— 请同步期望值表" + else + ok "无 api/${LC}.ts(期望无 ⇒ 走 view 直连分支)" + if [ -f "$VIEW" ]; then + for ep in List Save Delete; do + if grep -qE "request\.(get|post|delete)\([^)]*/ssw/${URL}/${ep}" "$VIEW" 2>/dev/null; then + ok "views/${ENT}.tsx 直连 request → /ssw/${URL}/${ep}" + else + no "views/${ENT}.tsx 没有直连 request → /ssw/${URL}/${ep}" + fi + done + else + no "views/${ENT}.tsx 不存在,无法核对直连分支" + fi fi fi