dev-screen-starter/doc/data-integration-guide.md

7.1 KiB
Raw Blame History

外部数据接入设计与使用教程

本文档说明 Dev Screen Starter 的统一数据源设计。目标是让一个大屏页面可以集中声明多个数据源,并同时支持 HTTP、WebSocket、SignalR、MQTT 等不同协议。

1. 核心原则

一个大屏页面可以有多个图表和多个数据源。不同数据源可以使用不同协议:

  • 指标卡来自 HTTP 轮询。
  • 告警列表来自 WebSocket 推送。
  • 设备状态来自 MQTT topic。
  • .NET 后端事件来自 SignalR hub。

页面不应该在组件里分散写 fetch、new WebSocket、MQTT 订阅等细节。推荐把数据源集中放在一个文件中:

apps/demo-screen/src/demo/dataSources.ts

业务组件只消费统一的 DataState<T>。

2. 当前实现状态

已实现:

  • mockSource
  • httpSource
  • websocketSource
  • defineDataSources
  • useScreenDataSources

已预留类型和声明函数:

  • signalrSource
  • mqttSource

SignalR 和 MQTT 当前不会引入 SDK,也不会真实连接;它们会返回 idle 状态和提示信息。后续客户项目需要时,再接入具体 SDK 或后端网关。

3. 统一状态模型

每个数据源都会返回同一种结构:

type DataState<T> = {
  data: T | null
  loading: boolean
  error: string | null
  status: 'idle' | 'connecting' | 'open' | 'closed' | 'error'
  lastUpdated?: number
  sourceType?: 'mock' | 'http' | 'websocket' | 'signalr' | 'mqtt'
}

组件不需要关心底层协议,只看 data/loading/error/status。

4. 页面集中声明数据源

示例:

import {
  defineDataSources,
  httpSource,
  mockSource,
  mqttSource,
  signalrSource,
  websocketSource
} from '@dev-screen-starter/data'

export const screenDataSources = defineDataSources({
  overview: httpSource({
    url: '/api/overview',
    intervalMs: 10000,
    transform: (raw) => ({
      todayOrders: raw.today_orders,
      onlineDevices: raw.online_devices,
      alertCount: raw.alert_count
    })
  }),

  orderTrend: httpSource({
    url: '/api/order-trend',
    intervalMs: 30000,
    transform: (raw) => ({
      categories: raw.times,
      values: raw.items.map((item) => item.count)
    })
  }),

  alerts: websocketSource({
    url: 'ws://localhost:3000/ws/alerts',
    mode: 'append',
    maxItems: 20,
    transform: (raw) => ({
      time: raw.time,
      area: raw.area,
      status: raw.message
    })
  }),

  deviceStatus: mqttSource({
    url: 'ws://broker.example.com/mqtt',
    topic: 'factory/device/status',
    mode: 'replace'
  }),

  dotnetEvents: signalrSource({
    url: '/hubs/screen',
    method: 'screenEvent',
    mode: 'append',
    maxItems: 50
  }),

  localFallback: mockSource({
    data: {
      title: '本地 mock 数据'
    }
  })
})

5. 页面消费数据源

import { useScreenDataSources } from '@dev-screen-starter/data'
import { screenDataSources } from './dataSources'

export function ProjectScreen() {
  const data = useScreenDataSources(screenDataSources)

  const overview = data.overview.data
  const alerts = data.alerts.data ?? []

  return (
    <>
      <MetricCard label="今日订单" value={overview?.todayOrders ?? 0} unit="单" />
      <AlertList rows={alerts} />
    </>
  )
}

6. HTTP 数据源

适合:

  • 指标卡
  • 趋势图
  • 排行图
  • 低频刷新数据
  • 页面初始化数据
const sources = defineDataSources({
  overview: httpSource({
    url: '/api/overview',
    intervalMs: 10000,
    transform: (raw) => ({
      orders: raw.orders,
      devices: raw.devices
    })
  })
})

