water/server/docs/WATER_DEVICE_DASHBOARD.md

智能设备管理看板

2026-09-11 按用户参考图重做 /water-devices：四项统计、组合筛选、每页8张设备卡片、设备详情/编辑、固件版本分布、近30日用水趋势和异常类型表。所有数量取数据库；没有套用图片中的1302台等示例值。

分层与复用

• WaterDeviceDashboard：Eloquent 读模型，负责全量统计、设备分页、版本分布、趋势、异常和完整导出。控制器只授权并封装响应。
• service/device/DeviceFilters：查询条件值对象，列表和导出共用校验及筛选。
• service/device/DeviceStatusPolicy：互斥状态策略，计数、筛选、卡片、导出使用相同规则。
• 档案仍通过 WaterBusiness::save('device', ...) 保存；上报仍经过 DeviceReport，不在页面或控制器复制写库逻辑。
• 前端 useDeviceDashboard.ts 管理查询条件、已应用条件、分页、错误及旧响应丢弃；页面只组合组件。
• DeviceCard、DeviceEditor、DeviceAnalytics、FirmwareDialog 各自负责卡片、表单、图表和版本入口。
• WaterMetricCards、useWaterOptions、waterDownload 分别提供可复用统计卡、远程选项及校验后下载，样式限定组件/设备页面范围。

口径与边界

1. 当前故障说明非空 → 告警；没有上报时间 → 未接入；最后上报早于15分钟前 → 离线；其余 → 在线。故障优先，四项状态数量之和为设备总数。在线率分母为全部设备。
2. 从未上报设备不算离线。离线超过24小时仅统计当前离线分类。列表页脚展示全量未接入数量。
3. 卡片今日用水只显示当天快照；真实0显示0.0L，没有当天上报显示“—”。最后上报同时提供相对时间及详情中的绝对时间。
4. 顶部统计、版本分布、趋势和异常表都取全量，不随列表筛选和翻页变化。关键词匹配SN、设备名称、企业，区域和版本精确匹配。
5. 异常表按当前离线/已保存故障说明分类，每台只计一次；没有故障历史及工单，标题使用“当前状态”，不显示虚构的“最近24小时”事件数或上门处理数量。
6. 固件管理提供已登记版本分布、按版本查看设备，并通过设备编辑维护版本。没有厂商协议/升级接口，未实施OTA上传或下发。用户界面有明确说明。

历史用水与迁移

新增模型 WaterDeviceUsage，表 sa_water_device_usage，唯一键 (device_id, day)，按日索引。执行：

php scripts/migrate_water_device_usage.php --apply

脚本只建新表并以 INSERT IGNORE 复制已有日期明确的设备用水快照，重跑不覆盖历史；此次实际复制0条，没有制造往日用量，旧设备/库存/权益保持不变。部署顺序为迁移先于开启新页面和上报代码。

DeviceReport 在原设备行锁和事务内保存每天累计最大值，重复/较小乱序报告不累加；跨日使用新日期行，旧日期保留。报告验证、HTTP/MQTT关闭默认值和供应商适配接口不变。无厂商协议时不启用采集；参见 WATER_DEVICE_INTEGRATION.md。

趋势返回今天及前29天；有上报则汇总各设备日累计值和上报设备数，无记录日期为 null，不伪装为0或连接空白区间。当前无历史数据时显示真实空状态，未来正常上报后自动积累。

接口

• GET /core/water/devices/dashboard：keyword/status/region/firmware/page/limit；默认8条，最多100条；返回 summary/list/options/trend/anomalies/updated_at。
• POST /core/water/devices/export：相同筛选，忽略分页，导出全部匹配设备XLSX；超过50,000条明确拒绝。文本公式前缀转义，临时文件清理。
• 读取/导出均需 water:devices:read；原写接口继续需 water:devices:write。未授权不能通过直接调用导出绕过权限。

验证

• php -d extension=mbstring tests/water_device_dashboard_test.php --http：45项，包括分页、状态边界/优先级、筛选、统计、零值/缺失值、日期边界、日累计去重、XLSX、权限及真实本地HTTP。临时设备、用水记录和关联档案全部回滚，HTTP只读/导出。
• 原 water_device_ingress_test.php 30项通过；未启用HTTP/MQTT网关。
• 新增/修改PHP文件语法通过；前端Prettier、ESLint、vue-tsc通过；Vite构建3290模块通过。保留原系统菜单静态/动态导入警告。
• 浏览器工具仍在启动时报 failed to start Node runtime: 系统找不到指定的路径。 (os error 3)；未完成截图和实际浏览器交互验收，不将类型/构建/API测试视为视觉通过。

回退页面可恢复 <WaterWorkspace module="devices" />。回退上报代码应保留新日汇总表，避免丢失已经积累的用水历史。