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

378 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.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`(旧布局)。
#
# 🔴 **CP5 是 C9 之后补的第 5 条**(v3 spec §2.3.2 的 4 条接触点之外):
# 「平台层不得 import 业务层」—— 拆 `AppState` 之前 `src/platform/state.rs`
# 直接 `use crate::tdc::service::account::AccountStore` ⇒ 依赖方向反了,
# 而 CP1(只查表名/端点前缀)查不出来 ⇒ 补这条钉住。
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)
# CP5:平台层**不得 import 业务层**(平台 → 业务的反向依赖)
#
# 🔴 这条是 C9 之后补上的:拆 `AppState` 之前,`src/platform/state.rs` 直接
# `use crate::tdc::service::account::AccountStore` / `use crate::tdc::client::tds::TdsClient`
# ⇒ 平台层被迫认识业务类型 ⇒ 依赖方向反了。
# CP1 只查「表名前缀 / 端点前缀」,查不出 `crate::tdc::` 这种**模块引用** ⇒ 补这条。
for path in PLATFORM_FILES:
lines = code_lines(path)
if lines is None:
continue
for lineno, s in lines:
for m in re.finditer(r"\buse\s+(?:crate|super)::tdc\b", s):
add("CP5", path, lineno, s, m.group(0))
# 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 不得出现字面量端点路径(只能引用业务层清单)",
"CP5": "平台层不得 import 业务层(平台 → 业务的反向依赖)",
}
for rule in ("CP1", "CP2", "CP3", "CP4", "CP5"):
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}"