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（记录创建时间），不使用 updatedAt 或 sampledAt 兜底。
 * 点位状态中文来自 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 } from './fields.js'
import { DETAIL_PLACEHOLDER } from './detailFlow.js'
import { valueText } from './equipmentDetailView.js'
import { shortEventTime } from './eventList.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,
    codeText,
    donutBlock,
    kpiBlock,
    listBlock,
    locateEntries,
    numberish,
    panelMissingNote,
    ratioText,
    regionText,
    rowsBlock,
    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
}

/** 数据时间和设备采样时间的语义说明。 */
export const METRIC_FRESHNESS_GAP =
    '数据时间＝记录创建时间，不是设备采样时刻；缺失时显示未知，不使用接口响应或快照时间代替'

/**
 * 全局状态分布**未取到**时的如实说明（票 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`**，所以本面板的筛选面就是行业 + 类型。
 */
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),
            }
        }),
        // 新鲜度：本端点只有信封级（见文件头第 ① 条）。
        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'),
        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），本层不重排、不丢行。
    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: metricStatusMap.get(status) || 0 }))

    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,
    }
}

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

/** 票 54：数据时间屏上短读，完整 ISO 进入 title；缺值先占位。 */
function createdAtKpi(value) {
    const full = valueText(value)
    if (full === DETAIL_PLACEHOLDER) return { key: 'createdAt', label: '数据时间', value: full, full }
    return { key: 'createdAt', label: '数据时间', value: shortEventTime(value) || full, full }
}

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

