shishengliang/lingniu-vehicle-ingest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8acd3806c98e4e33017c43b9818b3cb0961c00dc
lingniu-vehicle-ingest/docs/superpowers/specs/2026-07-03-vehicle-data-platform-design.md
lingniu 8acd3806c9 docs: add vehicle data platform design spec
2026-07-03 20:13:15 +08:00

11 KiB
Raw Blame History

车辆数据管理中台设计 Spec

目标

建设一套独立的车辆数据管理中台，放在新项目目录 vehicle-data-platform。中台包含前端和后端，前端使用 Semi UI，整体风格高级、简洁、接近大厂数据控制台；后端使用 Go BFF 聚合现有车辆接入链路的数据能力。系统一期目标是让业务和运营人员可以稳定完成查车、看实时状态、查历史、追溯 RAW、看里程和定位数据质量问题，同时给平台运维提供只读链路健康态势。

一期定位

一期优先服务运营和业务人员，核心问题是：

  • 车辆是否在线。
  • 车辆在哪里。
  • 最新状态是什么。
  • 最近是否断链。
  • 每日和区间里程是否可信。
  • 原始报文是否可追溯。
  • VIN、车牌、手机号、OEM 绑定是否正确。

链路运维能力作为辅助模块内嵌，展示 Gateway、NATS、Kafka、Redis、TDengine、MySQL 和 capacity-check 的关键健康状态，但一期不做复杂监控平台和告警工单闭环。

非目标

一期不做以下内容：

  • 复杂多租户权限体系。
  • 自定义大屏编排。
  • 报警通知和工单闭环。
  • 任意字段计算平台。
  • 完整 BI 报表系统。
  • 复杂轨迹回放动画。
  • 对现有 Go gateway、NATS bridge、history writer、stat writer、realtime API 做破坏性改造。

项目结构

新建项目目录：

vehicle-data-platform/
  apps/
    web/
    api/
  docs/
    product-spec.md
    api-contract.md
    deployment.md
  deploy/
    systemd/
    nginx/
  scripts/

前端技术栈

  • React
  • TypeScript
  • Vite
  • Semi UI
  • ECharts
  • 地图组件，一期可先用轻量地图封装，后续再替换为正式地图供应商

后端技术栈

  • Go
  • 标准库 HTTP 或轻量路由
  • MySQL driver
  • Redis client
  • TDengine driver
  • HTTP client 聚合现有 health、metrics、capacity-check 输出

后端作为 BFF，不让前端直接连接 MySQL、Redis、TDengine 或现有 realtime API。

信息架构

左侧导航包含 7 个一级模块。

1. 总览工作台

路径：/dashboard

能力：

  • 在线车辆数。
  • 今日活跃车辆。
  • 今日上报量。
  • 异常车辆数。
  • Kafka lag。
  • 链路健康状态。
  • 协议分布：GB32960、JT808、YUTONG_MQTT。
  • 最新车辆分布地图小窗。
  • 最近异常列表：断链、未绑定、里程异常、解析失败。

2. 车辆台账

路径：/vehicles

能力：

  • 表格展示车牌、VIN、手机号、OEM、协议来源、在线状态、最后上报、最近位置、绑定完整度。
  • 支持 VIN、车牌、手机号、OEM 搜索。
  • 支持协议、在线状态、绑定完整度筛选。
  • 支持查看详情、导出。
  • 支持导入绑定入口的一期展示：提供导入说明和模板下载按钮，不提交数据；正式写入流程不纳入一期验收。

3. 实时监控

路径：/realtime

能力：

  • 表格视图和地图视图切换。
  • 展示 VIN、车牌、协议、速度、SOC、总里程、最后上报时间、位置。
  • 按协议和在线状态分色。
  • 点击车辆后打开右侧抽屉展示最新 realtime raw 字段摘要。

4. 车辆详情

路径：/vehicles/:vin

能力：

  • 顶部身份卡：车牌、VIN、OEM、协议、在线状态。
  • Tabs：
    • 最新状态。
    • 历史位置。
    • RAW 报文。
    • 里程统计。
    • 数据质量。
  • 多协议对比：同一车辆在 GB32960、JT808、YUTONG_MQTT 下的最新时间、字段完整度、里程差异。

5. 历史数据

