概述（Overview）

vjmap 后端 REST 接口文档 — 面向二次开发者的版本（vjmapservice/）。

后端SDK下载 python、nodejs、swagger服务。下载地址：http://vjmap.com/download/vjmapservice.zip

1. 产品定位

vjmap 是一套以 CAD/GIS 图档为中心的服务端系统，核心能力包括：

• 上传 DWG / DXF / 图片等源文件，在服务端解析成数据库
• 以栅格瓦片或 MVT 矢量瓦片的形式提供 Web 地图访问
• 基于 cmd 指令完成元数据查询、样式切换、几何分析、表格/中心线提取、文件导出等
• 存储用户 KV 数据、工作区、符号库、全文索引等辅助能力
• 支持 Python / Node.js SDK 直接对接；

典型使用场景：

• 将单位内部 DWG 档案转成 Web 可浏览地图
• 需要把 CAD 图与 WMS / MVT 图层混合使用
• 针对 DWG 做图形分析（比较、表格提取、中心线）并导出 PDF / DXF
• 在业务系统里存储轻量 KV 配置或自定义属性

2. 系统架构

┌────────────────┐   JWT      ┌──────────────────────┐   stdin/stdout   ┌──────────────────────────┐
│ Client (Web/   │ ─────────► │ web服务       │ ───────────────► │ 图形引擎服务     │
│ Python / Node) │            │ :27660               │                  │ geom / render / export    │
└────────────────┘ ◄───────── │ router + handler  │ ◄─────────────── │ appCmd / mapPsCmd / ...   │
        ▲                     │ + 缓存 / 限流 / 权限 │                  │  持久化        │
        │ REST / HTTP         └──────────────────────┘                  └──────────────────────────┘
        │                              │
        │                              ├── Workspace（多租户命名空间）
        │                              ├── Full-text search
        │                              ├── 符号库
        │                              └── AI / 向量检索（可选）
        │
        └── Tile 通过 CDN / HTTP 缓存直接给前端

• web服务（：入口；做 JWT 鉴权、路由转发、缓存清理、工作区路由改写。
• **图形服务 **：实际的 CAD 解析/渲染/分析。
• 数据存储：每张图对应一个 数据库文件（默认 data/maps/{hash}.db），元数据、样式、缓存瓦片都放在里面；另有全局 KV、工作区、符号库等独立存储。
• 可选 AI服务：/ai/*、/aimcp/*、/aiagent/* 三套子服务通过反代挂载；不是所有部署都启用。

3. 常用接口分 13 大类

4. 该怎么读这份文档？

按兴趣从下面挑一条路径：

1. 第一次接触 vjmap：先过 01-getting-started.md 把 Python 或 Node SDK 跑起来。
2. 看得懂 curl 就够：直接翻 api/01-map-management.md，里面每个接口都有 curl + Python + Node 三列。

5. 命名与术语

6. 约定（Conventions）速览

• 所有 /api/v1/map/... 接口需要 token=<JWT>（query 或 header）
• 95 % 的 cmd 接口既接受 GET 也接受 POST；SDK 统一走 POST
• 成功响应结构两类：
  • 网关包装 {code:0, msg:"", data:{...}}
  • 图形服务 JSON（直接是 {...} 或数组）；SDK 自动识别并 unwrap
• 错误：HTTP 非 2xx → 抛 VjmapError；网关 {code≠0} 也视为错误抛出
• 详细规则见 02-conventions.md