地图视图

1. 页面概览

地图视图是 LightGotham 的空间情报展示页，路由 /gotham/map，对应源码 action/web/src/views/GothamMapPage.vue。页面用 Leaflet + OpenStreetMap 渲染地理要素（GET /map/features）：点要素以彩色圆点（divIcon，免图片资源）、线要素以红色 polyline 展示，点击要素弹出详情（名称/描述/类型/区域/属性）。

左侧为操作面板：bbox 包围盒查询、新增要素（point/linestring）、区域聚合统计（条形图）、图层控制（时空增强）——图层显隐、热力图（leaflet.heat，按当前视野）、轨迹回放（polyline + marker 动画）。一句话总结：地图视图是"要素浏览 + 空间检索 + 时空增强"的地理情报工作台。

2. 访问入口

• 路由与菜单：/gotham 布局子路由 path: 'map'，name GothamMap，标题「Gotham 地图视图」，requiresAuth: true；侧边栏第二项「地图视图」（{ path: '/gotham/map', label: '地图视图' }）。
• 认证与权限：请求经 gothamClient.js（baseURL /gotham-api/v1）附 aip_token，401 自动 refresh 重放；/map/* 在 protected 组，无 admin 角色限制。
• 端口与 API 前缀：Gotham 后端 18083，前端前缀 /gotham-api。

3. 界面布局

+------------------------------+------------------------------+
| 页头：Gotham 地图视图 要素<n> [刷新要素]  alert              |
+------------------------------+------------------------------+
| 左面板（map-sidebar 340px）  | 右地图（map-wrap 640px）      |
|  bbox 包围盒查询[框选查询]    | Leaflet 地图：点要素彩色圆点  |
|   minLng/minLat/maxLng/maxLat|  / 线要素红色polyline / 热力  |
|  新增要素(名称/类型/区域/坐标)|  / 轨迹(红色虚线+移动标记)    |
|   属性JSON [新增要素]         |                             |
|  区域聚合统计(区域名+条形+数量)|                             |
|  图层控制：图层显隐/热力图/    |                             |
|   轨迹回放(实体ID+回放/停止)  |                             |
+------------------------------+------------------------------+

各板块职责：

• bbox 包围盒查询：默认四角 115,39,118,41，按框选范围重拉要素并 fitBounds。
• 新增要素：point 输入 lng,lat，linestring 输入 lng,lat;lng,lat 多段；成功后并入并刷新。
• 区域聚合统计：/map/aggregate/regions 各区域计数，按最大值归一化成进度条。
• 图层控制（时空增强）：图层显隐（PUT /map/layers/:id）；热力图按当前视野与网格数（默认 32）调 /map/heatmap；轨迹回放按实体 ID 做 800ms 步进动画。

4. 交互元素

5. 后端关联

API 客户端：gothamClient.js，axios.create({ baseURL: '/gotham-api/v1', timeout: 30000 })；请求拦截器注入 Bearer token，响应 401 自动 refresh 重放。

端点表：

关键机制：

• divIcon 免图片资源：点要素用 L.divIcon + 全局 .g-dot 样式画彩色圆点，颜色按 properties.entity_type 判定（org 橙 / ship 绿 / 其余蓝）；popup 内容 escapeHtml 转义。
• 坐标解析（GeoJSON 语义）：point 为 [lng, lat] 逆转为 Leaflet [lat, lng]；linestring 逐点映射，fitBounds(pad 0.2) 自动适配。
• 热力图按视野联动：heatBounds() 取当前地图 getBounds() 东南西北；grid_size 默认 32（1~200），L.heatLayer（radius 30 / blur 18 / minOpacity 0.35）。
• 轨迹回放动画：setInterval 800ms 步进移动 marker 并 setView(max(zoom,6))，结束/停止时清理定时器与图层。

6. 权限与安全

• 认证：全部请求走 aip_token Bearer，401 自动 refresh 换发重放；刷新失效清 token 跳 /login。
• 角色限制：/map/* 全部在 protected 组，无 admin 细分。
• 写操作防护：新增要素校验名称/坐标必填、坐标格式、属性 JSON；图层名称必填。

7. 常见问题与排错

问题 1：地图底图空白但要素能显示

现象：地图区域空白，只有彩色圆点。

原因：OpenStreetMap 在线瓦片加载失败（无外网）。

处理：确认可访问 {s}.tile.openstreetmap.org；内网环境需替换 tileLayer 为内网瓦片源。

问题 2：新增要素报「点坐标格式：lng,lat」

现象：提交被前端拦截。

原因：坐标输入与 geometry_type 不匹配。

处理：point 输入如 116.4,39.9；linestring 输入如 116.4,39.9;121.4,31.2。

问题 3：热力图点了「刷新热力」没反应

现象：地图不出现热力层。

原因：未勾选「启用热力图（按当前视野）」，loadHeatmap 开头直接 return；或该视野无数据。

处理：先勾选启用热力图再点「刷新热力」；确认 /map/heatmap 返回非空网格。

问题 4：轨迹回放提示「该实体暂无轨迹点」

现象：实体 ID 正确但无轨迹。

原因：/map/trajectory/:entity_id 返回空数组。

处理：换成有轨迹数据的实体（如默认 graph:person:zhy），或先在「情报工作台」确认实体存在。

8. 已知缺陷与边界

注：图层勾选不真正过滤要素已于 2026-09-06 修复（按图层归属过滤并真实重绘，heat 联动）。