City-Lifeline-Cockpit/src/modules/cockpit/domain/monitoringPanels.js

/**
 * 运行监测模式四个二级面板的**领域与视图层**（票 18）。
 *
 * 四块面板：监测概览 `monitoringOverview` / 监测分布 `monitoringDistribution` /
 * 运行概况 `operationOverview` / 监测点台账 `monitoringPointLedger`。
 *
 * 分工与票 17 完全一致（本票沿用同一形状，不造第二套）：
 *   1. **契约适配**：后端三个面板级聚合读模型的载荷 → 领域对象（字段改名、缺失记账、码翻人话）；
 *   2. **视图计划**：领域对象 → 组件可以直接画的块。
 *   块的构造与码表在 `domain/panelBlocks.js`（票 18 从票 17 提出来共用），本文件只写"放哪些块"。
 *
 * 纯函数：不 import service、不碰 DOM、不自己发请求。
 *
 * 「入库时间」只认 createdAt（源记录 create_time），不使用 updatedAt 或 sampledAt 兜底。
 * 全部时间类措辞取自 `fields.js` 的 `TIME_LABELS`（票 62 的唯一词表），本文件不另写一版。
 * 点位状态中文来自 pointStatus；片区只消费正式 district 编码，空值显未分区。
 * 监测概览/运行概况不接收片区筛选，监测分布接收 district。
 *
 * 后端形状依据（`E:\pipe-ner-server`，逐类读过响应类、控制器与服务）：
 *   `CockpitMonitoringOverviewResponse` / `...DistributionResponse` / `...SituationResponse`、
 *   `CockpitMonitoringOverviewController` / `...DistributionController` / `...SituationController`、
 *   服务 `CockpitMonitoring{Overview,Distribution,Situation}Service`，
 *   演示载荷 `docs/cockpit/monitoring-{overview,distribution,operating-situation}-demo.html`。
 *   BigDecimal 在线上是字符串（`"0.32"`），所以走 `panelBlocks.js` 的 `numberish`。
 */
import { fieldReader, TIME_LABELS } from './fields.js'
import { DETAIL_PLACEHOLDER } from './detailFlow.js'
import { valueText } from './equipmentDetailView.js'
import { industryLabel, normalizeDistrict, districtLabel, districtFilterLabel } from './filterOptions.js'
import { legendVisuals, visualForStatus } from './pointStatus.js'
import { planStatusPie } from './statusPie.js'
import { abnormalCountRows } from './abnormalCounts.js'
import {
    barsBlock,
    CARD_ACTION,
    codeText,
    donutBlock,
    kpiBlock,
    listBlock,
    numberish,
    panelMissingNote,
    ratioText,
    regionText,
    rowsBlock,
    stackedBlock,
    supplementalBlock,
    sectionHasContent,
    sectionPlaceholder,
    sortByCountDesc,
    trendBlock,
} from './panelBlocks.js'

/** 运行监测模式的四个 panelId（与 `domain/panelCatalog.js` 的目录一致，顺序即界面顺序）。 */
export const MONITORING_PANEL_IDS = [
    'monitoringOverview',
    'monitoringDistribution',
    'operationOverview',
    'monitoringPointLedger',
]

/**
 * 指标状态码 → 人话（契约手册第 2 节冻结的六态：NORMAL/WARNING/ALARM/EXPIRED/OFFLINE/UNKNOWN）。
 *
 * 为什么自带一张而不是并进 `CODE_TEXT`：这六个词是**运行监测专用**的指标状态字典
 * （手册原句「运行监测专用，`EXPIRED` 不与 `OFFLINE` 合并」），而 `CODE_TEXT` 里
 * `EXPIRED` 属于新鲜度字典。两张字典在契约里就是两张，合成一张会让「指标过期」与
 * 「数据过期」共用措辞而看不出区别。六个取值**全部**登记，认不出的回原码。
 */
export const METRIC_STATUS_TEXT = {
    NORMAL: '正常',
    WARNING: '预警',
    ALARM: '报警',
    EXPIRED: '过期',
    OFFLINE: '离线',
    UNKNOWN: '未发布',
}

/** 后端 `abnormalType` 与 `status` 在响应里取的是同一个值（服务逐行读过），所以只翻一份。 */
export function metricStatusText(code) {
    const value = typeof code === 'string' ? code.trim() : ''
    if (!value) return '未知'
    return METRIC_STATUS_TEXT[value] || value
}

/** 入库时间与设备采样时间的语义说明（票 62：随唯一词表改名，措辞同步）。三种时间彼此不同：入库时间（createdAt，源记录写库时刻）／采样时间（sampledAt，设备采集时刻）／快照时间（信封 updatedAt，后端快照生成时刻）。 */
export const METRIC_FRESHNESS_GAP =
    `${TIME_LABELS.latestIngested}＝源记录写库时刻，不是设备采样时刻；缺失时显示占位符「—」，不使用接口响应或快照时间代替`

/**
 * 全局状态分布**未取到**时的如实说明（票 14；决策 02：状态栏与饼图共用同一份
 * 全局未筛分布，数据源是 `map-snapshot` 的八桶全局计数）。缺失时不伪造全零饼图。
 */
export const STATUS_DISTRIBUTION_UNPUBLISHED =
    '全局状态分布未取到（后端尚未发布八桶全局计数）；顶部状态栏与本饼图共用同一份数据，发布前两者都不显示计数'

/** 八桶 → 人话（来自票 09 的唯一一张表；含 UNKNOWN「状态未发布」与 UNASSOCIATED「无关联设备」）。 */
const POINT_STATUS_FILTER_LABELS = Object.fromEntries(legendVisuals().map((visual) => [visual.key, visual.label]))

/** 范围（区域）筛选的落点说明：三个端点里只有监测分布收 `region`。 */
export const REGION_SCOPE_NOTE = '片区筛选按后端片区编码作用于监测分布'

// 井盖（`MANHOLE`）**已可筛选**（票 18 实施时的缺口已由后端关闭）：
// 它现已是第四个正式行业，且全部 11 个 cockpit 服务都收（含 `map-snapshot`）。
// 映射已接上（`domain/filterOptions.js` 的 `INDUSTRY_CODES.manhole`），
// 因此本模块**不再有**「井盖无契约位」这条缺口常量 —— 曾用名 `MANHOLE_INDUSTRY_GAP` 已删除。

// ================================================================ 契约适配

/**
 * 监测概览（`/monitoring/overview`）→ 领域对象。
 * 票 18 验收第 1 条：监测点/设备规模、在线率、类型分布和最近采集时间。
 *
 * 端点入参只有 `industry` 与 `deviceType`（控制器逐行读过）——
 * **不收 `region`，也不收 `pointStatus`**，所以本面板的筛选面就是行业 + 类型。
 *
 * 票 62 追加需求：本端点还回出**逐设备台账** `devices[]`（与 `counts.equipmentCount`
 * 同源同口径，行数恒等于该计数）。运行概况面板的「设备台账」清单读的就是这一份 ——
 * 它替代了原先借用 `/monitoring/situation`「异常设备清单」的做法：那张清单只装异常四态
 * 设备（WARNING/ALARM/EXPIRED/OFFLINE），既不是台账、条数也与设备总数对不上。
 */
