water/docs/superpowers/specs/2026-06-24-bind-schedule-device-dispatch-design.md

绑定排程时向设备下发排程信息设计

背景

当前 AppController.addScheduleDevice 只负责建立排程与设备的关联关系，不会把排程详情同步下发给设备。这样会导致设备绑定成功后仍然缺少最新排程配置。

目标

在 APP 端绑定排程与设备成功时，服务端同步向对应设备下发该排程详情信息，确保设备立即拿到当前排程配置。

设计

入口与改动范围

• 入口保持在 water-modules/water-app/src/main/java/org/dromara/app/controller/AppController.java 的 addScheduleDevice
• 复用现有 IDeviceCommandService.sendScheduleBindCommand(...)
• 不修改现有 MQTT 发布器、ACK 处理器和设备主题路由

下发时机

对请求中的每个 deviceNo：

1. 校验设备归属
2. 写入排程设备关联
3. 读取当前排程详情
4. 同步下发排程命令

命令协议

• commandType: bindSchedule
• payload.deviceNo: 当前设备编号
• payload.details: 当前排程详情列表

payload.details 每项沿用当前 APP 查询排程详情时对外返回的结构，包含：

• weekday
• timeData
• triggerType
• status

如果排程详情里存在 zones 字段且当前查询对象可直接取到，则一并下发；否则不额外改造现有排程详情出参结构。

失败策略

绑定接口采用同步失败策略：

• 只要某台设备的排程命令下发失败，接口直接返回失败
• 不吞掉下发异常
• 前端可以明确感知“排程绑定/同步下发”未完全成功

本次不额外引入补偿、重试编排或异步任务。

测试与验证

• 优先补最小范围的自动化测试；如果模块当前没有现成测试基线，则至少执行模块编译或定向测试命令做回归验证
• 手工验证重点：
  • 绑定排程后关联表仍正常写入
  • MQTT 下发 payload 包含 deviceNo、details
  • 设备未登记 MAC 或命令下发异常时，接口返回失败