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

yeg

2026-09-29 b78295e8da96c3e5e76befeef9582ce5273dbb74

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

@@ -10,6 +10,7 @@
import com.battery.device.api.model.ChannelIdentity;
import com.battery.device.api.model.DetectedChannel;
import com.battery.device.api.model.DeviceObservation;
import com.battery.device.api.registry.AdapterRegistryException;
import com.battery.device.api.registry.DeviceAdapterRegistry;

/**
@@ -36,12 +37,14 @@
        this.registry = registry;
    }

    /** 返回聚合路由的固定编码，仅用于说明"按通道身份路由"，不是任何来源实例的编码。 */
    @Override
    public String adapterCode()
    {
        return ADAPTER_CODE;
    }

    /** 返回聚合适配器声明的能力：只观测，不提供控制能力。 */
    @Override
    public AdapterCapabilities capabilities()
    {
@@ -77,12 +80,27 @@
        return grouped;
    }

    /**
     * 按通道所属来源实例请求该通道最近一次实时观测。
     *
     * @param channel 检测柜通道身份，其中的适配器编码决定请求送到哪个实例
     * @return 最近一次实时观测；没有成功观测时为空
     * @throws AdapterRegistryException 该通道所属的实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public CabinetRealtime latestCabinet(ChannelIdentity channel)
    {
        return registry.executeTestData(channel.adapterCode(), adapter -> adapter.latestCabinet(channel));
    }

    /**
     * 按来源实例请求采集器的辅助测量快照。
     *
     * @param adapterCode   来源实例编码；为空表示来源未知，直接返回空值而不猜也不回退
     * @param collectorCode 采集器编码
     * @return 采集器实时快照；来源未知时为空
     * @throws AdapterRegistryException 来源实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public CollectorRealtime latestCollector(String adapterCode, String collectorCode)
    {
@@ -92,36 +110,79 @@
        return registry.executeTestData(adapterCode, adapter -> adapter.latestCollector(adapterCode, collectorCode));
    }

    /**
     * 按通道所属来源实例请求设备直接提供的工步统计。
     *
     * @param channel 检测柜通道身份
     * @return 该通道的设备工步统计；设备未提供时为空列表
     * @throws AdapterRegistryException 该通道所属的实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public List<StepRecord> stepRecords(ChannelIdentity channel)
    {
        return registry.executeTestData(channel.adapterCode(), adapter -> adapter.stepRecords(channel));
    }

    /**
     * 按通道所属来源实例请求循环统计，来源类别由实例写在记录上。
     *
     * @param channel 检测柜通道身份
     * @return 该通道的循环统计；设备未提供且无法聚合时为空列表
     * @throws AdapterRegistryException 该通道所属的实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public List<CycleRecord> cycleRecords(ChannelIdentity channel)
    {
        return registry.executeTestData(channel.adapterCode(), adapter -> adapter.cycleRecords(channel));
    }

    /**
     * 按通道所属来源实例取该来源定义的实时持久化槽位间隔。
     *
     * @param channel 检测柜通道身份
     * @return 持久化槽位间隔，单位毫秒
     * @throws AdapterRegistryException 该通道所属的实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public long persistenceIntervalMillis(ChannelIdentity channel)
    {
        return registry.executeTestData(channel.adapterCode(), adapter -> adapter.persistenceIntervalMillis(channel));
    }

    /**
     * 按通道所属来源实例取设备计划方案，只用于实时展示。
     *
     * @param channel 检测柜通道身份
     * @return 设备计划方案；设备未提供时为空
     * @throws AdapterRegistryException 该通道所属的实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public TestPlan testPlan(ChannelIdentity channel)
    {
        return registry.executeTestData(channel.adapterCode(), adapter -> adapter.testPlan(channel));
    }

    /**
     * 按通道所属来源实例读取接收水位，用于把开始接收与继续接收切在这一时刻之后。
     *
     * @param channel 检测柜通道身份
     * @return 通道当前接收水位；来源不按设备数据行接收时为空
     * @throws AdapterRegistryException 该通道所属的实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public SampleWatermark currentWatermark(ChannelIdentity channel)
    {
        return registry.executeTestData(channel.adapterCode(), adapter -> adapter.currentWatermark(channel));
    }

    /**
     * 按通道所属来源实例读取严格晚于水位的数据行，同秒多行各自成立、不按秒合并。
     *
     * @param channel   检测柜通道身份
     * @param watermark 上次取得的水位；为空表示尚未取水位，此时返回空列表而不并入设备历史
     * @return 水位之后的设备数据行，按设备时间与协议序号升序
     * @throws AdapterRegistryException 该通道所属的实例未启用，或实例未提供测试数据观测契约
     */
    @Override
    public List<CabinetRealtime> samplesSince(ChannelIdentity channel, SampleWatermark watermark)
    {