Files
ssw-jnpf-lite-rust/scripts/check-module.sh
T
adminandClaude Code ab8833af28 refactor(backend): 平台层 / 业务层分离 —— 加业务模块只碰 modules/
后端从平铺(src/{config,db,cipher,…,entities}.rs)改两层,对齐 react 版的
common+auth+sys / demo+shop+books 与官方 JNPF 的 jnpf-common+jnpf-system / jnpf-admin。

- 平台层 src/platform/:契约实现(config·db·cipher·envelope·ids·session·state·
  auth·permission·seed·sys·jnpf·entity·crud)—— 加业务模块不动
- 业务层 src/modules/:mod.rs + demo/shop/books,各自带 spec + 3 条路由 + 自己的 router()
- routes.rs 变成「平台路由 + 一次 merge(modules::router())」,业务路由不再登记在平台层
- 业务路由清单也搬到业务层(modules::ALL_ROUTES),平台层钉子测试遍历它
  ⇒ 原来「每加一模块要改 routes.rs 路由表」的口子被堵死
- 清掉平台层最后一个业务知识泄漏:S22 的 f_creator_user_id 规则原在引擎里写死
  app_code == "demo",改为业务 spec 自己声明(EntitySpec.creator_fixed)
- check-module.sh 新增反向断言(平台层不得注册业务路由)+ 正向断言(业务层须登记)
  ⇒ 断言 57 → 69
- 文档同步(SKILL/CLAUDE/README/HANDOFF/PERMISSION/MIGRATION/HOWTO_MODULE/contract),
  新增红线「平台层不许出现业务表名 / app_code」;decisions.md 补 P81

验证:cargo build --release 0 error 0 warning · cargo test 197 passed / 0 failed ·
check-module.sh PASS=69 FAIL=0 · 面 A PASS=32 FAIL=0 · 面 B PASS=18 FAIL=0 SKIP=0

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

