docs: 清掉三处"会静默过期"的小账 + check-test-profile 加固(F-98)
一、附录 A 从"手抄表"改成"可再生成的命令"
check-api-parity.py 加 --extra,现算"代码有、契约 §4 没有"的接口 = 41 个
(旧手抄表写 83/62/21,已差近一倍,而且没人会记得回来改它)。
并按"谁去改什么"分六类 —— 只有 E 类(8 个)要客户定口径,其余是文档侧补记。
二、F-6 已修:frontend-pc 的 Mock 说明
AGENTS.md 那句改正之外,连带修了 .agents/skills/project-api/SKILL.md ——
它整篇仍以 vite-plugin-mock / mock/** 为主线,而该项目里 mock/ 目录与插件都已删除。
只改指路牌、不改路的尽头,等于没改。
三、docs/03 两处文档内部口径冲突加 ⚠️ 注(不改口径,只把冲突摆明)
§2 notifyBizType 的 5/6 与 §13.5、落库值不一致 → 实现以 §13.5 为准(催报去重按 5);
§3.6/§9.5 的 collect_file.source 字段表(入口来源)与建表注释(谁传的)冲突 →
实现以建表口径为准。两处都写明"待客户确认",见 F-30 / F-38 / F-39。
四、check-test-profile.py 加固(新增 F-98)
· 子进程输出落盘(不再用没人读的 PIPE):失败时能看见"停在哪一行",
成功时打出启动用时(基线 ~10 秒 / 72 行 / 9.5KB);
· 开跑前按 jar + profile 清残留 JVM,且保留 dev 后端(E2E 正打着它);
· 等待期间每 15 秒报一次进度,卡住时不留沉默。
教训:随机端口这个防撞设计把残留 JVM 藏起来了 —— 撞不到端口就永远发现不了,
于是表现成"时好时坏",而失败时连日志都读不到。
验证:python scripts/verify-all.py --with-e2e → 通过 8 / 失败 0 / 跳过 0
(E2E 36 脚本 / 1548 断言 / 278s;prodguard 9/9;test profile 能起)
python scripts/verify-docs.py → 22 项全部通过
This commit is contained in:
@@ -15,6 +15,7 @@
|
||||
用法:
|
||||
python scripts/check-api-parity.py # 打印逐分类实现度 + 缺口清单
|
||||
python scripts/check-api-parity.py --quiet # 只打印汇总(CI 里用)
|
||||
python scripts/check-api-parity.py --extra # 反向:代码有、契约 §4 清单没有的(F-4 底稿)
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -88,9 +89,11 @@ def code_endpoints() -> list[tuple[str, str, str]]:
|
||||
def main() -> int:
|
||||
quiet = "--quiet" in sys.argv
|
||||
only_missing = "--missing" in sys.argv
|
||||
only_extra = "--extra" in sys.argv
|
||||
doc = doc_overview()
|
||||
code = code_endpoints()
|
||||
code_keys = {(m, norm(p)) for _, m, p in code}
|
||||
doc_keys = {(m, norm(p)) for eps in doc.values() for m, p in eps}
|
||||
|
||||
claimed = implemented = 0
|
||||
missing: list[tuple[str, str, str]] = []
|
||||
@@ -104,6 +107,27 @@ def main() -> int:
|
||||
missing += [(cat, m, p) for m, p in miss]
|
||||
rows.append((cat, len(uniq), len(done), len(miss)))
|
||||
|
||||
# ── 反向差集:代码注册了、而契约 §4 清单里没有 ──
|
||||
# ⚠️ 这个清单**必须由工具生成**:它以前是人工做一次差集后手抄进文档的,
|
||||
# 于是每加一个接口就悄悄过期一次(数字 83/62/21 与实际差了 3 倍)。
|
||||
# 手抄件会过期,命令不会。
|
||||
extra = [(f, m, p) for f, m, p in code if (m, norm(p)) not in doc_keys]
|
||||
|
||||
if only_extra:
|
||||
print("=" * 78)
|
||||
print("代码有、契约 §4 清单没有:%d 个" % len(extra))
|
||||
print("(代码共注册 %d 个;契约声称 %d 个,其中 %d 个已在代码里)"
|
||||
% (len(code), claimed, implemented))
|
||||
print("=" * 78)
|
||||
cur = None
|
||||
for f, m, p in extra:
|
||||
if f != cur:
|
||||
print("\n【%s】" % f)
|
||||
cur = f
|
||||
print(" %-6s %s" % (m, p))
|
||||
print()
|
||||
return 0
|
||||
|
||||
if not quiet and not only_missing:
|
||||
print("=" * 78)
|
||||
print("代码注册接口:%d 个" % len(code))
|
||||
|
||||
Reference in New Issue
Block a user