# vjmap 后端接口清单（73 个 / 13 类）

> 路径占位符：`{mapid}` / `{version}` 见 [conventions.md](conventions.md)。
> 所有 `/api/v1/map/cmd/...` 既可 GET 也可 POST，SDK 默认走 POST；本表 **方法** 列标注约定习惯用法。

---

## 1. 地图管理（category: map-management，15 接口）

| # | 接口（中文） | URL | 方法 | SDK (Py / Node) |
| --- | ---- | --- | --- | --- |
| 1 | 上传地图源文件 | `/api/v1/map/uploads` | POST (multipart) | `upload_map` / `uploadMap` |
| 2 | 检查文件是否已上传 | `/api/v1/map/mapfile?md5={md5}` | GET | `check_map_file` / `checkMapFile` |
| 3 | 打开/创建地图 | `/api/v1/map/openmap/{mapid}` | GET/POST | `open_map` / `openMap` |
| 4 | 更新地图 | `/api/v1/map/updatemap/{mapid}` | POST | `update_map` / `updateMap` |
| 5 | 关闭地图 | `/api/v1/map/cmd/closemap/{mapid}/{version}` | POST | `close_map` / `closeMap` |
| 6 | 删除地图 | `/api/v1/map/cmd/deletemap/{mapid}/{version}` | POST | `delete_map` / `deleteMap` |
| 7 | 重命名地图 | `/api/v1/map/cmd/renamemap/{mapid}/_` | POST | `rename_map` / `renameMap` |
| 8 | 删除源文件 | `/api/v1/map/cmd/deletemapfile/_/v1?files=a.dwg;b.dwg` | GET | `delete_map_file` / `deleteMapFile` |
| 9 | 列出地图 | `/api/v1/map/cmd/listmaps/{mapid}/{version}` | GET/POST | `list_maps` / `listMaps` |
| 10 | 获取元数据 | `/api/v1/map/cmd/metadata/{mapid}/{version}` | GET/POST | `metadata` / `metadata` |
| 11 | 修改元数据 | `/api/v1/map/cmd/updateMetadata/{mapid}/{version}` | POST | `update_metadata` / `updateMetadata` |
| 12 | 获取缩略图 | `/api/v1/map/cmd/thumbnail/{mapid}/{version}?width=&height=` | GET | `thumbnail_url` / `thumbnailUrl` |
| 13 | 支持的格式 | `/api/v1/map/cmd/supportFormat/_/v1` | GET | `support_format` / `supportFormat` |
| 14 | 系统常量 | `/api/v1/map/cmd/constData/_/v1` | GET | `const_data` / `constData` |
| 15 | 数据范围 | `/api/v1/map/cmd/getDataBounds/{mapid}/{version}` | GET | `get_data_bounds` / `getDataBounds` |

**测试入口**：C.1 分类将使用 `test/caf27de8a225.dwg` 做 upload → open → metadata → listmaps → thumbnail → close → delete 的全链路 smoke。

---

## 2. 瓦片 / 样式 / 缓存（category: tiles-and-styles，10 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 16 | 栅格瓦片 | `/api/v1/map/tile/{mapid}/{version}/{layer}/{z}/{x}/{y}` | GET | `raster_tile_url` / `rasterTileUrl` |
| 17 | 矢量瓦片 MVT | `/api/v1/map/tile/{mapid}/{version}/{layer}/{z}/{x}/{y}.mvt` | GET | `vector_tile_url` / `vectorTileUrl` |
| 18 | WMS 单图 | `/api/v1/map/cmd/wms/{mapid}/{version}` | GET | `wms_tile_url` / `wmsTileUrl` |
| 19 | WMS 多图叠加 | `/api/v1/service/wms` | GET | `wms_tile_url` (list 入参) / `wmsTileUrl` |
| 20 | 创建样式 | `/api/v1/map/cmd/createMapStyle/{mapid}/{version}` | POST | `create_map_style` / `createMapStyle` |
| 21 | 切换图层 | `/api/v1/map/cmd/switchlayer/{mapid}/{version}` | POST | `cmd_switch_layers` / `cmdSwitchLayers` |
| 22 | 更新样式 | `/api/v1/map/cmd/updateStyle/{mapid}/{version}` | POST | `cmd_update_style` / `cmdUpdateStyle` |
| 23 | 切片缓存 | `/api/v1/map/cmd/slicelayer/{mapid}/{version}` | POST | `slice_layer` / `sliceLayer` |
| 24 | 切片级别查询 | `/api/v1/map/cmd/getSliceCacheZoom/{mapid}/{version}` | GET | `get_slice_cache_zoom` / `getSliceCacheZoom` |
| 25 | 删除样式 | `/api/v1/map/cmd/deletestyle/{mapid}/{version}` | POST | `delete_style` / `deleteStyle` |

---

