15 KiB
车辆数据中台一期 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 |
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。