docs: add vehicle data platform design spec
This commit is contained in:
lingniu
@@ -0,0 +1,494 @@
|
||||
# 车辆数据管理中台设计 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 做破坏性改造。
|
||||
|
||||
## 项目结构
|
||||
|
||||
新建项目目录：
|
||||
|
||||
```text
|
||||
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 响应格式
|
||||
|
||||
成功：
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {},
|
||||
"traceId": "string",
|
||||
"timestamp": 1783080000000
|
||||
}
|
||||
```
|
||||
|
||||
分页：
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"items": [],
|
||||
"total": 100,
|
||||
"limit": 50,
|
||||
"offset": 0
|
||||
},
|
||||
"traceId": "string",
|
||||
"timestamp": 1783080000000
|
||||
}
|
||||
```
|
||||
|
||||
错误：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`。
|
||||
|
||||
访问地址：
|
||||
|
||||
```text
|
||||
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
Block a user