docs(device): document adapter service contracts

yeg

2026-08-26 a9e3435464f86a50ffa81a16ef92e47734adef6e

 ruoyi-device/src/main/java/com/ruoyi/device/bts/BtsXmlCodec.java

@@ -104,7 +104,7 @@
    public List<DetectedChannel> parseDeviceInfo(String xml)
    {
        Document document = parse(xml, "getdevinfo_resp");
        NodeList nodes = document.getElementsByTagName("channel");
        NodeList nodes = firstElement(document, "middle").getElementsByTagName("channel");
        List<DetectedChannel> channels = new ArrayList<>(nodes.getLength());
        for (int i = 0; i < nodes.getLength(); i++)
        {
@@ -121,7 +121,7 @@
    public Map<ChannelIdentity, RealtimeSnapshot> parseSnapshots(String xml, Instant receivedAt)
    {
        Document document = parse(xml, "inquire_resp");
        NodeList nodes = document.getElementsByTagName("inquire");
        NodeList nodes = firstElement(document, "list").getElementsByTagName("inquire");
        Map<ChannelIdentity, RealtimeSnapshot> snapshots = new LinkedHashMap<>();
        for (int i = 0; i < nodes.getLength(); i++)
        {
@@ -148,7 +148,7 @@
    public List<HistoryAvailability> parseHistoryAvailability(String xml)
    {
        Document document = parse(xml, "inquiredf_resp");
        NodeList nodes = document.getElementsByTagName("chl");
        NodeList nodes = firstElement(document, "list").getElementsByTagName("chl");
        List<HistoryAvailability> availability = new ArrayList<>(nodes.getLength());
        for (int i = 0; i < nodes.getLength(); i++)
        {
@@ -167,6 +167,7 @@
        Document document = parse(xml, "download_resp");
        Element download = firstElement(document, "download");
        String btsTestId = requiredAttribute(download, "testid");
        // download 是单通道响应，身份不一致时拒绝结果，避免历史事实被归入错误测试。
        if (integerAttribute(download, "devtype") != channel.devtype()
                || integerAttribute(download, "devid") != channel.devid()
                || integerAttribute(download, "subdevid") != channel.subdevid()
@@ -174,7 +175,7 @@
                || !btsTestId.equals(requestedTestId))
            throw new BtsProtocolException(BtsProtocolException.Reason.IDENTITY_MISMATCH,
                    "BTS history response identity does not match the request");
        NodeList nodes = document.getElementsByTagName("data");
        NodeList nodes = firstElement(document, "list").getElementsByTagName("data");
        List<HistorySample> samples = new ArrayList<>(nodes.getLength());
        long next = requestedStart;
        for (int i = 0; i < nodes.getLength(); i++)
@@ -186,6 +187,7 @@
                    requiredAttribute(element, "steptype"), optionalLong(element, "testtime"), parseDeviceTime(rawTime), rawTime,
                    optionalDecimal(element, "volt"), optionalDecimal(element, "curr"), optionalDecimal(element, "cap"),
                    optionalDecimal(element, "eng"), dynamicMeasurements(element, HISTORY_ATTRIBUTES)));
            // 解析层保留重复和乱序事实；完整性检查按 seqid 另行判定并解释缺口。
            next = Math.max(next, sequence + 1);
        }
        return new HistoryPage(channel, btsTestId, requestedStart, next, samples);
@@ -251,6 +253,7 @@
    {
        try
        {
            // BTS 时间不带时区，按适配器配置的现场时区解释后统一转换为 UTC 时间点。
            return LocalDateTime.parse(value, BTS_TIME).atZone(deviceZone).toInstant();
        }
        catch (DateTimeParseException ex)