docs(platform): define vehicle service center direction

docs/superpowers/specs/2026-07-03-vehicle-data-platform-design.md

@@ -4,16 +4,23 @@
 
 建设一套独立的车辆数据管理中台，放在新项目目录 `vehicle-data-platform`。中台包含前端和后端，前端使用 Semi UI，整体风格高级、简洁、接近大厂数据控制台；后端使用 Go BFF 聚合现有车辆接入链路的数据能力。系统一期目标是让业务和运营人员可以稳定完成查车、看实时状态、查历史、追溯 RAW、看里程和定位数据质量问题，同时给平台运维提供只读链路健康态势。
 
+## 产品定位更新：一个车辆服务
+
+中台的第一性原则是“一个车辆服务”。GB32960、JT808、宇通 MQTT 是同一辆车的数据来源证据，不是三个并列的业务产品。所有主页面都应先回答车辆层面的问题，再在需要排障、对账、追溯时下钻到协议来源。
+
+用户输入 VIN、车牌、手机号或来源标识后，系统需要尽量解析到同一个车辆上下文，并在实时监控、轨迹回放、历史查询、告警事件、统计分析之间保持这个上下文。协议只作为来源标签、可信度解释和 RAW 证据入口出现。
+
 ## 一期定位
 
-一期优先服务运营和业务人员，核心问题是：
+一期优先服务运营、业务和数据质量人员，核心问题是：
 
 - 车辆是否在线。
 - 车辆在哪里。
 - 最新状态是什么。
 - 最近是否断链。
 - 每日和区间里程是否可信。
-- 原始报文是否可追溯。
+- 原始报文和解析字段是否可追溯。
+- 告警事件是否能追到影响车辆和证据。
 - VIN、车牌、手机号、OEM 绑定是否正确。
 
 链路运维能力作为辅助模块内嵌，展示 Gateway、NATS、Kafka、Redis、TDengine、MySQL 和 capacity-check 的关键健康状态，但一期不做复杂监控平台和告警工单闭环。
@@ -24,10 +31,10 @@
 
 - 复杂多租户权限体系。
 - 自定义大屏编排。
-- 报警通知和工单闭环。
+- 复杂工单闭环。
 - 任意字段计算平台。
 - 完整 BI 报表系统。
-- 复杂轨迹回放动画。
+- 复杂三维轨迹或大屏动画。
 - 对现有 Go gateway、NATS bridge、history writer、stat writer、realtime API 做破坏性改造。
 
 ## 项目结构
@@ -71,9 +78,9 @@ vehicle-data-platform/
 
 ## 信息架构
 
-左侧导航包含 7 个一级模块。
+左侧导航围绕车辆服务组织，一期可以先保留现有 7 个一级模块，但命名和内容要向以下目标靠拢。
 
-### 1. 总览工作台
+### 1. 运营总览
 
 路径：`/dashboard`
 
@@ -85,19 +92,20 @@ vehicle-data-platform/
 - 异常车辆数。
 - Kafka lag。
 - 链路健康状态。
-- 协议分布：GB32960、JT808、YUTONG_MQTT。
+- 车辆服务状态分布：健康、降级、离线、身份缺失、暂无来源。
+- 来源覆盖分布：单源车辆、多源车辆、暂无来源车辆。
 - 最新车辆分布地图小窗。
-- 最近异常列表：断链、未绑定、里程异常、解析失败。
+- 最近异常列表：断链、未绑定、里程异常、解析失败、跨来源不一致。
 
-### 2. 车辆台账
+### 2. 车辆服务
 
 路径：`/vehicles`
 
 能力：
 
-- 表格展示车牌、VIN、手机号、OEM、协议来源、在线状态、最后上报、最近位置、绑定完整度。
+- 表格展示车牌、VIN、手机号、OEM、来源证据、在线来源数、车辆服务状态、最后上报、最近位置、绑定完整度。
 - 支持 VIN、车牌、手机号、OEM 搜索。
-- 支持协议、在线状态、绑定完整度筛选。
+- 支持服务状态、来源覆盖、在线状态、绑定完整度筛选。
 - 支持查看详情、导出。
 - 支持导入绑定入口的一期展示：提供导入说明和模板下载按钮，不提交数据；正式写入流程不纳入一期验收。
 
@@ -108,9 +116,10 @@ vehicle-data-platform/
 能力：
 
 - 表格视图和地图视图切换。