## 3. 要素查询 / 几何（category: query，4 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 26 | 要素查询 | `/api/v1/map/cmd/queryFeatures/{mapid}/{version}` | POST | `query_features` / `queryFeatures` |
| 27 | 构造实体几何 | `/api/v1/map/cmd/createEntityGeoData/_null/v1` | POST | `create_entity_geo_data` / `createEntityGeoData` |
| 28 | 坐标转换 | `/api/v1/map/cmd/coordtransform/_/_` | POST | `coord_transform` / `coordTransform` |
| 29 | WKT → PROJ4 | `/api/v1/map/cmd/prjWktToPrj4Str/_/_` | POST | `prj_wkt_to_prj4_str` / `prjWktToPrj4Str` |

---

## 4. 图形分析（category: analysis，6 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 30 | 像素差异 | `/api/v1/map/cmd/mapDiff/_null/v1` | POST | `cmd_map_diff` / `cmdMapDiff` |
| 31 | 实体对比 | `/api/v1/map/cmd/mapCompare/_null/v1` | POST | `cmd_map_compare` / `cmdMapCompare` |
| 32 | 表格提取 | `/api/v1/map/cmd/extractTable/_null/v1` | POST | `cmd_extract_table` / `cmdExtractTable` |
| 33 | 中心线提取 | `/api/v1/map/cmd/extractCenterLines/_null/v1` | POST | `cmd_extract_center_lines` / `cmdExtractCenterLines` |
| 34 | 目标匹配 | `/api/v1/map/cmd/objectMatch/_null/v1` | POST | `cmd_match_object` / `cmdMatchObject` |
| 35 | SVG/图像转 DWG | `/api/v1/map/cmd/imageSvgToDwg/_null/v1` | POST | `cmd_image_svg_to_dwg` / `cmdImageSvgToDwg` |

> 另有 `objectDetection`、`imageSimilarity`、`triangulate`、`modelPredict`、`correctImage` 等分析接口，本清单未收录。

---

## 5. 组合 / 拆分 / 导出（category: compose-and-export，6 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 36 | 组合新地图 | `/api/v1/map/cmd/composeNewMap/_null/v1` | POST | `cmd_compose_new_map` / `cmdComposeNewMap` |
| 37 | 拆分子图 | `/api/v1/map/cmd/cmdSplitMap/_null/v1` | POST | `cmd_split_map` / `cmdSplitMap` |
| 38 | 导出布局 | `/api/v1/map/cmd/exportLayout/_null/v1` | POST | `cmd_export_layout` / `cmdExportLayout` |
| 39 | 导出 PDF | `/api/v1/map/cmd/exportPdf/{mapid}/{version}` | POST | `cmd_export_pdf` / `cmdExportPdf` |
| 40 | 导出 DXF | `/api/v1/map/cmd/exportDxf/{mapid}/{version}` | POST | `cmd_export_dxf` / `cmdExportDxf` |
| 41 | 离线瓦片包 | `/api/v1/map/cmd/saveOfflineTileDb/_null/v1` | POST | `cmd_save_offline_tile_db` / `cmdSaveOfflineTileDb` |

---

## 6. WebCAD（category: webcad，6 接口）

> 无 feature flag：6 个 cmd 始终注册。`GET /api/v1/service/webcad` 是 WebCAD 前端 license 握手（需加密 `stamp`，否则 403 `error parameter!`；成功回 `{status,version,time,stamp}`），**不是**启用探针。

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 42 | 列 WebCAD 图 | `/api/v1/map/cmd/listWebcadDraws/_/v1` | GET | `list_webcad_draws` / `listWebcadDraws` |
| 43 | 读 WebCAD 数据 | `/api/v1/map/cmd/getWebcadData/{mapid}/{version}` | POST | `get_webcad_data` / `getWebcadData` |
| 44 | 保存补丁 | `/api/v1/map/cmd/saveWebcadPatch/{mapid}/{version}` | POST | `save_webcad_patch` / `saveWebcadPatch` |
| 45 | 删除图 | `/api/v1/map/cmd/deleteWebcadDraw/{mapid}/{version}` | POST | `delete_webcad_draw` / `deleteWebcadDraw` |
| 46 | 转为 WebCAD | `/api/v1/map/cmd/convertWebCAD/{mapid}/{version}` | POST | `convert_webcad` / `convertWebcad` |
| 47 | 导出为 DWG | `/api/v1/map/cmd/exportWebCAD/_null/v1` | POST | `export_webcad` / `exportWebcad` |

---