export function toMonitoringOverview(raw) {
    const reader = fieldReader(raw, 'monitoringOverview')
    const counts = fieldReader(reader.raw.counts, 'monitoringOverview.counts')
    const status = fieldReader(reader.raw.status, 'monitoringOverview.status')
    const onlineRate = fieldReader(reader.raw.onlineRate, 'monitoringOverview.onlineRate')
    const freshness = fieldReader(reader.raw.freshness, 'monitoringOverview.freshness')
    const mapFilter = reader.optionalObj('mapFilter') || {}

    return {
        createdAt: reader.optionalStr('createdAt'),
        updatedAt: reader.optionalStr('updatedAt'),
        rangeType: (reader.optionalObj('range') || {}).type || '',
        // 规模
        monitoringPointCount: numberish(counts.raw.monitoringPointCount),
        equipmentCount: numberish(counts.raw.equipmentCount),
        facilityCount: numberish(counts.raw.facilityCount),
        infrastructureFacilityCount: numberish(counts.raw.infrastructureFacilityCount),
        // 在线率：`value` 是 0–1 的小数（后端 BigDecimal），`state` 为 EMPTY 时表示分母为 0。
        onlineRate: numberish(onlineRate.raw.value),
        onlineCount: numberish(onlineRate.raw.numerator),
        onlineDenominator: numberish(onlineRate.raw.denominator),
        onlineState: onlineRate.optionalStr('state'),
        // 设备在线/离线/滞后/未知四态 + 口径分母（后端 `Status`）。
        deviceStatus: {
            online: numberish(status.raw.onlineCount),
            offline: numberish(status.raw.offlineCount),
            stale: numberish(status.raw.staleCount),
            unknownOrMissing: numberish(status.raw.unknownOrMissingCount),
            denominator: numberish(status.raw.denominator),
        },
        // 类型分布：后端已按 deviceCount 降序排好（服务里排序），本层不重排。
        typeDistribution: reader.optionalList('typeDistribution').map((item) => {
            const row = fieldReader(item, 'typeDistribution')
            const type = fieldReader(row.raw.deviceType, 'typeDistribution.deviceType')
            return {
                code: type.optionalStr('code'),
                name: type.optionalStr('name') || type.optionalStr('code'),
                industry: row.optionalStr('industry'),
                deviceCount: numberish(row.raw.deviceCount),
                onlineCount: numberish(row.raw.onlineCount),
                offlineCount: numberish(row.raw.offlineCount),
                staleCount: numberish(row.raw.staleCount),
            }
        }),
        // 票 62 追加需求：逐设备台账（行数恒等于 `equipmentCount`，与上面那个计数同源）。
        devices: reader.optionalList('devices').map(toLedgerDevice),
        // 新鲜度：本端点只有信封级（见文件头第 ① 条）。
        freshness: freshness.optionalStr('status'),
        freshUpdatedAt: freshness.optionalStr('updatedAt'),
        serverUpdatedAt: freshness.optionalStr('serverUpdatedAt'),
        selectedIndustry: mapFilter.industry || '',
        selectedDeviceType: mapFilter.deviceType || '',
        // 口径剔除（后端解释"为什么这些设备没算进来"，界面照实说明）。
        excluded: {
            unknownTypeCount: numberish((reader.raw.excluded || {}).unknownTypeCount),
            typeKindMismatchCount: numberish((reader.raw.excluded || {}).typeKindMismatchCount),
            nonFormalIndustryCount: numberish((reader.raw.excluded || {}).nonFormalIndustryCount),
        },
        missing: reader.missing,
    }
}

/** 分布行（区域/行业/设备类型三族共用同一个 `StatusCounts` 结构）→ 领域行。 */
function toStatusCounts(raw) {
    const reader = fieldReader(raw, 'statusCounts')
    return {
        alarm: numberish(reader.raw.alarm),
        warning: numberish(reader.raw.warning),
        workOrder: numberish(reader.raw.workOrder),
        normal: numberish(reader.raw.normal),
        offline: numberish(reader.raw.offline),
        empty: numberish(reader.raw.empty),
    }
}

/**
 * 监测分布的一个地图标记 → 领域行。
 *
 * **注意本端点不给设备编码列表**（那是 `/map-snapshot` 的 `CockpitMonitoringPointSummary.deviceCodes`），
 * 所以台账卡片的设备徽标只能逐点位拉详情（票 18 的 Q10 裁定），不由本层伪造。
 */
function toDistributionMarker(raw, kind) {
    const reader = fieldReader(raw, kind)
    const type = fieldReader(reader.raw.deviceType, `${kind}.deviceType`)
    return {
        kind,
        code: reader.optionalStr('pointCode') || reader.optionalStr('deviceCode'),
        name: reader.optionalStr('pointName') || reader.optionalStr('deviceName') || reader.optionalStr('deviceCode'),
        district: normalizeDistrict(reader.raw.district),
        createdAt: reader.optionalStr('createdAt'),
        industry: reader.optionalStr('industry'),
        typeCode: type.optionalStr('code'),
        typeName: type.optionalStr('name'),
        status: reader.optionalStr('pointStatus'),
        statusReasons: reader.optionalList('statusReasons').map((item) => String(item)),
        longitude: numberish(reader.raw.longitude),
        latitude: numberish(reader.raw.latitude),
        missing: reader.missing,
    }
}

/**
 * 监测分布（`/monitoring/distribution`）→ 领域对象。
 * 票 18 验收第 2 条：覆盖情况、状态分布和地图筛选。
 * 验收第 4 条的台账**共用这一次取数**（Q4 裁定）——它读同一个响应的 `monitoringPoints` 与 `pagination`。
 *
 * 三处后端语义（逐行读服务确认，不是猜的）：
 *   · 三份分布与状态计数是**全量口径**（服务先把全部 marker 聚合完再切片分页），
 *     所以它们不随翻页跳动 —— 面板报的是全城分布，不是"这一页的分布"；
 *   · 分页窗口横跨「监测点 + 未关联设备」一条总序列（与 `map-snapshot` 同一套语义）；
 *   · `region` 空值在响应里归一为字面量 `未分区`（是真实取值，不是空值）。
 */
export function toMonitoringDistribution(raw) {
    const reader = fieldReader(raw, 'monitoringDistribution')
    const pagination = fieldReader(reader.raw.pagination, 'monitoringDistribution.pagination')
    const freshness = fieldReader(reader.raw.freshness, 'monitoringDistribution.freshness')
    const mapFilter = reader.optionalObj('mapFilter') || {}

    const regionRows = reader.optionalList('districtDistribution').map((item) => {
        const row = fieldReader(item, 'districtDistribution')
        return {
            code: normalizeDistrict(row.raw.district),
            pointCount: numberish(row.raw.pointCount) || 0,
            deviceCount: numberish(row.raw.deviceCount) || 0,
            statusCounts: toStatusCounts(row.raw.statusCounts),
        }
    })
    const industryRows = reader.optionalList('industryDistribution').map((item) => {
        const row = fieldReader(item, 'industryDistribution')
        return {
            code: row.optionalStr('industry'),
            pointCount: numberish(row.raw.pointCount) || 0,
            deviceCount: numberish(row.raw.deviceCount) || 0,
            statusCounts: toStatusCounts(row.raw.statusCounts),
        }
    })
    const typeRows = reader.optionalList('deviceTypeDistribution').map((item) => {
        const row = fieldReader(item, 'deviceTypeDistribution')
        const type = fieldReader(row.raw.deviceType, 'deviceTypeDistribution.deviceType')
        return {
            code: type.optionalStr('code'),
            name: type.optionalStr('name') || type.optionalStr('code'),
            industry: row.optionalStr('industry'),
            pointCount: numberish(row.raw.pointCount) || 0,
            deviceCount: numberish(row.raw.deviceCount) || 0,
            statusCounts: toStatusCounts(row.raw.statusCounts),
        }
    })

    return {
        createdAt: reader.optionalStr('createdAt'),
        updatedAt: reader.optionalStr('updatedAt'),
        // 票 62：快照标记（执行票同期由后端补齐回显）。台账自动链第 2 页起必须原样回带它，
        // 否则后端 400；token 只认后端回显，不由前端挑时间戳去猜。
        snapshotAt: reader.optionalStr('snapshotAt'),
        freshUpdatedAt: freshness.optionalStr('updatedAt'),
        freshness: freshness.optionalStr('status'),
        regions: regionRows,
        industries: industryRows,
        deviceTypes: typeRows,
        // 状态分布：后端按字典顺序给全部六个状态（含计数为 0 的，界面据此不丢行）。
        pointStatuses: reader.optionalList('pointStatusDistribution').map((item) => {
            const row = fieldReader(item, 'pointStatusDistribution')
            return { status: row.optionalStr('status'), count: numberish(row.raw.count) || 0 }
        }),
        // 台账（Q4：与分布共用这次取数）
        points: reader.optionalList('monitoringPoints').map((item) => toDistributionMarker(item, 'monitoringPoint')),
        equipment: reader.optionalList('unassociatedEquipment').map((item) => toDistributionMarker(item, 'unassociatedEquipment')),
        pagination: {
            page: numberish(pagination.raw.page),
            pageSize: numberish(pagination.raw.pageSize),
            total: numberish(pagination.raw.total),
            totalPages: numberish(pagination.raw.totalPages),
            hasMore: pagination.bool('hasMore', false),
        },
        // 生效范围回显（Q3：筛选入口只有全局筛选条，面板靠这段回显，不自己存一份筛选状态）。
        selectedIndustry: mapFilter.industry || '',
        selectedDeviceType: mapFilter.deviceType || '',
        selectedPointStatus: mapFilter.pointStatus || '',
        selectedDistrict: normalizeDistrict(mapFilter.district),
        districtFilter: mapFilter.districtFilter || '',
        excluded: {
            unknownTypeCount: numberish((reader.raw.excluded || {}).unknownTypeCount),
            typeKindMismatchCount: numberish((reader.raw.excluded || {}).typeKindMismatchCount),
            nonFormalIndustryCount: numberish((reader.raw.excluded || {}).nonFormalIndustryCount),
            invalidCoordinateCount: numberish((reader.raw.excluded || {}).invalidCoordinateCount),
        },
        missing: reader.missing,
    }
}