字段说明:

  • url: 请求地址。
  • baseUrl: API 基础地址,建议来自 .env。
  • query: 查询参数。
  • headers: 静态 header 或返回 header 的函数。
  • authToken: token 字符串或返回 token 的函数,会自动写入 Authorization: Bearer <token>。
  • timeoutMs: 超时时间。
  • init: fetch 的 RequestInit 参数。
  • intervalMs: 轮询间隔,不传则只请求一次。
  • immediate: 是否立即请求,默认 true。
  • transform: 数据清洗函数。

7. WebSocket 数据源

适合:

  • 实时告警
  • 订单流水
  • 设备状态
  • 秒级推送数据
const sources = defineDataSources({
  alerts: websocketSource({
    url: 'ws://localhost:3000/ws/alerts',
    mode: 'append',
    maxItems: 20,
    reconnect: { enabled: true, maxRetries: 10, delayMs: 3000 },
    heartbeat: { message: 'ping', intervalMs: 30000 },
    transform: (raw) => ({
      time: raw.time,
      message: raw.message
    })
  })
})

字段说明:

  • url: WebSocket 地址。
  • protocols: 可选 WebSocket protocols。
  • mode: replace 或 append,默认 replace。
  • maxItems: append 模式最多保留多少条。
  • reconnect: 断线重连设置。
  • heartbeat: 心跳消息设置。
  • transform: 单条消息的清洗函数。

WebSocket 消息如果是字符串,会优先尝试 JSON.parse。如果不是 JSON,会把原始字符串传给 transform。

8. MQTT 数据源

当前已预留类型:

deviceStatus: mqttSource({
  url: 'ws://broker.example.com/mqtt',
  topic: 'factory/device/status',
  mode: 'replace'
})

建议:

  • 浏览器端 MQTT 通常使用 MQTT over WebSocket。
  • 如果客户现场已有 MQTT broker,可以按项目接入 MQTT SDK。
  • 如果鉴权复杂,优先让后端网关把 MQTT 转成 WebSocket,再给大屏消费。

9. SignalR 数据源

当前已预留类型:

dotnetEvents: signalrSource({
  url: '/hubs/screen',
  method: 'screenEvent',
  mode: 'append',
  maxItems: 50
})

建议:

  • 客户后端是 .NET 时再引入 SignalR SDK。
  • SignalR 适配器应只放在 packages/data 或客户项目的数据层,不要散落在业务组件里。

10. Demo 当前接入方式

当前 demo 使用 mockSource 模拟集中数据源:

export const demoDataSources = defineDataSources({
  metrics: mockSource({ data: metrics, intervalMs: 15000 }),
  alerts: mockSource({ data: alertRows, intervalMs: 12000 }),
  operationEvents: mockSource({ data: operationEvents, intervalMs: 10000 }),
  capacityTrend: mockSource({ data: capacityTrend })
})

页面中统一消费:

const data = useScreenDataSources(demoDataSources)
const metrics = data.metrics.data ?? []
const alertRows = data.alerts.data ?? []

后续替换成真实接口时,只需要改 dataSources.ts,页面渲染结构可以尽量少改。

11. 推荐落地顺序

第一步:

  • 使用 mockSource 完成页面开发。
  • 用 transform 提前对齐组件需要的数据结构。

第二步:

  • 把初始化数据换成 httpSource。
  • 对接客户 REST API。

第三步:

  • 把告警、设备状态、流水数据换成 websocketSource。

第四步:

  • 项目确实需要时,再引入 MQTT 或 SignalR SDK,实现对应 adapter。

12. 注意事项

  • dataSources 建议定义在组件外部,保证引用稳定。
  • 高频数据不要全部刷新整页,只更新对应数据源。
  • WebSocket 的 append 模式要设置 maxItems,避免列表无限增长。
  • 数据清洗放在 transform,展示组件只消费干净数据。
  • 真实项目里要补鉴权、断线重连、心跳、错误提示策略。