## 7. 工作区（category: workspace，5 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 48 | 列出工作区 | `/api/v1/service/getWorkspace` | GET | `get_workspaces` / `getWorkspaces` |
| 49 | 创建 | `/api/v1/service/workspaceCreate` | POST | `workspace_create` / `workspaceCreate` |
| 50 | 修改 | `/api/v1/service/workspaceModify` | POST | `workspace_modify` / `workspaceModify` |
| 51 | 删除 | `/api/v1/service/workspaceDelete/{name}` | DELETE | `workspace_delete` / `workspaceDelete` |
| 52 | 状态 | `/api/v1/service/workspaceStatus` | GET | `workspace_status` / `workspaceStatus` |

---

## 8. 键值数据存储（category: data-storage，5 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 53 | 取值 | `/api/v1/service/data/{key}` | GET | `get_custom_data` / `getCustomData` |
| 54 | 存值 | `/api/v1/service/data/{key}` | POST (JSON `{value,prop}`) | `save_custom_data` / `saveCustomData` |
| 55 | 删值 | `/api/v1/service/data/{key}` | DELETE | `delete_custom_data` / `deleteCustomData` |
| 56 | 批量存 | `/api/v1/service/datas` | POST | `save_multiple_custom_data` / `saveMultipleCustomData` |
| 57 | 按前缀取键 | `/api/v1/service/datakeys?prefix=` | GET | `get_custom_data_keys` / `getCustomDataKeys` |

---

## 9. 全文搜索（category: fullsearch，3 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 58 | 搜索 | `/api/v1/service/fullsearch/search` | GET/POST | `full_search` / `fullSearch` |
| 59 | 新增文档 | `/api/v1/service/fullsearch/add` | POST | `full_search_add` / `fullSearchAdd` |
| 60 | 删除文档 | `/api/v1/service/fullsearch/delete` | DELETE | `full_search_delete` / `fullSearchDelete` |

> 另有 `batchAdd`/`batchDelete`/`deleteByMapver`/`deleteByIDPrefix`/`count`/`sync`/`suggestions` 等全文搜索接口，本清单未收录。

---

## 10. 符号库（category: symbols，3 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 61 | 列出分类 | `/api/v1/service/symbol/categories` | GET | `symbol_categories` / `symbolCategories` |
| 62 | 列出符号 | `/api/v1/service/symbol/list/{categoryId}` | GET | `symbol_list` / `symbolList` |
| 63 | 获取单个 | `/api/v1/service/symbol/{id}` | GET | `symbol_get` / `symbolGet` |

> 符号库的写接口（`symbol/config`、分类与符号的 POST/PUT/DELETE）本清单未收录。

---

## 11. 系统（category: system，4 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 64 | 心跳 | `/heart` | GET | `heart` / `heart` |
| 65 | 版本 | `/version` | GET | `version` / `version` |
| 66 | 运行状态 | `/api/v1/map/cmd/runstatus/_/v1?detail=true` | GET | `run_status` / `runStatus` |
| 67 | 查看日志 | `/api/v1/map/cmd/viewlogs/_/v1?record=N` | GET | `view_logs` / `viewLogs` |

---

## 12. /service 杂项（category: service-misc，3 接口）

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 68 | 二维码图 | `/api/v1/service/qrcode?content=...&size=` | GET | `qrcode_url` / `qrcodeUrl` |
| 69 | 字体 PBF | `/api/v1/service/fonts/{fontstack}/{range}.pbf` | GET | `glyphs_url` / `glyphsUrl` |
| 70 | 上传图片 | `/api/v1/service/uploadImg` | POST (multipart) | `upload_img` / `uploadImg` |

---

## 13. AI（category: ai，3 接口，条件启用）

> AI 接口为条件启用：`runstatus?detail=true` 的返回值中没有 AI 子进程健康信息时，表示未启用。

| # | 接口 | URL | 方法 | SDK |
| --- | ------ | ------ | ------ | ----- |
| 71 | 向量相似搜索 | `/api/v1/service/vectorSearch` | GET/POST | `vector_search` / `vectorSearch` |
| 72 | FAQ | `/api/v1/service/chatFaq` | GET | `chat_faq` / `chatFaq` |
| 73 | 向量文档 | `/api/v1/service/vectorDocs` | GET | `vector_docs` / `vectorDocs` |

---

## 清单合计

| 分类 | 数量 |
|------|-------------|
| 1 地图管理 | 15 |
| 2 瓦片/样式 | 10 |
| 3 查询 | 4 |
| 4 分析 | 6 |
| 5 组合导出 | 6 |
| 6 WebCAD | 6 |
| 7 工作区 | 5 |
| 8 KV | 5 |
| 9 全文搜索 | 3 |
| 10 符号库 | 3 |
| 11 系统 | 4 |
| 12 /service 杂项 | 3 |
| 13 AI | 3 |
| **合计** | **73** |

---

## 未收录的接口

运维（客户端更新、注册码、运行统计）、授权激活、缓存清理、权限配置、跨节点同步等管理类接口，以及部分专业分析接口，不在本清单内；二次开发一般用不到。