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

302 lines
7.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 外部数据接入设计与使用教程
本文档说明 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<T>`。
## 2. 当前实现状态
已实现:
- `mockSource`
- `httpSource`
- `websocketSource`
- `defineDataSources`
- `useScreenDataSources`
已预留类型和声明函数:
- `signalrSource`
- `mqttSource`
SignalR 和 MQTT 当前不会引入 SDK,也不会真实连接;它们会返回 `idle` 状态和提示信息。后续客户项目需要时,再接入具体 SDK 或后端网关。
## 3. 统一状态模型
每个数据源都会返回同一种结构:
```ts
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. 页面集中声明数据源
示例:
```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 (
<>
<MetricCard label="今日订单" value={overview?.todayOrders ?? 0} unit="单" />
<AlertList rows={alerts} />
</>
)
}
```
## 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 <token>`。
- `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`,展示组件只消费干净数据。
- 真实项目里要补鉴权、断线重连、心跳、错误提示策略。