#!/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 json 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` 只是**声明**了它。) # 🔴 **批次 24**:官方 `LoginController.java:117` 的通配**同时收 GET 与 POST** # (`method = {RequestMethod.GET, RequestMethod.POST}`) # —— 官方 Web 前端用 POST、**官方移动端** `api/common.js:565` 的 `socialsLogin` # 不写 method(默认 GET)⇒ 两个方法都得注册,出处同指那行通配。 CORE_FRONTEND_OR_INDIRECT = { "POST /api/oauth/Login/socials": "LoginController.java:117", "GET /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, } # 🔴 **消息中心族(批次 20)**:官方 `jnpf-message` 的 Controller ⇒ 文件名 + 映射行号。 # # 🔴 **范围**:官方前端 `src/api/msgCenter/**` 的**全部 50 个接口**。 # 官方 Java 还多暴露 12 条前端从不调的(Account 的 `detail/{id}` / `unable/{id}` / # `Action/Export` / `Action/Import`,Template 的同 4 条,Send 的 `/Selector` / # `getInfoByEnCode/{enCode}` / `detail/{id}`,Monitor 的 `POST /Monitor`) # ⇒ **本期不做**(官方前端不需要)⇒ 记在 `HANDOFF.md` 的已知限制里。 _MSG_CENTER_CONTROLLERS = { "AccountController.java": { "GET /api/message/Account": 113, "PUT /api/message/Account/setdefault": 160, "POST /api/message/Account": 176, "GET /api/message/Account/{id}": 205, "PUT /api/message/Account/{id}": 255, "DELETE /api/message/Account/{id}": 324, "POST /api/message/Account/{id}/Actions/Copy": 394, "POST /api/message/Account/testSendMail": 470, }, "SendMessageConfigController.java": { "GET /api/message/Send": 143, "GET /api/message/Send/getSendConfigList": 226, "POST /api/message/Send": 304, "GET /api/message/Send/{id}": 443, "PUT /api/message/Send/{id}": 545, "DELETE /api/message/Send/{id}": 657, "POST /api/message/Send/getTestConfig/{id}": 680, "POST /api/message/Send/testSendConfig": 719, "POST /api/message/Send/{id}/Actions/Copy": 757, }, "MessageTemplateConfigController.java": { "GET /api/message/Template": 117, "POST /api/message/Template": 174, "GET /api/message/Template/{id}": 250, "PUT /api/message/Template/{id}": 334, "DELETE /api/message/Template/{id}": 518, "POST /api/message/Template/{id}/Actions/Copy": 569, }, "MsgSensitiveController.java": { "GET /api/message/Sensitive": 34, "POST /api/message/Sensitive": 42, "GET /api/message/Sensitive/{id}": 49, "DELETE /api/message/Sensitive/{id}": 56, "PUT /api/message/Sensitive/{id}": 63, }, "MsgReceiveController.java": { "GET /api/message/Receive": 29, "POST /api/message/Receive": 39, }, "MessageMonitorController.java": { "GET /api/message/Monitor": 100, "GET /api/message/Monitor/Info": 139, "DELETE /api/message/Monitor/batchRemove": 176, "DELETE /api/message/Monitor/empty": 190, "GET /api/message/Monitor/detail/{id}": 222, "GET /api/message/Monitor/{id}/RecordList": 277, "POST /api/message/Monitor/{id}/Retry": 315, }, "IntgSupplierController.java": { "GET /api/message/Supplier": 86, "POST /api/message/Supplier": 94, "PUT /api/message/Supplier/{id}": 166, "GET /api/message/Supplier/Selector": 193, "GET /api/message/Supplier/{id}": 201, "POST /api/message/Supplier/{id}/Actions/Copy": 209, "DELETE /api/message/Supplier/{id}": 221, "GET /api/message/Supplier/TemplateList": 240, "POST /api/message/Supplier/SyncTemplate": 260, "GET /api/message/Supplier/{id}/VariableList": 266, "PUT /api/message/Supplier/{id}/Actions/State": 275, }, } # 🔴 消息中心族里**官方 Java 没有对应 `@XxxMapping`** 的 3 条 # (官方前端自己声明了这三个接口,官方 Java 后端没实现)⇒ 出处指官方前端。 # # 🔴 第三条 `POST /api/message/Account/{id}` 是**动态路径**: # 官方前端 `api/msgCenter/accountConfig.ts:33` 写 `${Api.Prefix}/${data.testType}` # ⇒ 静态抽端点器把最后一段记成路径参数。官方 Java 只有静态端点 # `POST /api/message/Account/testSendMail`(`AccountController.java:470`), # 而前端**唯一调用点**(`src/views/integrationCenter/email/Test.vue:59`)把 # `testType` 写死成 `'testSendMail'` ⇒ 运行期 URL 就是那个静态端点(**已实现**)。 # 这条别名把「前端声明的路径形状」也接住(行为与静态端点完全一致)。 _MSG_CENTER_FRONTEND_ONLY = { "POST /api/message/Template/testSendMail": "api/msgCenter/msgTemplate.ts:33", "POST /api/message/Supplier/TestConnect": "api/msgCenter/supplier.ts:45", "POST /api/message/Account/{id}": "api/msgCenter/accountConfig.ts:33", } # 🔴 **状态判定**:本仓**诚实失败**(无文件服务 / 无渲染器 / 无数据引擎) # 的端点 ⇒ `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` 返流程主键" "(**不返假流程号**)") # 🔴 ---- 消息中心族(批次 20)---- # # 🔴 **6 条「真发消息 / 真连服务商」** ⇒ 本仓**没有 HTTP 客户端** # ⇒ 一律**明确业务失败**(不返假发送结果、不返假模板)。 _MSG_CENTER_SEND_PATHS = [ ("POST", "/api/message/Account/testSendMail"), ("POST", "/api/message/Send/testSendConfig"), ("POST", "/api/message/Template/testSendMail"), ("POST", "/api/message/Monitor/{id}/Retry"), ("POST", "/api/message/Supplier/SyncTemplate"), ("POST", "/api/message/Supplier/TestConnect"), ] for _m, _p in _MSG_CENTER_SEND_PATHS: PARTIAL_NOTES[(_m, _p)] = ( "partial", "本仓无 HTTP 客户端(不接任何消息服务商)⇒ **明确业务失败**" "(不返假发送结果 / 假模板)") # 🔴 官方前端 `testConfig` 的**动态路径**别名(`${Api.Prefix}/${data.testType}`): # 官方 Java 只有静态端点 `/Account/testSendMail`,前端调用点把 `testType` # 写死成 `'testSendMail'` ⇒ 运行期就是那个静态端点;本条是**同语义别名**。 PARTIAL_NOTES[("POST", "/api/message/Account/{id}")] = ( "partial", "官方前端 `testConfig` 的**动态**路径(`${Api.Prefix}/${data.testType}`," "`api/msgCenter/accountConfig.ts:33`)的**同语义别名**;运行期 " "`testType` 写死为 `testSendMail` ⇒ 打到官方静态端点(已实现)。" "本仓无 HTTP 客户端 ⇒ **明确业务失败**(不返假发送结果)") # 🔴 供应商的新增 / 更新:官方会先**真连服务商**做「测试连接」⇒ # 本仓跳过连通性检查(**写库照做**),其余校验(名称 / 编码 / 密钥重复)全做。 PARTIAL_NOTES[("POST", "/api/message/Supplier")] = ( "implemented", "面 B 已落地:官方在落库前会**真连服务商**做「测试连接」⇒ " "本仓**跳过连通性检查**(名称 / 编码 / 密钥重复校验全做," "落库照做)") PARTIAL_NOTES[("PUT", "/api/message/Supplier/{id}")] = ( "implemented", "面 B 已落地:同新增 —— 官方先真连服务商做「测试连接」⇒ " "本仓**跳过连通性检查**(其余校验全做)") # 🔴 消息账号 / 供应商的**密钥字段**:官方 DDL 就是**明文**存 # (`base_msg_account.f_smtp_password` / `base_intg_supplier.f_secret_key`) # 且官方前端**要拿回来编辑** ⇒ 本仓**照官方**返回(与「用户登录口令不得外泄」 # 是两码事 —— 那条只管 `base_user.f_password`)。 PARTIAL_NOTES[("GET", "/api/message/Account/{id}")] = ( "implemented", "面 B 已落地:`smtpPassword` 等密钥字段**照官方返回明文**" "(官方 DDL 即明文存、前端要拿回来编辑;与「用户登录口令不得外泄」" "是两条不同的红线)") PARTIAL_NOTES[("GET", "/api/message/Supplier")] = ( "implemented", "面 B 已落地:`secretKey` **照官方返回明文**(官方 DDL 即明文存);" "官方 VO 里 `supplierName`/`supplierId`/`smsSignature`/`isDefault`/" "`content` **没有数据来源**(实体里没这些字段)⇒ 本仓同官方返 null") PARTIAL_NOTES[("GET", "/api/message/Supplier/{id}")] = ( "implemented", "面 B 已落地:`secretKey` **照官方返回明文**;`isEditor` = 该供应商" "**没有模板**(官方:`CollUtil.isEmpty(tplEntities)`)") # 🔴 消息审计 `msgTypeInfo.msgTypeList`:官方走 `msgSendType` **字典** # ⇒ 本仓**没有这个字典** ⇒ 改用官方 `MessageTypeEnum` 的 8 个消息类型。 PARTIAL_NOTES[("GET", "/api/message/Monitor/Info")] = ( "implemented", "面 B 已落地:`msgTypeInfo.msgTypeList` 官方走 `msgSendType` **字典**" "⇒ 本仓**无此字典** ⇒ 改用官方 `MessageTypeEnum` 的 8 个消息类型;" "`noticeInfo` 按官方口径只统计「公告」业务分类" "(`f_category` 含 `2046494646179336192`)") # 🔴 消息接收配置 `GET /api/message/Receive`:官方返的是 **ListVO**(不是分页)。 PARTIAL_NOTES[("GET", "/api/message/Receive")] = ( "implemented", "面 B 已落地:官方返 **ListVO**(`{list:[…]}`,**不是分页**);" "每条含 `channels` / `configJson`(渠道矩阵)与业务分类的" "`categoryName` / `subCategoryName` / `topCategoryName`") # 🔴 **端点顺序**:按官方模块分组,组内按路径排 —— 与 `routes.rs` 的注册顺序对齐 # (⇒ 契约读起来与代码读起来同序 ⇒ 人工 review 不用来回跳)。 MODULE_ORDER = ["core", "online_dev", "report", "workflow", "msg_center", "ai", "extend", "teamwork", "mobile", "visualdata"] # 🔴 **批次 24:官方移动端**(`jnpf/7.0-jnpf-app-vue3` 的 `api/**`)。 # # 真源是**官方移动端前端**(不是 Web 前端):这批端点**只在 App 里出现** # —— App 菜单 / App 用户 / 版本号 / 扫码登录 / 工作日志 / 移动端首页 / 移动端日程 …… # ⇒ 官方 Web 前端 `src/api/**` 里**没有**它们,做「Web 前端 900/900」时覆盖不到。 # # 出处取**官方移动端 `api/<文件>:<行号>`**(与 `scripts/fe-gap.py` 同一套扫描)。 # 🔴 官方移动端仓库落在 `~/Desktop/workspace/jnpf/7.0/frontend/app` # (`check-citations.sh` 的 `--jnpf` 根是 `~/Desktop/workspace/jnpf` # ⇒ `api/xxx.js:行号` 会**基名匹配**到 `7.0/frontend/app/api/xxx.js`)。 _MOBILE_SOURCES = json.load( open(os.path.join(HERE, "official-mobile-sources.json"), encoding="utf-8")) # 🔴 **批次 25:官方大屏(blade-visual)**。 # # 真源是官方 `jnpf-visualdata` 模块(`jnpf-java-boot/jnpf-visualdata`)的 # **8 个 Controller**,共 **53 条** method+path,全部挂在 `/api/blade-visual/*` 下。 # # 🔴 **三源对照**(本族每条端点都对照过): # ① 后端源码 = 这份出处台账(`VisualXxxController.java:行号`); # ② 数据库 = 官方 DDL 的 **9 张 `blade_visual*` 表**; # ③ 前端 api = 官方大屏设计器前端 **`jnpf-web-datascreen-vue3/src/api/*.js`** # (9 个文件;它决定了「删除走 query」「大屏新增是 `{visual,config}` 双段」 # 等**入参位置**的细节)。 # # 🔴 出处行号指向**官方 Java Controller 的 `@XxxMapping` 那一行** # (逐条由脚本提取,与 `check-citations.sh` 的定位规则一致)。 _VISUALDATA_SOURCES = json.load( open(os.path.join(HERE, "official-visualdata-sources.json"), encoding="utf-8")) # 🔴 **批次 21–23**:AI 中心 / extend 示例 / teamwork(文件 + 日程)三族。 # 官方出处直接取官方前端 `api//**:行号`(与 `scripts/fe-gap.py` 同一份扫描结果), # 因为这三族在官方 Java 里分散在 `jnpf-ai-v3` / `jnpf-extend` / `jnpf-file` / # `jnpf-system` 四个模块,逐条对 Java 行号收益不大、且更容易漂。 _EXT_SOURCES = json.load( open(os.path.join(HERE, "official-ext-sources.json"), encoding="utf-8")) # 🔴 **默认 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 ⇒ **明确业务失败**", "ai": "面 B 已落地:AI 中心元数据(智能体 / 供应商 / 模型 / 知识库 / 文档 / MCP / " "提示词 / 服务 / 技能 / 工具 / 会话历史)真落库到官方 `base_ai_*` 表;" "**调模型推理 / 供应商连通性检查 / MCP 工具同步**因本仓无 HTTP 客户端明确失败", "extend": "面 B 已落地:官方示例模块真落库到 `ext_*` 15 张表;" "需要 SMTP/IMAP、文件服务、Excel 引擎的动作明确失败", "teamwork": "面 B 已落地:文件**元数据**(文件夹 / 改名 / 移动 / 复制 / 分享 / 回收站 / " "最近 / 标签 / 空间)与日程真落库;上传 / 打包下载 / 分片合并因本仓无文件服务明确失败", "msg_center": "面 B 已落地:消息中心(账号 / 发送配置 / 模板 / 敏感词 / 接收配置 / " "监控 / 供应商)**真落库**到官方 `base_msg_*` + `base_intg_supplier*` " "表(DDL 逐字照官方);**真发消息 / 真连服务商**的动作因本仓无 HTTP " "客户端 ⇒ **明确业务失败**", "mobile": "面 B 已落地:官方**移动端**(`jnpf-app-vue3`)专用端点 —— App 菜单 / " "App 用户 / 版本号 / 工作日志 / 移动端首页 / 移动端日程 / 组织用户查询 …" "已按官方 `api/**` 的调用形状实现;工作日志真落库到官方 `ext_work_log` 表;" "**需要外部通道的**(OAuth provider / 地图服务 / 扫码票据 / 账号注销)" "⇒ **明确业务失败**,绝不返假 URL / 假状态", "visualdata": "面 B 已落地:官方**大屏**(`jnpf-visualdata`)8 个 Controller 的 **53 条**" "端点,按官方 `blade_visual*` **9 张表**(DDL 逐字照官方)真落库;" "分页用官方 `VisualPageVO`(`{records,current,size,total,pages}`)," "分类 / 数据源下拉 / 地图懒加载返**裸数组**," "`visual/copy` 返**裸 id**,`visual/Selector` 是**两级树**;" "**需要外部通道的**(外部数据库连接 / 动态 SQL / 任意 URL 转发 / " "文件服务 / 导入导出)⇒ **明确业务失败**,绝不返假坐标 / 假连接成功", } 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 # ---- 批次 21–23:三族的「部分落地」说明(诚实的降级点)---- PARTIAL_NOTES.update({ ("POST", "/api/ai/Chat/Send"): ( "partial", "本仓无 HTTP 客户端 ⇒ 无法调 LLM,明确业务失败(元数据管理可用)"), ("POST", "/api/ai/Chat/Translate"): ( "partial", "本仓无 LLM 推理服务 ⇒ 明确业务失败"), ("POST", "/api/ai/Chat/Optimize"): ( "partial", "本仓无 LLM 推理服务 ⇒ 明确业务失败"), ("POST", "/api/ai/AiSupplier/checkAi"): ( "partial", "本仓无 HTTP 客户端 ⇒ 无法连供应商,明确业务失败"), ("GET", "/api/ai/Mcp/Sync/{id}"): ( "partial", "本仓无 HTTP/stdio 客户端 ⇒ 无法连 MCP 服务,明确业务失败"), ("POST", "/api/ai/visualdev"): ( "partial", "本仓无 LLM ⇒ 不生成表单;传 id 时按 id 查已有表单"), ("POST", "/api/ai/workflow"): ( "partial", "本仓无 LLM ⇒ 不生成流程;传 id 时按 id 查已有模板"), ("POST", "/api/ai/Document/{id}/section"): ( "partial", "本地按行切片(真做);无向量化"), ("POST", "/api/ai/Document/{id}/study"): ( "partial", "本地切片 + 落 f_state(真做);无向量库,召回走关键词"), ("POST", "/api/ai/Knowledge/{id}/Test"): ( "partial", "关键词召回(真做,score=命中词占比);无向量相似度"), ("POST", "/api/extend/Email"): ( "partial", "本仓无 SMTP ⇒ 不发信;草稿走 SaveDraft 真存"), ("POST", "/api/extend/Email/Config/Actions/CheckMail"): ( "partial", "本仓无 SMTP/IMAP 客户端 ⇒ 明确业务失败"), ("POST", "/api/extend/Email/Receive"): ( "partial", "本仓无 IMAP 客户端 ⇒ 明确业务失败"), ("GET", "/api/extend/Employee/ExportData"): ( "partial", "本仓无文件服务与 Excel 库 ⇒ 明确业务失败"), ("POST", "/api/extend/Employee/ImportData"): ( "partial", "本仓无文件服务与 Excel 库 ⇒ 明确业务失败"), ("GET", "/api/extend/Employee/ImportPreview"): ( "partial", "本仓无文件服务与 Excel 库 ⇒ 明确业务失败"), ("GET", "/api/extend/Employee/TemplateDownload"): ( "partial", "本仓无文件服务 ⇒ 明确业务失败"), ("GET", "/api/extend/DocumentPreview/{id}/Preview"): ( "partial", "本仓无 onlyoffice / 文件服务 ⇒ 明确业务失败"), ("POST", "/api/file/Document/UploadBlob"): ( "partial", "本仓无文件服务 ⇒ 只支持元数据,上传明确失败"), ("POST", "/api/file/Document/PackDownload"): ( "partial", "本仓无文件服务 ⇒ 明确业务失败"), ("POST", "/api/file/Document/merge"): ( "partial", "本仓无文件服务 ⇒ 分片合并明确失败"), # ---- 批次 24:官方移动端 ---- ("GET", "/api/oauth/confirmLogin/{ticket}"): ( "partial", "本仓无扫码票据服务(官方用 Redis 存票据)⇒ 明确业务失败;" "绝不返「已确认」这种假状态"), ("GET", "/api/oauth/socials/app/callback/{source}"): ( "partial", "本仓无 OAuth provider 注册表 ⇒ 明确业务失败"), ("GET", "/api/oauth/socials/render/{source}"): ( "partial", "本仓无 OAuth provider ⇒ 明确业务失败;绝不返假 URL"), ("POST", "/api/oauth/logoutCurrentUser"): ( "partial", "账号**注销**(≠ 退出登录):本仓没有注销的业务规则(软删还是硬删?" "关联数据怎么办?)⇒ 明确业务失败,不假装成功"), ("GET", "/api/system/Location/regeo"): ( "partial", "本仓无地图服务(高德/百度的 key 也没有)⇒ 明确业务失败"), ("GET", "/api/system/tenant/saas/inviteurl"): ( "partial", "本仓单租户(f_tenant_id 恒 '0')⇒ 没有「多租户邀请」⇒ 明确业务失败"), ("GET", "/api/permission/socials/login"): ( "partial", "本仓未配置第三方登录 ⇒ 返空数组(官方语义即「无可用平台」)"), ("GET", "/api/app/User/{id}"): ( "partial", "已落地:用户基础字段 + 组织名 / 岗位名 / 角色名;官方 VO 的其余" "自定义扩展字段未返"), ("GET", "/api/workflow/Engine/flowTemplate"): ( "partial", "已落地:按 `workflow_template` 真库返回分页列表;官方 Engine 侧的" "引擎版本 / 节点配置未返(WorkflowListVO 的完整形状)"), ("POST", "/api/workflow/Engine/FlowBefore/Cancel/{id}"): ( "partial", "已落地:任务置「已驳回」+ 处理人记录置已处理 + 驳回意见留痕;" "官方 Flowable 引擎的**流程实例回退**未做"), # ---- 批次 25:官方大屏(blade-visual)---- ("POST", "/api/blade-visual/db/db-test"): ( "partial", "本仓**不连外部数据库**(无 JDBC / 无驱动)⇒ 明确业务失败;" "绝不返「连接成功」的假答案"), ("POST", "/api/blade-visual/db/dynamic-query"): ( "partial", "本仓**不执行外部 SQL**(官方是在外部数据源上跑前端传来的 SQL)⇒ 明确业务失败"), ("POST", "/api/blade-visual/visual/proxy"): ( "partial", "官方是**任意 URL 转发**(前端 `axios.js:68` 把带 `headers.proxy` 的请求" "统一改写到这里)⇒ 本仓不做 SSRF 面 ⇒ 明确业务失败"), ("POST", "/api/blade-visual/visual/GetApiData"): ( "partial", "官方是**任意 URL 转发**(官方返回类型是裸 `String`)⇒ 本仓不做 SSRF 面 ⇒ 明确业务失败"), ("GET", "/api/blade-visual/visual/{type}"): ( "partial", "本仓**无文件服务**(无对象存储)⇒ 明确业务失败;绝不返假图片 URL"), ("POST", "/api/blade-visual/visual/put-file/{type}"): ( "partial", "本仓**无文件服务** ⇒ 明确业务失败;绝不返假链接"), ("POST", "/api/blade-visual/visual/{id}/Actions/ExportData"): ( "partial", "本仓**无文件导出服务** ⇒ 明确业务失败"), ("POST", "/api/blade-visual/visual/Model/Actions/ImportData"): ( "partial", "本仓**无文件服务** ⇒ 明确业务失败"), ("GET", "/api/blade-visual/map/data"): ( "partial", "已落地:返回 `blade_visual_map.data` 原文;官方那是**地图服务**" "(高德/百度)拉下来的 geojson ⇒ 本仓无该通道 ⇒ 没数据时明确业务失败," "绝不返假坐标"), ("GET", "/api/blade-visual/db/detail"): ( "partial", "已落地:数据源字段照官方 `VisualDbInfoVO`;**密码不回传**" "(官方是 AES 密文,回传也没有可用性)"), }) def official_entry(mod, key, path): """⇒ (src, status, note) —— 官方出处 + 落地状态 + 偏差说明。""" method = key[0] if mod == "mobile": # 🔴 批次 24:官方出处 = 官方**移动端** `api/<文件>:<行号>`。 table = _MOBILE_SOURCES src = table.get("%s %s" % (method, norm_path(path))) if not src: raise SystemExit("移动端没有官方出处可登记:%s %s" % (method, path)) status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["mobile"])) return src, status, note if mod == "visualdata": # 🔴 批次 25:官方出处 = 官方 `jnpf-visualdata` 的 `VisualXxxController.java:行号`。 src = _VISUALDATA_SOURCES.get("%s %s" % (method, norm_path(path))) if not src: raise SystemExit("大屏没有官方出处可登记:%s %s" % (method, path)) status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["visualdata"])) return src, status, note if mod in ("ai", "extend", "teamwork"): table = _EXT_SOURCES.get(mod) or {} src = table.get("%s %s" % (method, norm_path(path))) if not src: raise SystemExit("三族没有官方出处可登记:%s %s" % (mod, path)) status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES[mod])) return src, status, note 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)) if mod == "msg_center": # 🔴 消息中心族(批次 20):官方 `jnpf-message` 的 Controller 优先, # 官方 Java **没有**映射的 2 条 ⇒ 落到官方前端 `api/msgCenter/**`。 for ctrl, table in _MSG_CENTER_CONTROLLERS.items(): if k in table: src = "%s:%d" % (ctrl, table[k]) status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["msg_center"])) return src, status, note src = _MSG_CENTER_FRONTEND_ONLY.get(k) if src: status, note = PARTIAL_NOTES.get(key, ("implemented", DEFAULT_NOTES["msg_center"])) return src, status, note raise SystemExit("msg_center 族没有官方出处可登记:%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))