路径：/history

能力：

  • Tab：历史位置、RAW 报文。
  • 查询条件：VIN、协议、时间范围、消息类型、字段筛选。
  • RAW 支持分页、字段裁剪、是否包含 payload、JSON 详情查看。
  • 历史位置支持表格和轨迹简图。

6. 里程与统计

路径：/mileage

能力：

  • 日里程查询。
  • 区间里程查询。
  • 协议来源对比。
  • 异常标记：总里程倒退、突增、缺失、跨协议不一致。

7. 数据质量与链路健康

路径：/quality

能力：

  • 断链车辆。
  • 未绑定车辆。
  • 无 VIN、无车牌、无手机号车辆。
  • RAW 解析失败。
  • capacity-check 结果。
  • Kafka/NATS/TDengine/Redis/MySQL 关键状态。

视觉与交互设计

整体视觉使用 Semi UI 原生组件为基础，避免大屏炫技风。目标是云控制台、数据控制台、飞书后台一类的专业感。

设计原则

  • 灰白背景，深色正文，蓝青强调色。
  • 红橙只用于异常、告警、风险。
  • 表格优先，不用卡片堆满页面。
  • KPI 卡片少而准。
  • 右侧抽屉承载详情，不频繁跳整页。
  • RAW 和 parsed JSON 使用代码查看器或结构化 JSON Tree。
  • 地图是业务辅助，不作为首页背景。
  • 所有列表页都有稳定筛选区、刷新时间和导出入口。

页面骨架

  • 顶部栏：系统名、全局车辆搜索、环境状态、刷新时间、用户入口。
  • 左侧栏：7 个一级导航。
  • 主体区：页面标题、筛选/操作区、数据区。
  • 右侧抽屉：车辆摘要、RAW 详情、异常解释。

后端 BFF 设计

