82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
|
# HSAP 车队地图（演示 / T-Box）
|
|||
|
|
|
|||
|
|
## 功能
|
|||
|
|
|
|||
|
|
- 实时查看采集车位置与当前趟次轨迹（**默认高德栅格底图**，国内可访问；可选 `AS_MAP_TILE_PROVIDER=osm`）
|
|||
|
|
- 演示环境默认注入 3 台**长沙**周边假车（湘A），轨迹由贝塞尔曲线密点生成（弯道而非直线折线），后台每 8 秒模拟 T-Box 推进
|
|||
|
|
|
|||
|
|
## 环境变量
|
|||
|
|
|
|||
|
|
| 变量 | 默认 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `AS_FLEET_MAP_ENABLED` | `1` | 启用车队 API |
|
|||
|
|
| `AS_FLEET_MOCK_SEED` | `1` | 首次启动无车辆时注入演示数据 |
|
|||
|
|
| `AS_FLEET_MOCK_SIMULATE` | `1` | 后台模拟 GPS 推进 |
|
|||
|
|
| `AS_FLEET_SIM_INTERVAL_SEC` | `8` | 模拟间隔秒 |
|
|||
|
|
| `AS_TBOX_INGEST_TOKEN` | `hsap-demo-tbox-token` | T-Box 上报 Token |
|
|||
|
|
| `AS_MAP_TILE_PROVIDER` | `gaode` | 底图：`gaode` / `osm`（国内勿用 osm，易灰屏） |
|
|||
|
|
| `AS_AMAP_KEY` | 空 | 高德 Web JS Key（可选，后续 AMap API） |
|
|||
|
|
|
|||
|
|
## T-Box 与车辆关联（无需页面「新建车辆」）
|
|||
|
|
|
|||
|
|
关联键是 **`device_id`**（入库字段 `tbox_device_id`）：
|
|||
|
|
|
|||
|
|
1. 运维在 T-Box / 采集机配置 HSAP 上报地址与 `X-Tbox-Token`（环境变量 `AS_TBOX_INGEST_TOKEN`）。
|
|||
|
|
2. 终端首次 `POST /api/v1/tbox/gps` 时，若该 `device_id` 不存在，平台**自动创建**车辆记录（可用 body 里的 `plate_no` 填车牌）。
|
|||
|
|
3. 后续同一 `device_id` 的点写入当前 active 行程；`run_signal=end/idle` 时结束行程。
|
|||
|
|
|
|||
|
|
可选 body 字段：`plate_no`、`engineer`、`project`、`batch`、`speed_kmh`、`heading`、`ts`。
|
|||
|
|
|
|||
|
|
Web 页仅用于查看地图、改车牌备注、GPX 补录；**不需要**手工新建车辆。
|
|||
|
|
|
|||
|
|
## T-Box 上报示例
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST http://127.0.0.1:8787/api/v1/tbox/gps \
|
|||
|
|
-H "Content-Type: application/json" \
|
|||
|
|
-H "X-Tbox-Token: hsap-demo-tbox-token" \
|
|||
|
|
-d '{"device_id":"TBOX-001","lat":22.72,"lng":114.25,"speed_kmh":40,"run_signal":"active","plate_no":"湘A·采集01"}'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 手动重播种 / 推进
|
|||
|
|
|
|||
|
|
需登录且具备 `write:fleet`（工程师/管理员）：
|
|||
|
|
|
|||
|
|
- `POST /api/v1/fleet/mock/seed` — 仅在无车辆时创建演示数据
|
|||
|
|
- `POST /api/v1/fleet/mock/reseed` — 清空并重新注入长沙演示数据
|
|||
|
|
- `POST /api/v1/fleet/mock/tick` — 手动推进一轮模拟 GPS
|
|||
|
|
|
|||
|
|
切换区域后重新注入：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST http://127.0.0.1:8787/api/v1/fleet/mock/reseed \
|
|||
|
|
-H "Authorization: Bearer <你的 token>"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Phase 2 API（生产化）
|
|||
|
|
|
|||
|
|
| 方法 | 路径 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| POST | `/api/v1/tbox/gps/batch` | 批量上报（最多 100 点），body `{"points":[...]}` |
|
|||
|
|
| GET | `/api/v1/fleet/stream` | SSE 推送 `fleet.gps`（需 Redis + JWT） |
|
|||
|
|
| POST | `/api/v1/fleet/runs/import-csv` | CSV 补录：`lat,lng` 或带表头 `lat,lng,ts`；可选 `project`/`batch` 关联 DMS 批次 |
|
|||
|
|
|
|||
|
|
**超时关趟：** 车辆超过 10 分钟无新 GPS（`RUN_IDLE_TIMEOUT_MIN`）时，`/fleet/live` 与 ingest 前会自动结束 active 行程。
|
|||
|
|
|
|||
|
|
## GPX 轨迹补录
|
|||
|
|
|
|||
|
|
需 `write:fleet`：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST http://127.0.0.1:8787/api/v1/fleet/runs/import-gpx \
|
|||
|
|
-H "Authorization: Bearer <token>" \
|
|||
|
|
-F vehicle_id=1 \
|
|||
|
|
-F file=@track.gpx
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
前端车队页侧栏也可选择车辆上传 `.gpx` 文件。
|
|||
|
|
|
|||
|
|
## 前端
|
|||
|
|
|
|||
|
|
导航 **车队地图**（权限 `read:fleet`），页面每 15 秒轮询 live；选中行程显示里程与里程碑，地图红色点为里程碑。
|