Files
ssw-platform/scripts/gen-contract-endpoints.py
T
admin 1c224b7b79 feat(core): 补齐 core 族 22 条端点并同步契约三处
按官方三源(LoginController / UtilsController / LocationController +
官方前端 api/core/*.ts)逐条核对,实现 22 条 core 端点:
- 真实现 6 条:锁屏解锁、免密登录票据、扫码凭证状态流转
- 诚实失败 16 条:文件族 4 + 导入族 4 + 地图族 3 + 改密通知 1
  + SaaS 族 3 + socials 1(无文件存储 / 无导入引擎 / 无地图服务 /
  无邮件短信通道 / 无多租户切库 / 无第三方账号 ⇒ code=400 + 人话,
  不返假 URL、不返假坐标)

新增 TicketStore(进程内内存票据表,官方用 Redis 而本仓无 Redis):
两种票据带前缀隔离(tkt- / scc-),不互相串用。

同批修掉一个真偏差:Login/saas 原先写成 let _ = require_login_face_b(..)
丢弃了 Err ⇒ 实际不拦,但静态闸门推成「登录」⇒ 契约标签与运行时行为
不符;已改成真拦(官方 TenantSaasGranter.checkTenantUser 要求已有登录态)。

契约三处同步:[ENDPOINT] +22 / [OFFICIAL] +22 / [FACE] 面 B 558→580,
并顺手修正契约 §6 头两个无人校验的散文数字(132→610 条、53→607 行)。
2026-11-02 17:34:03 +08:00

540 lines
27 KiB
Python
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 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"
# 🔴 core 族(批次 18):官方 `jnpf-oauth` 的 `LoginController` +
# `jnpf-file` 的 `UtilsController` + `jnpf-system` 的 `LocationController`。
#
# 🔴 **core 族在官方前端全是「只有声明、没有消费点」**
# (`api/core/{auth,common,user}.ts` 里声明了,但两个前端版本里都搜不到
# 调用点)⇒ **形状以官方 Java 为准**,不能照前端消费点猜。
_CORE_CONTROLLERS = {
# 官方 `jnpf-oauth` 的 `LoginController`(`@RequestMapping("/api/oauth")`)
"LoginController.java": {
"POST /api/oauth/LockScreen": 130,
"POST /api/oauth/updatePasswordMessage": 269,
"GET /api/oauth/getConfig/{account}": 318,
"GET /api/oauth/getLoginConfig": 349,
"GET /api/oauth/getTicket": 383,
"GET /api/oauth/getTicketStatus/{ticket}": 398,
"GET /api/oauth/codeCertificate": 454,
"GET /api/oauth/codeCertificateStatus/{ticket}": 468,
"GET /api/oauth/setCodeCertificateStatus/{ticket}/{status}": 507,
"POST /api/oauth/Login/saas": 554,
"POST /api/oauth/apply/saas": 562,
"GET /api/oauth/mobilecode/saas": 571,
},
# 官方 `jnpf-file` 的 `UtilsController`(`@RequestMapping("/api/file")`)
"UtilsController.java": {
"GET /api/file/Download/{fileType}/{fileName}": 200,
"POST /api/file/PackDownload/{fileType}": 100,
"GET /api/file/Uploader/Preview": 277,
"POST /api/file/merge": 295,
},
# 官方 `jnpf-system` 的 `LocationController`(`@RequestMapping("/api/system/Location")`)
"LocationController.java": {
"GET /api/system/Location/around": 32,
"GET /api/system/Location/text": 47,
"GET /api/system/Location/inputtips": 62,
},
}
# 🔴 core 族里**官方 Java 没有独立 `@XxxMapping`** 的一条:
# `/api/oauth/Login/socials` —— 官方**没有**独立的 `socials` 映射,
# 它走 `LoginController.java:117` 的 `@RequestMapping("/Login/**")` 通配,
# 由 `SocialsTokenGranter`(`grant_type=socials`)分流。
# (官方前端 `api/core/user.ts:43` 只是**声明**了它。)
CORE_FRONTEND_OR_INDIRECT = {
"POST /api/oauth/Login/socials": "LoginController.java:117",
}
# 🔴 **导入族**:官方前端用 `/api/${url}/Xxx` 拼(`url` 是**模块名**)
# ⇒ 官方**每个模块的 Controller 各有一份**同路径的映射
# (`BaseLangController.java:142` / `VisualdevModelDataController.java:944` /
# `EmployeeController.java:208` / `VisualdevModelDataController.java:1000` /
# `VisualdevModelDataController.java:733` / `BaseLangController.java:182` /
# `VisualdevModelDataController.java:1073`)⇒ 出处指**其中一份**即可。
_CORE_IMPORT_SOURCES = {
"GET /api/{prefix}/TemplateDownload": "VisualdevModelDataController.java:944",
"GET /api/{prefix}/ImportPreview": "VisualdevModelDataController.java:1000",
"POST /api/{prefix}/ImportData": "VisualdevModelDataController.java:733",
"POST /api/{prefix}/ImportExceptionData": "VisualdevModelDataController.java:1073",
}
# 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", "本仓无文件服务 ⇒ **明确业务失败**"),
# ---- core(批次 18):框架自带能力 —— 本仓按「有落库/内存表可做」与
# 「能力缺失」分两类,逐条诚实落地。
("POST", "/api/oauth/LockScreen"): (
"implemented", "面 B 已落地:按**本仓口令口径**(`md5(明文)`,非官方 "
"`md5(明文+secretkey)`)校验 `base_user.f_password`;"
"账号不存在与口令错统一返「账号或密码错误」(防账号枚举)"),
("GET", "/api/oauth/getTicket"): (
"implemented", "面 B 已落地:照抄官方 `ActionResult.success(msg, data)` 的"
"**错位** —— 有效期(毫秒时间戳)进 `msg`、票据进 `data`;"
"官方票据存 Redis ⇒ 本仓用进程内内存表(进程重启即失效)"),
("GET", "/api/oauth/getTicketStatus/{ticket}"): (
"implemented", "面 B 已落地:返官方 `LoginTicketModel`(恰好 4 字段 "
"`status`/`value`/`theme`/`ticketTimeout`);"
"票据查不到返 `status=1`(**不报错**,照官方)"),
("GET", "/api/oauth/codeCertificate"): (
"implemented", "面 B 已落地:与 `getTicket` 同构(`msg`=超时、`data`=凭证);"
"扫码凭证与登录票据是**两张表**(`scc-` / `tkt-` 前缀),不串用"),
("GET", "/api/oauth/codeCertificateStatus/{ticket}"): (
"implemented", "面 B 已落地:返官方 `LoginTicketModel` 形状;查不到返 `status=1`"),
("GET", "/api/oauth/setCodeCertificateStatus/{ticket}/{status}"): (
"implemented", "面 B 已落地:改状态并**续期**(官方 `updateTicket` 同款);"
"凭证不存在返 `status=1` 的空模型(不报错)"),
("POST", "/api/oauth/updatePasswordMessage"): (
"partial", "本仓无邮件 / 短信通道 ⇒ **明确业务失败**(不假装发成功)"),
("POST", "/api/oauth/Login/saas"): (
"partial", "本仓无多租户数据源切换 ⇒ **明确业务失败**"),
("GET", "/api/oauth/mobilecode/saas"): (
"partial", "本仓无短信通道 ⇒ **明确业务失败**"),
("POST", "/api/oauth/apply/saas"): (
"partial", "本仓未接入官方 SaaS 平台 ⇒ **明确业务失败**"),
("POST", "/api/oauth/Login/socials"): (
"partial", "本仓无第三方账号配置 ⇒ **明确业务失败**"),
("GET", "/api/file/Download/{fileType}/{fileName}"): (
"partial", "本仓无文件存储 ⇒ **明确业务失败**(**不返假 URL**)"),
("POST", "/api/file/PackDownload/{fileType}"): (
"partial", "本仓无文件存储 ⇒ **明确业务失败**(**不返假 URL**)"),
("GET", "/api/file/Uploader/Preview"): (
"partial", "本仓无文件存储 ⇒ **明确业务失败**(官方返预览流)"),
("POST", "/api/file/merge"): (
"partial", "本仓无文件存储 ⇒ **明确业务失败**(分片无处可合)"),
("GET", "/api/{prefix}/TemplateDownload"): (
"partial", "本仓无导入模板文件 ⇒ **明确业务失败**"),
("GET", "/api/{prefix}/ImportPreview"): (
"partial", "本仓无导入引擎 ⇒ **明确业务失败**"),
("POST", "/api/{prefix}/ImportData"): (
"partial", "本仓无导入引擎 ⇒ **明确业务失败**"),
("POST", "/api/{prefix}/ImportExceptionData"): (
"partial", "本仓无导入引擎 ⇒ **明确业务失败**"),
("GET", "/api/system/Location/around"): (
"partial", "本仓无地图服务(无高德 key + `Cargo.toml` 里**无 HTTP 客户端**)"
"⇒ **明确业务失败**(**不返假坐标**)"),
("GET", "/api/system/Location/text"): (
"partial", "本仓无地图服务 ⇒ **明确业务失败**(**不返假坐标**)"),
("GET", "/api/system/Location/inputtips"): (
"partial", "本仓无地图服务 ⇒ **明确业务失败**(**不返假坐标**)"),
}
# 🔴 **端点顺序**:按官方模块分组,组内按路径排 —— 与 `routes.rs` 的注册顺序对齐
# (⇒ 契约读起来与代码读起来同序 ⇒ 人工 review 不用来回跳)。
MODULE_ORDER = ["core", "online_dev", "report"]
# 🔴 **默认 note**(未在 `PARTIAL_NOTES` 里显式标注的端点)。
DEFAULT_NOTES = {
"core": "面 B 已落地:按官方 `jnpf-oauth` / `jnpf-file` / `jnpf-system` "
"的 Controller 形状实现",
"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
k = "%s %s" % (method, path)
if mod == "core":
# 🔴 core 族的官方出处**分三层**(批次 18 逐条核对):
# ① 官方 Java Controller 有独立 `@XxxMapping` ⇒ 出处指 Java 行号;
# ② 官方 Java **没有**独立映射(走 `/Login/**` 通配)⇒ 出处指通配行号;
# ③ 导入族(官方前端用 `/api/${url}/Xxx` 拼,官方各模块 Controller
# 各有一份)⇒ 出处指**其中一份**即可。
for ctrl, table in _CORE_CONTROLLERS.items():
if k in table:
src = "%s:%d" % (ctrl, table[k])
status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["core"]))
return src, status, note
src = CORE_FRONTEND_OR_INDIRECT.get(k)
if src:
status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["core"]))
return src, status, note
src = _CORE_IMPORT_SOURCES.get(k)
if src:
status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["core"]))
return src, status, note
raise SystemExit("core 族没有官方出处可登记:%s %s" % (method, path))
# onlineDev
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))