feat: 新增eq_kwh多设备能耗查询接口

- 新增按时/日/月聚合的多设备能耗查询接口(/energy/eqKwhByType)
- 新增eq_kwh数据概况调试接口(/energy/debug/eqKwhInfo)
- 修复日期查询参数格式为ISO标准(T00:00:00)
- 规范代码格式与Javadoc注释

@@ -164,8 +164,8 @@ public class HealthController {
      * type=2(天): 传startDate和endDate，按日统计
      * type=3(月): 查本年年初到现在，按月统计
      *
-     * @param dtuSn    设备序列号
-     * @param type     类型：1-时，2-天，3-月
+     * @param dtuSn     设备序列号
+     * @param type      类型：1-时，2-天，3-月
      * @param startDate 开始日期 yyyy-MM-dd (type=1,2必填)
      * @param endDate   结束日期 yyyy-MM-dd (type=2必填)
      */
@@ -184,7 +184,7 @@ public class HealthController {
      *
      * @param date     查询日期 yyyy-MM-dd
      * @param pageNo   页码，默认1
-     * @param pageSize  每页条数，默认12
+     * @param pageSize 每页条数，默认12
      */
     @GetMapping("/energy/timelineStatus")
     public Map<String, Object> energyTimelineStatus(
@@ -208,4 +208,32 @@ public class HealthController {
             @RequestParam String endDate) {
         return energySearchService.queryEqKwhStatistics(startDate, endDate);
     }
+
+    /**
+     * 查询eq_kwh多设备能耗数据(按 时/日/月 聚合)
+     * type=1 (时): 传startDate，返回该日所有设备的原始用电量明细
+     * type=2 (日):
+     * - 传startDate+endDate: 按此范围每日统计每台设备能耗
+     * - 只传startDate: 自动取当月1号~月末，按日统计
+     * type=3 (月): 自动取本年1月~当前月，按月统计每台能耗数据
+     *
+     * @param type      类型: 1-时, 2-日, 3-月
+     * @param startDate 开始日期 yyyy-MM-dd
+     * @param endDate   结束日期 yyyy-MM-dd (type=2时可选)
+     */
+    @GetMapping("/energy/eqKwhByType")
+    public Map<String, Object> eqKwhByType(
+            @RequestParam(defaultValue = "1") String type,
+            @RequestParam(required = false) String startDate,
+            @RequestParam(required = false) String endDate) {
+        return energySearchService.queryEqKwhByType(type, startDate, endDate);
+    }
+
+    /**
+     * 调试：查看eq_kwh表中的数据概况
+     */
+    @GetMapping("/energy/debug/eqKwhInfo")
+    public Map<String, Object> debugEqKwhInfo() {
+        return energySearchService.debugEqKwhInfo();
+    }
 }

@@ -242,8 +242,8 @@ public class EnergySearchService {
      * type=2(天): 传startDate和endDate，按日统计
      * type=3(月): 查本年年初到现在，按月统计
      *
-     * @param dtuSn    设备序列号
-     * @param type     类型：1-时，2-天，3-月
+     * @param dtuSn     设备序列号
+     * @param type      类型：1-时，2-天，3-月
      * @param startDate 开始日期 yyyy-MM-dd (type=1,2必填)
      * @param endDate   结束日期 yyyy-MM-dd (type=2必填)
      */
@@ -323,7 +323,8 @@ public class EnergySearchService {
                     }
                     kwhRawData = dataArray;
                 }
-            } catch (Exception ignored) {}
+            } catch (Exception ignored) {
+            }
             totalKwhAll = totalKwhAll.add(dayKwh);
 
             String periodKey = "3".equals(type) ? dateStr.substring(0, 7) : dateStr;
@@ -455,7 +456,8 @@ public class EnergySearchService {
                             if (runStatus == 3) runDuration += duration; // 运行状态
                         }
                     }
-                } catch (Exception ignored) {}
+                } catch (Exception ignored) {
+                }
             }
 
             item.put("timelineList", oeeRawData);