419 lines
16 KiB
Bash
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env bash
# ssw-jnpf-lite-rust 加业务模块的「接触点」静态自检(Rust 版)
#
# 目的:在跑 perm-smoke 之前,**快速发现漏改的文件或字符串不一致**——这类问题一旦漏掉,
# 表现是「菜单不显示」「页面 404」「权限静默放行」,非常难定位。
#
# 🔴 **纯静态**:不启动后端、不发一个请求、不依赖 node(契约明令:后端与冒烟脚本零 node 依赖)。
# ⇒ 用法里**没有** `--live`;传了未知参数 ⇒ 退出码 2(用法错)。
#
# 用法:
# bash scripts/check-module.sh # 无参 ⇒ 检查全部三个业务模块
# bash scripts/check-module.sh <appCode> <Entity> # 也可只查一个(如 books Book)
# bash scripts/check-module.sh --help # 本用法
#
# 例:
# bash scripts/check-module.sh # demo / shop / books 全查
# bash scripts/check-module.sh books Book # 单模块
#
# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错
# 🔴 **故意只用 `set -u`,不加 `-e` / `pipefail`** —— 这是有意的取舍,不是漏写:
# 本脚本的判定**依赖 grep 的返回码**(grep 命中 ⇒ 记一条 ✅,不命中 ⇒ 记一条 ❌)。
# 若加 `-e`,**第一条没命中的 grep 就会中止整个脚本** ⇒ 闸门只跑了一半就“静默变绿/变红”,
# 反而把闸门弄坏。加 `pipefail` 同理(管道里任一段非 0 都会中止)。
# ⇒ 想要「失败即停」请自己看末尾的 `PASS=` / `FAIL=` 与退出码。
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
BACKEND="$ROOT/src/backend"
MODULES_DIR="$BACKEND/src/modules"
MODULES_MOD="$MODULES_DIR/mod.rs"
ROUTES="$BACKEND/src/routes.rs"
SCHEMA="$BACKEND/db/schema.sql"
SEED="$BACKEND/src/platform/seed.rs"
CRUD="$BACKEND/src/platform/crud.rs"
FE="$ROOT/src/frontend"
usage() {
echo "用法: bash scripts/check-module.sh [<appCode> <Entity>...]"
echo " 无参 ⇒ 检查全部三个业务模块(demo / shop / books)"
echo "例: bash scripts/check-module.sh"
echo " bash scripts/check-module.sh books Book"
echo "退出码: 0 全过 / 1 有 ❌ 项 / 2 用法错"
}
if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
usage
exit 0
fi
# ---- 目标清单:appCode:Entity ----
TARGETS=()
if [ "$#" -eq 0 ]; then
TARGETS=("demo:DemoItem" "shop:Product" "books:Book")
else
APP_ARG="$1"
shift
if [ "$#" -eq 0 ]; then
echo "❌ 用法错:<appCode> 后面至少要跟一个 <Entity>"
usage
exit 2
fi
for ENT_ARG in "$@"; do
case "${ENT_ARG}" in
-*)
echo "❌ 未知参数: ${ENT_ARG}"
usage
exit 2
;;
esac
TARGETS+=("${APP_ARG}:${ENT_ARG}")
done
fi
# ---- 期望值表(逐字,来自契约 §8.4 + 契约 §5.3)----
# 每个目标:表名 / ROUTE(= urlAddress = module_key)/ 种子 id / module_key(None = 仅登录)
# / **前端 api 文件该有没有**(有 = 有 / 无 = 走 view 直连分支)
# / **业务模块文件**(`src/backend/src/modules/<app>.rs` —— spec + handler + 路由)
#
# 🔴 **新增业务模块时须同步改这张期望表**(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_API=(); T_FILE=()
for T in "${TARGETS[@]}"; do
A="${T%%:*}"
E="${T##*:}"
case "${A}:${E}" in
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+=("无")
T_FILE+=("demo.rs")
;;
shop:Product)
T_TABLE+=("shop_product"); T_ROUTE+=("shop/Product")
T_SEED+=("m_product"); T_MK+=("shop/Product")
T_API+=("有")
T_FILE+=("shop.rs")
;;
books:Book)
T_TABLE+=("book_shop_book"); T_ROUTE+=("books/Book")
T_SEED+=("m_book"); T_MK+=("books/Book")
T_API+=("有")
T_FILE+=("books.rs")
;;
*)
echo "❌ 未知 app_code/Entity: ${A}/${E}"
echo " 本仓已知: demo/DemoItem、shop/Product、books/Book"
exit 2
;;
esac
T_APP+=("${A}"); T_ENT+=("${E}")
done
PASS=0; FAIL=0
ok() { echo " ✅ $1"; PASS=$((PASS+1)); }
no() { echo " ❌ $1"; FAIL=$((FAIL+1)); }
hdr() { echo; echo "── $1 ──"; }
# 小写(兼容 bash 3.x,不用 ${var,,})
lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
# 自然英语复数(兼容 bash 3.x,不依赖 declare -A)
# Apply → Applies / Box → Boxes / Match → Matches / Buy → Buys(y 辅音前) / Boy → Boys
plural() {
case "$1" in
*s|*x|*ch|*sh) echo "${1}es" ;; # -s/-x/-ch/-sh 直接加 es
*ay|*ey|*oy|*uy) echo "${1}s" ;; # 单元音 + y → 保留 +s(Boy → Boys)
*y) echo "${1%y}ies" ;; # 辅音 + y → 去 y 加 ies
*) echo "${1}s" ;; # 默认 +s
esac
}
# 从业务模块文件里取该模块的 spec 常量名(如 DEMO_SPEC / PRODUCT_SPEC / BOOK_SPEC)
spec_const_of() {
awk '
/pub const [A-Z_]+_SPEC: EntitySpec/ {
n = $0; sub(/.*pub const /, "", n); sub(/: EntitySpec.*/, "", n); print n; exit
}
' "$1"
}
# 从业务模块文件里取某个 spec 的 table 字面量
spec_table_of() {
awk -v want="$1" '
/entity: "/ { e = $0; sub(/.*entity: "/, "", e); sub(/".*/, "", e) }
/table: "/ { t = $0; sub(/.*table: "/, "", t); sub(/".*/, "", t);
if (e == want) { print t; exit } }
' "$2"
}
# 从业务模块文件里取某个 spec 的 module_key(None 或 Some("x") 的 x)
spec_module_key_of() {
awk -v want="$1" '
/entity: "/ { e = $0; sub(/.*entity: "/, "", e); sub(/".*/, "", e) }
/module_key:/ {
m = $0; sub(/.*module_key:[[:space:]]*/, "", m); sub(/,[[:space:]]*$/, "", m)
if (e == want) {
if (m ~ /^Some\(/) { s = m; sub(/^Some\("/, "", s); sub(/"\)$/, "", s); print s }
else print "None"
exit
}
}
' "$2"
}
# 从 seed.rs 里取某个内置菜单 id 的 url_address
seed_url_of() {
awk -v want="$1" '
/id: "/ { cur = $0; sub(/.*id: "/, "", cur); sub(/".*/, "", cur) }
/url_address: "/ {
u = $0; sub(/.*url_address: "/, "", u); sub(/".*/, "", u)
if (cur == want) { print u; exit }
}
' "$SEED"
}
# 从 schema.sql 里取某张表的 CREATE TABLE 块
schema_block_of() {
awk -v t="$1" '
$0 ~ ("CREATE TABLE " t " \\(") { inb = 1 }
inb { print }
inb && /^\);/ { exit }
' "$SCHEMA"
}
for i in $(seq 0 $((T_COUNT - 1))); do
APP="${T_APP[$i]}"
ENT="${T_ENT[$i]}"
TABLE="${T_TABLE[$i]}"
ROUTE="${T_ROUTE[$i]}"
SEED_ID="${T_SEED[$i]}"
MK="${T_MK[$i]}"
API_EXP="${T_API[$i]}"
MODFILE="$MODULES_DIR/${T_FILE[$i]}"
MODNAME="${T_FILE[$i]%.rs}"
LC="$(lower "$ENT")"
URL="${APP}/${ENT}"
hdr "[${ENT}] 1) 后端路由注册:modules/${T_FILE[$i]} 含 /api/ssw/${URL}/{List|Save|Delete}"
if [ -f "$MODFILE" ]; then
ok "业务模块文件存在: src/backend/src/modules/${T_FILE[$i]}"
else
no "缺业务模块文件: src/backend/src/modules/${T_FILE[$i]}"
fi
for ep in List Save Delete; do
if grep -q "/api/ssw/${URL}/${ep}" "$MODFILE" 2>/dev/null; then
ok "modules/${T_FILE[$i]} 已注册 /api/ssw/${URL}/${ep}"
else
no "modules/${T_FILE[$i]} 缺 /api/ssw/${URL}/${ep} → 端点 404"
fi
done
# 🔴 **业务路由不许进平台层** —— 平台层只 merge 一次(`modules::router()`)。
# 只看**真正的注册调用**(`.route("…")`)—— routes.rs 的路由表钉子测试里
# 有一份**路径清单**(那是契约快照,不是注册)⇒ 不能拿它当判据。
if grep -qE "\.route\(\"/api/ssw/${URL}/" "$ROUTES" 2>/dev/null; then
no "routes.rs 里注册了业务路由 /api/ssw/${URL}/ ⇒ 平台层混进了业务知识"
else
ok "routes.rs 未注册业务路由(平台层只 merge modules::router())"
fi
# 🔴 **模块必须被业务层登记表收编** —— `modules/mod.rs` 的 `router()` 要 merge 它、
# `ALL_SPECS` 要收它的 spec(漏一处 ⇒ 端点 404 / 启动自检报错)。
if grep -q "${MODNAME}::router()" "$MODULES_MOD" 2>/dev/null; then
ok "modules/mod.rs 的 router() merge 了 ${MODNAME}::router()"
else
no "modules/mod.rs 的 router() 没 merge ${MODNAME}::router() ⇒ 端点 404"
fi
SPEC_CONST="$(spec_const_of "$MODFILE")"
if [ -n "${SPEC_CONST}" ] && grep -q "${SPEC_CONST}" "$MODULES_MOD" 2>/dev/null; then
ok "modules/mod.rs 的 ALL_SPECS 收了 ${SPEC_CONST}"
else
no "modules/mod.rs 的 ALL_SPECS 没收 ${SPEC_CONST:-(没取到 spec 常量)} ⇒ 启动白名单自检会失败"
fi
hdr "[${ENT}] 2) spec 定义:modules/${T_FILE[$i]} 含 entity: \"${ENT}\" + table: \"${TABLE}\""
if grep -q "entity: \"${ENT}\"" "$MODFILE" 2>/dev/null; then
ok "modules/${T_FILE[$i]} 含 entity: \"${ENT}\""
else
no "modules/${T_FILE[$i]} 缺 entity: \"${ENT}\"(spec 没登记这个实体)"
fi
SPEC_TABLE="$(spec_table_of "${ENT}" "$MODFILE")"
if [ "${SPEC_TABLE}" = "${TABLE}" ]; then
ok "spec.table = ${TABLE}"
else
no "spec.table = ${SPEC_TABLE:-(没取到)},期望 ${TABLE}"
fi
hdr "[${ENT}] 3) 实体表存在:schema.sql 含 CREATE TABLE ${TABLE}"
if grep -q "CREATE TABLE ${TABLE}" "$SCHEMA" 2>/dev/null; then
ok "schema.sql 有表 ${TABLE}"
else
no "schema.sql 缺表 ${TABLE} → 业务模块跑不起来"
fi
hdr "[${ENT}] 4) 守卫 module_key:modules/${T_FILE[$i]} 的 spec.module_key"
SPEC_MK="$(spec_module_key_of "${ENT}" "$MODFILE")"
if [ "${SPEC_MK}" = "${MK}" ]; then
ok "spec.module_key = ${MK}"
else
no "spec.module_key = ${SPEC_MK:-(没取到)},期望 ${MK}"
fi
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 [ "${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 "${API} 缺 export const ${fn}(前端解构会 undefined)"
fi
done
else
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
hdr "[${ENT}] 6) 前端页面:views/${ENT}.tsx 存在"
if [ -f "$VIEW" ]; then
ok "views/${ENT}.tsx"
else
no "缺文件: views/${ENT}.tsx"
fi
hdr "[${ENT}] 7) 前端路由:App.tsx 含 <Route path=\"/${ROUTE}\""
# JSX 常写成多行(<Route\n path=...>),BSD grep 不支持 -P 跨行匹配,
# 用 tr 把换行去掉再 grep 最稳。
if tr '\n' ' ' < "$FE/src/App.tsx" | grep -q "<Route[^>]*path=\"/${ROUTE}\"" 2>/dev/null; then
ok "Route path=\"/${ROUTE}\" 已注册"
else
no "App.tsx 缺 <Route path=\"/${ROUTE}\" → 路由 404"
fi
hdr "[${ENT}] 8) 菜单种子:platform/seed.rs 的内置菜单 ${SEED_ID} 的 url_address"
SEED_URL="$(seed_url_of "${SEED_ID}")"
if [ "${SEED_URL}" = "${ROUTE}" ]; then
ok "seed ${SEED_ID}.url_address = ${ROUTE}"
else
no "seed ${SEED_ID}.url_address = ${SEED_URL:-(没取到)},期望 ${ROUTE} → 菜单不显示"
fi
hdr "[${ENT}] 9) 三处一字不差:module_key == url_address == Route path(去前导斜杠)"
if [ "${MK}" = "None" ]; then
# 🔴 demo 是「仅登录」守卫 ⇒ **没有** module_key 这一侧 ⇒ 只比 url_address == Route path。
if [ "${SEED_URL}" = "${ROUTE}" ]; then
ok "url_address == Route path:${SEED_URL} == ${ROUTE}(demo 仅登录 ⇒ 跳过 module_key 侧)"
else
no "url_address=${SEED_URL:-无} / Route=${ROUTE} 不一致"
fi
elif [ "${SPEC_MK}" = "${SEED_URL}" ] && [ "${SEED_URL}" = "${ROUTE}" ]; then
ok "三处相等:${SPEC_MK} == ${SEED_URL} == ${ROUTE}"
else
no "三处不一致:module_key=${SPEC_MK:-无} / url_address=${SEED_URL:-无} / Route=${ROUTE}"
fi
hdr "[${ENT}] 实体列 f_ 前缀 + 主键 f_id VARCHAR(50)(契约红线 4)"
BLOCK="$(schema_block_of "${TABLE}")"
if [ -z "${BLOCK}" ]; then
no "schema.sql 里没解析出 ${TABLE} 的建表块"
else
COLS="$(printf '%s\n' "${BLOCK}" | sed -n 's/^ \([A-Za-z_][A-Za-z0-9_]*\).*/\1/p')"
if [ -z "${COLS}" ]; then
no "${TABLE} 的建表块里没解析出任何列"
else
BADCOLS=""
for c in ${COLS}; do
case "${c}" in
f_*) ;;
*) BADCOLS="${BADCOLS} ${c}" ;;
esac
done
if [ -n "${BADCOLS}" ]; then
no "列名不是 f_ 前缀:${BADCOLS}"
else
ok "全部列名都是 f_ 前缀($(printf '%s\n' "${COLS}" | wc -l | tr -d ' ') 列)"
fi
fi
if printf '%s\n' "${BLOCK}" | grep -q "f_id VARCHAR(50)"; then
ok "主键 f_id VARCHAR(50)(36 位 UUID 装得下)"
else
no "主键必须是 f_id VARCHAR(50)(不要写成 32,否则 36 位 UUID 装不下)"
fi
fi
hdr "[${ENT}] 软删契约:list 带 f_delete_mark = 0 + remove 走软删(不是物理 DELETE)"
if grep -q "WHERE f_delete_mark = 0" "$CRUD" 2>/dev/null; then
ok "list 查询带 f_delete_mark = 0"
else
no "list 查询缺 f_delete_mark = 0 → 软删数据会显示"
fi
if grep -q "SET f_delete_mark = 1" "$CRUD" 2>/dev/null; then
ok "remove 置 f_delete_mark = 1(软删)"
else
no "remove 没软删(应是 UPDATE f_delete_mark=1,非物理 DELETE)"
fi
done
# -------- 全局红线(与具体模块无关,但一样会让闸门失真)--------
#
# 🔴 **面 A / 面 B 的判别头是 `Vue-Version: 3`**(见 JNPF_COMPAT_SURFACE.md §2.2):
# 官方 JNPF 前端**必带** `Jnpf-Origin: pc` / `App-Code` / `Vue-Version: 3` 三个头,
# 而本仓前端**只带前两个**(`App-Code: sswflow` + `Jnpf-Origin: pc`,与官方同款)
# ⇒ 三个头里**只有 `Vue-Version` 是本仓前端唯一不发的** ⇒ 判别只能用它。
# 本仓前端一旦开始发 `Vue-Version` ⇒ 面 A 的请求会被误判成面 B ⇒ 契约整体错位。
hdr "[全局] 面 A/面 B 判别头:前端**禁发** Vue-Version"
if grep -q "Vue-Version" "$FE/src/api/request.ts" 2>/dev/null; then
no "前端 request.ts 发了 Vue-Version 头 ⇒ 面 A 请求会被误判成面 B"
else
ok "前端 request.ts 未发 Vue-Version(面 A/面 B 判别成立)"
fi
hdr "[全局] 面 B 尺子必须带判别头 Vue-Version: 3"
if grep -q "Vue-Version: 3" "$ROOT/scripts/perm-smoke-jnpf.sh" 2>/dev/null; then
ok "perm-smoke-jnpf.sh 带了 Vue-Version: 3"
else
no "perm-smoke-jnpf.sh 缺 Vue-Version: 3 ⇒ 面 B 请求不会被识别成面 B"
fi
# -------- 总结 --------
echo
echo "── 总结 ──"
echo "Modules: ${TARGETS[*]}"
echo "PASS=$PASS FAIL=$FAIL"
if [ "$FAIL" -eq 0 ]; then
echo "全 ✅ 可以跑 perm-smoke 了"
else
echo "有 ❌,请按上面修复后再跑 perm-smoke"
fi
exit $([ "$FAIL" -eq 0 ] && echo 0 || echo 1)