把 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]>
102 lines
3.4 KiB
Bash
Executable File
102 lines
3.4 KiB
Bash
Executable File
#!/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}"
|