---
name: vjmap-service
description: Use when calling the shared VJMAP backend REST service (唯杰地图服务) that all client SDKs (vjmap/vjmapext/vjmap3d/vjcad/vjvp) depend on — map upload/open/close/delete/rename/metadata/thumbnail, raster & vector tiles and WMS, style create/switch/update/slice-cache, feature query & coord transform, analysis (mapDiff/mapCompare/extractTable/centerline/objectMatch/svg→dwg), compose/split/export PDF/DXF/offline tiles, WebCAD drawings CRUD & patches & DWG export, workspaces, KV data storage, full-text search, symbol library, system (heart/version/runstatus/logs), service misc (qrcode/fonts/uploadImg), AI (vectorSearch/chatFaq/vectorDocs). Includes single-file Node/Python SDKs, OpenAPI spec, and a live smoke test. Keywords vjmap 服务 REST API 后端 openmap tile wms queryFeatures webcad 瓦片 服务地址 token. Excludes client-side SDK usage (use the product skills).
metadata:
  product: vjmapservice
  kind: shared-backend-rest
  mcp: https://vjmap.com/server/mcp
---

# vjmap-service — 唯杰地图服务（共用后端 REST）

```yaml
kind: shared backend REST service
mcp: https://vjmap.com/server/mcp?token=xxxxxx
sdk: 本目录 sdk/nodejs/vjmap.js（零依赖，Node≥18）· sdk/python/vjmap.py（requests）
openapi: openapi/vjmap.openapi.yaml
```

服务地址与 token 换为你自己的（公有云 `https://vjmap.com/server/api/v1`，私有化 `http://<ip>:27660/api/v1`）。**不要把 token 写进提交的代码**。

## 快速验证

```bash
curl -s http://127.0.0.1:27660/heart      # => {"status":"ok",...}
curl -s http://127.0.0.1:27660/version    # => {"version":"...",...}
```

```js
// Node ≥18，零依赖
const { Vjmap } = require("./sdk/nodejs/vjmap.js");
const svc = new Vjmap("http://127.0.0.1:27660/api/v1", "<jwt-token>");
console.log(await svc.heart(), await svc.version());
```

```python
# Python ≥3.8 + requests
from vjmap import Vjmap
svc = Vjmap("http://127.0.0.1:27660/api/v1", "<jwt-token>")
print(svc.heart(), svc.version())
```

## 冒烟测试

```bash
VJMAP_SERVICE_URL=http://127.0.0.1:27660/api/v1 VJMAP_TOKEN=<jwt> \
  node vjmap-service/scripts/verify/smoke.mjs
# 可选 VJMAP_TEST_MAPID=<已有图名> 跑 metadata/bounds/thumbnail 读取链
# 无环境变量时只跑离线断言（SDK 方法存在性 + URL 组装）
```

## 按任务找文档（73 个接口 / 13 类）

