feat(platform): show realtime data freshness

vehicle-data-platform/apps/web/src/pages/Realtime.tsx

@@ -80,6 +80,57 @@ function formatRefreshTime(date: Date) {
   });
 }
 
+function parseVehicleTime(value?: string) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return Number.NaN;
+  }
+  return new Date(normalized.replace(' ', 'T')).getTime();
+}
+
+function dataFreshness(row: VehicleRealtimeRow) {
+  const timestamp = parseVehicleTime(row.lastSeen);
+  if (!Number.isFinite(timestamp)) {
+    return {
+      label: '无时间',
+      color: 'grey' as const,
+      detail: '未上报最后时间',
+      stale: true
+    };
+  }
+  const ageSeconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (ageSeconds <= 300) {
+    return {
+      label: '数据新鲜',
+      color: 'green' as const,
+      detail: ageSeconds <= 0 ? '刚刚更新' : `${Math.max(1, Math.ceil(ageSeconds / 60))} 分钟内更新`,
+      stale: false
+    };
+  }
+  if (ageSeconds < 3600) {
+    return {
+      label: '更新超时',
+      color: 'orange' as const,
+      detail: `${Math.ceil(ageSeconds / 60)} 分钟未更新`,
+      stale: true
+    };
+  }
+  if (ageSeconds < 86400) {
+    return {
+      label: '更新超时',
+      color: 'red' as const,
+      detail: `${Math.ceil(ageSeconds / 3600)} 小时未更新`,
+      stale: true
+    };
+  }
+  return {
+    label: '更新超时',
+    color: 'red' as const,
+    detail: `${Math.ceil(ageSeconds / 86400)} 天未更新`,
+    stale: true
+  };
+}
+
 function amapMarkerURL(row: VehicleRealtimeRow) {
   const name = encodeURIComponent(row.plate || row.vin || '车辆位置');
   return `https://uri.amap.com/marker?position=${row.longitude},${row.latitude}&name=${name}&src=lingniu-vehicle-platform`;
@@ -278,6 +329,7 @@ export function Realtime({
   const onlineCount = rows.filter((row) => row.online).length;
   const locatedCount = rows.filter(isValidCoordinate).length;
   const degradedCount = rows.filter((row) => row.onlineSourceCount < row.sourceCount).length;
+  const staleCount = rows.filter((row) => dataFreshness(row).stale).length;
   const onlineRate = rows.length > 0 ? (onlineCount / rows.length) * 100 : 0;
   const locatedRate = rows.length > 0 ? (locatedCount / rows.length) * 100 : 0;
   const degradedRate = rows.length > 0 ? (degradedCount / rows.length) * 100 : 0;
@@ -437,6 +489,7 @@ export function Realtime({
               { label: '当前车辆', value: pagination.total.toLocaleString(), color: 'blue' as const },
               { label: '在线车辆', value: onlineCount.toLocaleString(), color: 'green' as const },
               { label: '定位有效', value: locatedCount.toLocaleString(), color: 'green' as const },
+              { label: '超时车辆', value: staleCount.toLocaleString(), color: staleCount > 0 ? 'orange' as const : 'green' as const },
               { label: '降级服务', value: degradedCount.toLocaleString(), color: degradedCount > 0 ? 'orange' as const : 'green' as const },
               { label: '来源类型', value: primaryProtocols.size.toLocaleString(), color: 'blue' as const }
             ].map((item) => (
@@ -453,6 +506,7 @@ export function Realtime({
                 <div className="vp-map-service-queue-title">当前选中车辆</div>
                 <Space wrap>
                   <Tag color={vehicleServiceStatus(selectedMapRow).color}>{vehicleServiceStatus(selectedMapRow).label}</Tag>
+                  <Tag color={dataFreshness(selectedMapRow).color}>{dataFreshness(selectedMapRow).label}</Tag>
                   <Tag color={selectedMapRow.online ? 'green' : 'orange'}>{selectedMapRow.online ? '在线' : '离线'}</Tag>
                   <Tag color="blue">{selectedMapRow.primaryProtocol || '未知来源'}</Tag>
                 </Space>
@@ -464,6 +518,7 @@ export function Realtime({
                   <span>速度</span><strong>{selectedMapRow.speedKmh ?? '-'} km/h</strong>
                   <span>SOC</span><strong>{selectedMapRow.socPercent ?? '-'}%</strong>
                   <span>里程</span><strong>{selectedMapRow.totalMileageKm ?? '-'} km</strong>
+                  <span>新鲜度</span><strong>{dataFreshness(selectedMapRow).detail}</strong>
                   <span>最后时间</span><strong>{selectedMapRow.lastSeen || '-'}</strong>
                 </div>
                 <Space spacing={6} wrap>
@@ -503,6 +558,7 @@ export function Realtime({
                       </div>
                       <Space spacing={4} wrap>
                         <Tag color="blue">{sourceEvidenceText(row)}</Tag>
+                        <Tag color={dataFreshness(row).color}>{dataFreshness(row).label}</Tag>
                         {sourceIssueTags(row).map((item) => (
                           <Tag key={item} color="orange">一致性：{item}</Tag>
                         ))}
@@ -548,11 +604,17 @@ export function Realtime({
                           <Typography.Text strong>{row.plate || row.vin}</Typography.Text>
                           <Typography.Text type="tertiary" size="small">{row.vin}</Typography.Text>
                         </div>
-                        <Tag color={status.color}>{status.label}</Tag>
+                        <Space spacing={4} wrap>
+                          <Tag color={dataFreshness(row).color}>{dataFreshness(row).label}</Tag>
+                          <Tag color={status.color}>{status.label}</Tag>
+                        </Space>
                       </div>
                       <Typography.Text type="secondary" size="small">
                         {row.serviceStatus?.detail || sourceEvidenceText(row)}
                       </Typography.Text>
+                      <Typography.Text type="tertiary" size="small">
+                        新鲜度：{dataFreshness(row).detail}
+                      </Typography.Text>
                       <div className="vp-map-service-item-footer">
                         <Typography.Text type="tertiary" size="small">{row.lastSeen || '-'}</Typography.Text>
                         <Space spacing={4} wrap>
@@ -574,6 +636,7 @@ export function Realtime({
             {[
               { label: '在线率', value: formatPercent(onlineRate), color: onlineRate >= 80 ? 'green' as const : 'orange' as const, detail: `${onlineCount.toLocaleString()} / ${rows.length.toLocaleString()} 辆在线。` },
               { label: '定位有效率', value: formatPercent(locatedRate), color: locatedRate >= 80 ? 'green' as const : 'orange' as const, detail: `${locatedCount.toLocaleString()} / ${rows.length.toLocaleString()} 辆坐标有效。` },
+              { label: '新鲜数据', value: `${(rows.length - staleCount).toLocaleString()} 辆`, color: staleCount > 0 ? 'orange' as const : 'green' as const, detail: `${staleCount.toLocaleString()} 辆超过 5 分钟未更新。` },
               { label: '降级率', value: formatPercent(degradedRate), color: degradedCount > 0 ? 'orange' as const : 'green' as const, detail: `${degradedCount.toLocaleString()} 辆存在来源不完整或离线。` },
               { label: '分页覆盖率', value: formatPercent(pageCoverageRate), color: pageCoverageRate >= 100 ? 'green' as const : 'grey' as const, detail: '当前页车辆数 / 当前筛选总车辆数。' }
             ].map((item) => (
@@ -619,6 +682,14 @@ export function Realtime({
                       return <Tag color={status.color}>{status.label}</Tag>;
                     }
                   },
+                  {
+                    title: '数据新鲜度',
+                    width: 130,
+                    render: (_: unknown, row: VehicleRealtimeRow) => {
+                      const freshness = dataFreshness(row);
+                      return <Tag color={freshness.color}>{freshness.label}</Tag>;
+                    }
+                  },
                   {
                     title: '车辆核心数据',
                     width: 230,

vehicle-data-platform/apps/web/src/test/App.test.tsx

@@ -7626,6 +7626,79 @@ test('refreshes realtime vehicle data from the monitoring workspace', async () =
   expect(realtimeCalls).toBeGreaterThanOrEqual(2);
 });
 
+test('shows realtime freshness status for recently updated and stale vehicles', async () => {
+  window.history.replaceState(null, '', '/#/map');
+  vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+    const path = String(input);
+    if (path.includes('/api/realtime/vehicles')) {
+      return {
+        ok: true,
+        json: async () => ({
+          data: {
+            items: [
+              {
+                vin: 'VIN-FRESH-001',
+                plate: '粤A新鲜1',
+                protocols: ['GB32960'],
+                sourceStatus: [{ protocol: 'GB32960', online: true, lastSeen: '2999-07-04 17:00:00', hasRealtime: true, hasHistory: true, hasRaw: true, hasMileage: true }],
+                sourceCount: 1,
+                onlineSourceCount: 1,
+                online: true,
+                primaryProtocol: 'GB32960',
+                longitude: 113.2,
+                latitude: 23.1,
+                speedKmh: 30,
+                socPercent: 78,
+                totalMileageKm: 119925,
+                lastSeen: '2999-07-04 17:00:00',
+                bindingStatus: 'bound'
+              },
+              {
+                vin: 'VIN-STALE-001',
+                plate: '粤A超时1',
+                protocols: ['JT808'],
+                sourceStatus: [{ protocol: 'JT808', online: false, lastSeen: '2020-01-01 00:00:00', hasRealtime: true, hasHistory: true, hasRaw: true, hasMileage: true }],
+                sourceCount: 1,
+                onlineSourceCount: 0,
+                online: false,
+                primaryProtocol: 'JT808',
+                longitude: 113.3,
+                latitude: 23.2,
+                speedKmh: 0,
+                socPercent: 50,
+                totalMileageKm: 1000,
+                lastSeen: '2020-01-01 00:00:00',
+                bindingStatus: 'bound'
+              }
+            ],
+            total: 2,
+            limit: 50,
+            offset: 0
+          },
+          traceId: 'trace-test',
+          timestamp: 1783094400000
+        })
+      } as Response;
+    }
+    return {
+      ok: true,
+      json: async () => ({
+        data: { linkHealth: [], kafkaLag: 0, redisOnlineKeys: 0, tdengineWritable: true, mysqlWritable: true, runtime: { requestTimeoutMs: 5000 } },
+        traceId: 'trace-test',
+        timestamp: 1783094400000
+      })
+    } as Response;
+  });
+
+  render(<App />);
+
+  expect(await screen.findByRole('heading', { name: '地图态势' })).toBeInTheDocument();
+  expect(screen.getAllByText('数据新鲜').length).toBeGreaterThan(0);
+  expect(screen.getAllByText('更新超时').length).toBeGreaterThan(0);
+  expect(screen.getByText('超时车辆')).toBeInTheDocument();
+  expect(screen.getByText('1 辆超过 5 分钟未更新。')).toBeInTheDocument();
+});
+
 test('exports current realtime vehicles as CSV', async () => {
   window.history.replaceState(null, '', '/#/realtime?protocol=JT808');
   const createObjectURL = vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:realtime-export');