Files
tdc-rs/scripts/check-entity.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

351 lines
13 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.4 第三把尺子)
#
# 用法:
# bash scripts/check-entity.sh # 自检(绿 = 0)
# bash scripts/check-entity.sh --report # 只出报告,不判红
#
# 退出码:0 = 绿 / 1 = 有违规 / 2 = 前置错误
#
# 🔴 **纯静态**:不起后端、不连库、不 cargo ⇒ 一秒钟跑完。
# 🔴 **加一个实体时该跑什么**(这就是本尺子的存在理由):
# E1 表在 `schema/migrate.sql`
# E2 `path` 与 `api_name` 一致(/api/ssw/tdc/<Entity>)
# E3 **6 条路由**已注册(列表 / All / 详情 / 新增 / 修改 / 删除)
# E4 `hidden_fields` 覆盖上游 `@JsonIgnore`(漏一条 = 泄密)
# E5 服务端生成的编码前缀**不重复**
# E6 权限键**不重复**(B4 删除该表后本项自动跳过)
# E7 `f_` ↔ camelCase **双向闭合**(且尺子自己的映射实现必须复现仓里的单测向量)
set -u
if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'
exit 0
fi
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}"
IGNORE_TSV="${ROOT}/scripts/upstream-json-ignore.tsv"
REPORT_ONLY=0
[ "${1:-}" = "--report" ] && REPORT_ONLY=1
[ -n "${PY_BIN}" ] || { echo "❌ 前置错误:找不到 python3。"; exit 2; }
[ -f "${ROOT}/schema/migrate.sql" ] || { echo "❌ 前置错误:找不到 schema/migrate.sql。"; exit 2; }
[ -f "${IGNORE_TSV}" ] || { echo "❌ 前置错误:找不到 scripts/upstream-json-ignore.tsv。"; 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]
IGNORE_TSV = sys.argv[2]
REPORT_ONLY = sys.argv[3] == "report"
PASS = 0
FAIL = 0
def check(ok, desc, detail=""):
global PASS, FAIL
if ok:
PASS += 1
print(" ✅ %s%s" % (desc, ("(%s)" % detail) if detail else ""))
else:
FAIL += 1
print(" ❌ %s%s" % (desc, ("(%s)" % detail) if detail else ""))
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()
# ---- 找源文件(兼容旧布局 / v3 新布局) ----------------------------
NEW_LAYOUT = os.path.isdir(os.path.join(ROOT, "src/platform"))
spec_files = []
if os.path.isdir(os.path.join(ROOT, "src/tdc/entity")):
for dirpath, _d, files in os.walk(os.path.join(ROOT, "src/tdc/entity")):
for f in sorted(files):
if f.endswith(".rs"):
spec_files.append(os.path.relpath(os.path.join(dirpath, f), ROOT))
else:
spec_files = ["src/registry.rs"]
route_files = []
for cand in ("src/tdc/controller/crud.rs", "src/routes/crud.rs"):
if read(cand) is not None:
route_files.append(cand)
db_files = []
for cand in ("src/platform/db.rs", "src/db.rs"):
if read(cand) is not None:
db_files.append(cand)
if not spec_files:
print("❌ 前置错误:找不到实体 spec 源文件(src/registry.rs 或 src/tdc/entity/*.rs)。")
sys.exit(2)
# ---- 解析 TableSpec ------------------------------------------------
def brace_blocks(text, marker):
"""抽出 `marker {` 起始、括号配平结束的所有块。"""
out = []
for m in re.finditer(re.escape(marker) + r"\s*\{", text):
i = m.end() - 1
depth = 0
in_str = False
while i < len(text):
ch = text[i]
if in_str:
if ch == "\\":
i += 2
continue
if ch == '"':
in_str = False
elif ch == '"':
in_str = True
elif ch == "{":
depth += 1
elif ch == "}":
depth -= 1
if depth == 0:
out.append(text[m.end():i])
break
i += 1
return out
specs = []
all_src = ""
for path in spec_files:
text = read(path)
if text is None:
continue
all_src += "\n" + text
for block in brace_blocks(text, "TableSpec"):
def one(pat):
m = re.search(pat, block)
return m.group(1) if m else None
api = one(r'api_name:\s*"([^"]+)"')
if not api:
continue
hidden = []
m = re.search(r"hidden_fields:\s*&\[([^\]]*)\]", block)
if m:
hidden = re.findall(r'"([^"]+)"', m.group(1))
frozen = []
m = re.search(r"frozen_columns:\s*&\[([^\]]*)\]", block)
if m:
frozen = re.findall(r'"([^"]+)"', m.group(1))
specs.append({
"api_name": api,
"path": one(r'path:\s*"([^"]+)"'),
"table": one(r'table:\s*"([^"]+)"'),
"hidden_fields": hidden,
"frozen_columns": frozen,
})
if not specs:
print("❌ 前置错误:没解析出任何 TableSpec(源文件:%s)。" % ", ".join(spec_files))
sys.exit(2)
# ---- 解析 migrate.sql ---------------------------------------------
ddl_text = read("schema/migrate.sql")
tables = {}
for t, body in re.findall(r"CREATE TABLE public\.(\w+) \((.*?)\n\);", ddl_text, re.S):
cols = []
for m in re.finditer(r"^\s{4}([a-zA-Z_]\w*)\s+\S", body, re.M):
cols.append(m.group(1))
tables[t] = cols
# ---- 解析编码前缀(create_codes) ----------------------------------
codes = {}
for m in re.finditer(r'"(\w+)"\s*=>\s*&\[CodeSpec\s*\{(.*?)\}\]', all_src, re.S):
api, blk = m.group(1), m.group(2)
pm = re.search(r'prefix:\s*"([^"]+)"', blk)
km = re.search(r'key:\s*"([^"]+)"', blk)
if pm:
codes[api] = {"prefix": pm.group(1), "key": km.group(1) if km else ""}
# ---- 解析权限键(PERMISSION_KEYS;B4 后该表消失) ------------------
perm_pairs = []
pm = re.search(r"PERMISSION_KEYS[^{=]*=\s*&\[(.*?)\];", all_src, re.S)
if pm:
perm_pairs = re.findall(r'\(\s*"([^"]+)"\s*,\s*"([^"]+)"\s*\)', pm.group(1))
print("实体 %d 个(源:%s)· migrate.sql 表 %d 张 · 权限键 %d 条"
% (len(specs), ", ".join(spec_files), len(tables), len(perm_pairs)))
print()
# ---- E1 表在 migrate.sql ------------------------------------------
print("E1 表在 schema/migrate.sql")
missing = []
for s in specs:
if s["table"] not in tables:
missing.append("%s→%s" % (s["api_name"], s["table"]))
check(not missing, "每个实体的表都在 migrate.sql 里",
"缺 %d 张:%s" % (len(missing), ", ".join(missing)) if missing else "%d 张全在" % len(specs))
print()
# ---- E2 path 与 api_name 一致 -------------------------------------
print("E2 path 与 api_name 一致")
bad = []
for s in specs:
want = "/api/ssw/tdc/" + s["api_name"]
if s["path"] != want:
bad.append("%s: %s ≠ %s" % (s["api_name"], s["path"], want))
check(not bad, "path == /api/ssw/tdc/<api_name>", ";".join(bad) if bad else "%d 个全对" % len(specs))
print()
# ---- E3 六条路由已注册 --------------------------------------------
print("E3 六条路由已注册")
route_src = ""
for rf in route_files:
route_src += read(rf) or ""
need = {
"GET 列表": r"\.route\(\s*&?s?\.?path",
"POST 新增": r"\.post\(",
"GET All": r'\{\}/All"',
"GET 详情": r'\{\}/\{\{id\}\}"',
"PUT 修改": r"\.put\(",
"DELETE 删除": r"\.delete\(",
}
miss = [k for k, pat in need.items() if not re.search(pat, route_src)]
check(bool(route_files), "路由装配文件存在", "、".join(route_files) if route_files else "没找到")
check(not miss, "6 条路由形态齐全", "缺 %s" % ", ".join(miss) if miss else "列表/All/详情/新增/修改/删除")
iter_re = r"registry::REGISTRY|ALL_SPECS|REGISTRY\.iter|for spec in"
check(bool(re.search(iter_re, route_src)), "路由装配**遍历全量 spec**(不是手写实体名)")
# 每个实体的 6 条 URL 互不冲突
paths = [s["path"] for s in specs]
check(len(paths) == len(set(paths)), "18 个实体的 path 互不重复")
print()
# ---- E4 hidden_fields 覆盖上游 @JsonIgnore -------------------------
print("E4 hidden_fields 覆盖上游 @JsonIgnore")
upstream = []
with open(IGNORE_TSV, 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) >= 2:
upstream.append((parts[0].strip(), parts[1].strip()))
by_api = {s["api_name"]: s for s in specs}
leaks = []
for api, field in upstream:
s = by_api.get(api)
if s is None:
leaks.append("%s 不在本仓注册表里(上游 @JsonIgnore 字段无人认领)" % api)
elif field not in s["hidden_fields"]:
leaks.append("%s.%s 未登记进 hidden_fields" % (api, field))
check(not leaks, "上游 @JsonIgnore 字段全部被去敏", ";".join(leaks) if leaks
else "%d 个字段全覆盖" % len(upstream))
extra = []
for s in specs:
for f in s["hidden_fields"]:
if (s["api_name"], f) not in upstream:
extra.append("%s.%s" % (s["api_name"], f))
check(True, "本仓额外去敏(允许,比上游严)", ", ".join(extra) if extra else "无")
print()
# ---- E5 编码前缀不重复 ---------------------------------------------
print("E5 服务端生成的编码前缀不重复")
prefixes = [v["prefix"] for v in codes.values()]
dup = sorted({p for p in prefixes if prefixes.count(p) > 1})
check(not dup, "编码前缀互不相同", "重复:%s" % ", ".join(dup) if dup
else "%s 共 %d 个" % (", ".join(sorted(prefixes)), len(prefixes)) if prefixes else "无编码列")
check(len(codes) == len(specs) or True, "(参考)有编码列的实体数", "%d 个" % len(codes))
print()
# ---- E6 权限键不重复 -----------------------------------------------
print("E6 权限键不重复")
if perm_pairs:
keys = [k for _e, k in perm_pairs]
dupk = sorted({k for k in keys if keys.count(k) > 1})
apis = [e for e, _k in perm_pairs]
dupa = sorted({e for e in apis if apis.count(e) > 1})
check(not dupk, "权限键互不相同", "重复:%s" % ", ".join(dupk) if dupk else "%d 条" % len(perm_pairs))
check(not dupa, "实体在权限键表里不重复", "重复:%s" % ", ".join(dupa) if dupa else "无")
else:
print(" ✅ 权限键表已删除(B4 的 D6:删除 18 个实体级权限键)⇒ 本项自动跳过")
print()
# ---- E7 f_ ↔ camelCase 双向闭合 ------------------------------------
print("E7 f_ ↔ camelCase 双向闭合")
def c2k(col):
body = col[2:] if col.startswith("f_") else col
parts = body.split("_")
out = parts[0]
for p in parts[1:]:
out += (p[:1].upper() + p[1:]) if p else ""
return out
def k2c(key):
out = "f_"
for ch in key:
out += ("_" + ch.lower()) if (ch.isascii() and ch.isupper()) else ch
return out
# ① 尺子自己的映射实现必须复现仓里的单测向量(防"自证自洽")
vec_src = "\n".join(read(p) or "" for p in db_files)
vec_c2k = re.findall(r'column_to_json_key\("([^"]+)"\),\s*"([^"]+)"', vec_src)
vec_k2c = re.findall(r'json_key_to_column\("([^"]+)"\),\s*"([^"]+)"', vec_src)
bad_vec = []
for col, key in vec_c2k:
if c2k(col) != key:
bad_vec.append("column_to_json_key(%s) 期望 %s,尺子算出 %s" % (col, key, c2k(col)))
for key, col in vec_k2c:
if k2c(key) != col:
bad_vec.append("json_key_to_column(%s) 期望 %s,尺子算出 %s" % (key, col, k2c(key)))
check(not bad_vec, "尺子的映射实现复现仓里单测向量",
";".join(bad_vec) if bad_vec else "%d 个向量(%d + %d)" % (len(vec_c2k) + len(vec_k2c), len(vec_c2k), len(vec_k2c)))
# ② 18 张实体表:逐列往返闭合 + 键不撞车
bad_rt = []
bad_inj = []
for s in specs:
cols = tables.get(s["table"], [])
seen = {}
for col in cols:
k = c2k(col)
if k2c(k) != col:
bad_rt.append("%s.%s → %s → %s" % (s["table"], col, k, k2c(k)))
if k in seen:
bad_inj.append("%s:%s 与 %s 都映射到 %s" % (s["table"], seen[k], col, k))
seen[k] = col
check(not bad_rt, "逐列往返闭合(列 → 键 → 列)",
";".join(bad_rt[:3]) if bad_rt else "%d 张实体表全闭合" % len(specs))
check(not bad_inj, "同表内 JSON 键不撞车(映射单射)",
";".join(bad_inj[:3]) if bad_inj else "无")
print()
print("--------------------")
print("PASS=%d FAIL=%d" % (PASS, FAIL))
if FAIL == 0:
print("实体自检通过 ✅")
sys.exit(0)
if REPORT_ONLY:
print("(--report:只报告,不判红)")
sys.exit(0)
sys.exit(1)
PYEOF
"${PY_BIN}" "${TMP}/check.py" "${ROOT}" "${IGNORE_TSV}" "$([ "${REPORT_ONLY}" -eq 1 ] && echo report || echo check)"
rc=$?
if [ "${rc}" -eq 2 ]; then
exit 2
fi
exit "${rc}"