后端统一暴露 /api/*，并托管前端静态文件。

API 响应格式

成功：

{
  "data": {},
  "traceId": "string",
  "timestamp": 1783080000000
}

分页：

{
  "data": {
    "items": [],
    "total": 100,
    "limit": 50,
    "offset": 0
  },
  "traceId": "string",
  "timestamp": 1783080000000
}

错误：

{
  "error": {
    "code": "QUERY_FAILED",
    "message": "查询失败",
    "detail": "具体错误"
  },
  "traceId": "string",
  "timestamp": 1783080000000
}

后端模块

vehicle

职责：

  • 车辆台账。
  • 身份绑定。
  • VIN、车牌、手机号、OEM 查询。

数据源：

  • MySQL vehicle_identity_binding。
  • MySQL vehicle_realtime_snapshot 和 vehicle_realtime_location 用于补充在线状态和最新上报。

realtime

职责：

  • 实时位置。
  • 实时快照。
  • 单车当前状态。
  • 单车协议 realtime raw 摘要。

数据源：

  • MySQL vehicle_realtime_snapshot。
  • MySQL vehicle_realtime_location。
  • Redis vehicle:realtime-raw:{protocol}:{vin}。
  • Redis online key 族。

history

职责：

  • 历史位置。
  • RAW frame 查询。
  • RAW 字段过滤。

数据源：

  • TDengine vehicle_locations。
  • TDengine raw_frames。
  • TDengine raw_frame_payload_chunks。

mileage

职责：

  • 日里程。
  • 区间里程。
  • 里程异常解释。

数据源：

  • MySQL vehicle_daily_mileage。

quality

职责：

  • 无 VIN。
  • 无车牌。
  • 无手机号。
  • 长时间未上报。
  • 里程突变。
  • 解析失败。

数据源：

  • MySQL identity 和 realtime 表。
  • TDengine raw_frames。
  • Redis online。

ops

职责：

  • capacity-check。
  • 服务 readyz。
  • Kafka/NATS/Redis/TDengine/MySQL 状态摘要。

数据源：

  • 现有本机 health endpoint。
  • 现有 metrics endpoint。
  • /opt/lingniu-go-native/current/capacity-check 输出。

一期 API

Dashboard

  • GET /api/dashboard/summary

返回：

  • 车辆在线数。
  • 今日活跃数。
  • 今日上报量。
  • 协议分布。
  • 异常计数。
  • 链路健康摘要。

Vehicles

  • GET /api/vehicles
  • GET /api/vehicles/:vin
  • GET /api/vehicles/:vin/realtime
  • GET /api/vehicles/:vin/protocols

Realtime

  • GET /api/realtime/locations
  • GET /api/realtime/snapshots
  • GET /api/realtime/raw/:protocol/:vin

History

  • GET /api/history/locations
  • POST /api/history/raw-frames/query

RAW query 使用 POST，避免字段过滤数组导致 URL 过长。

Mileage

  • GET /api/mileage/daily
  • GET /api/mileage/range

Quality

  • GET /api/quality/issues
  • GET /api/quality/unbound-vehicles
  • GET /api/quality/offline-vehicles

Ops

  • GET /api/ops/health
  • GET /api/ops/capacity

数据源映射

MySQL

  • vehicle_identity_binding：车辆身份事实表。
  • vehicle_realtime_snapshot：每协议每 VIN 最新轻量快照。
  • vehicle_realtime_location：每协议每 VIN 最新位置。
  • vehicle_daily_mileage：每日里程统计。
  • jt808_registration：JT808 注册与鉴权辅助信息。

Redis

  • vehicle:realtime-raw:{protocol}:{vin}：最新完整协议 parsed 状态。
  • vehicle:online:*：在线状态。
  • vehicle:last_seen：最近活跃排序。
  • vehicle:rt-kv:*：扁平化实时字段。

TDengine

  • raw_frames：RAW 证据层。
  • raw_frame_payload_chunks：超长 payload 分片。
  • vehicle_locations：历史位置。

权限设计

一期做轻量鉴权：

  • 登录页。
  • 单一管理员账号或配置文件 token。
  • 前端请求带 bearer token。
  • 后端校验 token。

后续再扩展 RBAC：

  • 业务只读。
  • 运维只读。
  • 管理员。

部署设计

ECS 部署：

  • 后端端口：20300。
  • 后端托管前端静态文件。
  • /api/* 是后端接口。
  • / 和前端路由返回静态入口。
  • systemd unit：lingniu-vehicle-platform.service。

访问地址：

http://115.29.187.205:20300

环境变量

后端需要：

  • HTTP_ADDR=:20300
  • MYSQL_DSN
  • REDIS_ADDR
  • REDIS_USERNAME
  • REDIS_PASSWORD
  • REDIS_DB
  • TDENGINE_DSN
  • TDENGINE_DATABASE=lingniu_vehicle_ts
  • CAPACITY_CHECK_BIN=/opt/lingniu-go-native/current/capacity-check
  • AUTH_TOKEN

验收标准

一期完成时必须满足：

  1. 新项目目录 vehicle-data-platform 存在。
  2. 前端使用 Semi UI。
  3. UI 有完整导航、统一布局、统一视觉规范。
  4. 可以查看车辆台账。
  5. 可以查询实时位置和实时状态。
  6. 可以进入单车详情。
  7. 可以查询历史位置。
  8. 可以查询 RAW frame，并支持字段裁剪。
  9. 可以查看日里程和区间里程。
  10. 可以查看数据质量问题。
  11. 可以查看链路健康状态。
  12. 后端 API 返回统一响应结构。
  13. 前端核心列表、详情和查询来自真实后端 API。
  14. ECS 部署后可通过 http://115.29.187.205:20300 访问。
  15. 后端 systemd 服务健康。
  16. 浏览器验证主要页面可访问、筛选可用、详情抽屉可用。

测试策略

后端

  • API handler 单元测试。
  • query 参数解析测试。
  • response envelope 测试。
  • 数据源 repository 测试。
  • 健康检查测试。

前端

  • TypeScript build。
  • 页面 smoke test。
  • API client 测试。
  • 主要页面空态、加载态、错误态检查。

部署

  • 本地前端 build。
  • 后端 go test。
  • ECS systemd 启动。
  • /api/ops/health 返回正常。
  • 浏览器打开首页、车辆台账、实时监控、历史查询。

后续演进

  • RBAC 权限。
  • 车辆绑定导入写入流程。
  • 告警通知。
  • 轨迹回放。
  • BI 报表。
  • 自定义字段分析。
  • 运维监控大盘。
Reference in New Issue View Git Blame Copy Permalink