/** 一个异常设备 → 领域行（`abnormalType` 与 `status` 后端取同值，只留一个）。 */
function toAbnormalEquipment(raw) {
    const reader = fieldReader(raw, 'abnormalEquipment')
    const type = fieldReader(reader.raw.deviceType, 'abnormalEquipment.deviceType')
    return {
        // 设备编码（不是点位编码）：本端点逐行给的是设备维度。
        code: reader.optionalStr('deviceCode'),
        name: reader.optionalStr('deviceName') || reader.optionalStr('deviceCode'),
        typeCode: type.optionalStr('code'),
        typeName: type.optionalStr('name'),
        industry: reader.optionalStr('industry'),
        district: normalizeDistrict(reader.raw.district),
        createdAt: reader.optionalStr('createdAt'),
        status: reader.optionalStr('status'),
        statusReasons: reader.optionalList('statusReasons').map((item) => String(item)),
        longitude: numberish(reader.raw.longitude),
        latitude: numberish(reader.raw.latitude),
        missing: reader.missing,
    }
}

/** 趋势点 → 领域行；桶标签由 `bucketLabel()` 给人话，原始值留在 `key` 里供断言。 */
function toTrendPoint(raw) {
    const reader = fieldReader(raw, 'trendPoint')
    return { bucket: reader.optionalStr('bucketStart'), count: numberish(reader.raw.count) || 0 }
}

/**
 * ISO 时间戳 → 趋势桶的短标签（给人读；解析不了就回原串，不丢桶）。
 *
 * 后端桶是业务时区（Asia/Shanghai）的整点/整日 ISO 串，含偏移量。
 * 本函数**只做截断显示**，不改桶的粒度、不重采样、不补点 —— 那是后端语义。
 * @param {string} bucketStart ISO-8601 时间戳
 * @param {boolean} daily 桶是否为「日」粒度（7 天窗口用）
 */
export function bucketLabel(bucketStart, daily = false) {
    const value = typeof bucketStart === 'string' ? bucketStart : ''
    const matched = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})/.exec(value)
    if (!matched) return value
    const [, , month, day, hour, minute] = matched
    if (daily) return `${Number(month)}/${Number(day)}`
    return `${hour}:${minute}`
}

/**
 * 运行概况（`/monitoring/situation`）→ 领域对象。
 * 票 18 验收第 3 条：事件趋势、离线设备和异常态势。
 *
 * 端点语义（逐行读服务确认）：
 *   · 不传 `startTime`/`endTime` 时后端默认**最近 24 小时**、按小时分桶，上限 31 天；
 *   · **预警与报警两条趋势永不混合**（服务注释原句：warnings feed warningTrend only,
 *     alarms feed alarmTrend only），所以本层给两块，不自己加总成一条；
 *   · `abnormalEquipment` 是**异常设备清单**（服务定义：WARNING/ALARM/EXPIRED/OFFLINE 四态），
 *     离线设备是它的一个子集 —— 界面据此分开说"离线多少台"与"异常清单里有什么"。
 */
export function toMonitoringSituation(raw) {
    const reader = fieldReader(raw, 'monitoringSituation')
    const pagination = fieldReader(reader.raw.pagination, 'monitoringSituation.pagination')
    const freshness = fieldReader(reader.raw.freshness, 'monitoringSituation.freshness')
    const range = reader.optionalObj('range') || {}

    // 指标状态分布：后端按固定字典顺序给六态（含 0），本层不重排、不丢行。
    // 票 92：「整个分布没取到」≠「某一桶是 0」——前者六档全缺（count 为 null，界面画占位符），
    // 后者该档照实计 0（六态全铺是既有口径）。混在一起就是「没数据」被画成「0 台设备」。
    const distributionProvided = Array.isArray(reader.raw.metricStatusDistribution)
    const metricStatusMap = new Map(reader.optionalList('metricStatusDistribution').map((item) => {
        const row = fieldReader(item, 'metricStatusDistribution')
        return [row.optionalStr('status'), numberish(row.raw.count) ?? 0]
    }))
    const metricStatuses = ['NORMAL', 'WARNING', 'ALARM', 'EXPIRED', 'OFFLINE', 'UNKNOWN']
        .map((status) => ({ status, count: distributionProvided ? (metricStatusMap.get(status) ?? 0) : null }))

    const coverage = reader.optionalList('industryCoverage').map((item) => {
        const row = fieldReader(item, 'industryCoverage')
        return {
            code: row.optionalStr('industry'),
            deviceCount: numberish(row.raw.deviceCount) || 0,
            abnormalCount: numberish(row.raw.abnormalCount) || 0,
            statusCounts: toStatusCounts(row.raw.statusCounts),
        }
    })

    return {
        createdAt: reader.optionalStr('createdAt'),
        updatedAt: reader.optionalStr('updatedAt'),
        freshUpdatedAt: freshness.optionalStr('updatedAt'),
        freshness: freshness.optionalStr('status'),
        // 窗口：后端回显实际生效区间（不传时是最近 24 小时，`type` 为 `TREND_WINDOW`）。
        rangeType: range.type || '',
        rangeStart: range.startTime || '',
        rangeEnd: range.endTime || '',
        metricStatuses,
        warningTrend: reader.optionalList('warningTrend').map(toTrendPoint),
        alarmTrend: reader.optionalList('alarmTrend').map(toTrendPoint),
        coverage,
        abnormalEquipment: reader.optionalList('abnormalEquipment').map(toAbnormalEquipment),
        pagination: {
            page: numberish(pagination.raw.page),
            pageSize: numberish(pagination.raw.pageSize),
            total: numberish(pagination.raw.total),
            totalPages: numberish(pagination.raw.totalPages),
            hasMore: pagination.bool('hasMore', false),
        },
        selectedIndustry: (reader.optionalObj('mapFilter') || {}).industry || '',
        selectedDeviceType: (reader.optionalObj('mapFilter') || {}).deviceType || '',
        excluded: {
            unknownTypeCount: numberish((reader.raw.excluded || {}).unknownTypeCount),
            typeKindMismatchCount: numberish((reader.raw.excluded || {}).typeKindMismatchCount),
            nonFormalIndustryCount: numberish((reader.raw.excluded || {}).nonFormalIndustryCount),
            invalidCoordinateCount: numberish((reader.raw.excluded || {}).invalidCoordinateCount),
        },
        missing: reader.missing,
    }
}

// ================================================================ 视图计划

/**
 * 逐设备台账行（`/monitoring/overview` 的 `devices[]`）→ 领域行（票 62 追加需求）。
 * 与 `toAbnormalEquipment` 刻意分开：那张是**异常口径**（四态 + 阈值事由），
 * 这张是**设备台账**（全部智能设备 + 监测状态 + 所属点位），两者不可互换。
 */
