154 lines
15 KiB
Markdown
154 lines
15 KiB
Markdown
# 车辆数据中台一期 API 能力与缺口
|
||
|
||
## 1. 判定规则
|
||
|
||
- “已有”表示当前平台 BFF 已有路由和生产 Store 实现。
|
||
- “部分”表示可作为底层数据来源，但 DTO、筛选、性能或业务语义不足。
|
||
- “缺失”表示当前没有可支撑验收的持久化/API 链路。
|
||
- 新接口建议统一放 `/api/v2`；旧 `/api/alert-events*` 是质量接口别名，不得作为新告警契约继续扩展。
|
||
|
||
## 2. 现有接口清单
|
||
|
||
| 方法与路径 | 状态 | 数据源/说明 |
|
||
| --- | --- | --- |
|
||
| `GET /api/dashboard/summary` | 已有 | MySQL/运维探针聚合；口径偏现有服务健康 |
|
||
| `GET /api/vehicles` | 已有 | 车辆身份与实时快照集合，支持关键词/协议等基础过滤 |
|
||
| `GET /api/vehicles/resolve` | 已有 | 通过 VIN、车牌、手机号解析车辆 |
|
||
| `GET /api/vehicles/coverage`、`/summary` | 已有 | 多协议来源覆盖、绑定和在线来源数 |
|
||
| `GET /api/vehicle-service`、`/summary`、`/overview` | 已有 | 单车/车队证据聚合 |
|
||
| `POST /api/vehicle-service/overviews` | 已有 | 批量关键词概览 |
|
||
| `GET /api/realtime/vehicles` | 已有 | VIN 级聚合实时状态 |
|
||
| `GET /api/realtime/locations` | 已有 | MySQL 每协议最新位置 |
|
||
| `GET /api/history/locations` | 已有 | TDengine 位置历史；基础分页和时间过滤 |
|
||
| `GET /api/history/raw-frames` | 已有 | TDengine RAW；默认 100 条，可选解析字段 |
|
||
| `POST /api/history/raw-frames/query` | 已有 | 复杂 RAW 查询 |
|
||
| `GET /api/mileage/summary`、`/daily` | 已有 | MySQL 日里程 |
|
||
| `GET /api/statistics/online-summary`、`/online-vehicles` | 已有 | 固定口径在线统计 |
|
||
| `GET /api/quality/summary`、`/issues`、`/notification-plan` | 已有 | 推导质量信号和静态方案，不持久化 |
|
||
| `GET /api/alert-events*` | 语义错误 | 上述质量接口别名，不是告警规则/事件/通知 |
|
||
| `GET /api/map/reverse-geocode` | 已有 | 服务端高德逆地理编码 |
|
||
| `GET /api/ops/health`、`/source-readiness` | 已有 | 链路、release、lag、连接、可写性和来源准备度 |
|
||
|
||
## 3. 按一期功能的缺口矩阵
|
||
|
||
| 功能 | 当前可复用 | 仍缺少 | 优先级 |
|
||
| --- | --- | --- | --- |
|
||
| 全局统计 | V2 monitor summary 已实现接入/在线/离线/行驶/静止/未知/今日上报，以及活跃业务告警 VIN 与同筛选车辆集合交集后的权威告警车辆数；页面仅在服务端明确可用时展示数值 | 更复杂的车型/企业/接入商组合字典可在车辆规模增长时从接入管理筛选下沉复用 | P0（一期完成） |
|
||
| 地图车辆 | V2 monitor map 已实现 bounds/zoom、关键词/协议/状态筛选、低缩放聚合、高缩放轻量点、2,000 点自适应降级；前端独立缓存、防抖请求和 MassMarks，列表上限 200 | 差量 cursor/SSE 作为车辆规模或刷新频率继续增长后的扩展项 | P0（一期完成） |
|
||
| 车辆信息卡 | 选中车辆按需并发组合 realtime、vehicle service、daily mileage、服务端逆地理编码和 `status=active` 告警；展示当日里程、地址、全部真实来源、接入厂家、当前告警及三处深链 | 权威档案未提供接入厂家时明确显示“待补充”，不从协议猜测 | P0（一期完成） |
|
||
| 单车档案 | vehicle service 已合并 `vehicle_profile`；管理员可单车维护或用 CSV/API 批量同步，外部同步具备来源/版本幂等、人工及异源保护、显式接管、dry-run、身份校验和版本审计 | 仍需为具体车厂/GPS 厂商配置定时连接器；首次接入/运行时长的自动投影仍待网关权威源 | P0（部分完成） |
|
||
| 最新遥测 | `GET /api/v2/vehicles/:vin/telemetry/latest` 已服务端选择每个统一指标/源字段最新值，动态分组，保留厂家扩展，并返回中文名、单位、类型、设备/接收时间、帧、协议、端点、freshness/delay 与值级质量原因；页面独立缓存刷新且不再猜测 RAW 元数据 | 更多动态 RAW 指标进入统一目录仍需受控发现和管理端审计，不影响一期最新值取证 | P0（一期完成） |
|
||
| 轨迹 | V2 playback 已有覆盖边界、最多 7 天校验、GPS 质量过滤、推断停车、活动分段、关键点保留抽稀、方向/SOC/告警同步字段和统计元数据 | ignition 可信怠速、持久 queryId/游标分段仍缺少 | P0（部分完成） |
|
||
| 回放地址 | 暂停点按坐标缓存逆地理编码，播放时暂停解析，避免逐点请求 | 服务端批量地址目录仅在未来需要轨迹点地址表时再建设 | P1（一期完成） |
|
||
| 历史列表/曲线 | V2 动态指标目录、多车多指标列表、服务端分页、按单位拆轴的时间序列聚合、空窗/覆盖率/异常证据和 60–600 点受控曲线已上线 | 更多可聚合遥测指标需随统一指标目录逐项开放；RAW 保持离散证据 | P0（一期完成） |
|
||
| 导出 | 单 ECS 持久异步 CSV 队列已上线：进度/状态/完成时间/下载、单并发、31 天/5 车/32 指标/100 万行/30 分钟配额、游标流式写入、重启恢复和原子文件发布 | XLSX、取消和多实例对象存储属于扩容项，不阻塞一期 CSV 验收 | P0（一期完成） |
|
||
| 告警规则 | V2 MySQL 规则、版本审计、CRUD/启停/校验、统一指标目录动态校验、数值区间内外、布尔状态变化、协议/VIN/OEM/车型/企业范围、持续/恢复/重复抑制已实现 | 软删除、复杂范围组合预估和批量规则导入仍待补齐 | P0（部分完成） |
|
||
| 告警事件 | V2 持久事件、事件时间持续候选、活跃指纹去重、恢复/处置时间线、通知、Kafka fields active consumer、规则副作用与 checkpoint 同事务、数据库权威重放抑制、迟到门禁、动态/墙钟所有权拆分、真实规则灰度、锁竞争及连续运行门禁均已上线 | 跨窗口历史重算属于后续分析能力；短信/邮件/企微供应商明确不在一期范围 | P0（一期完成） |
|
||
| 站内通知 | V2 列表、未读数、批量已读和页面轮询已实现；外部通道明确为 reserved | SSE 可在通知规模增长时替换轮询；外部供应商不在一期范围 | P1（一期完成） |
|
||
| 接入状态 | V2 summary/vehicles/thresholds 已实现动态阈值、事件/接收延迟、状态区分、协议/车辆厂家/车型/接入厂家/首次接入/最新上报筛选、同口径统计和版本审计；网关同一快照 upsert 已维护首次/前次/最新接收、连续间隔、样本数及回填边界；缺 VIN 的 JT808 终端已进入脱敏处置队列 | 仍需运维核对来源并维护权威 phone→VIN 绑定；历史首次接入只能由未来权威台账补齐，不能把上线回填当历史真值 | P0（部分完成） |
|
||
| 权限审计 | ECS 强制 Bearer 鉴权；viewer/operator/admin 累积权限、前端会话门禁、后端逐操作校验、规则/阈值/告警动作版本审计及越权拒绝均已验证 | 企业 SSO 与复杂多租户不在一期范围 | P0（一期完成） |
|
||
|
||
## 4. 推荐 V2 API
|
||
|
||
### 4.1 元数据与车辆
|
||
|
||
| 方法与路径 | 用途 | 关键参数/响应 |
|
||
| --- | --- | --- |
|
||
| `GET /api/v2/meta/vehicle-filters` | 全局筛选字典 | OEM、车型、公司、协议、接入厂家、状态；带版本/ETag |
|
||
| `GET /api/v2/metrics` | 动态指标目录 | `protocol, category, valueType, searchable, chartable, alertable` |
|
||
| `GET /api/v2/vehicles/search` | 远程车辆选择 | `q, cursor, limit`；返回 VIN、车牌、车辆编号 |
|
||
| `GET /api/v2/vehicles/:vin` | 单车数字档案 | 档案、实时摘要、接入摘要、当前告警摘要 |
|
||
| `GET /api/v2/vehicles/:vin/telemetry/latest` | 动态最新遥测 | 按 category 分组，值含时间、单位、质量、来源 |
|
||
|
||
### 4.2 全局监控
|
||
|
||
| 方法与路径 | 用途 | 关键参数/响应 |
|
||
| --- | --- | --- |
|
||
| `POST /api/v2/monitor/summary` | 与筛选完全一致的状态统计 | 组合过滤对象、`asOf`、在线阈值版本 |
|
||
| `POST /api/v2/monitor/map` | 视口聚合/车辆点 | `bounds, zoom, filters, cursor`；返回 `mode=clusters|points`、聚合数或轻量点 |
|
||
| `GET /api/v2/monitor/vehicles/:vin/card` | 点位详情卡 | 核心实时、当日里程、来源、告警、地址缓存 |
|
||
| `GET /api/v2/monitor/changes` | 可选差量刷新 | `since` 或 SSE；返回变更车辆和统计版本 |
|
||
|
||
`monitor/map` 必须有最大点数和聚合降级；低缩放级别绝不返回全部明细。轻量点不携带完整 telemetry JSON。
|
||
|
||
### 4.3 轨迹
|
||
|
||
| 方法与路径 | 用途 | 关键参数/响应 |
|
||
| --- | --- | --- |
|
||
| `POST /api/v2/tracks/query` | 轨迹分段查询 | VIN、时间、协议、filter、targetPoints、cursor；返回点、起终点、过滤/抽稀计数和算法版本 |
|
||
| `GET /api/v2/tracks/:queryId/segments` | 大查询后续分段 | segment/cursor；支持取消/过期 |
|
||
| `GET /api/v2/tracks/:queryId/stops` | 停车点 | 起止时间、时长、坐标、地址缓存状态 |
|
||
|
||
轨迹点至少包含 `eventTime, receivedAt, lng, lat, speedKmh, directionDeg, socPercent, totalMileageKm, alarmFlag, statusFlag, state`。抽稀必须保留起终点、停车边界和告警点，并返回原始/有效/返回点数。
|
||
|
||
### 4.4 历史分析
|
||
|
||
| 方法与路径 | 用途 | 关键参数/响应 |
|
||
| --- | --- | --- |
|
||
| `POST /api/v2/timeseries/query` | 多车多指标曲线 | VINs、metricKeys、时间、granularity、aggregation、targetPoints、fillPolicy |
|
||
| `POST /api/v2/timeseries/rows` | 动态列列表 | 同上 + cursor、limit、sort、filters |
|
||
| `POST /api/v2/timeseries/estimate` | 查询/导出预估 | 估算点数、行数、扫描范围并给出建议粒度 |
|
||
|
||
服务端只允许指标目录白名单，不能把客户端 metricKey 直接拼入 SQL。响应带指标显示名、单位、类型、来源、采样方式和空值策略。
|
||
|
||
### 4.5 导出任务
|
||
|
||
| 方法与路径 | 用途 |
|
||
| --- | --- |
|
||
| `POST /api/v2/exports` | 创建任务；携带查询快照、CSV/XLSX、时区；使用幂等键 |
|
||
| `GET /api/v2/exports` | 当前用户任务分页 |
|
||
| `GET /api/v2/exports/:id` | 状态、进度、行数、完成/过期时间、错误 |
|
||
| `POST /api/v2/exports/:id/cancel` | 取消排队/运行任务 |
|
||
| `GET /api/v2/exports/:id/download` | 权限检查后短期下载或签名 URL |
|
||
|
||
状态：`queued, running, succeeded, failed, canceled, expired`。同步 API 不生成大文件。
|
||
|
||
### 4.6 告警与通知
|
||
|
||
| 方法与路径 | 用途 |
|
||
| --- | --- |
|
||
| `GET/POST /api/v2/alert-rules` | 规则列表/创建 |
|
||
| `GET/PUT/DELETE /api/v2/alert-rules/:id` | 详情/修改/软删除 |
|
||
| `POST /api/v2/alert-rules/:id/enable|disable` | 明确启停操作 |
|
||
| `POST /api/v2/alert-rules/validate` | 校验指标类型、操作符、阈值和范围 |
|
||
| `GET /api/v2/alert-events`、`/summary` | 事件列表和统计 |
|
||
| `GET /api/v2/alert-events/:id` | 事件详情与完整处理时间线 |
|
||
| `POST /api/v2/alert-events/:id/acknowledge` | 确认/进入处理中 |
|
||
| `POST /api/v2/alert-events/:id/close` | 关闭，要求备注 |
|
||
| `POST /api/v2/alert-events/:id/ignore` | 忽略，要求原因 |
|
||
| `GET /api/v2/notifications`、`/unread-count` | 站内通知/未读数 |
|
||
| `POST /api/v2/notifications/read` | 批量已读 |
|
||
|
||
所有变更接口记录操作者、时间、前后状态、备注和 traceId；规则修改采用 `version` 乐观锁。
|
||
|
||
实现记录（2026-07-14）：实际落地路由统一在 `/api/v2/alerts/*`，列表/汇总使用 POST 同构筛选体，处置统一为 `POST /events/:id/actions`，规则启停为版本化 `PUT /rules/:id/enabled`。迁移为 `002_alert_center.sql`、`003_alert_rule_advanced.sql` 与 `004_alert_repeat_index.sql`，独立 `alert-evaluator` systemd 服务以当前 MySQL realtime location 作为一期评估输入。旧 `/api/alert-events*` 继续只是质量投影兼容接口，新页面不依赖它们。Kafka 可重放消费、迟到窗口和 traceId 写入通用审计仍是生产退出缺口。
|
||
|
||
指标目录实现记录（2026-07-14）：`GET /api/v2/metrics` 已返回统一 key、中文名、单位、类别、值类型、协议及源字段映射和三类能力标记；生产权威数据已落入 `vehicle_metric_definition/vehicle_metric_protocol_mapping`，`005_metric_catalog.sql` 仅补齐初始缺失项，不覆盖后续配置。告警编辑器只消费其中 `alertable=true` 且类型匹配的指标，规则写接口再次校验白名单、能力、值类型和 evaluator 支持。`GET /api/v2/vehicles/:vin/telemetry/latest` 现消费同一目录并为未入目录的厂家字段保留源字段、动态分类和质量证据；历史页仍保留 `/api/v2/history/metrics` 兼容目录。后续仅剩动态 RAW 指标受控发现与管理端版本审计。
|
||
|
||
### 4.7 接入管理
|
||
|
||
| 方法与路径 | 用途 |
|
||
| --- | --- |
|
||
| `POST /api/v2/access/summary` | 按同一筛选口径统计协议、厂家、在线率、今日上报、长离线、从未上报、延迟异常 |
|
||
| `POST /api/v2/access/vehicles` | 接入状态分页；支持阈值、时间、厂家/车型/协议过滤 |
|
||
| `POST /api/v2/access/unresolved-identities` | 无权威 VIN 的真实终端处置队列；只返回哈希 ID、脱敏标识和登记/上报证据 |
|
||
| `GET /api/v2/access/thresholds` | 获取全局默认和协议覆盖阈值 |
|
||
| `PUT /api/v2/access/thresholds` | 管理员更新阈值并记录版本/审计 |
|
||
|
||
接入行应返回 `firstSeenAt, latestEventAt, latestReceivedAt, reportIntervalSec, dataDelaySec, onlineState, thresholdSec, latestMessageType, latestError`，并区分 `online/offline/never_reported/unknown`。
|
||
|
||
实现记录（2026-07-14）：状态/阈值接口、同口径筛选、动态状态、阈值乐观锁和 MySQL 审计已落地；gateway access projection 已维护 first/previous/latest received、latest error、样本数和连续间隔。`platform-v2-20260714080619` 新增身份待绑定接口和紧凑处置队列：生产当前识别 1 个真实 JT808 缺 VIN 终端，响应和复制证据均仅含脱敏标识，20 次顺序查询 p50 2.02ms、p95 2.44ms、最大 4.66ms。该队列用于推动权威绑定，不会把手机号猜成 VIN，也不会让未绑定身份参与车辆告警。
|
||
|
||
## 5. 横切契约
|
||
|
||
- 时间统一使用 RFC 3339/UTC 传输，UI 按 Asia/Shanghai 展示；同时保留事件时间和接收时间。
|
||
- 列表固定 `items + pageInfo`；大时序优先 cursor，管理列表可 offset；总数默认可选，避免高成本 COUNT。
|
||
- 所有筛选/排序字段白名单化；请求体大小、VIN 数、指标数、时间范围、返回点数均设上限。
|
||
- API 返回 `traceId`、数据 `asOf`、口径/算法版本；可取消请求使用 `AbortSignal`。
|
||
- 查询 GET 可 ETag/短缓存；任务/规则 POST 使用幂等键；状态修改使用版本号。
|
||
- 前端只访问平台 BFF。Redis/TDengine/MySQL 连接与高德 REST key 均不暴露。
|
||
|
||
## 6. 兼容与下线
|
||
|
||
旧接口在 V2 联调期保留；新页面不依赖旧 `alert-events` 别名。完成迁移后先增加 deprecation 响应头和调用监控，再按版本窗口下线。现有 `/api/history/locations` 和 RAW 查询可继续作为运维证据接口，不强行替换为业务时序 DTO。
|