Files
tdc-rs/scripts/check-boundary.sh
T
admin 49e5fcefe4 refactor(b1b-c9): 状态分家 —— 平台 AppState 只留运行态,业务态进 TdcState
影响:平台层不再认识业务类型(引导身份 / 本地账号库 / TDS 客户端 / 业务配置
全部移出 AppState);对外行为零变化(237 条测试全绿、冒烟断言数仍 75)。

改动:
- src/platform/state.rs:AppState 收敛为 {config, db, db_lock, sessions}
- src/tdc/state.rs(新):TdcState = platform + 业务配置 + 引导身份 + 账号库 + TDS 客户端
  · Deref<Target = AppState> => 业务层字段访问(state.db 等)写法不变
  · impl FromRef<TdcState> for AppState => axum 里 State<AppState> 仍可用
- src/main.rs:装配顺序改为 platform -> bootstrap_identity -> TdcState
- 控制器/服务/测试:入参一律换成 &TdcState(bootstrap_identity 仍是 &AppState,
  它跑在装配期,那时 TdcState 还没造出来)
- scripts/check-boundary.sh:新增第 5 个接触点 CP5(平台层不得 use crate::tdc::),
  专门盯这条反向依赖;CP1 只查表名/端点前缀,查不出模块引用
- CLAUDE.md / .workbuddy/memory/2026-10-26.md 同步

设计:FromRef 在 axum::extract(不是 axum::core::extract)=> 手写 impl。
2026-10-26 22:24:54 +08:00

378 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.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}"