#!/usr/bin/env python3 # -*- coding: utf-8 -*- """gen-contract-endpoints —— 从**代码真实路由**生成契约的 `[ENDPOINT]` / `[OFFICIAL]` 行。 🔴 为什么存在(批次 17): 契约面的实现按**官方模块名**分文件(`platform/compat/<模块>.rs`), 一次做完就是**上百条**端点 ⇒ 手工往 `docs/contract.md` 里抄 `[ENDPOINT]`(5 列)与 `[OFFICIAL]`(5 列)**必然漏抄**: - `[ENDPOINT]` 漏一条 ⇒ CC2 报「契约 N 条 / 代码 M 条」+ CC4 报漂移; - `[OFFICIAL]` 漏一条 ⇒ CC10 报「代码注册了面 B 路由,但台账里没有这一条」。 ⇒ 本脚本把**代码侧的路由 + 守卫推导**作为真源,**自动生成**登记行。 🔴 **不覆盖、只追加**:脚本只在 `[ENDPOINT]` / `[OFFICIAL]` 段的**末尾** 追加**本仓代码里已有、但契约里还没有**的端点 ⇒ 已有登记**不动** (契约里人工写的 note / 状态不会被冲掉)。 🔴 守卫**不猜**:直接调用 `check-contract-scan.py` 的 `guard_of_platform` (与 CC6 **同一套**推导规则)⇒ 生成的 guard 必然与代码一致 ⇒ CC6 不会因为「登记时的手抖」而假漂移。 用法: python3 scripts/gen-contract-endpoints.py # 生成并写入 docs/contract.md python3 scripts/gen-contract-endpoints.py --dry-run # 只打印,不写 python3 scripts/gen-contract-endpoints.py --only online_dev,report """ import importlib.util import os import re import sys HERE = os.path.dirname(os.path.abspath(__file__)) ROOT = os.path.dirname(HERE) CONTRACT = os.path.join(ROOT, "docs", "contract.md") def _load(name, path): spec = importlib.util.spec_from_file_location(name, path) mod = importlib.util.module_from_spec(spec) spec.loader.exec_module(mod) return mod S = _load("ccs", os.path.join(HERE, "check-contract-scan.py")) # 🔴 **官方出处表**(`文件:行号`)—— 手工核对过官方 Java Controller 的 # `@XxxMapping` 行号(批次 17 逐条查证)。 # 键 = `(method, 官方路径)`;值 = (出处, 备注模板)。 # # 🔴 **官方 `/api/Report/*` 是独立部署的第三方服务** # (`jnpf-java-datareport-univer`,端口 32000)—— 主后端 `jnpf-java-boot` # 里**没有** `/api/Report` 的 Controller ⇒ 出处只能指向**官方前端** # 的 `api/onlineDev/report.ts`(本仓按官方前端的消费点定契约)。 REPORT_SRC = "api/onlineDev/report.ts" # onlineDev:官方 Controller(`jnpf-visualdev` 模块)⇒ 文件名 + 映射行号 _VISUALDEV_CONTROLLERS = { "VisualdevController.java": { "GET /api/visualdev/Base": 134, "GET /api/visualdev/Base/list": 180, "GET /api/visualdev/Base/Selector": 210, "GET /api/visualdev/Base/{id}": 328, "GET /api/visualdev/Base/{id}/FormDataFields": 348, "GET /api/visualdev/Base/{id}/FieldDataSelect": 363, "POST /api/visualdev/Base/{id}/Actions/Copy": 377, "PUT /api/visualdev/Base/{id}": 429, "POST /api/visualdev/Base": 504, "DELETE /api/visualdev/Base/{id}": 578, "POST /api/visualdev/Base/{id}/Actions/Release": 600, "POST /api/visualdev/Base/{id}/Actions/Module": 687, "GET /api/visualdev/Base/{id}/getReleaseMenu": 738, "GET /api/visualdev/Base/getColumnList": 764, "GET /api/visualdev/Base/getListBySystem": 819, }, "VisualdevShortLinkController.java": { "GET /api/visualdev/ShortLink/{id}": 101, "PUT /api/visualdev/ShortLink": 139, "GET /api/visualdev/ShortLink/getConfig/{id}": 229, "POST /api/visualdev/ShortLink/checkPwd": 244, "GET /api/visualdev/ShortLink/Config": 263, "POST /api/visualdev/ShortLink/{id}/ListLink": 292, "GET /api/visualdev/ShortLink/{id}/{id}/DataChange": 322, "POST /api/visualdev/ShortLink/{id}": 341, }, "VisualdevGenController.java": { "POST /api/visualdev/Generater/{id}/Actions/DownloadCode": 122, "POST /api/visualdev/Generater/{id}/Actions/CodePreview": 175, "GET /api/visualdev/Generater/{id}/Alias/Info": 289, "POST /api/visualdev/Generater/{id}/Alias/Save": 298, }, "VisualdevModelDataController.java": { "POST /api/visualdev/OnlineDev/{model_id}/List": 312, "GET /api/visualdev/OnlineDev/{model_id}/Config": 417, "GET /api/visualdev/OnlineDev/{model_id}/FormData": 460, "GET /api/visualdev/OnlineDev/{model_id}/{id}": 470, "POST /api/visualdev/OnlineDev/{model_id}/DataChange": 484, "POST /api/visualdev/OnlineDev/{model_id}": 515, "PUT /api/visualdev/OnlineDev/{model_id}/{id}": 545, "DELETE /api/visualdev/OnlineDev/{model_id}/{id}": 574, "POST /api/visualdev/OnlineDev/batchDelete/{model_id}": 638, "POST /api/visualdev/OnlineDev/{model_id}/Actions/ExportData": 790, "POST /api/visualdev/OnlineDev/{model_id}/Actions/Export": 855, "POST /api/visualdev/OnlineDev/{model_id}/actionLaunchFlow": 1103, "GET /api/visualdev/OnlineDev/Config": 1143, "POST /api/visualdev/OnlineDev/RelationQuery": 1177, }, "VisualPersonalController.java": { "GET /api/visualdev/personal": 51, "POST /api/visualdev/personal": 60, "GET /api/visualdev/personal/{id}": 86, "PUT /api/visualdev/personal/{id}": 96, "PUT /api/visualdev/personal/{id}/setDefault": 118, "DELETE /api/visualdev/personal/{id}": 140, }, "VisualLogController.java": { "GET /api/visualdev/OnlineLog": 39, }, "SystemShareController.java": { "GET /api/visualdev/share": 61, "POST /api/visualdev/share/SelectedList": 72, "POST /api/visualdev/share/save": 80, "GET /api/visualdev/share/Selector": 87, }, "OcrController.java": { "POST /api/visualdev/ocr": 48, }, "PortalController.java": { "GET /api/visualdev/Portal": 94, "GET /api/visualdev/Portal/Selector": 106, "GET /api/visualdev/Portal/Selector/Menu": 115, "GET /api/visualdev/Portal/{id}": 122, "DELETE /api/visualdev/Portal/{id}": 149, "POST /api/visualdev/Portal": 165, "POST /api/visualdev/Portal/{id}/Actions/Copy": 192, "PUT /api/visualdev/Portal/{id}": 217, "POST /api/visualdev/Portal/{id}/Actions/Export": 256, "GET /api/visualdev/Portal/systemFilter/{id}": 347, }, "PortalDataController.java": { "PUT /api/visualdev/Portal/{id}/Actions/SetDefault": 57, "PUT /api/visualdev/Portal/Custom/Save/{id}": 71, "PUT /api/visualdev/Portal/Actions/release/{id}": 93, "GET /api/visualdev/Portal/{id}/auth": 114, }, "DashboardController.java": { "POST /api/visualdev/Dashboard/Notice": 45, "GET /api/visualdev/Dashboard/Email": 59, }, } # 🔴 **官方没有 Java Controller** 的少数几条 ⇒ 出处指向**官方前端 api 文件** # (官方就是靠前端声明访问这些端点的)。 FRONTEND_ONLY_SOURCES = { "GET /api/system/PortalManage/list/{system_id}": "api/onlineDev/portal.ts:79", "GET /api/system/PortalManage/{id}": "api/onlineDev/portal.ts:87", "POST /api/system/PortalManage": "api/onlineDev/portal.ts:91", "PUT /api/system/PortalManage/{id}": "api/onlineDev/portal.ts:95", "DELETE /api/system/PortalManage/{id}": "api/onlineDev/portal.ts:99", "GET /api/system/atlas": "ProvinceAtlasController.java:78", "GET /api/system/atlas/geojson": "ProvinceAtlasController.java:121", "GET /api/blade-visual/visual/Selector": "VisualController.java:288", "GET /api/visualdev/Portal/manage/Selector/{system_id}": "api/onlineDev/portal.ts:84", # 🔴 官方前端声明了,但官方 Java **没有**对应 `@XxxMapping` # (Controller 里只有 `/TemplateDownload`)⇒ 出处指向官方前端声明行。 "GET /api/visualdev/OnlineDev/{model_id}/Template": "api/onlineDev/visualDev.ts:137", "POST /api/visualdev/OnlineDev/{model_id}/Actions/Export": "api/onlineDev/visualDev.ts:141", } # 🔴 官方前端 `api/onlineDev/report.ts` 的行号(逐条核对过官方源文件)。 REPORT_FRONTEND_LINES = { "GET /api/Report": 14, "POST /api/Report": 18, "PUT /api/Report/{id}": 22, "GET /api/Report/{id}": 26, "DELETE /api/Report/{id}": 30, "POST /api/Report/{id}/Actions/Copy": 34, "GET /api/Report/{id}/Actions/Export": 42, "POST /api/Report/Data": 46, "POST /api/Report/Save": 50, "GET /api/Report/Info/{id}": 54, "GET /api/Report/Version/{id}": 58, "DELETE /api/Report/Info/{id}": 62, "POST /api/Report/Info/{id}": 66, "POST /api/Report/data/{id}/preview": 70, "POST /api/Report/data/{id}/previewTemplate": 74, "GET /api/Report/Selector": 78, "POST /api/Report/data/upload/file": 82, "POST /api/Report/data/downImg": 86, "POST /api/Report/data/ImportExcel": 90, "POST /api/Report/data/{id}/DownExcel": 94, "GET /api/Report/{id}/getReleaseMenu": 98, "POST /api/Report/{id}/Actions/Module": 102, "GET /api/Report/data/{id}/getQueryList": 106, } # 🔴 **状态判定**:本仓**诚实失败**(无文件服务 / 无渲染器 / 无数据引擎) # 的端点 ⇒ `partial`(已落地但**形状有偏差**);完全对齐 ⇒ `implemented`。 # 键 = `(method, path)`;值 = (status, note)。 PARTIAL_NOTES = { # ---- Report:无文件服务 / 无 Univer 渲染器 / 无数据引擎 ⇒ 明确业务失败 ---- ("POST", "/api/Report/data/upload/file"): ( "partial", "本仓无文件服务 ⇒ **明确业务失败**(不返假 URL)"), ("POST", "/api/Report/data/downImg"): ( "partial", "本仓无文件服务 ⇒ **明确业务失败**(不返假 URL)"), ("POST", "/api/Report/data/ImportExcel"): ( "partial", "本仓无 Excel 引擎 ⇒ **明确业务失败**"), ("POST", "/api/Report/data/{id}/DownExcel"): ( "partial", "本仓无 Excel 引擎 ⇒ **明确业务失败**"), ("POST", "/api/Report/data/{id}/preview"): ( "partial", "本仓无 Univer 渲染器 ⇒ **明确业务失败**(不返假 URL)"), ("POST", "/api/Report/data/{id}/previewTemplate"): ( "partial", "本仓无 Univer 渲染器 ⇒ **明确业务失败**(不返假 URL)"), ("GET", "/api/Report/{id}/Actions/Export"): ( "partial", "本仓无数据引擎 ⇒ **明确业务失败**"), ("POST", "/api/Report/Data"): ( "partial", "本仓无数据引擎 ⇒ **明确业务失败**"), ("POST", "/api/Report/{id}/Actions/Module"): ( "partial", "菜单 URL 用官方前端路由 `/reportPreview`(`router/routes/core.ts:92`);" "本仓无菜单服务 ⇒ 只回填 id / 父节点"), ("GET", "/api/Report/{id}/getReleaseMenu"): ( "partial", "本仓无菜单服务 ⇒ `pcIsRelease`/`appIsRelease` 恒 false," "两个 `*ReleaseName` 恒空串(官方消费这四个字段)"), # ---- onlineDev:官方依赖**代码生成器 / 表引擎 / 流程引擎**的部分 ---- ("POST", "/api/visualdev/Generater/{id}/Actions/DownloadCode"): ( "partial", "本仓无代码生成器 ⇒ **明确业务失败**"), ("POST", "/api/visualdev/Generater/{id}/Actions/CodePreview"): ( "partial", "本仓无代码生成器 ⇒ **明确业务失败**"), ("GET", "/api/visualdev/Generater/{id}/Alias/Info"): ( "partial", "本仓无代码生成器别名表 ⇒ 恒空"), ("POST", "/api/visualdev/Generater/{id}/Alias/Save"): ( "partial", "本仓无代码生成器别名表 ⇒ **明确业务失败**"), ("POST", "/api/visualdev/OnlineDev/{model_id}/Actions/Export"): ( "partial", "本仓无代码生成器 ⇒ **明确业务失败**"), ("GET", "/api/visualdev/OnlineDev/{model_id}/Template"): ( "partial", "本仓无代码生成器 ⇒ **明确业务失败**"), ("POST", "/api/visualdev/OnlineDev/{model_id}/DataChange"): ( "partial", "本仓无数据引擎(在线表单的数据增删改查)⇒ **明确业务失败**"), ("POST", "/api/visualdev/OnlineDev/{model_id}/List"): ( "partial", "本仓无数据引擎(在线表单的数据列表)⇒ **明确业务失败**"), ("GET", "/api/visualdev/OnlineDev/{model_id}/FormData"): ( "partial", "本仓无数据引擎(在线表单的表结构)⇒ **明确业务失败**"), ("POST", "/api/visualdev/OnlineDev/{model_id}"): ( "partial", "本仓无数据引擎(在线表单建表)⇒ **明确业务失败**"), ("PUT", "/api/visualdev/OnlineDev/{model_id}/{id}"): ( "partial", "本仓无数据引擎(在线表单改表)⇒ **明确业务失败**"), ("GET", "/api/visualdev/OnlineDev/{model_id}/{id}"): ( "partial", "本仓无数据引擎(在线表单数据详情)⇒ **明确业务失败**"), ("DELETE", "/api/visualdev/OnlineDev/{model_id}/{id}"): ( "partial", "本仓无数据引擎(在线表单删表)⇒ **明确业务失败**"), ("POST", "/api/visualdev/OnlineDev/batchDelete/{model_id}"): ( "partial", "本仓无数据引擎 ⇒ **明确业务失败**"), ("POST", "/api/visualdev/OnlineDev/{model_id}/Actions/ExportData"): ( "partial", "本仓无 Excel 引擎 ⇒ **明确业务失败**"), ("POST", "/api/visualdev/OnlineDev/{model_id}/actionLaunchFlow"): ( "partial", "本仓无流程引擎 ⇒ **明确业务失败**"), ("GET", "/api/visualdev/Base/{id}/FieldDataSelect"): ( "partial", "本仓无数据引擎(关联数据分页)⇒ **明确业务失败**"), ("POST", "/api/visualdev/ocr"): ( "partial", "本仓无 OCR 服务 ⇒ **明确业务失败**"), ("GET", "/api/system/atlas/geojson"): ( "partial", "本仓无省级行政区划 GeoJSON 数据 ⇒ **明确业务失败**"), ("GET", "/api/blade-visual/visual/Selector"): ( "partial", "本仓无 DataV 组件库 ⇒ 恒空列表"), ("POST", "/api/visualdev/Portal/{id}/Actions/Export"): ( "partial", "本仓无文件服务 ⇒ **明确业务失败**"), } # 🔴 **端点顺序**:按官方模块分组,组内按路径排 —— 与 `routes.rs` 的注册顺序对齐 # (⇒ 契约读起来与代码读起来同序 ⇒ 人工 review 不用来回跳)。 MODULE_ORDER = ["online_dev", "report"] # 🔴 **默认 note**(未在 `PARTIAL_NOTES` 里显式标注的端点)。 DEFAULT_NOTES = { "online_dev": "面 B 已落地:按官方 `jnpf-visualdev` 的 Controller 形状实现", "report": "面 B 已落地:官方 `/api/Report/*` 在官方是**独立部署的第三方服务**" "(`jnpf-java-datareport-univer`,端口 32000)⇒ 本仓把报表元数据**就地落库**" "(`report_template` + `report_version`,表结构照官方 DDL 逐字导入)", } def norm_path(p): return re.sub(r"\{[^/{}]*\}", "{}", p) def build_rows(modules): """⇒ (endpoint_rows, official_rows) —— 两张表都是「代码里已有、契约里还没有」的。""" snap = S.scan_code(os.path.join(ROOT, "src", "backend", "src"), os.path.join(ROOT, "packs")) plat_files = snap["plat_files"] plat_consts = snap.get("plat_consts") or {} # 契约里**已经登记**的(method, 归一路径) sections = S.contract_expect.load_sections(CONTRACT) done_ep = set() for e in sections["ENDPOINT"]: done_ep.add((e["method"], norm_path(e["path"]))) done_off = set() for o in sections["OFFICIAL"]: if o["method"] != "*": done_off.add((o["method"], norm_path(o["path"]))) ep_rows = [] off_rows = [] for r in snap["plat"]: if r.get("source") != "platform": continue mp = r.get("mod_path") or "" if not mp.startswith("compat::"): continue mod = r["mod"] if mod not in modules: continue guard = S.guard_of_platform(plat_files, mod, r["fn"], mp, plat_consts) if guard is None: raise SystemExit("推不出守卫:%s %s(%s::%s)" % (r["method"], r["path"], mod, r["fn"])) key = (r["method"], r["path"]) nkey = (r["method"], norm_path(r["path"])) if nkey not in done_ep: ep_rows.append(("B", r["method"], r["path"], guard, "platform")) done_ep.add(nkey) if nkey in done_off: continue src, status, note = official_entry(mod, key, r["path"]) off_rows.append((r["method"], r["path"], status, src, note)) done_off.add(nkey) return ep_rows, off_rows def official_entry(mod, key, path): """⇒ (src, status, note) —— 官方出处 + 落地状态 + 偏差说明。""" method = key[0] if mod == "report": line = REPORT_FRONTEND_LINES.get("%s %s" % (method, path)) src = "%s:%d" % (REPORT_SRC, line) if line else REPORT_SRC status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["report"])) return src, status, note # onlineDev k = "%s %s" % (method, path) for ctrl, table in _VISUALDEV_CONTROLLERS.items(): if k in table: src = "%s:%d" % (ctrl, table[k]) status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["online_dev"])) return src, status, note src = FRONTEND_ONLY_SOURCES.get(k) if src: status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["online_dev"])) return src, status, note raise SystemExit("没有官方出处可登记:%s %s" % (method, path)) def append_to_contract(ep_rows, off_rows, dry=False): """把两批行写进 `docs/contract.md`(追加到对应段的末尾)。""" with open(CONTRACT, encoding="utf-8") as fh: text = fh.read() def append_at(section, rows, render): marker = "\n[%s]\n" % section i = text.find(marker) if i < 0: raise SystemExit("契约里找不到区段 [%s]" % section) # 找到该区的**结束**位置(下一个 `[\n` 开头的区段,或围栏结束) j = text.find("\n[", i + len(marker)) if j < 0: j = len(text) block = text[i:j] if not rows: return text add = "".join(render(r) for r in rows) return text[:j] + add + text[j:] if ep_rows: text = append_at("ENDPOINT", ep_rows, lambda r: "%s\t%s\t%s\t%s\t%s\n" % r) if off_rows: text = append_at("OFFICIAL", off_rows, lambda r: "%s\t%s\t%s\t%s\t%s\n" % r) if dry: for r in ep_rows: print("EP\t" + "\t".join(r)) for r in off_rows: print("OFF\t" + "\t".join(r)) return with open(CONTRACT, "w", encoding="utf-8") as fh: fh.write(text) def main(argv): modules = MODULE_ORDER dry = False if "--dry-run" in argv: dry = True if "--only" in argv: i = argv.index("--only") modules = [m.strip() for m in argv[i + 1].split(",") if m.strip()] ep_rows, off_rows = build_rows(modules) append_to_contract(ep_rows, off_rows, dry) if not dry: print("已写入 %s:[ENDPOINT] +%d 条 / [OFFICIAL] +%d 条" % (os.path.relpath(CONTRACT, ROOT), len(ep_rows), len(off_rows))) return 0 if __name__ == "__main__": sys.exit(main(sys.argv))