function toLedgerDevice(raw) {
    const reader = fieldReader(raw, 'overviewDevice')
    const type = fieldReader(reader.raw.deviceType, 'overviewDevice.deviceType')
    return {
        // 设备编码（不是点位编码）：本清单是**设备**台账。
        code: reader.optionalStr('deviceCode'),
        name: reader.optionalStr('deviceName'),
        typeCode: type.optionalStr('code'),
        typeName: type.optionalStr('name'),
        industry: reader.optionalStr('industry'),
        // 监测状态（后端五态之一）；缺失留空，视图层按「未发布」如实说（不猜成正常）。
        status: reader.optionalStr('monitoringState'),
        pointCode: reader.optionalStr('monitoringPointCode'),
        sampledAt: reader.optionalStr('sampledAt'),
        createdAt: reader.optionalStr('createdAt'),
        missing: reader.missing,
    }
}

/** 该状态在指标状态分布里的计数。 */
function metricCount(statuses, code) {
    const found = (statuses || []).find((row) => row.status === code)
    return found ? found.count : null
}

/**
 * 设备状态四态 → 环形图行（票 39 第 7 条）。
 *
 * **只保留读得出的计数**：`numberish` 认不出回 `null`（字段缺失／载荷形状不对），
 * 而 `donutBlock` 内部按 `Number(count) || 0` 建扇区与图例——把 `null` 交出去就是
 * 画一个「在线 0 台」的假读数（票 27 修的是同一类缺陷：`undefined` 冒充有效值）。
 * 真实的 `0` 是有效读数，照旧保留（图例行在、不产扇区）。
 * 四态一个都没读出来时 `rows` 为空、`total=0`，渲染层走既有空态（`data-donut-empty`），
 * **不会**画一个「合计 0」的空环——「后端没给状态」与「状态全是 0」在界面上分得开。
 * 顺序固定为在线→离线→滞后→未知，**不套 `sortByCountDesc`**（四态是语义字典序，
 * 非排名类别；同异常桶 t44 的 FIXED 立场）。
 */
function deviceStatusRows(deviceStatus) {
    const source = deviceStatus || {}
    return [
        { code: 'online', label: '在线', count: numberish(source.online) },
        { code: 'offline', label: '离线', count: numberish(source.offline) },
        { code: 'stale', label: '数据滞后', count: numberish(source.stale) },
        { code: 'unknownOrMissing', label: '未知/缺失', count: numberish(source.unknownOrMissing) },
    ].filter((row) => row.count !== null)
}

/* 票 92：旧「数据入库时间」KPI（createdAtKpi）已随概览/运行概况的 KPI 改版退役 —— 两处消费点
   都不再展示时间类读数（票面 6 张清单里没有时间卡），按「无消费点不提交」纪律删除。 */
/**
 * 监测概览面板视图。
 * 验收四项：监测点/设备规模、在线率、类型分布、最近采集时间。
 */
export function monitoringOverviewPanel(data, section) {
    const current = data || {}
    const deviceStatus = current.deviceStatus || {}
    // 在线率：分母为 0 时后端回 `state: EMPTY` + `value: 0`，那个 0 是**没有分母时的占位**，
    // 不是"在线率确实是 0"——照它画成 0.0% 就是票 16 明令禁止的虚假零值。所以先按 state 收口。
    const rateAvailable = current.onlineState !== 'EMPTY' && current.onlineDenominator !== null && current.onlineDenominator > 0
    const rate = rateAvailable ? current.onlineRate : null

    const blocks = [
        kpiBlock([
            { key: 'monitoringPointCount', label: '监测点', value: valueText(current.monitoringPointCount), unit: '个' },
            { key: 'equipmentCount', label: '监测设备', value: valueText(current.equipmentCount), unit: '台' },
            {
                key: 'onlineRate',
                label: '在线率',
                value: ratioText(rate),
                // 在线率的分母是后端给的「已解析设备数」，把分子分母摊开说，免得读者自己猜口径；
                // 后端明说没有分母（`EMPTY`）时如实说"没有可算的设备"，不算出一个 0。
                hint: rateAvailable
                    ? `在线 ${valueText(current.onlineCount)} / 设备 ${valueText(current.onlineDenominator)}`
                    : '当前范围内没有可参与计算的设备，在线率不适用',
            },
            // 离线设备：取**本端点自己的设备状态**（status.offlineCount），与运行概况那张卡
            // （来自 /monitoring/situation 的**指标**状态 OFFLINE 档）不是同一口径——
            // 同名词不同义，所以各自卡上把口径说清（维护者 2026-10-27 裁定：第 4 张卡取离线设备）。
            {
                key: 'offline',
                label: '离线设备',
                value: valueText(deviceStatus.offline),
                unit: '台',
                hint: '按设备在线状态统计（本端点口径）',
            },
        ], { layout: 'two-by-two' }),
        // 票 39（第 7 条）：设备状态由纯键值行改**环形图**（复用既有块，不新造渲染分支）。
        //   · 选型按仓库自己记录的图表选型表（`donutBlock` 头注）：「类别占比、类别少」
        //     → 环形图；四态＝4 个互斥类别，且本面板已有一条横条（类型分布）、维护者
        //     2026-10-13 明说「条形图太多易疲劳」——堆叠条仍是一条横条，形态不解疲劳。
        //   · **四态照实**：在线/离线/数据滞后/未知缺失各一行图例带读数，不折算成
        //     「故障」（后端逐设备走 ONLINE/OFFLINE/STALE 判定链，其余落 unknownOrMissing，
        //     四桶互斥且穷尽——`CockpitMonitoringOverviewService` 第 165–175 行，服务逐行读过）。
        //   · 0 计数态**保留图例行不画扇区**（`donutBlock` 既有语义）：「确实没有离线设备」
        //     与「没这项数据」在图上分得开，读数为 0 是真实值。
        //   · 「在线率分母」不再是独立一行：环形合计含「未知/缺失」，而后端在线率
        //     分母＝在线+离线+滞后（**不含**未知/缺失，服务第 185 行）。分母摊在 KPI 的
        //     hint（`在线 X / 设备 Y`）上与在线率同口径；画进图例就是制造第二个口径的数。
        //   · 缺值仍是占位符纪律：四态计数经 `numberish` 认不出回 null → 该行**整行不出**
        //     （见 `deviceStatusRows`），绝不把 null 交给 `donutBlock` 补成假 0（票 27 同类）。
        donutBlock('设备状态分布（按设备数）', deviceStatusRows(deviceStatus), { layout: 'compact' }),
        // 维护者第 15 轮：排行用得太多 —— 设备类型分布改**堆叠条**（一条读出八类各多少与占比），
        // 与下方「各类型在线 / 离线」两张环图形成"总量 → 分状态"的层级。
        stackedBlock(
            '设备类型分布',
            sortByCountDesc(
                (current.typeDistribution || []).map((row) => ({
                    code: row.code,
                    label: row.name || codeText(row.code),
                    count: row.deviceCount || 0,
                })),
                (row) => row.count,
            ),
        ),
        supplementalBlock(donutBlock('各类型在线设备', (current.typeDistribution || [])
            .filter((row) => numberish(row.onlineCount) !== null)
            .map((row) => ({ code: row.code, label: row.name || codeText(row.code), count: row.onlineCount })), { layout: 'compact' })),
        // 与「各类型在线设备」同形态：两张环图并排读"在线 / 离线"的对照（排行反而看不出对照）。
        supplementalBlock(donutBlock('各类型离线设备', (current.typeDistribution || [])
            .filter((row) => numberish(row.offlineCount) !== null)
            .map((row) => ({ code: row.code, label: row.name || codeText(row.code), count: row.offlineCount })), { layout: 'compact' })),
    ]

    return {
        name: 'monitoringOverview',
        label: '监测概览',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        // 概览是聚合口径（后端只给分类型计数，不给逐点位坐标），没有可定位对象。
        locate: [],
        locateNote: '监测概览是分类型聚合口径（后端不返回逐点位坐标），本面板没有可定位对象',
        // 入库时间与采样时间的区别如实说明（文件头第 ① 条 + `TIME_LABELS`）。
        gap: METRIC_FRESHNESS_GAP,
        industryNote: current.selectedIndustry ? `当前行业：${industryLabel(current.selectedIndustry) || current.selectedIndustry}` : '当前行业：全部',
        // 票 37：生效类型必须看得见 —— 否则读者只会看到"类型分布少了几行"，
        // 不知道该条件从哪来、也不知道怎么撤（同一条行再点一次）。
        typeNote: current.selectedDeviceType
            ? `当前类型：${deviceTypeLabel(current.typeDistribution, current.selectedDeviceType)}（再点同一行取消）`
            : '当前类型：全部',
        missing: panelMissingNote(current),
        placeholder: sectionPlaceholder(section),
    }
}

