行政区划 Area(7) + 公有变量 Variate(7);新表 base_province / base_common_variate (官方 DDL 逐字)⇒ tables 53、BASE_TABLES 50。 影响:/system/Area 与 /system/Variate 页面前端可以真跑(树懒加载、子树排除、 type 是字符串、creatorUser 真填上);回归测试 tests/batch13_it.rs 12 条。 钉子测试不再手抄:删掉 routes.rs 里 255 行 FACE_B_REGISTERED,改成从契约 [ENDPOINT] 读路径(漏抄仍全绿 = 假闸门);CC7 相应只守面 A,并加「清单回来就红」。 顺手把两处写死表数改成与真值源同口径(sspf-store 常量、batch6 的表清单)。
169 lines
6.2 KiB
Bash
169 lines
6.2 KiB
Bash
#!/usr/bin/env bash
|
||
# ssw-platform 契约对账尺子 —— `docs/contract.md` ↔ 代码里的真实路由
|
||
#
|
||
# 目的:把「契约文档」和「代码」这两份**独立**的真相**对账**。
|
||
# 契约 §6 的端点表原先是**散文表格**,代码里的路由注册是**另一处**
|
||
# ⇒ 加端点 / 改路径 / 改守卫 ⇒ 各改各的 ⇒ 漂移没人发现。
|
||
# 本尺子把契约附录 A 的 `[ENDPOINT]`(机器可读)与代码里**真实注册**的路由
|
||
# **双向**逐条对账:契约多 / 代码多 / 方法不符 / 归属层不符 / 守卫不符。
|
||
#
|
||
# 🔴 **纯静态**:不启动后端、不发请求。只需要 `python3`(macOS 自带)。
|
||
#
|
||
# 用法:
|
||
# bash scripts/check-contract.sh # 无参 ⇒ 全查
|
||
# bash scripts/check-contract.sh --help # 本用法
|
||
#
|
||
# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错或前置错误
|
||
#
|
||
# ── 判据(CC1–CC10)──
|
||
# CC2 端点**总数**一致(契约 N 条 == 代码 N 条)
|
||
# CC3 契约 → 代码:每条端点在代码里存在且**方法**一致
|
||
# CC4 代码 → 契约:代码里没有契约未登记的端点
|
||
# CC5 **归属层**一致(platform / 业务模块代号)
|
||
# CC6 **守卫**一致(面A 菜单 key / 面B 点权限编码 / 登录 / 无)——静态推导
|
||
# CC7 钉子测试 **面 A 的字面量清单**(REGISTERED)与面 A 平台路由双向覆盖(面 B 已退役,读契约)
|
||
# CC8 业务路由**三处**一致(各模块 ROUTES 常量 / router() 注册 / ALL_ROUTES)
|
||
# CC9 契约面计数**自洽**([FACE] 登记的条数 == [ENDPOINT] 里各 face 的实际条数)
|
||
# CC10 **官方端点台账** ↔ 代码真实路由(双向)+ 打印「官方端点覆盖 N/M」
|
||
# CC1' **反自证**:注入已知漂移 ⇒ 必须被抓到(永远返回「干净」的尺子 = 没有尺子)
|
||
#
|
||
# 🔴 **期望值来自 `docs/contract.md` 附录 A**(机器可读)⇒ 改契约只改那一处。
|
||
|
||
set -u
|
||
|
||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||
SCRIPTS="$ROOT/scripts"
|
||
CONTRACT="$ROOT/docs/contract.md"
|
||
SRC="$ROOT/src/backend/src"
|
||
SCAN="$SCRIPTS/check-contract-scan.py"
|
||
CE_PY="$SCRIPTS/contract_expect.py"
|
||
|
||
usage() {
|
||
echo "用法: bash scripts/check-contract.sh"
|
||
echo " 纯静态对账「契约端点表 ↔ 代码里真实注册的路由」"
|
||
echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错或前置错误"
|
||
}
|
||
|
||
if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
|
||
usage
|
||
exit 0
|
||
fi
|
||
if [ "$#" -ne 0 ]; then
|
||
echo "❌ 未知参数: ${1}"
|
||
usage
|
||
exit 2
|
||
fi
|
||
|
||
# ---- 前置:python3 / 扫描器 / 契约文件 ----
|
||
PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}"
|
||
if [ -z "${PY_BIN}" ]; then
|
||
echo "❌ 找不到 python3(扫描器需要它)"
|
||
exit 2
|
||
fi
|
||
if [ ! -f "${SCAN}" ]; then
|
||
echo "❌ 缺扫描器: ${SCAN}"
|
||
exit 2
|
||
fi
|
||
if [ ! -f "${CE_PY}" ]; then
|
||
echo "❌ 缺契约期望值读取器: ${CE_PY}"
|
||
exit 2
|
||
fi
|
||
if [ ! -f "${CONTRACT}" ]; then
|
||
echo "❌ 缺契约文件: ${CONTRACT}"
|
||
exit 2
|
||
fi
|
||
|
||
# ---- 契约期望值(唯一真源:docs/contract.md 附录 A)----
|
||
CE_RULER_ROWS="$("${PY_BIN}" "${CE_PY}" rows RULER 2>/dev/null)" || CE_RULER_ROWS=""
|
||
if [ -z "${CE_RULER_ROWS}" ]; then
|
||
echo "❌ 读契约期望值失败(docs/contract.md 附录 A 是不是被改坏了?)"
|
||
exit 2
|
||
fi
|
||
CE_EXP_ASSERTIONS="$(printf '%s\n' "${CE_RULER_ROWS}" | awk -F'\t' '$1=="check-contract.sh" { print $2; exit }')"
|
||
|
||
PASS=0; FAIL=0
|
||
ok() { echo " ✅ $1"; PASS=$((PASS+1)); }
|
||
no() { echo " ❌ $1"; FAIL=$((FAIL+1)); }
|
||
hdr() { echo; echo "── $1 ──"; }
|
||
|
||
# ---- 跑扫描器 ----
|
||
SCAN_OUT="$("${PY_BIN}" "${SCAN}" --contract "${CONTRACT}" --src "${SRC}" 2>&1)"
|
||
SCAN_RC=$?
|
||
if [ "${SCAN_RC}" -eq 2 ]; then
|
||
echo "❌ 扫描器前置失败(契约读不出来 / 参数错):"
|
||
printf '%s\n' "${SCAN_OUT}" | sed 's/^/ /'
|
||
exit 2
|
||
fi
|
||
|
||
hdr "[CC2–CC10] 契约端点表 ↔ 代码真实路由 逐条对账"
|
||
DRIFT_LINES=""
|
||
while IFS=$'\t' read -r kind f1 f2 f3; do
|
||
[ -z "${kind:-}" ] && continue
|
||
case "${kind}" in
|
||
CHECK)
|
||
if [ "${f2}" = "OK" ]; then
|
||
ok "${f1}:${f3}"
|
||
else
|
||
no "${f1}:${f3}"
|
||
fi
|
||
;;
|
||
INFO)
|
||
# 🔴 进度信息(官方端点覆盖 N/M)—— **不计入** PASS/FAIL
|
||
echo " 📊 ${f1}:${f2}"
|
||
;;
|
||
WARN)
|
||
# WARN 行只有 3 列(kind / id / 说明)⇒ 说明在 f2
|
||
if [ -n "${f3}" ]; then
|
||
DRIFT_LINES="${DRIFT_LINES}${f1}:${f3}"$'\n'
|
||
else
|
||
DRIFT_LINES="${DRIFT_LINES}${f1}:${f2}"$'\n'
|
||
fi
|
||
;;
|
||
esac
|
||
done <<< "${SCAN_OUT}"
|
||
|
||
if [ -n "${DRIFT_LINES}" ]; then
|
||
hdr "漂移明细"
|
||
printf '%s' "${DRIFT_LINES}" | sed 's/^/ ⚠️ /'
|
||
fi
|
||
|
||
# ---- CC1' 反自证:尺子自己必须能抓到漂移 ----
|
||
hdr "[CC1'] 扫描器反自证(--self-test 必须过)"
|
||
SELFTEST_OUT="$("${PY_BIN}" "${SCAN}" --self-test 2>&1)"
|
||
if [ "$?" -eq 0 ]; then
|
||
ok "扫描器自证通过:${SELFTEST_OUT}"
|
||
else
|
||
no "扫描器自证失败:${SELFTEST_OUT}"
|
||
fi
|
||
|
||
# -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 --------
|
||
#
|
||
# 🔴 尺子自己知道它断言了几条(PASS+FAIL)。哪天有人删掉几条断言、或者某个分支提前
|
||
# return 了,尺子照样「全绿」—— 变弱的尺子比没有尺子更危险 ⇒ 条数由**契约**钉死。
|
||
hdr "[自证] 尺子条数与契约登记一致"
|
||
if [ -n "${CE_EXP_ASSERTIONS}" ]; then
|
||
CE_ACT_ASSERTIONS=$((PASS + FAIL))
|
||
if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then
|
||
# 自证**不计入** PASS/FAIL(它是元断言,不是业务断言)
|
||
echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条"
|
||
else
|
||
echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)"
|
||
FAIL=$((FAIL + 1))
|
||
fi
|
||
else
|
||
echo " ❌ 契约 [RULER] 里没有登记 check-contract.sh 的期望条数"
|
||
FAIL=$((FAIL + 1))
|
||
fi
|
||
|
||
# -------- 总结 --------
|
||
echo
|
||
echo "── 总结 ──"
|
||
echo "PASS=${PASS} FAIL=${FAIL}"
|
||
if [ "${FAIL}" -eq 0 ]; then
|
||
echo "全 ✅ 契约与代码没漂移"
|
||
else
|
||
echo "有 ❌,请按上面修复(改契约 ⇒ 改 docs/contract.md 附录 A 的 [ENDPOINT])"
|
||
fi
|
||
|
||
exit $([ "${FAIL}" -eq 0 ] && echo 0 || echo 1)
|