/**
 * 监测概览面板视图。
 * 验收四项：监测点/设备规模、在线率、类型分布、最近采集时间。
 */
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)}`
                    : '当前范围内没有可参与计算的设备，在线率不适用',
            },
            // 采集时间：本端点只有信封级时间（见文件头第 ① 条），措辞与"采集"区分开。
            createdAtKpi(current.createdAt),
        ], { layout: 'two-by-two' }),
        rowsBlock('设备状态', [
            { key: 'online', label: '在线', value: valueText(deviceStatus.online) },
            { key: 'offline', label: '离线', value: valueText(deviceStatus.offline) },
            { key: 'stale', label: '数据滞后', value: valueText(deviceStatus.stale) },
            { key: 'unknownOrMissing', label: '未知/缺失', value: valueText(deviceStatus.unknownOrMissing) },
            { key: 'denominator', label: '在线率分母', value: valueText(deviceStatus.denominator) },
        ]),
        barsBlock(
            '设备类型分布',
            // 票 37：按设备数**从多到少**降序；并列时保持后端给的次序（后端已排好则是恒等变换）。
            sortByCountDesc(
                (current.typeDistribution || []).map((row) => ({
                    code: row.code,
                    label: row.name || codeText(row.code),
                    count: row.deviceCount || 0,
                    // 当前生效的类型行：渲染层画选中态，用户据此知道"再点一下就取消"。
                    selected: Boolean(row.code) && row.code === current.selectedDeviceType,
                })),
                (row) => row.count,
            ),
            // 行可点 → 写全局类型筛选（复用票 20 立的 `panel-action` 接缝）。
            // 只带得出后端类型码的行才可点：`code` 为空时 `barsBlock` 不给 `actionKey`，
            // 那一行在渲染层就不是按钮 —— 不拿展示名冒充筛选码去换后端 400。
            { action: 'deviceType' },
        ),
    ]

    return {
        name: 'monitoringOverview',
        label: '监测概览',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        // 概览是聚合口径（后端只给分类型计数，不给逐点位坐标），没有可定位对象。
        locate: [],
        locateNote: '监测概览是分类型聚合口径（后端不返回逐点位坐标），本面板没有可定位对象',
        // 采集时间与数据时间的区别如实说明（文件头第 ① 条）。
        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 }`（外壳给的共用数据与当前选中）
 */
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 = [
        // 2026-10-13 维护者反馈：条形图太多易疲劳——行业行改环形图（行业语义色），
        // 片区/设备类型保留条形（多类别排名比较）。
        donutBlock('覆盖情况 · 行业', industryRows),
        barsBlock('覆盖情况 · 片区', regionRows),
        barsBlock('覆盖情况 · 设备类型', typeRows),
        ...(extra.statusDistribution && extra.statusDistribution.available
            ? [barsBlock('监测点异常统计（全局未筛）', abnormalCountRows(
                Object.entries(extra.statusDistribution.counts || {}).map(([status, count]) => ({ status, count })), 'point'))]
            : []),
        // 状态分布饼图：消费全局未筛分布并高亮当前选中；**不可点**（筛选入口只在顶部状态栏）。
        {
            kind: 'pie',
            label: '点位状态分布（全局未筛）',
            ready: pie.ready,
            hasSelection: pie.hasSelection,
            total: pie.total,
            slices: pie.slices,
            rows: pie.rows,
            note: pie.ready ? '' : STATUS_DISTRIBUTION_UNPUBLISHED,
        },
        rowsBlock('口径', [
            { key: 'pointTotal', label: '监测点总数', value: valueText(current.pagination && current.pagination.total) },
            { key: 'industry', label: '生效行业', value: current.selectedIndustry ? industryLabel(current.selectedIndustry) || current.selectedIndustry : '全部' },
            { key: 'district', label: '生效片区', value: districtFilterLabel({ district: current.selectedDistrict, districtFilter: current.districtFilter }) },
            // 票 37：类型是全局筛选条件之一，生效范围必须与本模式其它条件一样看得见
            // （否则读者只看到"类型分布少了几行"，不知道条件从哪来、怎么撤）。
            { key: 'deviceType', label: '生效类型', value: current.selectedDeviceType ? deviceTypeLabel(current.deviceTypes, current.selectedDeviceType) : '全部' },
            { key: 'createdAt', label: '数据时间', value: valueText(current.createdAt) },
            // 票 14：状态多值化——回显是逗号串，逐桶翻人话；空 = 全部。
            {
                key: 'pointStatus',
                label: '生效状态',
                value: current.selectedPointStatus
                    ? String(current.selectedPointStatus)
                          .split(',')
                          .map((code) => POINT_STATUS_FILTER_LABELS[code] || code)
                          .filter(Boolean)
                          .join('、')
                    : '全部',
            },
            // 坐标准入被拦下的对象数：分布口径只统计可上图对象，这个数解释差值（票 07 的口径）。
            { key: 'invalidCoordinate', label: '坐标未通过校验', value: valueText(current.excluded && current.excluded.invalidCoordinateCount) },
        ]),
    ]

    return {
        name: 'monitoringDistribution',
        label: '监测分布',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        locate: [],
        locateNote: '监测分布是聚合分布口径（后端不返回逐点位坐标），本面板没有可定位对象',
        // 范围筛选落点说明保留；「状态筛选不作用到一张图」的缺口说明已随票 14 的契约修订删除。
        gap: REGION_SCOPE_NOTE,
        missing: panelMissingNote(current),
        placeholder: sectionPlaceholder(section),
    }
}

/**
 * 运行概况面板视图。
 * 验收三项：事件趋势、离线设备、异常态势。
 */
