# 外部数据接入设计与使用教程 本文档说明 Dev Screen Starter 的统一数据源设计。目标是让一个大屏页面可以集中声明多个数据源,并同时支持 HTTP、WebSocket、SignalR、MQTT 等不同协议。 ## 1. 核心原则 一个大屏页面可以有多个图表和多个数据源。不同数据源可以使用不同协议: - 指标卡来自 HTTP 轮询。 - 告警列表来自 WebSocket 推送。 - 设备状态来自 MQTT topic。 - .NET 后端事件来自 SignalR hub。 页面不应该在组件里分散写 `fetch`、`new WebSocket`、MQTT 订阅等细节。推荐把数据源集中放在一个文件中: ```txt apps/demo-screen/src/demo/dataSources.ts ``` 业务组件只消费统一的 `DataState`。 ## 2. 当前实现状态 已实现: - `mockSource` - `httpSource` - `websocketSource` - `defineDataSources` - `useScreenDataSources` 已预留类型和声明函数: - `signalrSource` - `mqttSource` SignalR 和 MQTT 当前不会引入 SDK,也不会真实连接;它们会返回 `idle` 状态和提示信息。后续客户项目需要时,再接入具体 SDK 或后端网关。 ## 3. 统一状态模型 每个数据源都会返回同一种结构: ```ts type DataState = { 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. 页面集中声明数据源 示例: ```ts 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. 页面消费数据源 ```tsx 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 ( <> ) } ``` ## 6. HTTP 数据源 适合: - 指标卡 - 趋势图 - 排行图 - 低频刷新数据 - 页面初始化数据 ```ts 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 `。 - `timeoutMs`: 超时时间。 - `init`: `fetch` 的 RequestInit 参数。 - `intervalMs`: 轮询间隔,不传则只请求一次。 - `immediate`: 是否立即请求,默认 `true`。 - `transform`: 数据清洗函数。 ## 7. WebSocket 数据源 适合: - 实时告警 - 订单流水 - 设备状态 - 秒级推送数据 ```ts 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 数据源 当前已预留类型: ```ts 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 数据源 当前已预留类型: ```ts dotnetEvents: signalrSource({ url: '/hubs/screen', method: 'screenEvent', mode: 'append', maxItems: 50 }) ``` 建议: - 客户后端是 .NET 时再引入 SignalR SDK。 - SignalR 适配器应只放在 `packages/data` 或客户项目的数据层,不要散落在业务组件里。 ## 10. Demo 当前接入方式 当前 demo 使用 `mockSource` 模拟集中数据源: ```ts 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 }) }) ``` 页面中统一消费: ```ts 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`,展示组件只消费干净数据。 - 真实项目里要补鉴权、断线重连、心跳、错误提示策略。