dev-screen-starter/doc/factory-dashboard-wms-progress.md

262 lines
11 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.

# 工厂看板与 WMS 对接进度
更新时间:2026-06-01
本文档记录当前工厂看板项目和 WMS 后端改造的已完成工作、验证结果和后续建议。当前目标不是通用拖拽式大屏设计器,而是沉淀一个可直接承接项目需求的 React 看板基础工程,并逐步接入 WMS 后端清洗后的实时数据。
## 1. 当前项目定位
- `dev-screen-starter`:项目型大屏开发基础框架,负责屏幕适配、图表工厂、视觉组件、示例看板和客户项目模板。
- `apps/factory-dashboard`:工厂设备看板示例项目,当前以 CNC、激光设备、配电柜为业务场景。
- `WMS`:现有业务后端,负责 MQTT 数据接收、死区过滤、数据清洗、汇总落库,并通过 SignalR 向看板推送清洗后的数据。
## 2. 看板侧已完成
### 2.1 基础框架
- 已采用 React、TypeScript、Vite、pnpm workspace。
- 已保留项目型开发模式,不做拖拽编辑器。
- 已完成 `ScreenStage` 屏幕适配能力,支持 `fit`、`fill`、`stretch`、`none` 等缩放模式。
- 已沉淀 `packages/charts` 图表工厂,基于 ECharts 生成常用图表 option。
- 已沉淀 `packages/visual-kit`,用于大屏视觉装饰和展示组件。
- 已提供 `ChartPanel`、`Panel`、`MetricCard` 等基础组合能力。
### 2.2 factory-dashboard 页面
- 已将主界面从“每台设备一个大方框”的模式,调整为更适合老板和参观人员观看的焦点设备模式。
- 当前布局包括:
- 左侧设备列表和设备状态入口。
- 中间焦点设备实时信息。
- 中间设备近 7 日产量或趋势图。
- 右侧设备总览、今日产量、近 7 日趋势、告警列表。
- 已支持设备点击切换焦点设备。
- 已补齐 CNC、激光、配电柜的 mock 展示数据。
- CNC 设备编号已统一为 `CNC-001` 到 `CNC-013`。
- 自动滚动列表已调整到面板内显示,避免越界。
### 2.3 SignalR 数据接入
- 已新增 `@microsoft/signalr` 依赖。
- 已新增 `apps/factory-dashboard/src/api/dashboardSignalR.ts`。
- 看板支持通过 URL 参数或环境变量切换数据模式:
- 默认:mock 数据。
- `?dataMode=signalr`:连接 WMS SignalR。
- 已支持连接 WMS `/dashboardHub`。
- 已支持启动后调用 `GetSnapshot` 获取设备快照和当前告警。
- 已支持监听:
- `device.updated`
- `alarm.updated`
- `trend.updated`
- 已将后端 CNC、配电柜 DTO 映射到现有前端 `FactoryDevice` 类型。
- 页面底部已展示实时链路状态,例如 `SignalR 已连接`。
- `dataMode=signalr` 时不再使用 mock 设备和 mock 告警兜底,避免连接失败时误展示假数据。
- SignalR 连接失败时会展示空状态和连接错误,方便现场判断后端链路问题。
- 告警推送已改为按设备合并和清空,避免单设备告警覆盖全局告警列表。
### 2.4 产量口径调整
- CNC 类型已新增 `todayProduce` 字段。
- CNC 卡片的“今日产量”优先使用后端推送的 `todayProduce`。
- 焦点设备的“今日产量”优先使用后端推送的 `todayProduce`。
- 右侧汇总区的“今日产量”对 CNC 优先使用后端推送的 `todayProduce`。
- mock/周统计数据仅作为无后端数据时的 fallback。
- CNC 焦点下方图表使用后端 `DeviceProductionDaily` 的最近 7 天日期、日产量和运行时长,避免前端日期与 mock 数据错位。
- CNC 当天产量使用实时 `todayProduce` 覆盖 7 天图表最后一天,保证当天数据及时。
### 2.5 配电柜趋势展示
- 配电柜焦点下方图表已调整为最近 1 小时三相电流趋势。
- 趋势数据来自后端 `DeviceMetricTrendPoint`。
- 前端用阶梯线展示死区后的稀疏趋势点,表达“数值保持到下一次变化”。
- 图表末尾会补入最新 `device.updated` 中的实时 A/B/C 电流。
- 如果最近 1 小时内无趋势点,但设备有当前实时值,图表仍会显示当前点,不会空白。
## 3. WMS 后端已完成
### 3.1 MQTT 接收运行控制
- 已新增 MQTT 全局运行状态。
- 启动时读取 `MqttSubscription.IsEnabled`:
- 只要存在一条启用订阅,就认为 MQTT 接收开启。
- 全部禁用则认为 MQTT 接收关闭。
- 前端修改订阅启用状态时,同步更新全局运行变量。
- MQTT job 消费消息时读取全局变量,用于判断是否继续处理。
### 3.2 设备数据表
已新增并通过 EF Core 同步到 MySQL 的表:
- `DeviceCurrentState`
- 保存设备当前状态。
- 用于看板快照、设备在线状态、最后一次实时数据展示。
- `DeviceMetricTrendPoint`
- 保存清洗后的趋势点。
- 用于电流趋势、转速趋势、进给趋势、运行时长等图表。
- `DeviceAlarmRecord`
- 保存设备告警生命周期。
- 用于当前告警列表和后续告警统计。
- `DeviceProductionDaily`
- 保存设备日产能汇总。
- 用于今日产量、日报、近 7 日产量趋势。
### 3.3 配电柜清洗流程
- 已新增 `PowerCabinetMessageProcessor`。
- 已支持识别配电柜 MQTT payload。
- 已提取 A/B/C 三相电流。
- 已做电流死区过滤,减少无意义写库和推送。
- 已更新 `DeviceCurrentState`。
- 死区命中时不会新增 `DeviceMetricTrendPoint`,但会更新 `DeviceCurrentState.LastPayloadTime`、`LastUpdateTime` 和 `RealtimeJson`,表示设备仍在持续上报且当前值有效。
- 已写入分钟级趋势点:
- `currentA`
- `currentB`
- `currentC`
- `currentAvg`
- `estimatedPower`
- `imbalanceRate`
- 已同步配电柜异常告警。
- 已返回统一 `ProcessingResult`,供 job 和 SignalR 推送使用。
### 3.4 CNC 清洗流程
- 已新增 `CncMessageProcessor`。
- 已支持识别 CNC MQTT payload。
- 已提取:
- 设备状态。
- 当前程序名和程序号。
- 累计产量 `currentProduceCount`。
- 主轴转速。
- 进给速度。
- 设定主轴倍率。
- 设定进给倍率。
- 运行时间。
- 切削时间。
- 循环时间。
- 工作模式。
- 告警信息。
- CNC 类型和轴数。
- 已支持设备号解析,例如从 topic 或 payload 映射到 `CNC-001`。
- 已做死区过滤:
- 状态、程序、产量、告警变化会触发更新。
- 主轴转速小幅变化、进给速度小幅变化可被过滤。
- 超过最大静默时间后仍会更新,避免长期无推送。
- 已更新 `DeviceCurrentState`。
- 已写入趋势点:
- `cncProduceCount`
- `spindleSpeed`
- `feedRate`
- `runtimeMinutes`
- `cuttimeMinutes`
- 已更新 `DeviceProductionDaily`:
- `StartCounter`
- `EndCounter`
- `ProduceCount`
- `RuntimeMinutes`
- `CuttimeMinutes`
- 已同步 CNC 告警。
- 已在清洗后的实时数据中加入 `todayProduce`。
### 3.5 SignalR 推送服务
- 已新增 `DashboardHub`。
- 已将 hub 映射到 `/dashboardHub`。
- 已新增 CORS 策略,允许本地看板连接:
- `http://localhost:5173`
- `http://127.0.0.1:5173`
- 已新增 `DashboardPushService`。
- MQTT job 在清洗成功后会推送:
- `device.updated`
- `trend.updated`
- `alarm.updated`
- MQTT job 已调整为先保存清洗结果,再推送 SignalR,避免趋势和告警查询滞后一拍。
- `device.updated` 使用 `ProcessingResult.ParsedData`,也就是清洗后的数据,而不是重新从原始报文解析。
- `GetSnapshot` 会返回当前设备状态和当前活跃告警。
- `GetSnapshot` 会从 `DeviceProductionDaily` 合并当天 CNC `todayProduce`,保证页面刚打开时也能拿到今日产量。
- `GetSnapshot` 和 `device.updated` 会返回 CNC 最近 7 天 `DailyProduction`,作为前端 7 天产量/运行趋势的唯一数据源。
- 配电柜 `trend.updated` 会返回最近 1 小时 `DeviceMetricTrendPoint`,并补窗口开始前最后一个有效点,保证死区稳定时趋势图不断档。
## 4. 当前验证结果
已执行并通过:
```bash
dotnet build WMS.sln
pnpm --filter @dev-screen-starter/factory-dashboard typecheck
pnpm --filter @dev-screen-starter/factory-dashboard build
```
验证情况:
- WMS 编译通过。
- WMS 编译仅存在 `.NET 6` 停止支持的 SDK warning。
- factory-dashboard 类型检查通过。
- factory-dashboard 生产构建通过。
- 前端构建存在 SignalR/ECharts chunk 较大的提示,不影响当前运行。
- WMS 已可监听 `http://127.0.0.1:5000`。
- `/dashboardHub/negotiate` 已验证返回 `200`。
- 浏览器中 `http://localhost:5173/?scaleMode=fit&dataMode=signalr` 已可显示 SignalR 连接状态。
## 5. 本次提交范围
本次提交包含 WMS 后端和 `factory-dashboard` 看板的联动改造。
WMS 侧主要改动:
- `HHWMS.Web/Program.cs`
- `HHWMS.Web/Areas/System/Controllers/jobs/MqttMessageJob.cs`
- `HHWMS.Web/Areas/Hub/DashboardHub.cs`
- `HHWMS.Web/Services/DeviceData/PowerCabinetMessageProcessor.cs`
- `HHWMS.Web/Services/DeviceData/CncMessageProcessor.cs`
- `HHWMS.Web/Services/DeviceData/DashboardPushService.cs`
- `HHWMS.Web/Services/DeviceData/ProcessingResult.cs`
看板侧主要改动:
- `apps/factory-dashboard/package.json`
- `apps/factory-dashboard/src/api/dashboardSignalR.ts`
- `apps/factory-dashboard/src/pages/DashboardPage.tsx`
- `apps/factory-dashboard/src/components/CncCard.tsx`
- `apps/factory-dashboard/src/components/FocusDevicePanel.tsx`
- `apps/factory-dashboard/src/components/StatusSummary.tsx`
- `apps/factory-dashboard/src/domain/deviceTypes.ts`
- `apps/factory-dashboard/src/mock/factoryDevices.ts`
- `apps/factory-dashboard/src/styles/factory-dashboard.css`
- `packages/charts/src/optionFactories.ts`
- `pnpm-lock.yaml`
- `doc/factory-dashboard-wms-progress.md`
## 6. 后续建议
### 6.1 后端优先事项
- 激光设备暂时继续使用外部 HTTP 信息,不纳入当前 MQTT/SignalR 清洗链路。
- 增加看板专用查询接口:
- 设备列表。
- 最近 1 小时或自定义时间窗电流趋势。
- 近 7 日产量趋势。
- 当前告警列表。
- 设备详情页数据。
- 增加聚合推送事件,例如 `summary.updated`,用于推送整屏汇总指标。
- 为 `DeviceMetricTrendPoint` 增加按设备、指标、时间范围查询能力。
- 明确设备编码映射规则,避免 topic、payload、数据库设备号不一致。
- 后续将 .NET 6 升级到受支持版本,减少运行环境风险。
### 6.2 看板优先事项
- 将右侧近 7 日趋势从 mock 切到后端接口。
- 将焦点设备趋势图从 mock 切到后端接口或 SignalR 聚合数据。
- 增加设备详情页:
- CNC 详情。
- 激光详情。
- 配电柜详情。
- 增加真实数据和 mock 数据并行调试开关。
- 对 SignalR 断线、重连、空数据、后端异常增加更明确的页面状态。
- 对生产环境构建做代码拆分,降低首屏 JS 体积。
### 6.3 数据口径建议
- 今日产量、总产能、近 7 日产量这类业务指标应以后端汇总表为准。
- 前端只负责展示,不再计算核心业务口径。
- 原始 MQTT 数据只用于采集和审计,不直接推给看板。
- 看板实时链路统一消费后端清洗后的 WebSocket/SignalR 数据。