# 大屏 — 集中化 GIS 地图对接技术方案

> 依据《中国移动集中化 GIS 平台 JSAPI 接口协议 v1.0》（`集中化GIS系统JSAPI接口文档.docx`）。  
> 前端引擎为 **cmmap GL JS**（API 形态与 Mapbox GL JS 接近），全局对象 **`cmmapgl`**。

---

## 1. 对接前提（向 GIS 平台申请）

| 项 | 说明 |
| --- | --- |
| **GIS 服务根地址** | 文档中的「GIS 服务地址」，如 `https://gis.example.com` |
| **地图密钥 accessToken** | 文档 §2.2；初始化前赋值 `cmmapgl.accessToken` |
| **底图样式 style** | Mapbox Style 规范 JSON 或样式 URL（`MapOptions.style`） |
| **跨域** | 生产由 GIS/Nginx 放行；开发可用 Vite 代理 `/gis-dev-proxy` |

---

## 2. 静态资源引入

文档 §2.1 要求在页面引入（将 `GIS服务地址` 替换为实际根地址）：

```html
<script src="{GIS_BASE}/agis/resources/v1/tile-server/dist/cmmap-gl/1.0/cmmap-gl.js"></script>
<link href="{GIS_BASE}/agis/resources/v1/tile-server/dist/cmmap-gl/1.0/cmmap-gl.css" rel="stylesheet" />
```

`ruoyi-screen` 通过 `src/utils/gisLoader.js` **按需动态加载**，避免未配置 GIS 时阻塞整站。

---

## 3. 初始化流程

```text
loadGisSdk() → cmmapgl.accessToken = token → new cmmapgl.Map({ container, center, zoom, style })
```

| 参数 | 说明 |
| --- | --- |
| `container` | 地图容器 DOM 或 id |
| `center` | **`[经度, 纬度]`**（与 GeoJSON 一致，勿写反） |
| `zoom` | 0–24，默认约 2–9 |
| `style` | 底图样式 URL 或 JSON |
| `accessToken` | 也可在 `MapOptions` 中传 `accessToken`，会覆盖全局 `cmmapgl.accessToken` |

巴青县默认中心（可在页面覆盖）：`[94.05, 31.92]`，缩放 `9`。

---

## 4. 常用能力（按大屏场景）

| 文档章节 | 能力 | 大屏典型用途 |
| --- | --- | --- |
| §3.1 | `cmmapgl.Map` | 底图展示 |
| §3.3 | `NavigationControl` / `ScaleControl` | 导航、比例尺（大屏可关闭交互） |
| §4 | `addSource` + `addLayer` | 矢量/栅格/GeoJSON 业务图层 |
| §5.1 | `cmmapgl.Marker` | 牧场、检疫站、交易市场点位 |
| §5.2 | `Popup` | 点位详情气泡 |
| §7 | 热力图、散点、轨迹等 | 疫病风险、资源分布 |
| §8 | `agis.turf` | 空间计算（点线面关系） |
| §10–11 | POI / 路线 | 后续扩展 |

---

## 5. ruoyi-screen 工程约定

### 5.1 环境变量（`.env.development` / `.env.production`）

```bash
# GIS 服务根地址（勿带末尾 /）
VITE_GIS_BASE_URL=/gis-dev-proxy
# 地图密钥（§2.2，由 GIS 平台发放）
VITE_GIS_ACCESS_TOKEN=
# 底图样式 URL 或 JSON 路径
VITE_GIS_MAP_STYLE=
# 默认中心：经度,纬度
VITE_GIS_DEFAULT_CENTER=94.05,31.92
VITE_GIS_DEFAULT_ZOOM=9
```

开发环境在 `vite.config.js` 将 `/gis-dev-proxy` 代理到真实 GIS 服务（`VITE_GIS_PROXY_TARGET`）。

### 5.2 代码入口

| 文件 | 职责 |
| --- | --- |
| `src/utils/gisLoader.js` | 动态加载 cmmap-gl.js/css、读取 env |
| `src/components/GisMap.vue` | 通用地图容器，`@ready` 抛出 `map` 实例 |

### 5.3 页面使用示例

```vue
<GisMap
  class="my-map"
  :interactive="false"
  @ready="onMapReady"
  @error="onMapError"
/>
```

```javascript
function onMapReady(map) {
  // map 为 cmmapgl.Map 实例
  // map.addSource / addLayer / Marker 等见文档 §4–§5
}
```

---

## 6. 注意事项

1. **坐标顺序**：一律 `[lng, lat]`。
2. **容器尺寸**：父级须有明确宽高（大屏组件内 `width/height: 100%`）。
3. **销毁**：路由离开须 `map.remove()`（`GisMap.vue` 已在 `onUnmounted` 处理）。
4. **resize**：大屏 `screenFit` 缩放后若地图空白，在布局稳定后调用 `map.resize()`。
5. **token 缺失**：未配置 `VITE_GIS_ACCESS_TOKEN` 时组件展示占位提示，不抛白屏。

---

## 7. 交付清单

- [x] `gisLoader.js` 动态加载 SDK
- [x] `GisMap.vue` 基础地图组件
- [x] Vite 开发代理占位
- [x] 业务页嵌入地图（`ScreenLayout` 中间栏共用底图，各子页左右面板叠在两侧）
- [ ] 业务点位/GeoJSON 与后端接口联调