按代码规范检查整改实体注释、Service Javadoc 与分层边界

yeg

2026-09-29 b78295e8da96c3e5e76befeef9582ce5273dbb74

 battery-business/src/main/java/com/battery/business/service/impl/TestDataQueryServiceImpl.java

@@ -1,6 +1,8 @@
package com.battery.business.service.impl;

import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.util.Date;
import java.util.List;
import java.util.Map;
@@ -19,14 +21,21 @@
    public TestDataQueryServiceImpl(TTestMapper mapper, ITTestService tests)
    { this.mapper = mapper; this.tests = tests; }

    /** 查询实时槽位，保留检测柜和采集器各自的设备时间。 */
    /** 查询尚存实时采样与授权历史导入记录，保留检测柜和采集器各自的设备时间。 */
    @Override public List<Map<String, Object>> records(Long testId)
    {
        tests.selectTestById(testId);
        return normalizeApiTimes(mapper.selectPersistedFinalRealtimeRecords(testId));
        List<Map<String, Object>> rows = normalizeApiTimes(mapper.selectPersistedFinalRealtimeRecords(testId));
        for (Map<String, Object> row : rows)
        {
            Object extension = row.get("extensionMeasurementsJson");
            if (extension != null) row.put("relativeTimeSeconds",
                    com.alibaba.fastjson2.JSON.parseObject(extension.toString()).get("relativeTimeSeconds"));
        }
        return rows;
    }

    /** 查询设备实际提供且尚存的工步记录。 */
    /** 查询尚存工步记录，包含设备统计与授权历史导入。 */
    @Override public List<Map<String, Object>> steps(Long testId)
    {
        tests.selectTestById(testId);
@@ -36,13 +45,16 @@
            Object extension = row.get("extensionMeasurementsJson");
            if (extension == null) continue;
            Map<String, Object> values = com.alibaba.fastjson2.JSON.parseObject(extension.toString());
            for (String field : List.of("stepDuration", "startVoltage", "chargePeakVoltage", "dischargeValleyVoltage"))
            // 中值与历史峰谷值是不同测量，不将旧扩展字段回退映射为中值。
            // 四组容量能量是设备工步层事实：单项列无法表达未确认方向时，调用方读这四组核对。
            for (String field : List.of("stepDuration", "startVoltage", "chargeMedianVoltage", "dischargeMedianVoltage",
                    "chargeCapacity", "dischargeCapacity", "chargeEnergy", "dischargeEnergy"))
                if (values.containsKey(field)) row.put(field, values.get(field));
        }
        return rows;
    }

    /** 查询设备实际提供且尚存的循环记录。 */
    /** 查询尚存循环记录，包含设备统计、工步层聚合与授权历史导入；携带来源类别供界面标注聚合来源。 */
    @Override public List<Map<String, Object>> cycles(Long testId)
    {
        tests.selectTestById(testId);
@@ -52,9 +64,11 @@
    private List<Map<String, Object>> normalizeApiTimes(List<Map<String, Object>> rows)
    {
        if (rows == null) return List.of();
        // DATETIME(3) 保存 UTC，JDBC 返回的无时区值也必须按 UTC 转换，不能采用服务器默认时区。
        for (Map<String, Object> row : rows)
            row.replaceAll((key, value) -> value instanceof Date date ? date.getTime()
                    : value instanceof Instant instant ? instant.toEpochMilli() : value);
                    : value instanceof Instant instant ? instant.toEpochMilli()
                    : value instanceof LocalDateTime time ? time.toInstant(ZoneOffset.UTC).toEpochMilli() : value);
        return rows;
    }
}