@@ -475,7 +477,8 @@ public class EnergySearchService {
                         if (value != null) totalKwh = totalKwh.add(BigDecimal.valueOf(value));
                     }
                 }
-            } catch (Exception ignored) {}
+            } catch (Exception ignored) {
+            }
 
             item.put("totalKwh", totalKwh.setScale(2, RoundingMode.HALF_UP));
             // 稼动率 = 运行时长 / 总时长
@@ -559,10 +562,10 @@ public class EnergySearchService {
     /**
      * 查询 eq_kwh 表的综合统计数据
      * 返回：
-     *   1. 所有设备的总的稼动率 + 每个状态的时间(xxx.xx时)
-     *   2. 当前设备的运行状态
-     *   3. 异常机台排名(待机+停机时间最长往下排, xx时xx分xx秒)
-     *   4. 每个设备统计时间内的总的0/1/2/3的时间(xx时xx分xx秒)
+     * 1. 所有设备的总的稼动率 + 每个状态的时间(xxx.xx时)
+     * 2. 当前设备的运行状态
+     * 3. 异常机台排名(待机+停机时间最长往下排, xx时xx分xx秒)
+     * 4. 每个设备统计时间内的总的0/1/2/3的时间(xx时xx分xx秒)
      *
      * @param startDate 开始日期 yyyy-MM-dd
      * @param endDate   结束日期 yyyy-MM-dd
@@ -605,7 +608,9 @@ public class EnergySearchService {
         return buildEqKwhStatisticsResult(deviceStatMap, deviceNameMap);
     }
 
-    /** 设备统计内部结构 */
+    /**
+     * 设备统计内部结构
+     */
     static class DeviceStatResult {
         String dtuSn;
         String deviceName;
@@ -620,15 +625,31 @@ public class EnergySearchService {
             this.deviceName = deviceName;
         }
 
-        /** 总时长(秒) */
-        long totalDuration() { return status0 + status1 + status2 + status3; }
-        /** 异常时长 = 停机 + 待机 */
-        long abnormalDuration() { return status1 + status2; }
-        /** 稼动分母 = 停机 + 待机 + 运行 (排除离线) */
-        long activeDuration() { return status1 + status2 + status3; }
+        /**
+         * 总时长(秒)
+         */
+        long totalDuration() {
+            return status0 + status1 + status2 + status3;
+        }
+
+        /**
+         * 异常时长 = 停机 + 待机
+         */
+        long abnormalDuration() {
+            return status1 + status2;
+        }
+
+        /**
+         * 稼动分母 = 停机 + 待机 + 运行 (排除离线)
+         */
+        long activeDuration() {
+            return status1 + status2 + status3;
+        }
     }
 
-    /** 构建空结果 */
+    /**
+     * 构建空结果
+     */
     private Map<String, Object> buildEmptyEqKwhStats() {
         return Map.of(
                 "code", 200, "msg", "请求成功", "data",
@@ -649,7 +670,9 @@ public class EnergySearchService {
         );
     }
 
-    /** 获取能耗设备表所有dtuSn及名称 */
+    /**
+     * 获取能耗设备表所有dtuSn及名称
+     */
     private Map<String, String> queryAllEnergyDeviceNames() {
         String sql = "SELECT dtuSn, deviceName FROM " + energyTableName + " WHERE corp_code = ? ORDER BY dtuSn";
         List<Map<String, Object>> rows = jdbcTemplate.queryForList(sql, energyCorpCode);
@@ -660,7 +683,9 @@ public class EnergySearchService {
         return result;
     }
 
-    /** 构建连续日期列表 */
+    /**
+     * 构建连续日期列表
+     */
     private List<String> buildDateList(String startDate, String endDate) {
         List<String> result = new ArrayList<>();
         try {
@@ -679,7 +704,9 @@ public class EnergySearchService {
         return result;
     }
 
-    /** 从 eq_kwh 表批量查询指定日期范围的所有记录 */
+    /**
+     * 从 eq_kwh 表批量查询指定日期范围的所有记录
+     */
     private List<Map<String, Object>> queryEqKwhBatch(List<String> dateList) {
         if (dateList.isEmpty()) return Collections.emptyList();
 
@@ -689,14 +716,19 @@ public class EnergySearchService {
         List<Object> params = new ArrayList<>();
         params.add(energyCorpCode);
 
-        for (String d : dateList) { sql.append("?,"); params.add(d + " 00:00:00"); }
+        for (String d : dateList) {
+            sql.append("?,");
+            params.add(d + "T00:00:00");
+        }
         sql.deleteCharAt(sql.length() - 1).append(")");
         sql.append(" ORDER BY dtuSn, use_date");
 
         return jdbcTemplate.queryForList(sql.toString(), params.toArray());
     }
 
-    /** 按 dtuSn 分组聚合各状态时长 */
+    /**
+     * 按 dtuSn 分组聚合各状态时长
+     */
     private Map<String, DeviceStatResult> aggregateByDevice(List<Map<String, Object>> rawData,
                                                             Map<String, String> deviceNameMap) {
         Map<String, DeviceStatResult> resultMap = new LinkedHashMap<>();
@@ -743,7 +775,9 @@ public class EnergySearchService {
         return resultMap;
     }
 
-    /** 构建最终统计结果 */
+    /**
+     * 构建最终统计结果
+     */
     private Map<String, Object> buildEqKwhStatisticsResult(Map<String, DeviceStatResult> deviceStatMap,
                                                            Map<String, String> deviceNameMap) {
         // ---- 全局汇总 ----
@@ -756,8 +790,10 @@ public class EnergySearchService {
         for (Map.Entry<String, DeviceStatResult> entry : deviceStatMap.entrySet()) {
             DeviceStatResult dsr = entry.getValue();
 
-            totalS0 += dsr.status0; totalS1 += dsr.status1;
-            totalS2 += dsr.status2; totalS3 += dsr.status3;
+            totalS0 += dsr.status0;
+            totalS1 += dsr.status1;
+            totalS2 += dsr.status2;
+            totalS3 += dsr.status3;
             totalKwhSum += dsr.totalKwh;
 
             // 单设备稼动率 = 运行 / (停机+待机+运行)
@@ -856,7 +892,9 @@ public class EnergySearchService {
         );
     }
 
-    /** 查询当前设备运行状态分布(从energy表) runStatus: 0-离线, 1-停机, 2-待机, 3-运行 */
+    /**
+     * 查询当前设备运行状态分布(从energy表) runStatus: 0-离线, 1-停机, 2-待机, 3-运行
+     */
     private Map<String, Integer> queryCurrentRunStatus() {
         String sql = "SELECT runStatus, COUNT(*) as cnt FROM " + energyTableName +
                 " WHERE corp_code = ? GROUP BY runStatus";
@@ -875,4 +913,452 @@ public class EnergySearchService {
         }
         return Map.of("0", s0, "1", s1, "2", s2, "3", s3);
     }
+
+    // ==================== eq_kwh 多设备时/日/月查询 ====================
+
+    /**
+     * 查询 eq_kwh 表的多设备能耗数据(按 时/日/月 聚合)
+     * <p>
+     * type=1 (时): 只需传 startDate，返回该日所有设备的原始用电量明细(kwhList)
+     * type=2 (日):
+     * - 若传了 startDate+endDate: 按此范围每日统计每台设备能耗
+     * - 若只传 startDate: 自动补全为当月的第1天~最后一天
+     * type=3 (月): 自动取本年1月~当前月，按月统计每台设备能耗
+     *
+     * @param type      查询类型: 1-时, 2-日, 3-月
+     * @param startDate 开始日期 yyyy-MM-dd (type=1,2必填; type=3可选)
+     * @param endDate   结束日期 yyyy-MM-dd (type=2可选)
+     */
+    public Map<String, Object> queryEqKwhByType(String type, String startDate, String endDate) {
+        log.info("========== [eq_kwh多设备查询] type={}, startDate={}, endDate={} ==========", type, startDate, endDate);
+
+        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
+        List<String> dateList = new ArrayList<>();
+
+        // 根据type构建日期列表 + 实际起止日期
+        String actualStart;
+        String actualEnd;
+
+        if ("1".equals(type)) {
+            // type=1: 单日查询，直接返回原始kwh数据
+            if (!StringUtils.hasText(startDate)) {
+                return Map.of("code", 400, "msg", "参数错误: type=1时startDate必填");
+            }
+            dateList.add(startDate);
+            actualStart = startDate;
+            actualEnd = startDate;
+        } else if ("2".equals(type)) {
+            // type=2: 按日统计
+            if (!StringUtils.hasText(startDate)) {
+                return Map.of("code", 400, "msg", "参数错误: type=2时startDate必填");
+            }
+            if (StringUtils.hasText(endDate)) {
+                // 有结束日期，直接用传入范围
+                try {
+                    Date start = sdf.parse(startDate);
+                    Date end = sdf.parse(endDate);
+                    Calendar cur = Calendar.getInstance();
+                    cur.setTime(start);
+                    while (!cur.getTime().after(end)) {
+                        dateList.add(sdf.format(cur.getTime()));
+                        cur.add(Calendar.DAY_OF_MONTH, 1);
+                    }
+                    actualStart = startDate;
+                    actualEnd = endDate;
+                } catch (Exception e) {
+                    return Map.of("code", 400, "msg", "日期格式错误: " + startDate + " ~ " + endDate);
+                }
+            } else {
+                // 只有开始日期 -> 自动取所在月的1号~最后一天
+                try {
+                    Date startD = sdf.parse(startDate);
+                    Calendar cal = Calendar.getInstance();
+                    cal.setTime(startD);
+                    cal.set(Calendar.DAY_OF_MONTH, 1);       // 月初
+                    actualStart = sdf.format(cal.getTime());
+                    cal.set(Calendar.DAY_OF_MONTH, cal.getActualMaximum(Calendar.DAY_OF_MONTH)); // 月末
+                    actualEnd = sdf.format(cal.getTime());
+
+                    Calendar cur = Calendar.getInstance();
+                    cur.setTime(sdf.parse(actualStart));
+                    while (!cur.after(cal)) { // cur <= actualEnd
+                        dateList.add(sdf.format(cur.getTime()));
+                        cur.add(Calendar.DAY_OF_MONTH, 1);
+                    }
+                } catch (Exception e) {
+                    return Map.of("code", 400, "msg", "日期格式错误: " + startDate);
+                }
+            }
+        } else if ("3".equals(type)) {
+            // type=3: 按月统计
+            if (StringUtils.hasText(startDate) && StringUtils.hasText(endDate)) {
+                // 有起止日期：按传入范围按月聚合
+                try {
+                    Date start = sdf.parse(startDate);
+                    Date end = sdf.parse(endDate);
+                    actualStart = startDate;
+                    actualEnd = endDate;
+                    Calendar cur = Calendar.getInstance();
+                    cur.setTime(start);
+                    while (!cur.getTime().after(end)) {
+                        dateList.add(sdf.format(cur.getTime()));
+                        cur.add(Calendar.DAY_OF_MONTH, 1);
+                    }
+                } catch (Exception e) {
+                    return Map.of("code", 400, "msg", "日期格式错误: " + startDate + " ~ " + endDate);
+                }
+            } else {
+                // 无日期：默认本年1月1日 ~ 今天
+                Calendar now = Calendar.getInstance();
+                int year = now.get(Calendar.YEAR);
+                Calendar startCal = Calendar.getInstance();
+                startCal.set(year, Calendar.JANUARY, 1);
+                actualStart = sdf.format(startCal.getTime());
+                actualEnd = sdf.format(now.getTime());
+
+                Calendar cur = Calendar.getInstance();
+                cur.setTime(startCal.getTime());
+                while (!cur.getTime().after(now.getTime())) {
+                    dateList.add(sdf.format(cur.getTime()));
+                    cur.add(Calendar.DAY_OF_MONTH, 1);
+                }
+            }
+        } else {
+            return Map.of("code", 400, "msg", "参数错误: type只支持1/2/3");
+        }
+
+        log.info("实际日期范围: {} ~ {}, 共{}天", actualStart, actualEnd, dateList.size());
+
+        // 获取所有设备列表及名称
+        Map<String, String> deviceNameMap = queryAllEnergyDeviceNames();
+
+        // 从 eq_kwh 批量查询所有记录
+        List<Map<String, Object>> allRawData = queryEqKwhBatch(dateList);
+        log.info("eq_kwh 批量查询返回 {} 条原始记录", allRawData.size());
+
+        // 构建结果
+        return buildEqKwhByTypeResult(type, dateList, allRawData, deviceNameMap, actualStart, actualEnd);
+    }
+
+    /**
+     * 构建 type=1/2/3 的多设备查询结果
+     */
+    private Map<String, Object> buildEqKwhByTypeResult(String type, List<String> dateList,
+                                                       List<Map<String, Object>> allRawData,
+                                                       Map<String, String> deviceNameMap,
+                                                       String actualStart, String actualEnd) {
+        // 按 dtuSn+日期 建立快速查找Map: key="dtuSn|yyyy-MM-dd" -> JSONArray(kwh原始数据)
+        Map<String, Object> rawDataMap = new LinkedHashMap<>();
+        for (Map<String, Object> row : allRawData) {
+            String sn = (String) row.get("dtuSn");
+            String ud = String.valueOf(row.get("use_date"));
+            String desc = row.get("description") != null ? String.valueOf(row.get("description")) : "";
+            if (StringUtils.hasText(desc)) {
+                try {
+                    // use_date 可能是 "2026-05-21T00:00:00" 或 "2026-05-21 00:00:00"，统一截取前10位作为纯日期key
+                    String dateKey = ud.length() > 10 ? ud.substring(0, 10) : ud;
+                    rawDataMap.put(sn + "|" + dateKey, JSON.parseArray(desc));
+                } catch (Exception ignored) {
+                }
+            }
+        }
+
+        // ---- type=1: 返回所有设备的原始kwh明细 ----
+        if ("1".equals(type)) {
+            return buildType1Result(dateList.get(0), rawDataMap, deviceNameMap);
+        }
+
+        // ---- type=2: 按日统计 ----
+        if ("2".equals(type)) {
+            return buildType2Result(dateList, rawDataMap, deviceNameMap, actualStart, actualEnd);
+        }
+
+        // ---- type=3: 按月统计 ----
+        if ("3".equals(type)) {
+            return buildType3Result(dateList, rawDataMap, deviceNameMap, actualStart, actualEnd);
+        }
+
+        return Map.of("code", 500, "msg", "未知type");
+    }
+
+    /**
+     * type=1 (时): 单日查询 - 返回每个设备的 kwh 原始数据 + 当日汇总
+     */
+    private Map<String, Object> buildType1Result(String dateStr, Map<String, Object> rawDataMap,
+                                                 Map<String, String> deviceNameMap) {
+        List<Map<String, Object>> list = new ArrayList<>();
+        BigDecimal totalKwhAll = BigDecimal.ZERO;
+
+        for (String sn : deviceNameMap.keySet()) {
+            String mapKey = sn + "|" + dateStr;
+            Object rawObj = rawDataMap.getOrDefault(mapKey, Collections.emptyList());
+            @SuppressWarnings("unchecked")
+            JSONArray dataArray = rawObj instanceof JSONArray ? (JSONArray) rawObj : new JSONArray();
+
+            // 统计当日总用电量
+            BigDecimal dayKwh = BigDecimal.ZERO;
+            for (int i = 0; i < dataArray.size(); i++) {
+                JSONObject item = dataArray.getJSONObject(i);
+                if (item != null && item.getDouble("value") != null) {
+                    dayKwh = dayKwh.add(BigDecimal.valueOf(item.getDouble("value")));
+                }
+            }
+            totalKwhAll = totalKwhAll.add(dayKwh);
+
+            Map<String, Object> item = new LinkedHashMap<>();
+            item.put("dtuSn", sn);
+            item.put("deviceName", deviceNameMap.getOrDefault(sn, ""));
+            item.put("date", dateStr);
+            item.put("kwhList", dataArray);
+            item.put("totalKwh", dayKwh.setScale(2, RoundingMode.HALF_UP));
+            list.add(item);
+        }
+
+        return Map.of(
+                "code", 200, "msg", "请求成功",
+                "type", "1",
+                "date", dateStr,
+                "totalDevices", deviceNameMap.size(),
+                "totalKwh", totalKwhAll.setScale(2, RoundingMode.HALF_UP),
+                "list", list
+        );
+    }
+
+    /**
+     * type=2 (日): 按设备统计 - 每个设备一行，包含该设备每天的能耗明细
+     */
+    private Map<String, Object> buildType2Result(List<String> dateList, Map<String, Object> rawDataMap,
+                                                 Map<String, String> deviceNameMap,
+                                                 String actualStart, String actualEnd) {
+        BigDecimal grandTotalKwh = BigDecimal.ZERO;
+        List<Map<String, Object>> deviceList = new ArrayList<>(deviceNameMap.size());
+
+        for (String sn : deviceNameMap.keySet()) {
+            Map<String, Object> devItem = new LinkedHashMap<>();
+            devItem.put("dtuSn", sn);
+            devItem.put("deviceName", deviceNameMap.getOrDefault(sn, ""));
+
+            // 该设备的每日数据列表
+            List<Map<String, Object>> dailyDataList = new ArrayList<>(dateList.size());
+            BigDecimal devTotalKwh = BigDecimal.ZERO;
+            long devTotalDur = 0;
+            Map<Integer, Long> devStatusAll = initStatusMap();
+
+            for (String d : dateList) {
+                String mapKey = sn + "|" + d;
+                Object rawObj = rawDataMap.getOrDefault(mapKey, Collections.emptyList());
+                @SuppressWarnings("unchecked")
+                JSONArray dataArray = rawObj instanceof JSONArray ? (JSONArray) rawObj : new JSONArray();
+
+                BigDecimal dayKwh = BigDecimal.ZERO;
+                long dayDur = 0;
+                Map<Integer, Long> dayStatus = initStatusMap();
+
+                for (int i = 0; i < dataArray.size(); i++) {
+                    JSONObject item = dataArray.getJSONObject(i);
+                    if (item == null) continue;
+
+                    Double value = item.getDouble("value");
+                    if (value != null) dayKwh = dayKwh.add(BigDecimal.valueOf(value));
+
+                    for (int sk = 0; sk <= 3; sk++) {
+                        Long dur = item.getLong(String.valueOf(sk));
+                        if (dur != null && dur > 0) {
+                            dayDur += dur;
+                            dayStatus.merge(sk, dur, Long::sum);
+                            devTotalDur += dur;
+                            devStatusAll.merge(sk, dur, Long::sum);
+                        }
+                    }
+                }
+
+                devTotalKwh = devTotalKwh.add(dayKwh);
+
+                Map<String, Object> dayEntry = new LinkedHashMap<>();
+                dayEntry.put("date", d);
+                dayEntry.put("totalKwh", dayKwh.setScale(2, RoundingMode.HALF_UP));
+                dayEntry.put("totalDurationFormatted", formatDuration(dayDur));
+                dayEntry.put("totalDurationSeconds", dayDur);
+                dayEntry.put("statusStats", buildStatusStats(dayStatus, dayDur));
+                dailyDataList.add(dayEntry);
+            }
+
+            grandTotalKwh = grandTotalKwh.add(devTotalKwh);
+
+            devItem.put("totalKwh", devTotalKwh.setScale(2, RoundingMode.HALF_UP));
+            devItem.put("totalDurationFormatted", formatDuration(devTotalDur));
+            devItem.put("totalDurationSeconds", devTotalDur);
+            devItem.put("statusStats", buildStatusStats(devStatusAll, devTotalDur));
+            devItem.put("dailyData", dailyDataList);
+
+            deviceList.add(devItem);
+        }
+
+        return Map.of(
+                "code", 200, "msg", "请求成功",
+                "type", "2",
+                "actualStartDate", actualStart,
+                "actualEndDate", actualEnd,
+                "totalDays", dateList.size(),
+                "totalDevices", deviceList.size(),
+                "grandTotalKwh", grandTotalKwh.setScale(2, RoundingMode.HALF_UP),
+                "list", deviceList
+        );
+    }
+
+    /**
+     * type=3 (月): 按设备统计 - 每个设备一行，包含该设备每月的能耗明细
+     */
+    private Map<String, Object> buildType3Result(List<String> dateList, Map<String, Object> rawDataMap,
+                                                 Map<String, String> deviceNameMap,
+                                                 String actualStart, String actualEnd) {
+        BigDecimal grandTotalKwh = BigDecimal.ZERO;
+        List<Map<String, Object>> deviceList = new ArrayList<>(deviceNameMap.size());
+
+        for (String sn : deviceNameMap.keySet()) {
+            Map<String, Object> devItem = new LinkedHashMap<>();
+            devItem.put("dtuSn", sn);
+            devItem.put("deviceName", deviceNameMap.getOrDefault(sn, ""));
+
+            // 该设备的按月聚合数据
+            Map<String, Map<String, Object>> monthAgg = new LinkedHashMap<>();
+
+            for (String d : dateList) {
+                String monthKey = d.substring(0, 7);
+
+                monthAgg.computeIfAbsent(monthKey, k -> {
+                    Map<String, Object> m = new LinkedHashMap<>();
+                    m.put("month", k);
+                    m.put("label", Integer.parseInt(k.substring(5)) + "月");
+                    m.put("totalKwh", BigDecimal.ZERO);
+                    m.put("totalDurationSeconds", 0L);
+                    m.put("statusDurationMap", initStatusMap());
+                    return m;
+                });
+
+                String mapKey = sn + "|" + d;
+                Object rawObj = rawDataMap.getOrDefault(mapKey, Collections.emptyList());
+                @SuppressWarnings("unchecked")
+                JSONArray dataArray = rawObj instanceof JSONArray ? (JSONArray) rawObj : new JSONArray();
+
+                Map<String, Object> mEntry = monthAgg.get(monthKey);
+
+                for (int i = 0; i < dataArray.size(); i++) {
+                    JSONObject item = dataArray.getJSONObject(i);
+                    if (item == null) continue;
+
+                    Double value = item.getDouble("value");
+                    if (value != null) {
+                        BigDecimal valBd = BigDecimal.valueOf(value);
+                        mEntry.put("totalKwh", ((BigDecimal) mEntry.get("totalKwh")).add(valBd));
+                    }
+
+                    for (int sk = 0; sk <= 3; sk++) {
+                        Long dur = item.getLong(String.valueOf(sk));
+                        if (dur != null && dur > 0) {
+                            mEntry.put("totalDurationSeconds", (Long) mEntry.get("totalDurationSeconds") + dur);
+                            @SuppressWarnings("unchecked")
+                            Map<Integer, Long> sMap = (Map<Integer, Long>) mEntry.get("statusDurationMap");
+                            sMap.merge(sk, dur, Long::sum);
+                        }
+                    }
+                }
+            }
+
+            // 构建该设备的月度数据列表
+            List<Map<String, Object>> monthlyDataList = new ArrayList<>(monthAgg.size());
+            BigDecimal devTotalKwh = BigDecimal.ZERO;
+            long devTotalDur = 0;
+            Map<Integer, Long> devStatusAll = initStatusMap();
+
+            for (Map.Entry<String, Map<String, Object>> me : monthAgg.entrySet()) {
+                Map<String, Object> m = me.getValue();
+                long mDur = (Long) m.get("totalDurationSeconds");
+                BigDecimal mKwh = (BigDecimal) m.get("totalKwh");
+                @SuppressWarnings("unchecked")
+                Map<Integer, Long> mStatus = (Map<Integer, Long>) m.get("statusDurationMap");
+
+                devTotalKwh = devTotalKwh.add(mKwh);
+                devTotalDur += mDur;
+                for (int sk = 0; sk <= 3; sk++) {
+                    long sd = mStatus.getOrDefault(sk, 0L);
+                    if (sd > 0) devStatusAll.merge(sk, sd, Long::sum);
+                }
+
+                Map<String, Object> monthEntry = new LinkedHashMap<>();
+                monthEntry.put("month", m.get("month"));
+                monthEntry.put("label", m.get("label"));
+                monthEntry.put("totalKwh", mKwh.setScale(2, RoundingMode.HALF_UP));
+                monthEntry.put("totalDurationFormatted", formatDuration(mDur));
+                monthEntry.put("totalDurationSeconds", mDur);
+                monthEntry.put("statusStats", buildStatusStats(mStatus, mDur));
+                monthlyDataList.add(monthEntry);
+            }
+
+            grandTotalKwh = grandTotalKwh.add(devTotalKwh);
+
+            devItem.put("totalKwh", devTotalKwh.setScale(2, RoundingMode.HALF_UP));
+            devItem.put("totalDurationFormatted", formatDuration(devTotalDur));
+            devItem.put("totalDurationSeconds", devTotalDur);
+            devItem.put("statusStats", buildStatusStats(devStatusAll, devTotalDur));
+            devItem.put("monthlyData", monthlyDataList);
+
+            deviceList.add(devItem);
+        }
+
+        return Map.of(
+                "code", 200, "msg", "请求成功",
+                "type", "3",
+                "year", actualStart.substring(0, 4),
+                "actualStartDate", actualStart,
+                "actualEndDate", actualEnd,
+                "totalMonths", dateList.isEmpty() ? 0 :
+                        (dateList.stream().map(d -> d.substring(0, 7)).distinct().toList()).size(),
+                "totalDevices", deviceList.size(),
+                "grandTotalKwh", grandTotalKwh.setScale(2, RoundingMode.HALF_UP),
+                "list", deviceList
+        );
+    }
+
+    /** 调试接口: 查看eq_kwh表中的数据概况 */
+    public Map<String, Object> debugEqKwhInfo() {
+        // 总记录数
+        Long totalCount = jdbcTemplate.queryForObject(
+                "SELECT COUNT(*) FROM " + eqKwhTableName + " WHERE corp_code = ?", Long.class, energyCorpCode);
+
+        // 按日期分组统计
+        List<Map<String, Object>> dateStats = jdbcTemplate.queryForList(
+                "SELECT use_date, COUNT(*) as cnt FROM " + eqKwhTableName +
+                        " WHERE corp_code = ? GROUP BY use_date ORDER BY use_date DESC LIMIT 20",
+                energyCorpCode);
+
+        // 按设备分组统计
+        List<Map<String, Object>> deviceStats = jdbcTemplate.queryForList(
+                "SELECT dtuSn, COUNT(*) as cnt FROM " + eqKwhTableName +
+                        " WHERE corp_code = ? GROUP BY dtuSn ORDER BY dtuSn",
+                energyCorpCode);
+
+        // 最新一条记录的 description 预览
+        Map<String, Object> lastRecord = null;
+        try {
+            String sql = "SELECT dtuSn, use_date, LEFT(description, 500) AS desc_preview, LENGTH(description) as desc_len " +
+                    "FROM " + eqKwhTableName + " WHERE corp_code = ? ORDER BY use_date DESC LIMIT 1";
+            lastRecord = jdbcTemplate.queryForMap(sql, energyCorpCode);
+        } catch (Exception ignored) {}
+
+        // energy 表设备数
+        Long deviceCount = jdbcTemplate.queryForObject(
+                "SELECT COUNT(*) FROM " + energyTableName + " WHERE corp_code = ?", Long.class, energyCorpCode);
+
+        return Map.of(
+                "code", 200, "msg", "请求成功",
+                "tableName", eqKwhTableName,
+                "corpCode", energyCorpCode,
+                "totalRecords", totalCount != null ? totalCount : 0,
+                "deviceCountInEnergyTable", deviceCount != null ? deviceCount : 0,
+                "latestDateRecords", dateStats,
+                "perDeviceRecordCount", deviceStats,
+                "lastRecordPreview", lastRecord
+        );
+    }
 }