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