#!/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, }, } # 🔴 **流程族(批次 19)**:官方 `jnpf-flowable` 的 Controller。 # 键 = `(method, 本仓路径)`(本仓路径与官方路径**同段**,只把路径段名归一)。 _WORKFLOW_CONTROLLERS = { # 官方 `jnpf-flowable` 的 `TemplateController`(`@RequestMapping("/api/workflow/template")`) "TemplateController.java": { "GET /api/workflow/template": 117, "GET /api/workflow/template/Selector": 150, "GET /api/workflow/template/TreeList": 202, "GET /api/workflow/template/{id}": 216, "GET /api/workflow/template/Version/{id}": 230, "GET /api/workflow/template/Info/{id}": 253, "POST /api/workflow/template": 265, "PUT /api/workflow/template/{id}": 285, "PUT /api/workflow/template/{id}/UpdateType": 308, "DELETE /api/workflow/template/{id}": 323, "DELETE /api/workflow/template/Info/{id}": 338, "PUT /api/workflow/template/{id}/UpDownShelf": 364, "POST /api/workflow/template/{id}/Actions/Copy": 385, "POST /api/workflow/template/Info/{id}": 400, "POST /api/workflow/template/Save": 415, "GET /api/workflow/template/{id}/Actions/Export": 428, "POST /api/workflow/template/GetFlowList": 467, "GET /api/workflow/template/{id}/FormInfo": 487, "GET /api/workflow/template/{id}/DecisionParameter": 499, # 🔴 官方路径段名是 `{formId}`(`getFlowByFormId`)—— 本仓按前端调用 # 归一成 `{id}`(**同一条路由**),语义在 `workflow.rs` 里写明。 "GET /api/workflow/template/{id}/FlowList": 511, "GET /api/workflow/template/{id}/SubFlowUserList": 524, "POST /api/workflow/template/SetCommonFlow/{id}": 540, "GET /api/workflow/template/getCommonFlowList": 553, "GET /api/workflow/template/StartForm/{id}": 566, "GET /api/workflow/template/StartFormId/{id}": 578, }, # 官方 `CommentController`(`@RequestMapping("/api/workflow/comment")`) "CommentController.java": { "GET /api/workflow/comment": 76, "POST /api/workflow/comment": 150, "DELETE /api/workflow/comment/{id}": 166, }, # 官方 `DelegateController`(`@RequestMapping("/api/workflow/delegate")`) "DelegateController.java": { "GET /api/workflow/delegate": 76, "GET /api/workflow/delegate/Info/{id}": 94, "GET /api/workflow/delegate/{id}": 106, "POST /api/workflow/delegate": 133, "PUT /api/workflow/delegate/{id}": 177, "PUT /api/workflow/delegate/Stop/{id}": 263, "DELETE /api/workflow/delegate/{id}": 285, "GET /api/workflow/delegate/UserList": 300, "POST /api/workflow/delegate/Notarize/{id}": 314, }, # 官方 `OperatorController`(`@RequestMapping("/api/workflow/operator")`) "OperatorController.java": { "POST /api/workflow/operator/CandidateNode/{id}": 99, "POST /api/workflow/operator/CandidateUser/{id}": 115, "GET /api/workflow/operator/List/{category}": 134, "POST /api/workflow/operator/Sign": 184, "POST /api/workflow/operator/Transact": 196, "POST /api/workflow/operator/SaveAudit/{id}": 209, "POST /api/workflow/operator/Audit/{id}": 224, "POST /api/workflow/operator/AddSign/{id}": 274, "POST /api/workflow/operator/AddSignUserIdList/{id}": 293, "POST /api/workflow/operator/ReduceApprover/{id}": 308, "GET /api/workflow/operator/SendBackNodeList/{id}": 325, "POST /api/workflow/operator/SendBack/{id}": 339, "POST /api/workflow/operator/Recall/{id}": 367, "POST /api/workflow/operator/Transfer/{id}": 406, "POST /api/workflow/operator/Assist/{id}": 428, "POST /api/workflow/operator/AssistSave/{id}": 443, "GET /api/workflow/operator/BatchFlowSelector": 455, "GET /api/workflow/operator/BatchVersionSelector/{id}": 467, "GET /api/workflow/operator/BatchNodeSelector/{id}": 479, "GET /api/workflow/operator/BatchNode": 491, "GET /api/workflow/operator/BatchCandidate": 505, "POST /api/workflow/operator/BatchOperation": 518, "GET /api/workflow/operator/{id}/Info": 549, "GET /api/workflow/operator/RecordList": 579, "GET /api/workflow/operator/CirculateList": 592, }, # 官方 `TaskController`(`@RequestMapping("/api/workflow/task")`) "TaskController.java": { "GET /api/workflow/task/{id}": 103, "POST /api/workflow/task": 127, "PUT /api/workflow/task/{id}": 147, "DELETE /api/workflow/task/{id}": 181, "GET /api/workflow/task": 193, "PUT /api/workflow/task/Recall/{id}": 218, "POST /api/workflow/task/Press/{id}": 233, "PUT /api/workflow/task/Revoke/{id}": 247, "GET /api/workflow/task/TaskUserList/{id}": 261, "GET /api/workflow/task/SubFlowInfo": 279, "GET /api/workflow/task/ViewStartForm/{id}": 291, "GET /api/workflow/task/Hooks/Retry/{id}": 301, }, # 官方 `TriggerWebHookController`(`@RequestMapping("/api/workflow/Hooks")`) "TriggerWebHookController.java": { "GET /api/workflow/Hooks/getUrl": 92, "GET /api/workflow/Hooks/{id}/start/{randomStr}": 170, "GET /api/workflow/Hooks/getParams/{randomStr}": 180, }, # 官方 `WorkflowMonitorController`(`@RequestMapping("/api/workflow/monitor")`) "WorkflowMonitorController.java": { "GET /api/workflow/monitor": 64, "DELETE /api/workflow/monitor": 102, "GET /api/workflow/monitor/AnySubFlow/{id}": 115, "POST /api/workflow/monitor/Pause/{id}": 127, "POST /api/workflow/monitor/Reboot/{id}": 143, "POST /api/workflow/monitor/Cancel/{id}": 159, "POST /api/workflow/monitor/Activate/{id}": 175, "POST /api/workflow/monitor/Assign/{id}": 191, "POST /api/workflow/monitor/FlowTodoCount": 205, "GET /api/workflow/monitor/FlowTodo": 218, }, # 官方 `TriggerTaskController`(`@RequestMapping("/api/workflow/trigger/task")`) "TriggerTaskController.java": { "GET /api/workflow/trigger/task/List": 59, "GET /api/workflow/trigger/task": 72, "POST /api/workflow/trigger/task/Retry/{id}": 97, "DELETE /api/workflow/trigger/task": 110, }, } # 🔴 **流程族里官方 Java 没有对应 `@XxxMapping`** 的 13 条 ⇒ 出处指向官方前端 # `api/workFlow/**`(官方就是靠前端声明访问这些端点的)。 # # 🔴 `/api/flowForm/Form/**` 11 条:官方**整个 `jnpf-java-boot` 树里没有** # 任何 Controller 声明过这个前缀(在线表单设计器官方也没后端)⇒ 全部前端出处。 _WORKFLOW_FRONTEND_ONLY = { "GET /api/workflow/task/{id}/EventLog": "api/workFlow/task.ts:51", "GET /api/workflow/monitor/{id}/EventLog": "api/workFlow/flowMonitor.ts:17", "GET /api/flowForm/Form": "api/workFlow/formDesign.ts:9", "POST /api/flowForm/Form": "api/workFlow/formDesign.ts:13", "PUT /api/flowForm/Form": "api/workFlow/formDesign.ts:17", "GET /api/flowForm/Form/{id}": "api/workFlow/formDesign.ts:21", "DELETE /api/flowForm/Form/{id}": "api/workFlow/formDesign.ts:25", "POST /api/flowForm/Form/Release/{id}": "api/workFlow/formDesign.ts:29", "GET /api/flowForm/Form/{id}/Actions/Copy": "api/workFlow/formDesign.ts:33", "GET /api/flowForm/Form/{id}/Actions/Export": "api/workFlow/formDesign.ts:37", "GET /api/flowForm/Form/{id}/getField": "api/workFlow/formDesign.ts:41", "GET /api/flowForm/Form/select": "api/workFlow/formDesign.ts:45", "GET /api/flowForm/Form/getFormById/{id}": "api/workFlow/formDesign.ts:49", } # 🔴 **官方没有 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", "本仓无地图服务 ⇒ **明确业务失败**(**不返假坐标**)"), } # 🔴 ---- 流程族(批次 19)---- # # 🔴 **官方流程引擎是独立 HTTP 服务**:官方前端把引擎地址配在 `FlowAbleUrl` # (`/api/Flow/*`)—— 本仓**没有**该服务 ⇒ 凡是「动作类」 # (发起 / 审批 / 办理 / 转审 / 撤回 / 撤销 / 退回 / 加签 / 减签 / 协办 / # 批量审批 / 暂停 / 终止 / 复活 / 重试 / 催办 / 签收 / 触发器)的端点 # ⇒ **明确业务失败**(绝不返假结果、假流程号)。 _WORKFLOW_ENGINE_PATHS = [ ("GET", "/api/workflow/Hooks/getUrl"), ("GET", "/api/workflow/Hooks/getParams/{randomStr}"), ("GET", "/api/workflow/Hooks/{id}/start/{randomStr}"), ("POST", "/api/workflow/task"), ("PUT", "/api/workflow/task/{id}"), ("PUT", "/api/workflow/task/Recall/{id}"), ("PUT", "/api/workflow/task/Revoke/{id}"), ("POST", "/api/workflow/task/Press/{id}"), ("GET", "/api/workflow/task/Hooks/Retry/{id}"), ("POST", "/api/workflow/operator/Sign"), ("POST", "/api/workflow/operator/Transact"), ("POST", "/api/workflow/operator/Audit/{id}"), ("POST", "/api/workflow/operator/ReduceApprover/{id}"), ("POST", "/api/workflow/operator/SaveAudit/{id}"), ("POST", "/api/workflow/operator/AssistSave/{id}"), ("POST", "/api/workflow/operator/Recall/{id}"), ("POST", "/api/workflow/operator/Transfer/{id}"), ("POST", "/api/workflow/operator/Assist/{id}"), ("POST", "/api/workflow/operator/BatchOperation"), ("POST", "/api/workflow/operator/SendBack/{id}"), ("POST", "/api/workflow/operator/AddSign/{id}"), ("POST", "/api/workflow/monitor/Cancel/{id}"), ("POST", "/api/workflow/monitor/Assign/{id}"), ("POST", "/api/workflow/monitor/Activate/{id}"), ("POST", "/api/workflow/monitor/Pause/{id}"), ("POST", "/api/workflow/monitor/Reboot/{id}"), ("POST", "/api/workflow/trigger/task/Retry/{id}"), ] for _m, _p in _WORKFLOW_ENGINE_PATHS: PARTIAL_NOTES[(_m, _p)] = ( "partial", "本仓未接入流程引擎(Flowable,官方是**独立 HTTP 服务** " "`FlowAbleUrl`)⇒ **明确业务失败**") # 🔴 **文件类**:本仓无文件服务 ⇒ 导出端点明确失败(**不返假文件 / 假 URL**)。 _WORKFLOW_FILE_PATHS = [ ("GET", "/api/workflow/template/{id}/Actions/Export"), ("GET", "/api/flowForm/Form/{id}/Actions/Export"), ] for _m, _p in _WORKFLOW_FILE_PATHS: PARTIAL_NOTES[(_m, _p)] = ( "partial", "本仓无文件服务 ⇒ **明确业务失败**(**不返假文件 / 假 URL**)") # 🔴 **在线表单设计器类**:本仓**没有 `visualdev_*` 表**(官方表单设计器是 # `jnpf-visualdev` 的在线表单)⇒ 表单本体查不到 ⇒ 明确失败。 _WORKFLOW_FORM_PATHS = [ ("GET", "/api/workflow/template/{id}/FormInfo"), ("GET", "/api/workflow/template/StartForm/{id}"), ("GET", "/api/workflow/template/StartFormId/{id}"), ("GET", "/api/workflow/task/ViewStartForm/{id}"), ("GET", "/api/flowForm/Form"), ("POST", "/api/flowForm/Form"), ("PUT", "/api/flowForm/Form"), ("GET", "/api/flowForm/Form/{id}"), ("DELETE", "/api/flowForm/Form/{id}"), ("POST", "/api/flowForm/Form/Release/{id}"), ("GET", "/api/flowForm/Form/{id}/Actions/Copy"), ("GET", "/api/flowForm/Form/{id}/getField"), ("GET", "/api/flowForm/Form/select"), ] for _m, _p in _WORKFLOW_FORM_PATHS: PARTIAL_NOTES[(_m, _p)] = ( "partial", "本仓无在线表单设计器(无 `visualdev_*` 表)⇒ **明确业务失败**") # 🔴 两条**已落地但形状有讲究**的 ⇒ 状态仍是 `implemented`,只补说明。 PARTIAL_NOTES[("GET", "/api/workflow/template/{id}/FlowList")] = ( "implemented", "面 B 已落地:官方路径段名是 `{formId}`(`getFlowByFormId`)," "前端按 `/{id}/FlowList` 调(**同一条路由**)⇒ 本仓按**表单主键**" "查 `workflow_node.f_form_id` → 版本 → 模板;`data` 是裸对象 " "`{list,isConfig}`(官方 `FlowByFormModel`)") PARTIAL_NOTES[("GET", "/api/flowForm/Form/getFormById/{id}")] = ( "implemented", "面 B 已落地:官方**没有**对应 Java Controller(整个 " "`jnpf-java-boot` 树里没人声明过 `/api/flowForm/Form`)⇒ 按官方" "前端 `api/workFlow/formDesign.ts:49` 的契约实现;用 " "`workflow_form_relation.f_form_id → f_flow_id` 返流程主键" "(**不返假流程号**)") # 🔴 **端点顺序**:按官方模块分组,组内按路径排 —— 与 `routes.rs` 的注册顺序对齐 # (⇒ 契约读起来与代码读起来同序 ⇒ 人工 review 不用来回跳)。 MODULE_ORDER = ["core", "online_dev", "report", "workflow"] # 🔴 **默认 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 逐字导入)", "workflow": "面 B 已落地:流程**元数据**(模板 / 版本 / 节点 / 评论 / 委托 / " "监控 / 触发记录)**真落库**到官方 24 张 `workflow_*` 表(DDL 逐字照官方);" "**引擎动作**(发起 / 审批 / 办理 …)因本仓未接入 Flowable ⇒ **明确业务失败**", } 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)) if mod == "workflow": # 🔴 流程族(批次 19):官方 `jnpf-flowable` 的 Controller 优先, # 官方 Java **没有**映射的 13 条 ⇒ 落到官方前端 `api/workFlow/**`。 for ctrl, table in _WORKFLOW_CONTROLLERS.items(): if k in table: src = "%s:%d" % (ctrl, table[k]) status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["workflow"])) return src, status, note src = _WORKFLOW_FRONTEND_ONLY.get(k) if src: status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["workflow"])) return src, status, note raise SystemExit("workflow 族没有官方出处可登记:%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))