| 我要做 | 去读 | SDK 方法名（Node camelCase；Python 对应 snake_case） |
|---|---|---|
| 上传 DWG / 打开 / 关闭 / 删除 / 重命名 / 元数据 / 缩略图 / 支持格式 / 数据范围 | [api/01-map-management](references/api/01-map-management.md) | `uploadMap` `checkMapFile` `openMap` `waitMapOpenFinish` `closeMap` `metadata` `thumbnailUrl` `supportFormat` `getDataBounds` |
| 栅格瓦片 XYZ / 矢量瓦片 MVT / WMS 单图多图 / 样式创建切换更新 / 切片缓存 | [api/02-tiles-styles](references/api/02-tiles-styles.md) | `rasterTileUrl` `vectorTileUrl` `wmsTileUrl` `createMapStyle` `cmdSwitchLayers` `sliceLayer` `getSliceCacheZoom` `deleteStyle` |
| 要素查询 / 构造实体几何 / 坐标转换 / WKT→PROJ4 | [api/03-query](references/api/03-query.md) | `queryFeatures` `createEntityGeoData` `coordTransform` `prjWktToPrj4Str` |
| 像素差异 / 实体对比 / 表格提取 / 中心线 / 目标匹配 / SVG→DWG | [api/04-analysis](references/api/04-analysis.md) | `cmdMapDiff` `cmdMapCompare` `cmdExtractTable` `cmdExtractCenterLines` `cmdMatchObject` `cmdImageSvgToDwg` |
| 组合新图 / 拆分子图 / 导出布局 / PDF / DXF / 离线瓦片包 | [api/05-compose-export](references/api/05-compose-export.md) | `cmdComposeNewMap` `cmdSplitMap` `cmdExportLayout` `cmdExportPdf` `cmdExportDxf` `cmdSaveOfflineTileDb` |
| WebCAD 图列表 / 读数据 / 存补丁 / 删图 / 转 WebCAD / 导出 DWG | [api/06-webcad](references/api/06-webcad.md)（cmd 始终注册；`/service/webcad` 是前端 license 握手，不是启用探针） | `listWebcadDraws` `getWebcadData` `saveWebcadPatch` `deleteWebcadDraw` `convertWebcad` `exportWebcad` |
| 工作区 增删改查 / 状态 | [api/07-workspace](references/api/07-workspace.md) | `getWorkspaces` `workspaceCreate` `workspaceModify` `workspaceDelete` `workspaceStatus` |
| KV 存储（配置/小数据） | [api/08-data-storage](references/api/08-data-storage.md) | `getCustomData` `saveCustomData` `deleteCustomData` `saveMultipleCustomData` `getCustomDataKeys` |
| 全文搜索 | [api/09-fullsearch](references/api/09-fullsearch.md) | `fullSearch` `fullSearchAdd` `fullSearchDelete` |
| 符号库 | [api/10-symbols](references/api/10-symbols.md) | `symbolCategories` `symbolList` `symbolGet` |
| 心跳 / 版本 / 运行状态 / 日志 | [api/11-system](references/api/11-system.md) | `heart` `version` `runStatus` `viewLogs` |
| 二维码 / 字体 PBF / 传图片 | [api/12-service-misc](references/api/12-service-misc.md) | `qrcodeUrl` `glyphsUrl` `uploadImg` |
| AI 向量搜索 / FAQ / 向量文档 | [api/13-ai](references/api/13-ai.md)（条件启用） | `vectorSearch` `chatFaq` `vectorDocs` |

完整清单（URL + 方法 + SDK 方法名）：[references/inventory.md](references/inventory.md)。约定与鉴权：[conventions.md](references/conventions.md) · [authentication.md](references/authentication.md)。入门：[overview.md](references/overview.md) · [getting-started.md](references/getting-started.md) · [api/index.md](references/api/index.md)（13 类接口导航）。

## 约定要点（先读）

- 所有 `/api/v1/map/cmd/...` **GET/POST 均可**（网关 `Router.Any`）；SDK 默认 POST。路径占位 `{mapid}`/`{version}` 见 [conventions.md](references/conventions.md)。
- web 服务响应包 `{code,msg,data}`，SDK 自动 unwrap 成 `data`；图形服务 JSON 原样返回；HTTP 非 2xx → `VjmapError { status, url, body }`。
- `rasterTileUrl({mapid,version,layer,z,x,y})` 是**对象入参**；`z/x/y` 缺省返回 `{z}/{x}/{y}` 模板串（给前端地图库用）。
- AI 组是**条件启用**——先 `aiEnabled()` 探测，不可用就 skip，不要当错误。WebCAD cmd 始终注册，没有启用开关可探（`GET /service/webcad` 是前端 license 握手，不带加密 `stamp` 就回 403 `error parameter!`）。
- MCP（streamable HTTP，默认关闭，`mcp.enable`）的鉴权与工具过滤见 [authentication.md §7](references/authentication.md#7-mcp-路由)。
- 官方 SDK zip（python/nodejs/swagger UI）：`http://vjmap.com/download/vjmapservice.zip`；本 skill 已内置单文件版 `sdk/`（[nodejs](sdk/nodejs/README.md) / [python](sdk/python/README.md)）。

## 红旗

1. REST 的 `token` 只认请求头 `token`（优先）或 query `?token=`；`Authorization: Bearer` 仅 MCP 路由认（见 authentication.md）——别把 token 写进提交代码。
2. `openMap` 第一次打开新图必须带 `fileid`（上传响应里有）；缺了返回"图不存在"。打开方式由 body 布尔 `geom` 决定（后端不读 `mapopenway`，SDK 自动换算）；GeomRender 首开回 `status:"working"`，要 `waitMapOpenFinish` 后再开一次。
3. 瓦片 URL 的 `layer` 是样式图层名，`switchlayer` 切的是显隐不是样式本身。
4. `queryFeatures` 的查询体随几何类型（点/矩形/条件/表达式）差异大——按 [api/03-query](references/api/03-query.md) 的形态写，别套 REST 直觉。
5. 大文件上传是 multipart `uploads`，先 `checkMapFile(md5)` 可秒传跳过。