/**
 * 类型码 → 展示名（票 37）。名字优先取自**本端点返回的类型分布**（同一份数据里带着 name，
 * 不另建一份类型词典）；分布里没有该码时用 `codeText` 的既有口径——**数据值照原样带出**，
 * 因为空白会被读成"没有数据"，而"没见过的类型码"是真实数据。
 * @param {Array} rows 类型分布行（含 `code`/`name`）
 * @param {string} code 生效的类型码
 */
function deviceTypeLabel(rows, code) {
    if (!code) return ''
    const found = (rows || []).find((row) => row.code === code)
    return (found && found.name) || codeText(code)
}

/**
 * 监测分布面板视图。
 * 验收三项：覆盖情况、状态分布、地图筛选（本票的筛选入口是全局筛选条，面板只回显生效范围）。
 *
 * **票 14 改写**：状态统计从「可点状态条」改为**饼图**（决策 02 的 Q12/Q19）——
 *   · 数据源是**全局未筛分布**（`extra.statusDistribution`，与地图顶部状态栏共用同一份，
 *     来自 `map-snapshot` 的八桶全局计数；不是本端点随筛选变的那份）；
 *   · 饼图只**高亮当前选中**，不再是筛选入口——全局条件只有一个可操作面（顶部状态栏），
 *     面板自带筛选正是票 07 点名的「入口分散且重复」缺陷；
 *   · 全局分布未取到时如实说明（不伪造全零饼图）。
 *
 * @param {object} data `toMonitoringDistribution()` 的结果
 * @param {object} section 分区
 * @param {object} [extra] `{ statusDistribution, selectedStatuses }`（外壳给的共用数据与当前选中）
 */
/**
 * 异常监测点 → **指标卡 2×2**（维护者第 15 轮）。
 *
 * 为什么不再用横条：这组读数是「当前有多少个异常点位」的**结论型数字**，值班人员要的是
 * 一眼读出四类各多少，而不是比条长；而且它原本挂在面板中段，被上面的覆盖分布压住了。
 * 卡片顺序固定为 报警 / 预警 / 工单处置 / 离线（与地图顶部状态栏同一套语义顺序）。
 *
 * 缺值纪律不变：`extra.statusDistribution` 不可用时整块不出（调用点已判 available），
 * 单个桶缺失按「未知」画占位符 —— 不把「没给」画成 0 个异常点。
 */
export function abnormalPointCards(counts) {
    const source = counts && typeof counts === 'object' ? counts : {}
    const rows = [
        { key: 'ALARM', label: '报警', tone: 'lv1' },
        { key: 'WARNING', label: '预警', tone: 'lv2' },
        { key: 'WORK_ORDER', label: '工单处置', tone: 'lv3' },
        { key: 'OFFLINE', label: '离线', tone: 'neutral' },
    ]
    const countOf = (key) => {
        const raw = source[key]
        if (raw === null || raw === undefined || raw === '') return null
        const value = numberish(raw)
        return value === null ? null : value
    }
    return rows.map((row) => ({
        key: row.key,
        label: row.label,
        value: valueText(countOf(row.key)),
        unit: '个',
        valueTone: row.tone,
        accent: row.tone,
        caption: '全局未筛',
    }))
}
/**
 * 「口径 · 生效范围与总数」→ 面板摘要文案（维护者第 15 轮：并入摘要）。
 *
 * 为什么搬到摘要：这六条是**抬头读数**（现在按什么条件在看），不是图表，占一整块把面板撑长；
 * 做过期/空态说明也已经在摘要里，同一族信息收在一处更好读。
 * 措辞纪律不变：只说范围与口径，不出现接口字段名；缺值照占位符（不编「全部」）。
 */
function distributionScopeNote(current) {
    const total = valueText(current.pagination && current.pagination.total)
    const industry = current.selectedIndustry
        ? industryLabel(current.selectedIndustry) || current.selectedIndustry
        : '全部'
    const district = districtFilterLabel({ district: current.selectedDistrict, districtFilter: current.districtFilter })
    const deviceType = current.selectedDeviceType
        ? deviceTypeLabel(current.deviceTypes, current.selectedDeviceType)
        : '全部'
    const pointStatus = current.selectedPointStatus
        ? String(current.selectedPointStatus)
              .split(',')
              .map((code) => POINT_STATUS_FILTER_LABELS[code] || code)
              .filter(Boolean)
              .join('、')
        : '全部'
    const invalid = valueText(current.excluded && current.excluded.invalidCoordinateCount)
    return [
        '监测点总数 ' + total,
        '生效行业 ' + industry,
        '生效片区 ' + district,
        '生效类型 ' + deviceType,
        '生效状态 ' + pointStatus,
        '坐标未通过校验 ' + invalid,
    ].join(' · ')
}
export function monitoringDistributionPanel(data, section, extra = {}) {
    const current = data || {}

    // 覆盖情况（Q11 裁定）：用**本端点自己的**区域/行业/设备类型分布 ——
    // 票 24 指向的 `overview/monitoring` 的 `formalScope` 不在本端点上，拿不到也不去拉。
    // 票 37 走查扩展（维护者 2026-10-14）：三块都是排名类别，统一按计数降序（并列保序）；
    // 环形图（行业）与条形（片区/类型）同口径。
    const regionRows = sortByCountDesc(
        (current.regions || []).map((row) => ({
            code: row.code,
            label: districtLabel(row.code),
            count: row.pointCount || 0,
            // 每一行带上设备数与状态明细，但主条长按**点位数**归一（图与数同源：口径写在标题里）。
            hint: `设备 ${valueText(row.deviceCount)}`,
        })),
        (row) => row.count,
    )
    const industryRows = sortByCountDesc(
        (current.industries || []).map((row) => ({
            code: row.code,
            label: industryLabel(row.code) || regionText(row.code),
            count: row.pointCount || 0,
            hint: `设备 ${valueText(row.deviceCount)}`,
        })),
        (row) => row.count,
    )
    const typeRows = sortByCountDesc(
        (current.deviceTypes || []).map((row) => ({
            code: row.code || row.name,
            label: row.name || codeText(row.code),
            count: row.pointCount || 0,
            hint: `设备 ${valueText(row.deviceCount)}`,
        })),
        (row) => row.count,
    )

    // 票 14：饼图切片（几何与高亮判定都在 `domain/statusPie.js`，本层只搬运）。
    const pie = planStatusPie({
        distribution: extra.statusDistribution || null,
        rows: legendVisuals(),
        selected: Array.isArray(extra.selectedStatuses) ? extra.selectedStatuses : [],
    })

    const blocks = [
        // 票 39（第 8 条）：每块标题 = **「分节 · 维度（条长口径）」**。
        // 维护者反馈第 8 条的原话是「图与数据指代对象不明确」——同一个面板里既有按
        // **点位数**排的覆盖分布、又有**全局未筛**的状态分布，三种口径混在一屏而不写在
        // 标题上，读者无从判断每张图数的是什么、数的是点位还是设备。
        // 分节词（覆盖情况 / 状态分布 / 口径）让三族各自成节，括号里的口径说明
        // 「这条长度量的是什么」；悬停行的 hint 仍给设备数（图与数同源，不另算一份）。
        // 条形/环形的分工沿用 2026-10-13 的既有结论（行业＝类别少→环形；
        // 片区/类型＝多类别排名→横条），本票不动图形形态，只把指代写清楚。
        // 维护者第 15 轮：① 覆盖情况 · 片区与覆盖情况 · 行业统一成饼图（同族对照，形态一致才好比）；
        // ② 覆盖情况 · 设备类型与下面的「设备类型构成（按点位数）」内容重叠、意义也不清楚 —— 整块删除；
        // ③「异常监测点」从横条改**指标卡 2×2**，并提到面板最顶部（它是值班人员最先要看的一组读数）。
        ...(extra.statusDistribution && extra.statusDistribution.available
            ? [kpiBlock(abnormalPointCards(extra.statusDistribution.counts || {}), { layout: 'two-by-two' })]
            : []),
        donutBlock('覆盖情况 · 行业（按点位数）', industryRows, { layout: 'compact' }),
        donutBlock('覆盖情况 · 片区（按点位数）', regionRows, { layout: 'compact' }),
        stackedBlock('设备类型构成（按点位数）', typeRows),
        // 状态分布饼图：消费全局未筛分布并高亮当前选中；**不可点**（筛选入口只在顶部状态栏）。
        {
            kind: 'pie',
            label: '状态分布 · 点位状态（全局未筛）',
            ready: pie.ready,
            hasSelection: pie.hasSelection,
            total: pie.total,
            slices: pie.slices,
            rows: pie.rows,
            note: pie.ready ? '' : STATUS_DISTRIBUTION_UNPUBLISHED,
        },
    ]

    return {
        name: 'monitoringDistribution',
        label: '监测分布',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        locate: [],
        locateNote: '监测分布是聚合分布口径（后端不返回逐点位坐标），本面板没有可定位对象',
        // 范围筛选落点说明保留；「状态筛选不作用到一张图」的缺口说明已随票 14 的契约修订删除。
        gap: REGION_SCOPE_NOTE,
        // 维护者第 15 轮：原「口径 · 生效范围与总数」块并入摘要（数据时间仍在，见下）。
        note: distributionScopeNote(current) + (current.createdAt ? ' · ' + TIME_LABELS.latestIngested + ' ' + valueText(current.createdAt) : ''),
        // 数据时间是唯一带「测量含义」的读数，单独留在摘要尾巴上，不丢。
        rangeNote: '',
        missing: panelMissingNote(current),
        placeholder: sectionPlaceholder(section),
    }
}

