Files
ssw-platform/scripts/gen-contract-endpoints.py
admin b957a11b4c feat(compat): 批次 25 补齐官方大屏 52 条端点(blade-visual 53/53)
官方大屏设计器(jnpf-visualdata)8 个 Controller / 53 条端点,此前本仓
只有 1 条「恒失败」占位 ⇒ 真实缺口 52 条,本批全部补齐。

三源对照:官方后端源码(8 Controller)+ 官方 PostgreSQL DDL(9 张
blade_visual* 表)+ 官方前端 api(jnpf-web-datascreen-vue3/src/api/**)。

关键设计:
- 列族是 Blade 系(id / is_deleted / create_time),与本仓其它契约面的
  f_ 列族不同 ⇒ 不复用 compat::res 引擎,另建 BRes 专用层;DDL 逐字照官方。
- 分页用官方 VisualPageVO(records/current/size/total/pages),不是 PageListVO;
  入参只认 size(默认 10)/ current,官方 VisualPaginationModel 没有
  pageSize / currentPage。
- 官方形状不统一照抄:category/list、visual/category、db/db-list、
  map/lazy-list 返裸数组;visual/copy 返裸 id;visual/Selector 是两级树。
- 删除走 query 的 ids(逗号分隔);软删只对 3 张有 is_deleted 的表,
  其余 6 张官方是物理删。
- 需要外部通道的(外部库连接 / 动态 SQL / 任意 URL 转发 / 文件服务 /
  导入导出 / 地图数据源)⇒ 明确业务失败,绝不返假连接成功 / 假 geojson。

新增:platform/compat/visualdata.rs、tests/visualdata_it.rs(11 条)、
scripts/official-visualdata-sources.json(53 条出处)、db/schema.sql 追加
9 张表、sspf_store::db::VISUALDATA_TABLES。

验证:cargo test --workspace 695 passed / 0 failed;verify --smoke 14 步
全绿;check-contract PASS=10(契约 1040 条,官方台账覆盖 1026/1031);
check-citations PASS=4(1264 条引文)。
2026-11-03 10:56:03 +08:00

1138 lines
63 KiB
Python
Raw Permalink 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 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`
# (`<flowDomain>/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/<dir>/**:行号`(与 `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))