Files
tdc-rs/scripts/check-boundary.sh
T
adminandClaude Code 2180660523 feat(b1a): 三把尺子 —— HTTP 契约冒烟 + 边界静态自检 + 实体静态自检
cargo test 是进程内 oneshot,从不经过 HTTP 层 ⇒ HTTP 状态码 / 响应头 /
body 原始 JSON 文本 / 404·405 真实形状 / 隐藏字段是否真不在出参 —— 全都没被测到。
本批只加尺子,不改任何行为。

scripts/smoke.sh(真进程真 HTTP,零 node 依赖,墙钟 ≈12s)
  ① 业务信封 200 + code ② 鉴权 401/403 裸三键(无 data)
  ③ /api/** 未命中 = 404 JSON(不是 SPA HTML)④ 405 = {code,msg,data:null} 且保留 Allow 头
  ⑤ hidden_fields(secretKey/devUrl/devToken)不在出参 ⑥ numeric 列 = JSON 数字
  ⑦ 列表分页信封 {pagination,list} ⑧ /api/health 真查库
  ⇒ 基线断言数 N = 75(后续每批只许增不许减;B1b 搬家前后必须 == 75)

scripts/check-boundary.sh(纯静态)+ scripts/boundary-ledger.txt(账本制)
  CP1 平台层无 tdc_/实体端点前缀 · CP2 平台层无业务实体名
  CP3 引擎不按实体名分支(零 match api_name) · CP4 平台 auth 无字面量端点路径
  越界不是一律红而是必须被记账;已失效的账本条目也红(账本只许变短)
  ⇒ 现状 7 条待 B1b 清 + 2 条永久豁免(SessionKind::Identity 是会话口径,非业务实体)

scripts/check-entity.sh(纯静态)+ scripts/upstream-json-ignore.tsv
  E1 表在 migrate.sql · E2 path == /api/ssw/tdc/<api_name> · E3 六条路由齐全
  E4 hidden_fields 覆盖上游 @JsonIgnore(可更严不可更松)· E5 编码前缀不重复
  E6 权限键不重复(B4 删表后自动跳过)· E7 f_↔camelCase 双向闭合
  ⇒ PASS=15 FAIL=0

src/main.rs:加 --enc 自证开关(cipher 用后端自己加密,脚本拿密文打登录)

规格更正(改提示词不改 spec 的决定):numeric 列是 JSON 数字,不是 JSON 字符串。
取证:上游 ProductEntity.java:88 的 BigDecimal 只带 @TableField、无 @JsonSerialize;
application.yml 无 spring.jackson 设置;上游全树无 SimpleModule/ToStringSerializer;
无任何 jnpf jar 含 BigDecimal 类 ⇒ Jackson 默认 ⇒ 上游发数字 ⇒ 本仓一致。
记入 v3 spec §12 D16,并改 v3 spec §2.4 ⑥ 与执行提示词 ⑥。

实测:cargo test 223 passed / 0 failed / 1 ignored;smoke.sh PASS=75 FAIL=0;
check-boundary.sh exit 0;check-entity.sh PASS=15 FAIL=0

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 19:50:58 +08:00

358 lines
12 KiB
Bash
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
# tdc-rs 平台层 / 业务层**边界静态自检**(v3 spec §2.3.2 的 4 个接触点)
#
# 用法:
# bash scripts/check-boundary.sh # 自检(绿 = 0)
# bash scripts/check-boundary.sh --report # 只出报告,不判红(排障用)
#
# 退出码:0 = 绿 / 1 = 有越界(或账本里有失效条目)/ 2 = 前置错误
#
# 🔴 **纯静态**:不起后端、不连库、不需要 cargo ⇒ 可以在任何一秒钟跑一遍。
# 🔴 **账本制(ratchet)**:越界不是"一律红",而是"**必须被记账**"——
# `scripts/boundary-ledger.txt` 里逐条列出「已知越界 + 为什么 + 谁负责清」。
# 没记账的越界 ⇒ 红(当场抓新增泄漏);记账已失效的条目 ⇒ 红(账本只许变短)。
# ⇒ B1b 的 C1–C12 做完,账本必须清空。
#
# 扫描口径(**四条接触点的判定规则,写死在这里,避免"尺子随实现漂移"**):
# ① 只扫**非测试代码**:每个文件里第一处 `#[cfg(test)]` 之后的内容不计入
# (单元测试必须引用具体实体/端点才有意义;生产代码不许)。
# ② 注释不计入(`//` 行注释、`/* */` 块注释都先剥掉)。
# ③ 平台层 = `src/platform/**`(新布局)或旧布局的平台件清单(见 `PLATFORM_LEGACY`)。
# ④ 通用 CRUD 引擎 = `src/tdc/{mapper,service/crud,controller/crud}.rs`(新布局)
# 或 `src/crud.rs` + `src/routes/crud.rs`(旧布局)。
set -u
if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'
exit 0
fi
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
LEDGER="${ROOT}/scripts/boundary-ledger.txt"
PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}"
REPORT_ONLY=0
[ "${1:-}" = "--report" ] && REPORT_ONLY=1
[ -n "${PY_BIN}" ] || { echo "❌ 前置错误:找不到 python3。"; exit 2; }
[ -f "${LEDGER}" ] || { echo "❌ 前置错误:账本 ${LEDGER} 不存在。"; exit 2; }
TMP="$(mktemp -d)"
trap 'rm -rf "${TMP}"' EXIT
cat >"${TMP}/check.py" <<'PYEOF'
import os
import re
import sys
ROOT = sys.argv[1]
LEDGER = sys.argv[2]
REPORT_ONLY = sys.argv[3] == "report"
# ---- 布局判定 ------------------------------------------------------
NEW_LAYOUT = os.path.isdir(os.path.join(ROOT, "src/platform"))
if NEW_LAYOUT:
PLATFORM_FILES = []
for dirpath, _dirs, files in os.walk(os.path.join(ROOT, "src/platform")):
for f in files:
if f.endswith(".rs"):
PLATFORM_FILES.append(os.path.relpath(os.path.join(dirpath, f), ROOT))
ENGINE_FILES = [
"src/tdc/mapper.rs",
"src/tdc/service/crud.rs",
"src/tdc/controller/crud.rs",
]
AUTH_FILE = "src/platform/auth.rs"
LAYOUT = "新布局(src/platform + src/tdc)"
else:
PLATFORM_FILES = [
"src/auth.rs", "src/db.rs", "src/session.rs", "src/envelope.rs",
"src/cipher.rs", "src/ids.rs", "src/protocol.rs", "src/state.rs",
"src/config.rs", "src/routes/mw.rs", "src/routes/fallback.rs",
"src/routes/body.rs",
]
ENGINE_FILES = ["src/crud.rs", "src/routes/crud.rs"]
AUTH_FILE = "src/auth.rs"
LAYOUT = "旧布局(src/*.rs + src/routes/*)"
# 业务实体名(18 个)——从注册表源码里抽,抽不到就用兜底清单
REGISTRY_CANDIDATES = ["src/registry.rs"]
if os.path.isdir(os.path.join(ROOT, "src/tdc/entity")):
for dirpath, _dirs, files in os.walk(os.path.join(ROOT, "src/tdc/entity")):
for f in files:
if f.endswith(".rs"):
REGISTRY_CANDIDATES.append(
os.path.relpath(os.path.join(dirpath, f), ROOT))
ENTITY_FALLBACK = [
"ApiConsumeLog", "AuditLog", "Contract", "Credential", "DataInterface",
"Dataset", "Datasource", "DeliveryLog", "DeliveryTask", "DestroyLog",
"Identity", "Notification", "Order", "Policy", "PolicyCheckLog",
"PolicyTemplate", "Product", "Resource",
]
def read(path):
p = os.path.join(ROOT, path)
if not os.path.isfile(p):
return None
with open(p, encoding="utf-8", errors="replace") as fh:
return fh.read()
def strip_comments(text):
"""剥掉行注释与块注释,**但保留字符串字面量里的 // 与 /* **
(白名单里就有 "/api/ssw/tdc/P2P/Transfer/*/Chunk" 这种串 ⇒ 用朴素的
正则剥注释会把它误判成块注释开头,把后面的行整片吃掉)。"""
out = []
i = 0
n = len(text)
in_str = False
in_block = False
in_line = False
while i < n:
ch = text[i]
if in_line:
if ch == "\n":
in_line = False
out.append(ch)
i += 1
continue
if in_block:
if ch == "*" and i + 1 < n and text[i + 1] == "/":
in_block = False
i += 2
continue
if ch == "\n":
out.append(ch)
i += 1
continue
if in_str:
out.append(ch)
if ch == "\\" and i + 1 < n:
out.append(text[i + 1])
i += 2
continue
if ch == '"':
in_str = False
i += 1
continue
if ch == "/" and i + 1 < n and text[i + 1] == "/":
in_line = True
i += 2
continue
if ch == "/" and i + 1 < n and text[i + 1] == "*":
in_block = True
i += 2
continue
if ch == '"':
in_str = True
out.append(ch)
i += 1
continue
out.append(ch)
i += 1
return "".join(out)
def code_lines(path):
"""只返回**非测试、非注释**的代码行(行号从 1 开始)。"""
text = read(path)
if text is None:
return None
lines = text.split("\n")
cut = len(lines)
for i, l in enumerate(lines):
if re.match(r"\s*#\[cfg\(test\)\]", l):
cut = i
break
stripped = strip_comments("\n".join(lines[:cut]))
return [(i + 1, l) for i, l in enumerate(stripped.split("\n"))]
def entity_names():
names = set()
for path in REGISTRY_CANDIDATES:
text = read(path)
if text is None:
continue
names.update(re.findall(r'api_name:\s*"([A-Za-z0-9_]+)"', text))
return sorted(names) if names else ENTITY_FALLBACK
# ---- 账本 ----------------------------------------------------------
def load_ledger():
rows = []
if not os.path.isfile(LEDGER):
return rows
with open(LEDGER, encoding="utf-8") as fh:
for raw in fh:
line = raw.rstrip("\n")
if not line.strip() or line.lstrip().startswith("#"):
continue
parts = line.split("\t")
if len(parts) < 4:
continue
rows.append({
"rule": parts[0].strip(),
"file": parts[1].strip(),
"pattern": parts[2].strip(),
"note": parts[3].strip(),
"owner": (parts[4].strip() if len(parts) > 4 else "B1b"),
})
return rows
def ledger_file_matches(ledger_file, actual_file):
"""账本里的文件字段按**路径后缀**匹配 ⇒ 搬家(src/auth.rs → src/platform/auth.rs)
不会让账本条目失效。"""
if not ledger_file:
return False
return actual_file == ledger_file or actual_file.endswith("/" + ledger_file)
# ---- 采集发现 ------------------------------------------------------
findings = [] # (rule, file, line, text, token)
def add(rule, path, lineno, text, token):
findings.append((rule, path, lineno, text.strip(), token))
ENTITIES = entity_names()
# CP1:平台层不得出现 tdc_ 表名前缀 / /api/ssw/tdc/ 端点前缀
for path in PLATFORM_FILES:
lines = code_lines(path)
if lines is None:
continue
for lineno, s in lines:
for pat in ("tdc_", "/api/ssw/tdc/"):
if pat in s:
add("CP1", path, lineno, s, pat)
# CP2:平台层不得出现具体实体名
for path in PLATFORM_FILES:
lines = code_lines(path)
if lines is None:
continue
for lineno, s in lines:
for ent in ENTITIES:
if re.search(r"\b" + re.escape(ent) + r"\b", s):
add("CP2", path, lineno, s, ent)
# CP3:通用 CRUD 引擎不得按实体名分支
ENGINE_PATTERNS = [
r"match\s+api_name",
r"match\s+spec\.api_name",
r"api_name\s*==",
r"api_name\.eq\(",
r"api_name\.starts_with\(",
r"api_name\.as_str\(",
r"find\(\s*\"[A-Za-z]+\"\s*\)",
]
for path in ENGINE_FILES:
lines = code_lines(path)
if lines is None:
continue
for lineno, s in lines:
for pat in ENGINE_PATTERNS:
if re.search(pat, s):
add("CP3", path, lineno, s, pat)
# CP4:平台 auth 不得出现字面量端点路径("/api/" + 至少一段)
auth_lines = code_lines(AUTH_FILE)
if auth_lines is None:
print("❌ 前置错误:找不到平台 auth 文件(%s)。" % AUTH_FILE)
sys.exit(2)
for lineno, s in auth_lines:
for m in re.finditer(r'"(/api/[^"]+)"', s):
add("CP4", AUTH_FILE, lineno, s, m.group(1))
# ---- 分类 ----------------------------------------------------------
ledger = load_ledger()
new_findings = []
known = []
matched_rows = set()
for f in findings:
hit = None
for i, row in enumerate(ledger):
if row["rule"] != f[0]:
continue
if not ledger_file_matches(row["file"], f[1]):
continue
if row["pattern"] and row["pattern"] not in f[3]:
continue
hit = i
break
if hit is None:
new_findings.append(f)
else:
# 🔴 一条账本条目可以覆盖**多处**发现(如 auth.rs 的整张白名单)⇒ 不做一对一消耗。
matched_rows.add(hit)
known.append((f, ledger[hit]))
stale = [row for i, row in enumerate(ledger) if i not in matched_rows]
# ---- 报告 ----------------------------------------------------------
print("布局:%s" % LAYOUT)
print("平台层文件 %d 个 · 引擎文件 %d 个 · 业务实体 %d 个"
% (len(PLATFORM_FILES), len(ENGINE_FILES), len(ENTITIES)))
print("账本条目 %d 条" % len(ledger))
print()
RULE_DESC = {
"CP1": "平台层不得出现 tdc_ 表名前缀 / /api/ssw/tdc/ 端点前缀",
"CP2": "平台层不得出现具体业务实体名",
"CP3": "通用 CRUD 引擎不得按实体名分支(只能读 TableSpec 字段)",
"CP4": "平台 auth 不得出现字面量端点路径(只能引用业务层清单)",
}
for rule in ("CP1", "CP2", "CP3", "CP4"):
rs = [f for f in findings if f[0] == rule]
print("%s:%d 处发现 —— %s" % (rule, len(rs), RULE_DESC[rule]))
for f in rs:
print(" %s:%s %s" % (f[1], f[2], f[3][:96]))
print()
if known:
print("已记账(%d 处)—— 账本里写明为什么可接受:" % len(known))
for f, row in known:
print(" %s %s:%s ← 账本[%s]:%s(%s)"
% (f[0], f[1], f[2], row["owner"], row["pattern"] or "<该文件全部>", row["note"]))
print()
if new_findings:
print("❌ 未记账的越界 %d 处(**当场红**):" % len(new_findings))
for f in new_findings:
print(" %s %s:%s %s" % (f[0], f[1], f[2], f[3][:96]))
print()
if stale:
print("❌ 账本里 %d 条已失效(越界已消失,账本只许变短 ⇒ 请删行):" % len(stale))
for row in stale:
print(" %s %s [%s] %s" % (row["rule"], row["file"], row["pattern"], row["note"]))
print()
pending = [r for r in ledger if r["owner"] != "永久"]
print("账本待清账(B1b 责任)%d 条 · 永久豁免 %d 条"
% (len(pending), len(ledger) - len(pending)))
ok = (not new_findings) and (not stale)
if ok:
print("边界自检通过 ✅(0 处未记账越界,0 条失效账本条目)")
sys.exit(0)
if REPORT_ONLY:
print("(--report:只报告,不判红)")
sys.exit(0)
sys.exit(1)
PYEOF
"${PY_BIN}" "${TMP}/check.py" "${ROOT}" "${LEDGER}" "$([ "${REPORT_ONLY}" -eq 1 ] && echo report || echo check)"
rc=$?
if [ "${rc}" -eq 2 ]; then
exit 2
fi
exit "${rc}"