/**
 * 运行概况面板视图。
 * 验收三项：事件趋势、离线设备、异常态势。
 *
 * **票 62 追加需求（2026-10-22 维护者）**：本面板不再展示「异常设备清单」，改展示
 * **设备台账**——按当前数据应列出全部 9 台监测设备，而不是只列异常四态的 8 台。
 * 台账数据来自 `/monitoring/overview` 的 `devices[]`（与那边的 `counts.equipmentCount`
 * 同源同口径），由外壳作为 `extra.devices` 搬进来；本面板自己的分区
 * （`/monitoring/situation`）继续供趋势、指标状态与异常统计——**异常口径不丢，只是
 * 不再用它当台账**。两者不是一回事：异常清单只装 WARNING/ALARM/EXPIRED/OFFLINE 四态设备。
 * @param {object} data `toMonitoringSituation()` 的结果
 * @param {object} section 分区
 * @param {object} [extra] `{ devices }`（`toMonitoringOverview().devices`，外壳给）
 */
/**
 * 预警 / 报警两条趋势合并成**同轴双线**（维护者 2026-10-29）。
 *
 * 为什么要在这里合并：两个端点序列的桶起点可能不完全一致（一侧少一个桶、或粒度不同），
 * 直接按数组下标配对会在图上画出错位的对照 —— 这是**假数据**，不是排版问题。
 * 所以按桶键求并集、缺失一侧记 null（**不补 0**：没这个桶 ≠ 这个桶是 0），
 * 序列里出现 null 时该点不画点、不计入折线（渲染层按 filter(Boolean) 处理）。
 *
 * @param {Array} warningRows `warningTrend` 行（`bucket`/`count`）
 * @param {Array} alarmRows `alarmTrend` 行
 * @returns {{points: Array, warningCounts: Array, alarmCounts: Array}}
 */
export function mergeTrendSeries(warningRows, alarmRows) {
    const warning = Array.isArray(warningRows) ? warningRows : []
    const alarm = Array.isArray(alarmRows) ? alarmRows : []
    const buckets = []
    const seen = new Set()
    for (const row of [...warning, ...alarm]) {
        const key = String((row && row.bucket) || '')
        if (!key || seen.has(key)) continue
        seen.add(key)
        buckets.push(key)
    }
    buckets.sort()
    const index = (rows) => {
        const map = new Map()
        for (const row of rows) map.set(String((row && row.bucket) || ''), numberish(row && row.count))
        return map
    }
    const warningMap = index(warning)
    const alarmMap = index(alarm)
    return {
        points: buckets.map((bucket) => ({ bucket })),
        warningCounts: buckets.map((bucket) => warningMap.get(bucket) ?? null),
        alarmCounts: buckets.map((bucket) => alarmMap.get(bucket) ?? null),
    }
}
export function operationOverviewPanel(data, section, extra = {}) {
    const current = data || {}
    // 7 天窗口的桶是「日」粒度，标签按日期显示（只影响显示，不改桶）。
    const daily = isDailyWindow(current)

    const trendPoints = (list) =>
        (list || []).map((row) => ({
            key: row.bucket,
            label: bucketLabel(row.bucket, daily),
            count: row.count,
        }))

    // 维护者 2026-10-29：两条趋势合成一张双线图（按桶键求并集，缺失不补 0）。
    const mergedTrend = mergeTrendSeries(current.warningTrend, current.alarmTrend)
    const offlineCount = metricCount(current.metricStatuses, 'OFFLINE')
    // 离线设备：从异常清单里挑出离线的那一档。**只挑，不推断**——状态来自后端 `status`。
    // 票 62：这段只服务 `offlineNote`（顶部摘要那行），**不再画成清单**。
    const offlineDevices = (current.abnormalEquipment || []).filter((item) => item.status === 'OFFLINE')
    // 票 62：设备台账数据源（与 `counts.equipmentCount` 同源，行数恒等于它）。
    const devices = Array.isArray(extra.devices) ? extra.devices : []
    // 票 92（维护者 2026-10-27）：KPI 改为 6 张、3×2 排版。全部取自本面板自己的分区
    // `/monitoring/situation`（不跨面板取数），数值真实且分区独立：
    //   · 设备总数 ＝ 六档指标状态计数之和（后端按设备粒度给，总和 = 设备台数）；
    //   · 在线设备 ＝ 正常 + 预警 + 报警（正在上报的设备；与监测概览设备轴「在线」口径一致，已实测比对）；
    //   · 离线设备 ＝ 指标状态 OFFLINE 档（沿用既有取数）；
    //   · 预警/报警设备 ＝ WARNING / ALARM 档（沿用既有取数，改名）；
    //   · 总异常设备 ＝ 异常设备清单总数（pagination.total = 预警+报警+离线+过期）。
    // 旧「数据入库时间」卡退役（不在 6 张清单里）。
    // 分布没取到时（六档 count 全 null）→ 总数/在线/离线/预警/报警全走占位符，绝不画 0（票 16）。
    const distributionProvided = (current.metricStatuses || []).some((row) => row.count !== null)
    const deviceTotal = distributionProvided
        ? current.metricStatuses.reduce((sum, row) => sum + (row.count || 0), 0)
        : null
    const onlineCount = distributionProvided
        ? metricCount(current.metricStatuses, 'NORMAL')
            + metricCount(current.metricStatuses, 'WARNING')
            + metricCount(current.metricStatuses, 'ALARM')
        : null

    const blocks = [
        kpiBlock([
            { key: 'deviceCount', label: '设备总数', value: valueText(deviceTotal), unit: '台', hint: '按指标状态统计（六档之和）' },
            { key: 'online', label: '在线设备', value: valueText(onlineCount), unit: '台', hint: '正常 + 预警 + 报警的设备（正在上报）' },
            { key: 'offlineCount', label: '离线设备', value: valueText(offlineCount), unit: '台' },
            { key: 'warningCount', label: '预警设备', value: valueText(metricCount(current.metricStatuses, 'WARNING')), unit: '台' },
            { key: 'alarmCount', label: '报警设备', value: valueText(metricCount(current.metricStatuses, 'ALARM')), unit: '台' },
            { key: 'abnormalCount', label: '总异常设备', value: valueText(current.pagination && current.pagination.total), unit: '台', hint: '预警 + 报警 + 离线 + 过期' },
        ], { layout: 'three', emphasis: true }),
        // 维护者第 15 轮：「设备/指标异常统计」与「异常态势 · 指标状态分布」是同一份六态数据的
        // 两种画法（横条 + 横条）—— 合并成**一张饼图**，一次读出六态占比与读数。
        donutBlock('指标状态分布（六态）', abnormalCountRows(current.metricStatuses, 'metric').map((row) => ({
            code: row.key,
            label: row.label,
            count: row.count,
        })), { layout: 'compact' }),
        // 维护者 2026-10-29：预警与报警合成**一张双线折线**（同一时间窗、同一量纲），并给块顶留出
        // 呼吸空间（compact 版式），避免与块标题/点顶数值重叠。两条线仍是两个独立数据源，
        // 只共享坐标轴与图例 —— 不改变任何统计口径。
        trendBlock('预警与报警趋势', mergedTrend.points.map((row) => ({
            key: row.bucket,
            label: bucketLabel(row.bucket, daily),
            count: 0,
            hint: row.bucket,
        })), {
            chart: 'line',
            compact: true,
            tall: true,
            aside: '双线对照：预警 / 报警',
            series: [
                { key: 'warning', label: '预警', tone: 'lv2', counts: mergedTrend.warningCounts },
                { key: 'alarm', label: '报警', tone: 'lv1', counts: mergedTrend.alarmCounts },
            ],
        }),
        deviceLedgerBlock(devices),
    ]

    return {
        name: 'operationOverview',
        label: '运行概况',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        // 维护者 2026-10-29：定位入口与监测点台账对齐 —— **整卡点击**即定位并进详情，
        // 不再额外画一排「定位」按钮（两条路径会让同一件事有两种手感）。
        // 三种"点不动"仍由 `domain/mapLocate.js` 分开，由 locateCode 如实反馈。
        locate: [],
        locateNote: '点击设备卡片即定位并进入设备详情（与监测点台账同一交互）；设备坐标由一张图回联，未加载到的设备不下发飞行',
        // 窗口口径：后端回显的实际生效区间（本面板的 24 小时 / 7 天切换写在界面上，见票面 Q8）。
        rangeNote: current.rangeStart && current.rangeEnd ? `统计窗口：${current.rangeStart} 至 ${current.rangeEnd}` : '',
        offlineNote: offlineDevices.length
            ? `离线 ${offlineDevices.length} 台：${offlineDevices.map((item) => item.name).join('、')}`
            : '当前窗口没有离线设备',
        missing: panelMissingNote(current),
        placeholder: sectionPlaceholder(section),
    }
}

