# 羚牛 Vehicle Map

全国氢能车辆与加氢站运营驾驶舱。浏览器只访问本服务的 `/api/dashboard`，服务端使用开放平台 AppKey 获取其授权车辆、当日里程和资产库只读加氢站点位，AppKey 不会下发到浏览器。

## 当前部署

- ECS 服务：`lingniu-vehicle-map.service`
- 访问地址：<https://map.d.lnoneos.com/>
- 健康检查：<https://map.d.lnoneos.com/api/health>

原始仓库只有静态页面和静态文件服务，没有车辆数据接口；当前版本已改为通过服务端代理对接车辆数据开放平台，页面展示的数据不再使用硬编码车辆和加氢站样例。

## 本地运行

```bash
export OPEN_PLATFORM_APP_KEY='<32位AppKey>'
python3 server.py
```

默认地址：`http://127.0.0.1:20800`。

请通过上述 HTTP 地址访问，不能直接双击打开 `index.html`：页面需要同源调用本服务的公开站点与授权 API。

## 公开与授权数据边界

- `GET /api/public/stations` 无需授权，仅返回站点名称、坐标、省市区、地址与合作状态；加氢量字段不在响应中。
- `GET /api/dashboard` 需要 `operations:read` 会话，返回全部车辆信息及加氢站加氢量。
- `POST /api/session` 接收访问码，服务端验证后写入短期 HttpOnly 会话 Cookie；浏览器可保存该会话，访问码不会下发或存入前端。
- `DELETE /api/session` 清除当前浏览器的运营会话。

当前默认 `VEHICLE_MAP_AUTH_PROVIDER=local`，生产环境在 `/opt/lingniu-vehicle-map/env/vehicle-map.env` 设置：

```bash
VEHICLE_MAP_ACCESS_CODE=<访问码>
VEHICLE_MAP_SESSION_SECRET=<至少32位随机密钥>
VEHICLE_MAP_SESSION_TTL_SECONDS=1800
VEHICLE_MAP_COOKIE_SECURE=true
```

授权会话有效期为 30 分钟；到期后自动回到仅展示公开加氢站目录的状态。

后续接入统一鉴权中心时，将 `VEHICLE_MAP_AUTH_PROVIDER` 改为 `auth-center` 并配置 `VEHICLE_MAP_AUTH_CENTER_INTROSPECTION_URL`；前端流程与受保护接口不需要调整。鉴权中心适配器的约定为接收 `{accessCode, audience:"vehicle-map"}`，返回 `{active, subject, scopes}`，且 scopes 需要包含 `operations:read`。

## 接口依赖

- `POST /api/v1/vehicles/realtime/query`：全部授权车辆实时位置与状态；
- `POST /api/v1/vehicles/mileage/query`：全部授权车辆当日里程；
- `POST /api/v1/hydrogen-stations/query`：资产库只读加氢站地图点位。

以上三个接口均使用开放平台的 `Authorization: Bearer <AppKey>` 鉴权。生产 AppKey 仅保存在 ECS 的 `/opt/lingniu-vehicle-map/env/vehicle-map.env`，文件权限为 `root:vehicle-map 0640`。

本服务提供：

- `GET /api/health`：进程及配置状态；
- `GET /api/dashboard`：面向前端的聚合数据，默认缓存5秒；加氢站缓存1小时。

全国视图按车辆最新 GPS 坐标落入省级行政区，不按车牌归属地推断；没有有效实时坐标的车辆会单独计入“无实时位置”，不会伪造省份归属。页面每15秒刷新一次。

车辆地图按缩放级别逐级下钻：全国视角（小于7级）按省聚合，7–9.5级按市聚合，9.5–12级按区县聚合，12级及以上显示当前视野内的单车真实位置。点击省、市、区县气泡会自动进入下一级。