Files
tdc-rs/scripts/upstream-action-census.py
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

181 lines
7.5 KiB
Python
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 python3
"""上游动作端点普查:把「上游有、本仓没有」的动作端点按**路径形态**分成两类。
用法:
python3 scripts/upstream-action-census.py # 打印普查表
python3 scripts/upstream-action-census.py --json # 机器可读
🔴 **为什么要有这个脚本**:
`docs/known-limitations.md` 的 L5(上游动作端点未实现)与 L7(通用详情路由
**吞掉**单段尾动作端点)都带具体数字 ⇒ 数字必须**可复算**,不能只写在散文里。
本脚本只读上游克隆(`/tmp/sswtdc-probe`),**不碰本仓任何东西**。
🔴 **口径**(与 L5/L7 的措辞一一对应):
① 范围 = 18 个 `extends TdcCrudController` 的控制器**自己声明**的 method-level
映射(`@GetMapping` / `@PostMapping` / `@PutMapping` / `@DeleteMapping`,
含**空路径**写法)。
—— CRUD-6 基线(列表 GET / `All` GET / `{id}` GET·PUT·DELETE / POST 创建)
**住在基类** `TdcCrudController` 里,子类不重复声明 ⇒ 不在计数里。
② 扣掉 **6 条 CRUD `{id}` 覆写**(子类显式重写基类的 `@PutMapping("/{id}")` /
`@DeleteMapping("/{id}")` 以禁写)—— 本仓**已实现**这些路径。
③ 扣掉 **2 条只读聚合体** `Resource/{id}/Detail` · `Dataset/{id}/Detail`
—— 本仓 B3 已实现。
④ 剩下的按**尾段数**分两类:
· 形态 A = `/{Entity}/{action}`(**恰好 1 个尾段**)
⇒ 本仓的通用详情路由 `/{Entity}/{id}`(`src/tdc/controller/crud.rs`)
**会先匹配上** ⇒ 请求**不会 404**,而是走到 detail 处理器 ⇒
查出「记录不存在」⇒ **HTTP 200 + `code:400`**。
· 形态 B = `/{Entity}/{x}/{y}`(**≥2 个尾段**)
⇒ 本仓无此路由 ⇒ **真 404**。
"""
import argparse
import json
import os
import re
import sys
UPSTREAM_ROOT = os.environ.get("SSW_TDC_UPSTREAM", "/tmp/sswtdc-probe")
CTRL_DIR = os.path.join(
UPSTREAM_ROOT, "boot/ssw-tdc/ssw-tdc-controller/src/main/java/ssw/tdc/controller"
)
# 本仓 B3 已实现的只读聚合体
AGGREGATE_DETAIL = {
"/api/ssw/tdc/Resource/{id}/Detail",
"/api/ssw/tdc/Dataset/{id}/Detail",
}
MAPPING_RE = re.compile(r'@(Get|Post|Put|Delete)Mapping(\(\s*"([^"]*)"\s*\))?')
# 18 个实体的 api_name(与本仓 `src/tdc/entity/mod.rs` 的 `ALL_SPECS` 一一对应)。
ENTITIES = [
"ApiConsumeLog", "AuditLog", "Contract", "Credential", "DataInterface", "Dataset",
"Datasource", "DeliveryLog", "DeliveryTask", "DestroyLog", "Identity", "Notification",
"Order", "Policy", "PolicyCheckLog", "PolicyTemplate", "Product", "Resource",
]
def crud_baseline():
"""CRUD-6 基线(基类 `TdcCrudController` 提供,子类**也会重复声明**):
列表 GET / 创建 POST / `All` GET / `{id}` GET·PUT·DELETE。
⇒ 这些**不是**动作端点,本仓**全部已实现**,必须扣掉。
"""
base = set()
for e in ENTITIES:
p = "/api/ssw/tdc/" + e
base.add(("GET", p))
base.add(("POST", p))
base.add(("GET", p + "/All"))
base.add(("GET", p + "/{id}"))
base.add(("PUT", p + "/{id}"))
base.add(("DELETE", p + "/{id}"))
return base
def segs(path):
return [s for s in path.strip("/").split("/") if s]
def collect():
"""⇒ [(method, full_path, file)],含空路径映射;method 已**大写**(HTTP 方法大小写敏感)。"""
rows = []
if not os.path.isdir(CTRL_DIR):
return rows
for dirpath, _dirs, files in os.walk(CTRL_DIR):
for name in files:
if not name.endswith(".java"):
continue
full = os.path.join(dirpath, name)
with open(full, encoding="utf-8", errors="replace") as fh:
text = fh.read()
if "extends TdcCrudController" not in text:
continue
cm = re.search(r'@RequestMapping\("([^"]*)"\)', text)
prefix = cm.group(1) if cm else ""
for m in MAPPING_RE.finditer(text):
method = m.group(1).upper() # 🔴 HTTP 方法大小写敏感 ⇒ 统一大写
path = m.group(3) or ""
full_path = (prefix + path).replace("//", "/")
rows.append((method, full_path, name))
return rows
def classify(rows):
"""⇒ (crud_base, aggregate, shadowed, true404) 四个集合。"""
baseline = crud_baseline()
crud_base = [] # CRUD-6 基线 —— 本仓已实现
aggregate = [] # 只读聚合体 —— 本仓 B3 已实现
shadowed = [] # 形态 A:被通用详情路由吞掉
true404 = [] # 形态 B:真 404
for method, path, name in rows:
if (method, path) in baseline:
crud_base.append((method, path, name))
continue
if path in AGGREGATE_DETAIL:
aggregate.append((method, path, name))
continue
s = segs(path)
if len(s) == 5:
# 尾段是**字面量**(`Options` / `Types` / `Enabled` …)⇒ 形态 A
shadowed.append((method, path, name))
else:
true404.append((method, path, name))
return crud_base, aggregate, shadowed, true404
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--json", action="store_true")
args = ap.parse_args()
if not os.path.isdir(CTRL_DIR):
print("❌ 上游克隆不在:%s" % CTRL_DIR)
print(" (只读克隆;本脚本不下载任何东西)")
return 2
rows = collect()
crud_base, agg, shadowed, true404 = classify(rows)
shadowed_u = sorted(set((m, p) for m, p, _ in shadowed))
true404_u = sorted(set((m, p) for m, p, _ in true404))
if args.json:
print(json.dumps({
"upstream_root": UPSTREAM_ROOT,
"declared_mappings": len(rows),
"crud_baseline": sorted(set((m, p) for m, p, _ in crud_base)),
"aggregate_detail": sorted(set((m, p) for m, p, _ in agg)),
"shadowed": shadowed_u,
"true404": true404_u,
"unimplemented_total": len(shadowed_u) + len(true404_u),
}, ensure_ascii=False, indent=1))
return 0
get_a = len([1 for m, _ in shadowed_u if m == "GET"])
post_a = len([1 for m, _ in shadowed_u if m == "POST"])
print("上游动作端点普查(只读上游克隆)")
print("-" * 72)
print(" 上游根:%s" % UPSTREAM_ROOT)
print(" 18 个 `extends TdcCrudController` 控制器自声明的 method-level 映射:%d 条" % len(rows))
print(" ├─ CRUD-6 基线(列表/创建/All/{id})—— 本仓已实现:%d 条" % len(set(crud_base)))
print(" ├─ 只读聚合体 Detail —— 本仓 B3 已实现:%d 条" % len(set(agg)))
print(" ├─ ★形态 A /{Entity}/{action} 单尾段 ⇒ 被通用详情路由吞掉:%d 条" % len(shadowed_u))
print(" │ ├ GET %d 条 ⇒ HTTP 200 + `code:400`「记录不存在或已删除」(**不是 404**)" % get_a)
print(" │ └ POST %d 条 ⇒ HTTP 405「方法不被允许」(`{id}` 上没注册 POST)" % post_a)
print(" └─ ★形态 B ≥2 尾段 ⇒ 真 404:%d 条" % len(true404_u))
print("-" * 72)
print(" 未实现动作端点合计:%d 条(形态 A %d + 形态 B %d)"
% (len(shadowed_u) + len(true404_u), len(shadowed_u), len(true404_u)))
print()
print("★ 形态 A 明细(逐条):")
for m, p in shadowed_u:
print(" %-6s %s" % (m, p))
return 0
if __name__ == "__main__":
sys.exit(main())