Add unified data sources and stage debug
This commit is contained in:
1 parent
3fae670e6b
commit
5b300dee0d
18 files changed
+940
-72
No files matched your search
@@ -0,0 +1,292 @@
|
||||
# 外部数据接入设计与使用教程
|
||||
|
||||
本文档说明 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`: 请求地址。
|
||||
- `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,
|
||||
transform: (raw) => ({
|
||||
time: raw.time,
|
||||
message: raw.message
|
||||
})
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
字段说明:
|
||||
|
||||
- `url`: WebSocket 地址。
|
||||
- `protocols`: 可选 WebSocket protocols。
|
||||
- `mode`: `replace` 或 `append`,默认 `replace`。
|
||||
- `maxItems`: `append` 模式最多保留多少条。
|
||||
- `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`,展示组件只消费干净数据。
|
||||
- 真实项目里要补鉴权、断线重连、心跳、错误提示策略。
|
||||
+43
-12
@@ -38,11 +38,27 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
使用方式:
|
||||
|
||||
```tsx
|
||||
<ScreenStage background="#061826">
|
||||
<ScreenStage background="#061826" scaleMode="fit" debug>
|
||||
<YourScreen />
|
||||
</ScreenStage>
|
||||
```
|
||||
|
||||
`scaleMode` 支持:
|
||||
|
||||
- `fit`:完整显示设计稿,保持比例,可能留黑边,推荐默认使用。
|
||||
- `fill`:铺满窗口,保持比例,可能裁切边缘。
|
||||
- `stretch`:横向和纵向分别缩放,不留黑边,但会变形。
|
||||
- `none`:不缩放,适合局部调试。
|
||||
|
||||
`debug` 开启后会显示设计尺寸、视口尺寸、缩放模式和缩放比例。demo 页面支持通过 URL 参数切换:
|
||||
|
||||
```txt
|
||||
http://localhost:5173/?scaleMode=fit
|
||||
http://localhost:5173/?scaleMode=fill
|
||||
http://localhost:5173/?scaleMode=stretch
|
||||
http://localhost:5173/?scaleMode=none
|
||||
```
|
||||
|
||||
### Panel
|
||||
|
||||
用于常规图表面板或信息区域。
|
||||
@@ -75,11 +91,16 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
当前提供:
|
||||
|
||||
- `createLineOption`:折线图,支持单序列和多序列。
|
||||
- `createAreaTrendOption`:面积趋势图。
|
||||
- `createBarOption`:柱状图,支持单序列和多序列。
|
||||
- `createStackedBarOption`:堆叠柱状图。
|
||||
- `createDualAxisOption`:双轴折线柱状图。
|
||||
- `createRankBarOption`:横向排名条。
|
||||
- `createPieOption`:饼图/环图。
|
||||
- `createRosePieOption`:玫瑰图。
|
||||
- `createGaugeOption`:仪表盘。
|
||||
- `createRadarOption`:雷达图。
|
||||
- `mergeChartOption`:在默认工厂配置基础上做局部覆盖。
|
||||
|
||||
推荐用法:
|
||||
|
||||
@@ -95,7 +116,7 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
|
||||
## 4. data
|
||||
|
||||
`data` 提供轻量数据工具。
|
||||
`data` 提供统一数据源工具。一个页面可以集中声明多个数据源,并让不同组件消费同一种 `DataState<T>`。
|
||||
|
||||
### requestJson
|
||||
|
||||
@@ -105,18 +126,25 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
|
||||
用于定时刷新接口数据。
|
||||
|
||||
适合:
|
||||
### useScreenDataSources
|
||||
|
||||
- 30 秒刷新指标。
|
||||
- 5 秒刷新告警。
|
||||
- 项目开发时接 mock loader。
|
||||
统一消费页面级数据源:
|
||||
|
||||
不适合:
|
||||
```tsx
|
||||
const data = useScreenDataSources(screenDataSources)
|
||||
const metrics = data.metrics.data ?? []
|
||||
```
|
||||
|
||||
- 高频毫秒级数据。
|
||||
- 大规模实时流。
|
||||
配套声明函数:
|
||||
|
||||
这些场景建议按项目单独实现 WebSocket、SSE 或 MQTT。
|
||||
- `defineDataSources`
|
||||
- `mockSource`
|
||||
- `httpSource`
|
||||
- `websocketSource`
|
||||
- `mqttSource`
|
||||
- `signalrSource`
|
||||
|
||||
其中 `mockSource`、`httpSource`、`websocketSource` 已可用;`mqttSource`、`signalrSource` 已预留类型和声明入口,具体 SDK 在客户项目需要时再接。
|
||||
|
||||
## 5. debug
|
||||
|
||||
@@ -126,8 +154,6 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
|
||||
显示缩放比例、数据更新时间等轻量信息。生产环境默认不显示,项目可显式打开。
|
||||
|
||||
## 6. 项目模板
|
||||
|
||||
## 6. visual-kit
|
||||
|
||||
`visual-kit` 提供轻量大屏视觉材料,不承担图表逻辑。
|
||||
@@ -137,9 +163,14 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
- `GlowPanel`:带轻微光感的内容面板。
|
||||
- `CornerFrame`:四角框容器。
|
||||
- `SectionTitle`:区块标题。
|
||||
- `TitleBar`:标题栏,支持右侧 action。
|
||||
- `Divider`:装饰分割线。
|
||||
- `DigitalNumber`:数字强调。
|
||||
- `FlipNumber`:数字翻牌。
|
||||
- `StatusPill`:状态标签。
|
||||
- `TrendBadge`:趋势标签。
|
||||
- `ScrollTable`:紧凑滚动表格结构。
|
||||
- `MarqueeList`:自动滚动列表。
|
||||
- `WaterLevel`:水位图。
|
||||
|
||||
推荐组合:
|
||||
|
||||
+5
-2
@@ -98,6 +98,8 @@ doc/
|
||||
- `TrendBadge`
|
||||
- `MarqueeList`
|
||||
- demo-screen 已改为使用图表工厂和 visual-kit 组合出项目型模板。
|
||||
- `ScreenStage` 已增强 debug 信息展示,支持运行时查看设计尺寸、视口尺寸、缩放模式和缩放比例。
|
||||
- demo-screen 支持通过 `?scaleMode=fit|fill|stretch|none` 验证不同屏幕适配策略。
|
||||
|
||||
后续计划:
|
||||
|
||||
@@ -126,13 +128,14 @@ doc/
|
||||
- 基础装饰组件支持 `className`、`style`、`tone`、`size` 等通用属性。
|
||||
- 图表工厂覆盖常用交付场景,并保留 ECharts 原生 option 覆盖能力。
|
||||
- demo-screen 已包含状态区、运行事件、指标卡、趋势、堆叠、排行、玫瑰、双轴、雷达和仪表盘示例。
|
||||
- `data` 包已新增统一数据源设计,支持页面集中声明 mock、HTTP、WebSocket 数据源,并预留 MQTT、SignalR 类型。
|
||||
|
||||
下一步建议:
|
||||
|
||||
- 做 `ChartPanel` 组合组件,把 `Panel + EChart + loading/empty/error` 固化下来。
|
||||
- 给 `data` 包增加 mock/real 数据源切换。
|
||||
- 给 `data` 包补 WebSocket 重连、心跳、鉴权 header/token 约定。
|
||||
- 增加 `.env.example` 和项目级接口配置约定。
|
||||
- 对 `ScreenStage` 做 1366x768、1920x1080、4K 的浏览器截图验收。
|
||||
- 对 `ScreenStage` 做更多截图验收,覆盖 1366x768、1920x1080、4K 和不同 `scaleMode`。
|
||||
|
||||
## 8. 成功标准
|
||||
|
||||
|
||||
Reference in new issue
Block a user