export function operationOverviewPanel(data, section) {
    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,
        }))

    const offlineCount = metricCount(current.metricStatuses, 'OFFLINE')
    // 离线设备：从异常清单里挑出离线的那一档。**只挑，不推断**——状态来自后端 `status`。
    const offlineDevices = (current.abnormalEquipment || []).filter((item) => item.status === 'OFFLINE')

    const blocks = [
        kpiBlock([
            createdAtKpi(current.createdAt),
            { key: 'offlineCount', label: '离线设备', value: valueText(offlineCount), unit: '台' },
            { key: 'alarmCount', label: '报警中', value: valueText(metricCount(current.metricStatuses, 'ALARM')), unit: '台' },
            { key: 'warningCount', label: '预警中', value: valueText(metricCount(current.metricStatuses, 'WARNING')), unit: '台' },
            { key: 'abnormalCount', label: '异常设备', value: valueText(current.pagination && current.pagination.total), unit: '台' },
        ]),
        barsBlock('设备/指标异常统计', abnormalCountRows(current.metricStatuses, 'metric')),
        // 预警与报警**分开画**：后端注释明确两者不混合，合成一条就是把两类事件混成一份。
        // 2026-10-13 图表选型：时间趋势用折线。
        trendBlock('预警趋势', trendPoints(current.warningTrend), { chart: 'line' }),
        trendBlock('报警趋势', trendPoints(current.alarmTrend), { chart: 'line' }),
        barsBlock(
            '异常态势 · 指标状态分布',
            (current.metricStatuses || []).map((row) => ({
                code: row.status,
                label: metricStatusText(row.status),
                count: row.count || 0,
            })),
        ),
        listBlock(
            '异常设备清单',
            (current.abnormalEquipment || []).map((item) => ({
                key: item.code,
                title: item.name,
                dataTime: valueText(item.createdAt),
                tone: abnormalTone(item.status),
                // 色键必带文字（票 06）：状态词来自指标状态字典，退化成"未知"也不留空标签。
                toneLabel: metricStatusText(item.status),
                meta: [
                    item.typeName,
                    industryLabel(item.industry) || codeText(item.industry),
                    districtLabel(item.district),
                    ...item.statusReasons,
                ].filter(Boolean),
                // 设备编码即该设备在地图上的对象编码（未关联设备以自身编码上图），
                // 但**只有已加载到一张图里**才飞得动 —— 三种"点不动"由 `domain/mapLocate.js` 分开。
                points: item.code
                    ? [{ key: `${item.code}|locate`, label: item.name, pointCode: item.code, objectCode: item.code, objectName: item.name }]
                    : [],
            })),
            '当前窗口没有异常设备',
        ),
    ]

    return {
        name: 'operationOverview',
        label: '运行概况',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        locate: (current.abnormalEquipment || []).flatMap((item) =>
            locateEntries(item.code, item.name, { code: item.code, name: item.name }, item.code ? [item.code] : []),
        ),
        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
}

/** 异常状态 → 色键（报警最重、其次预警、离线与过期走中性）。 */
function abnormalTone(status) {
    if (status === 'ALARM') return 'lv1'
    if (status === 'WARNING') return 'lv2'
    if (status === 'OFFLINE' || status === 'EXPIRED') return 'neutral'
    return 'neutral'
}

/**
 * 监测点台账面板视图。
 * 验收第 4 条：以滚动卡片列出当前行业筛选内的监测点；点击卡片走与地图相同的两级详情。
 *
 * 台账与监测分布**共用一次取数**（Q4 裁定），所以卡片就是分布响应里的 `monitoringPoints`；
 * 分页由端点自己的 `pagination` 决定，本层只把"还有没有下一页"如实带出。
 *
 * **设备徽标不在这里**（Q10 裁定走 N+1）：本端点不给设备编码，
 * 徽标由 store 逐点位取 `/monitoring-points/{code}` 的 `deviceStatistics` 后补进卡片视图。
 * @param {object} data `toMonitoringDistribution()` 的结果
 * @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,
            dataTime: valueText(point.createdAt),
            // 状态词与色键来自票 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',
        }
    })

    const blocks = [
        listBlock('监测点', cards, '当前筛选范围内没有监测点'),
    ]

    return {
        name: 'monitoringPointLedger',
        label: '监测点台账',
        section,
        hasContent: sectionHasContent(section),
        blocks,
        // 卡片本身就是可定位/可详情的对象，所以这里不再另给一批按钮：
        // 点击卡片走**与地图相同**的两级详情入口（`detailStore.openPoint`），不隐式移动相机
        // —— 与"点地图标记"的行为一致（票 10 的既有语义）。
        locate: [],
        locateNote: '点击卡片进入与地图一致的两级详情（点位摘要 → 设备卡片）；本面板不移动相机',
        // 分页口径：本端点分页窗口横跨「监测点 + 未关联设备」，所以 total 含设备，
        // 卡片数会小于 total —— 这个差值说明白，免得读成"还有一些点没列出来"。
        // 分母缺失（`total === null`）时整句不出：宁可不说，也不报一个假读数。
        pageNote:
            total === null
                ? ''
                : `已列出 ${cards.length} 个点位 · 本端点序列共 ${total} 条（含未关联设备）${pagination.hasMore ? ' · 还有下一页' : ''}`,
        hasMore: pagination.hasMore === true,
        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` = 不用再翻）。纯函数，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