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

351 lines
13 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
# 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}"