#!/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/) # 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/", ";".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}"