/** 7 天窗口的桶按日显示（判据是后端回显的区间长度，不是前端自己记的开关）。 */
function isDailyWindow(current) {
    const start = Date.parse((current && current.rangeStart) || '')
    const end = Date.parse((current && current.rangeEnd) || '')
    if (!Number.isFinite(start) || !Number.isFinite(end)) return false
    return end - start > 36 * 3600 * 1000
}

/**
 * 异常状态 → 色键（报警最重、其次预警、离线与过期走中性）。
 * 票 62：异常清单已从运行概况撤下（改展示设备台账），本函数仍服务于
 * `offlineNote` 的语义与 `toAbnormalEquipment` 的既有消费点，故保留。
 */
function abnormalTone(status) {
    if (status === 'ALARM') return 'lv1'
    if (status === 'WARNING') return 'lv2'
    if (status === 'OFFLINE' || status === 'EXPIRED') return 'neutral'
    return 'neutral'
}

/** 设备台账行的展示名：有名称用名称，没名称用编码（**不编造**，也不留空行）。 */
function deviceLabel(item) {
    return (item && (item.name || item.code)) || DETAIL_PLACEHOLDER
}

/**
 * 设备监测状态 → 色键（票 62）。按语义分档，与 `abnormalTone` 同一套色；
 * 在线/正常走成功色，滞后走关注色，离线/未发布走中性（**不把"没状态"画成正常**）。
 */
function deviceStateTone(status) {
    if (status === 'ALARM') return 'lv1'
    if (status === 'WARNING' || status === 'STALE') return 'lv2'
    if (status === 'ONLINE' || status === 'NORMAL') return 'lv4'
    return 'neutral'
}

/**
 * 设备监测状态码 → 人话（票 62）。
 * `ONLINE` 是设备轴上的补充取值（指标状态字典里没有它）；其余复用六态字典，
 * 认不出的回原码、空值如实说「状态未发布」——不猜成正常。
 */
function deviceStateText(status) {
    const value = typeof status === 'string' ? status.trim() : ''
    if (!value) return '状态未发布'
    if (value === 'ONLINE') return '在线'
    return metricStatusText(value)
}

/**
 * 运行概况的**设备台账**清单块（票 62 追加需求，2026-10-22 维护者）。
 *
 * 与原先「异常设备清单」是**结构性差别**，不只是换个标题：
 *   · **数据源**：`/monitoring/overview` 的 `devices[]`（全部智能设备，行数 ≡ `counts.equipmentCount`），
 *     不是 `/monitoring/situation` 的 `abnormalEquipment[]`（只装 WARNING/ALARM/EXPIRED/OFFLINE）；
 *   · **每行内容**：名称（主键展示）＋ 设备编码、类型、行业、监测状态、所属点位、数据入库时间；
 *   · **总数口径**：读设备台账行数本身（＝ `equipmentCount`），页脚明说「共 N 台监测设备」；
 *   · 仍是前端集合分页 10/页（规范三分法），翻页**零请求**。
 * @param {Array} devices 领域设备行（`toMonitoringOverview().devices`）
 */
function deviceLedgerBlock(devices) {
    const rows = (devices || []).map((item) => ({
        key: item.code || `${item.typeCode}|${item.pointCode}`,
        title: deviceLabel(item),
        identityKind: CARD_ACTION.DEVICE,
        identityCode: item.code,
        identityReason: item.code ? '' : '缺少设备编码，无法展开',
        dataTime: valueText(item.createdAt),
        // 标签由 domain 给（`TIME_LABELS` 单点词表）：渲染层不认「时间」这个词，更不自己拼。
        dataTimeLabel: TIME_LABELS.ingested,
        tone: deviceStateTone(item.status),
        // 色键必带文字（票 06）：状态词认不出也回原码，不留空标签、不猜成正常。
        toneLabel: deviceStateText(item.status),
        meta: [
            item.code,
            item.typeName,
            industryLabel(item.industry) || codeText(item.industry),
            item.pointCode ? `点位 ${item.pointCode}` : '未关联点位',
        ].filter(Boolean),
        // 维护者 2026-10-29：设备卡**不再单独画「定位」小按钮**，改为与监测点台账一致 ——
        // 整卡点击 = 定位 + 进详情（一个动作，不是"先点小按钮定位、再点卡进详情"两条路径）。
        // 定位本身仍走既有设备维度接缝 `monitoringStore.locateCode`（判定→相机→详情），
        // 三种"点不动"由 `domain/mapLocate.js` 分开，不在这里另造一套。
        points: [],
    }))
    return listBlock('设备台账', rows, '当前范围内没有监测设备', {
        paginate: true,
        // 页码归属键：只看设备全集的身份（行数）——换筛选导致集合变化时自然复位。
        // 标量键，不接受对象身份（票 43 教训：视图计划每次重算都是新对象）。
        pageScope: `devices|${rows.length}`,
        pageNote: rows.length ? `共 ${rows.length} 台监测设备（当前筛选范围）` : '',
    })
}

