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

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 写进提交的代码。

快速验证

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

// 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 ≥3.8 + requests
from vjmap import Vjmap
svc = Vjmap("http://127.0.0.1:27660/api/v1", "<jwt-token>")
print(svc.heart(), svc.version())

冒烟测试

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 类）

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

约定要点（先读）

• 所有 /api/v1/map/cmd/... GET/POST 均可（网关 Router.Any）；SDK 默认 POST。路径占位 {mapid}/{version} 见 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。
• 官方 SDK zip（python/nodejs/swagger UI）：http://vjmap.com/download/vjmapservice.zip；本 skill 已内置单文件版 sdk/（nodejs / python）。

红旗

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 的形态写，别套 REST 直觉。
5. 大文件上传是 multipart uploads，先 checkMapFile(md5) 可秒传跳过。