把 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]>
181 lines
7.5 KiB
Python
Executable File
181 lines
7.5 KiB
Python
Executable File
#!/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())
|