/**
 * 监测点台账面板视图。
 * 验收第 4 条：以滚动卡片列出当前行业筛选内的监测点；点击卡片走与地图相同的两级详情。
 *
 * **票 62 改写（批次四）**：数据不再取「分布这一次响应的第 1 页切片」，而是 store 的
 * **自动渐进装载链**（`domain/ledgerLoader.js`）已经装好的**完整序列**；
 *   · 装载与一张图点位数据同款（条件变化 → 新快照 → 自动连翻到 settled）；
 *   · 界面只对**已装载集合**做统一页码分页（10/页、页码直达），翻页是**纯视图动作**；
 *   · 「加载下一页监测点」按钮与 `ledger-more` 接缝**退役**（自动链自己会翻完）；
 *   · 页脚如实给「已装载 M · 共 N 条（含未关联设备）」+ 装载中/失败标注。
 *
 * **设备徽标仍走 N+1**（Q10/Q14 不变）：本端点不给设备编码，徽标由 store 逐点位取。
 * 票 62 的改进是**只为当前页窗口内的卡片补拉**——窗口化之后一屏最多 10 张卡，
 * 不再"一页 500 张卡进视口就打出 500 个请求"。
 * @param {object} data `toMonitoringDistribution()`/装载链条目（读 `points`/`equipment`/`pagination`）
 * @param {object} section 分区
 * @param {object} [badges] `{ [pointCode]: { state, total, alarm, warning, offline } }`（store 给）
 */
export function monitoringPointLedgerPanel(data, section, badges = {}) {
    const current = data || {}
    const pagination = current.pagination || {}
    // 分母认不出就**整句不出**（作者本意），且绝不用 `undefined` 冒充读数：
    // `data` 为 null（真实空态/失败态，见 `sectionFromResult()` 的 `isEmpty` 分支）时
    // `pagination` 是 `{}`，`total` 是 `undefined` 而不是 `null` —— 只判 `=== null` 会把
    // 它漏进模板串。`numberish()` 是仓库里「数字/数字串→数字，认不出回 null」的唯一口径。
    const total = numberish(pagination.total)

    const cards = (current.points || []).map((point) => {
        const visual = visualForStatus(point.status)
        const badge = badges[point.code] || null
        return {
            key: point.code,
            code: point.code,
            name: point.name,
            identityKind: CARD_ACTION.POINT,
            identityCode: point.code,
            identityReason: point.code ? '' : '缺少点位编码，无法展开',
            dataTime: valueText(point.createdAt),
            // 同上：标签由 domain 给，渲染层只拼值。
            dataTimeLabel: TIME_LABELS.ingested,
            // 状态词与色键来自票 09 的唯一一张表（认不出的状态落「状态未发布」，不猜成正常）。
            status: visual.key,
            tone: visual.tone,
            shape: visual.shape,
            statusLabel: visual.label,
            meta: [
                industryLabel(point.industry) || codeText(point.industry),
                districtLabel(point.district),
                point.typeName,
            ].filter(Boolean),
            reason: (point.statusReasons || []).join('；'),
            // 徽标：还没取到就**不给 0**（0 是"确实没有设备"，与"还没问过"是两件事）。
            badge: badge && badge.state === 'success'
                ? {
                      total: valueText(badge.total),
                      alarm: valueText(badge.alarm),
                      warning: valueText(badge.warning),
                      offline: valueText(badge.offline),
                  }
                : null,
            badgePending: !badge || badge.state === 'pending',
        }
    })

    // 票 62：页脚口径由 store 的装载链给（它才知道「已装载多少 / 总数多少 / 还在不在装」）；
    // 装载链没给（走查注入的裸载荷）时退回既有措辞，保持 t27 的防回归判据不变。
    const pageNote = typeof current.ledgerNote === 'string' && current.ledgerNote
        ? current.ledgerNote
        : total === null
          ? ''
          : `已列出 ${cards.length} 个点位 · 本端点序列共 ${total} 条（含未关联设备）`

    const blocks = [
        listBlock('监测点', cards, '当前筛选范围内没有监测点', {
            // 票 62：已装载集合做前端集合分页（翻页零请求）。
            paginate: true,
            // 页码归属键只用条件（换筛选/换快照即复位）；装载链继续往集合里追加时**不复位**
            // ——用户停在第 3 页读台账，自动链补完后面的批次不该把人弹回第 1 页（条文 6）。
            pageScope: `${current.snapshotAt || ''}|${pagination.pageSize || ''}`,
        }),
    ]

    return {
        name: 'monitoringPointLedger',
        label: '监测点台账',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        // 卡片本身就是可定位/可详情的对象，所以这里不再另给一批按钮：
        // 点击卡片走**与地图相同**的两级详情入口（`detailStore.openPoint`），不隐式移动相机
        // —— 与"点地图标记"的行为一致（票 10 的既有语义）。
        locate: [],
        locateNote: '点击卡片进入与地图一致的两级详情（点位摘要 → 设备卡片）；本面板不移动相机',
        // 分页口径：本端点分页窗口横跨「监测点 + 未关联设备」，所以 total 含设备，
        // 卡片数会小于 total —— 这个差值说明白，免得读成"还有一些点没列出来"。
        pageNote,
        // 票 62：「加载下一页」按钮退役（自动链负责装载），`hasMore` 恒 false 让渲染层不画按钮。
        hasMore: false,
        page: pagination.page,
        missing: panelMissingNote(current),
        placeholder: sectionPlaceholder(section),
    }
}

/** panelId → 视图构造函数（本模式自己的四块）。 */
export const MONITORING_PANEL_BUILDERS = {
    monitoringOverview: monitoringOverviewPanel,
    monitoringDistribution: monitoringDistributionPanel,
    operationOverview: operationOverviewPanel,
    // 台账签名多一个 `badges`（N+1 徽标）；注册表调用时给 undefined 即为「还没取到」。
    monitoringPointLedger: (data, section, badges) => monitoringPointLedgerPanel(data, section, badges),
}

/**
 * 一个面板的视图。`data` 为 null（失败/空）时仍返回结构完整的视图（块为空），
 * 组件据此画占位说明 —— 「失败」不该让整块面板消失，那会连面板标题都没了。
 */
export function monitoringPanelView(panelId, data, section, badges) {
    const build = MONITORING_PANEL_BUILDERS[panelId]
    if (!build) return null
    return build(data, section, badges)
}

/**
 * 台账当前该请求的下一页（`null` = 不用再翻）。纯函数，断言与旧调用共用。
 *
 * 票 62：装载链的推进已收进 `domain/ledgerLoader.js`（它同时管快照锁定与失败纪律）；
 * 本函数保留为**载荷层面的只读判据**（「这份响应还有没有下一页」），不再被 store 用作
 * 推进手段 —— 两处各推一次会把「谁决定下一页」变成两个答案。
 */
export function nextLedgerPage(data) {
    const pagination = (data && data.pagination) || null
    if (!pagination || pagination.page === null) return 1
    if (pagination.hasMore !== true) return null
    return pagination.page + 1
}

/** 该点位是否需要补拉徽标（已被要求过就不重复发请求）。纯函数，便于断言。 */
export function shouldLoadBadge(badges, pointCode) {
    if (!pointCode) return false
    return !(badges && badges[pointCode])
}

/** 台账卡片的状态分布（走查与人工排查读它，不读中文）。 */
export function ledgerStatusCounts(data) {
    const counts = {}
    for (const point of (data && data.points) || []) {
        const key = visualForStatus(point.status).key
        counts[key] = (counts[key] || 0) + 1
    }
    return counts
}

/** 缺失值占位符（组件与本模块共用同一个词，免得两处各写一个字面量）。 */
export const LEDGER_PLACEHOLDER = DETAIL_PLACEHOLDER