-- 展示 VIN、车牌、协议、速度、SOC、总里程、最后上报时间、位置。
-- 按协议和在线状态分色。
-- 点击车辆后打开右侧抽屉展示最新 realtime raw 字段摘要。
+- 展示 VIN、车牌、来源证据、速度、SOC、总里程、最后上报时间、位置。
+- 地图按车辆服务状态和在线状态分色，协议只用于点位详情里的来源证据。
+- 支持只看在线车辆、异常车辆、断链车辆和多源不一致车辆。
+- 点击车辆后打开右侧抽屉展示最新实时字段摘要、来源新鲜度和跳转入口。
 
 ### 4. 车辆详情
 
@@ -127,18 +136,39 @@ vehicle-data-platform/
   - 数据质量。
 - 多协议对比：同一车辆在 GB32960、JT808、YUTONG_MQTT 下的最新时间、字段完整度、里程差异。
 
-### 5. 历史数据
+### 5. 轨迹回放
 
 路径：`/history`
 
 能力：
 
-- Tab：历史位置、RAW 报文。
+- 查询条件：VIN/车牌/手机号、时间范围、来源筛选。
+- 地图轨迹播放，支持起点、终点、当前播放点和速度。
+- 表格与地图联动：点击点位能看到该点时间、位置、速度、里程和来源。
+- 可跳转 RAW 证据、统计分析和告警事件。
+
+### 6. 历史查询
+
+路径：`/history`
+
+能力：
+
+- Tab：历史位置、RAW 报文、解析字段。
 - 查询条件：VIN、协议、时间范围、消息类型、字段筛选。
 - RAW 支持分页、字段裁剪、是否包含 payload、JSON 详情查看。
-- 历史位置支持表格和轨迹简图。
+- 解析字段使用扁平化字段名，支持选择字段缩小响应体。
 
-### 6. 里程与统计
+### 7. 告警事件
+
+路径：`/quality`，后续可独立为 `/alerts`
+
+能力：
+
+- 展示来源断链、未绑定、无 VIN、无车牌、无手机号、RAW 解析失败、里程突变、跨来源不一致。
+- 每条告警必须能跳回车辆详情、轨迹回放、历史 RAW 或统计证据。
+- 一期支持人工确认和状态展示，通知发送作为后续阶段。
+
+### 8. 统计分析
 
 路径：`/mileage`
 
@@ -148,8 +178,9 @@ vehicle-data-platform/
 - 区间里程查询。
 - 协议来源对比。
 - 异常标记：总里程倒退、突增、缺失、跨协议不一致。
+- 在线率、数据完整率和来源一致性作为后续统计卡片。
 
-### 7. 数据质量与链路健康
+### 9. 运维质量
 
 路径：`/quality`
 
@@ -162,6 +193,33 @@ vehicle-data-platform/
 - capacity-check 结果。
 - Kafka/NATS/TDengine/Redis/MySQL 关键状态。
 
+## 高德地图设计
+
+地图供应商使用高德地图。用户提供了 Web JS 和 API 服务两类 key，系统实现时需要按用途分开：
+
+- Web JS key 只通过前端运行时配置注入，例如 `window.__LINGNIU_PLATFORM_CONFIG__.amap.webJsKey`，不写死在 TypeScript 源码。
+- 安全密钥或代理服务地址同样通过运行时配置注入。
+- API 服务 key 放在后端或 ECS 环境变量中，只用于后端地理编码、行政区划或后续服务端地图能力。
+- 前端没有拿到可用 key 时，`VehicleMap` 使用坐标预览降级，不阻塞查车、查轨迹和查告警。
+
+地图一期覆盖三类业务场景：
+
+- 实时监控：多车点位、在线状态、异常状态、点位详情。
+- 轨迹回放：折线、起终点、当前播放点、表格联动。
+- 告警事件：告警车辆定位和影响范围提示。
+
+## 跨页面车辆上下文
+
+全局搜索解析到车辆后，需要把 VIN、车牌、手机号、来源和服务状态作为页面上下文：
+
+- 车辆服务行可以跳转车辆档案。
+- 实时监控车辆可以跳转轨迹回放、历史查询、统计分析和告警事件。
+- 轨迹点可以跳转同日里程统计和 RAW 证据。
+- 里程异常可以跳转对应日期轨迹和 RAW 证据。
+- 告警事件可以跳转车辆档案、历史证据和统计证据。
+
+这一点是产品一致性的硬约束。页面之间不应只靠用户手动复制 VIN。
+
 ## 视觉与交互设计
 
 整体视觉使用 Semi UI 原生组件为基础，避免大屏炫技风。目标是云控制台、数据控制台、飞书后台一类的专业感。