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 原生组件为基础，避免大屏炫技风。目标是云控制台、数据控制台、飞书后台一类的专业感。

vehicle-data-platform/docs/product-spec.md

@@ -4,15 +4,23 @@
 
 The UI is a professional vehicle data operations console. It uses Semi UI as the component base, a restrained gray-white control-room palette, dense but readable tables, right-side drawers for detail, and blue-cyan accents for primary actions. It should feel closer to a cloud data console than a marketing dashboard.
 
+## Product North Star
+
+The platform is a vehicle service center. GB32960, JT808, and Yutong MQTT are ingestion evidence for the same vehicle, not three separate product surfaces. A user should be able to search one VIN, plate, or phone number and understand whether that vehicle is online, where it is, what its latest state is, how reliable its mileage is, and which source produced each piece of evidence.
+
+Every primary workflow should answer a vehicle-level question first, then allow protocol-level drill-down only when diagnosis or raw evidence is needed.
+
 ## Primary Screens
 
-1. Dashboard: KPI summary, protocol distribution, vehicle map preview, quality issues, and link health.
-2. Vehicles: table-first identity and vehicle registry.
-3. Realtime: table/map switch for current vehicle state.
-4. Vehicle Detail: identity header and tabs for latest state, history, raw, mileage, and quality.
-5. History: location and raw-frame query workspace.
-6. Mileage: daily and range mileage analysis.
-7. Quality: data quality and link health workspace.
+1. Dashboard: vehicle service KPI summary, service status distribution, map preview, alerts, data quality, and link health.
+2. Vehicle Service: table-first vehicle registry, binding state, source coverage, and service status.
+3. Realtime Monitor: map/table switch for current online vehicles and abnormal vehicles.
+4. Vehicle Detail: one vehicle profile with latest state, sources, history, raw, mileage, alerts, and quality evidence.
+5. Trajectory Playback: location history with map track playback and table evidence.
+6. History Query: historical locations, raw frames, and flattened parsed fields with pagination and field trimming.
+7. Alert Events: alert trigger records, affected vehicles, notification state, and evidence links.
+8. Statistics: daily/range mileage, online rate, data completeness, and source consistency.
+9. Ops Quality: Kafka, NATS, Redis, TDengine, MySQL, gateway, and writer health.
 
 ## Domain Principle
 
@@ -30,6 +38,49 @@ Dashboard and vehicle-list summary cards should expose both `单源车辆` and `
 
 `暂无来源车辆` is also a first-class governance entry. It represents bound vehicles that have no current GB32960, JT808, or Yutong MQTT source evidence, and should route directly to the `no_data` vehicle service filter.
 
+## Vehicle Service Workflow
+
+Global vehicle search accepts VIN, plate, JT808 phone, or known source identifier. The resolved vehicle context should travel across the whole product:
+
+- Realtime monitor opens the current position and source freshness for that vehicle.
+- Trajectory playback opens the same VIN and selected time window.
+- History query opens raw and parsed evidence for the same VIN.
+- Statistics opens daily or range mileage for the same VIN.
+- Alert events opens active and historical alerts for the same VIN.
+- Vehicle detail acts as the hub that links all of the above.
+
+The user should rarely need to choose a protocol before choosing a vehicle. Protocol filters are secondary and are used for source diagnosis, cross-source comparison, and raw frame verification.
+
+## Map Capability
+
+The product uses AMap as the map provider for production map rendering.
+
+- Web JS key is injected through frontend runtime config, not hard-coded into source.
+- API/server key is kept in backend or ECS environment configuration.
+- Realtime monitor shows current vehicle points, online/offline color, abnormal highlights, and source freshness.
+- Trajectory playback shows historical polyline, start/end markers, current playback marker, and the table row that backs the selected point.
+- Alert events can highlight affected vehicle locations when the alert has valid coordinates.
+- If AMap is unavailable or not configured, pages must fall back to coordinate preview instead of blocking the workflow.
+
+## Alert And Notification Scope
+
+Alert events are first-class product records, but notification delivery can be implemented incrementally.
+
+- Phase 1: alert list, severity, trigger time, affected vehicle, evidence links, and manual status.
+- Phase 2: notification channels such as email, webhook, or enterprise chat.
+- Phase 3: escalation policy for unresolved data breakage and affected-user notification.
+
+Alerts should cover source offline, no realtime update, location missing, mileage abnormality, raw parse failure, binding missing, and cross-source inconsistency.
+
+## Statistics Scope
+
+Statistics must stay vehicle-first and evidence-backed:
+
+- Daily mileage and range mileage should link back to trajectory and raw evidence.
+- Online rate should be computed by vehicle and then broken down by source.
+- Data completeness should report missing location, mileage, SOC, speed, and source freshness.
+- Source consistency should compare GB32960, JT808, and Yutong MQTT only when the same VIN has multiple sources.
+
 ## Interaction Rules
 
 - Tables are the default data surface.