Files
tdc-rs/scripts/check-contract.sh
T
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。

新增文档:

- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
  唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。

新增尺子(第四把 + 两把专项):

- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。

影响:

- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
  (`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
  ⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
  吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
  POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
  失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
  **不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。

实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。

⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 00:56:09 +08:00

102 lines
3.4 KiB
Bash
Executable File
Raw Permalink 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
# 契约对账尺子:`docs/contract.md` 的端点表 ↔ **实际注册路由**(v3 spec §8 B5 验收)
#
# 用法:
# bash scripts/check-contract.sh # 自己起一个真进程(隔离数据目录 + 空闲端口),跑完即收
# B=http://127.0.0.1:30000 bash scripts/check-contract.sh # 打已经在跑的实例
# KEEP=1 bash scripts/check-contract.sh # 保留临时数据目录(排障用)
#
# 退出码:0 = 全绿 / 1 = 对账不一致 / 2 = 前置错误(起不来等)
#
# 🔴 **对账的是「实际注册路由」,不是源码字面量**:每个 (方法, 路径) 都真打一次,
# 用「404 = 未注册 / 405 = 方法不对 / 其它 = 已注册」反推方法集合。
# ⇒ 文档写错方法、漏写端点、多写端点,三种都会判红。
# 🔴 所有 curl / urllib 都禁代理(本机 HTTP_PROXY 会劫持 loopback)。
# 🔴 所有含中文的变量引用一律写 ${VAR}(变量名后紧跟中文时,bash 会把中文并进变量名 ⇒ set -u 下 unbound variable)。
set -u
if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'
exit 0
fi
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
BIN="${BIN:-$ROOT/target/debug/tdc-connector}"
PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}"
KEEP="${KEEP:-0}"
INTERNAL_TOKEN="${INTERNAL_TOKEN:-contract-probe-internal-token}"
DOC="${DOC:-$ROOT/docs/contract.md}"
TMP="$(mktemp -d)"
SERVER_PID=""
cleanup() {
if [ -n "${SERVER_PID}" ]; then
# 🔴 后端**不响应 SIGTERM**(实测)⇒ TERM → 最多等 5 秒 → KILL,最后 `wait` 收尸。
kill "${SERVER_PID}" 2>/dev/null || true
for _ in $(seq 1 10); do
kill -0 "${SERVER_PID}" 2>/dev/null || break
sleep 0.5
done
kill -9 "${SERVER_PID}" 2>/dev/null || true
wait "${SERVER_PID}" 2>/dev/null || true
fi
if [ "${KEEP}" = "1" ]; then
echo "(KEEP=1)临时目录保留在:${TMP}"
else
rm -rf "${TMP}"
fi
}
trap cleanup EXIT
pre_fail() {
echo "❌ 前置错误:${1}"
exit 2
}
[ -n "${PY_BIN}" ] || pre_fail "找不到 python3。"
if [ -z "${B:-}" ]; then
if [ ! -x "${BIN}" ]; then
echo "… ${BIN} 不存在,先 cargo build"
(cd "${ROOT}" && cargo build --quiet) || pre_fail "cargo build 失败。"
fi
PORT="$("${PY_BIN}" -c 'import socket
s = socket.socket()
s.bind(("127.0.0.1", 0))
print(s.getsockname()[1])
s.close()')"
B="http://127.0.0.1:${PORT}"
DATA_DIR="${TMP}/data"
mkdir -p "${DATA_DIR}"
echo "… 起进程:${B}(数据目录 ${DATA_DIR})"
TDC_DATA_DIR="${DATA_DIR}" \
PORT="${PORT}" \
TDC_IDENTITY_SECRET="contract-probe-dummy-not-a-real-secret" \
SSW_INTERNAL_TOKEN="${INTERNAL_TOKEN}" \
"${BIN}" >"${TMP}/server.log" 2>&1 &
SERVER_PID=$!
READY=0
for _ in $(seq 1 120); do
if ! kill -0 "${SERVER_PID}" 2>/dev/null; then
echo "--- server.log ---"
sed -n '1,40p' "${TMP}/server.log"
pre_fail "后端进程启动即退出。"
fi
if curl -s --noproxy '*' --max-time 3 -o /dev/null "${B}/api/health" 2>/dev/null; then
READY=1
break
fi
sleep 1
done
[ "${READY}" -eq 1 ] || { sed -n '1,40p' "${TMP}/server.log"; pre_fail "后端 120 秒内没起来。"; }
else
echo "… 打已在跑的实例:${B}"
fi
"${PY_BIN}" "${ROOT}/scripts/contract_probe.py" --base "${B}" --doc "${DOC}" --token "${INTERNAL_TOKEN}"
RC=$?
[ "${RC}" -eq 2 ] && exit 2
exit "${RC}"