# 智能设备管理看板

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)`，按日索引。执行：

```powershell
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" />`。回退上报代码应保留新日汇总表，避免丢失已经积累的用水历史。