City-Lifeline-Cockpit/src/modules/cockpit/mocks/contractMocks.js

/**
 * 契约化 mock 样例（票 05）：与真实接口**同一份字段名与嵌套形状**。
 *
 * 依据（Q3=A）：字段名与结构照抄后端演示载荷 ——
 * `E:\pipe-ner-server\docs\cockpit\*.html` 与 `research/panel-field-coverage.md` 的逐字段表。
 * 因此适配器单测证明的是「转换吃得下真载荷」，而不是「吃得下我自己编的小样」。
 *
 * 覆盖票 05 要求的五类样例（每个接口都能取到）：
 *   `success`（正常）/ `empty`（空数据）/ `degraded`（字段缺失）/ `failed`（失败）/ `stale`（过期）。
 * 另有 `unauthorized`：票 05 验收第 6 条的 401 场景，只影响被请求的那个分区。
 *
 * 数据是**精心构造的边界值**，不是随手填的：坐标覆盖 VALID/UNVERIFIED/INVALID/ZERO、
 * 指标覆盖 0 与「无采样」、时间覆盖未结案（null）。
 */
import { REQUEST_REASON } from '../domain/requestReason.js'

const SNAPSHOT_AT = '2026-09-02T10:00:00+08:00'

// ---------------------------------------------------------------- 地图摘要

const MAP_POINTS = [
    {
        pointCode: 'MP-001',
        pointName: '供水干管监测点',
        pointStatus: 'NORMAL',
        statusReasons: [],
        longitude: 110.141,
        latitude: 28.452,
        coordinateValidation: { state: 'VALID', reason: null, renderable: true, crs: 'WGS84' },
    },
    {
        pointCode: 'MP-002',
        pointName: '燃气调压站监测点',
        pointStatus: 'ALARM',
        statusReasons: ['EQ-ASSOC-001 报警'],
        longitude: 110.142,
        latitude: 28.453,
        coordinateValidation: { state: 'VALID', reason: null, renderable: true, crs: 'WGS84' },
    },
    {
        pointCode: 'MP-003',
        pointName: '污水排口监测点',
        pointStatus: 'WARNING',
        statusReasons: ['EQ-FREE-003 预警'],
        longitude: 110.143,
        latitude: 28.454,
        coordinateValidation: { state: 'UNVERIFIED', reason: 'UNVERIFIED_COORDINATE', renderable: false, crs: 'WGS84' },
    },
]

const MAP_EQUIPMENT = [
    {
        deviceCode: 'EQ-FREE-001',
        deviceName: '供水压力计-001',
        longitude: 181,
        latitude: 28.455,
        coordinateValidation: { state: 'INVALID', reason: 'LONGITUDE_OUT_OF_RANGE', renderable: false, crs: 'WGS84' },
    },
    {
        deviceCode: 'EQ-FREE-004',
        deviceName: '零坐标设备-004',
        longitude: 0,
        latitude: 0,
        coordinateValidation: { state: 'INVALID', reason: 'ZERO_COORDINATE', renderable: false, crs: 'WGS84' },
    },
]

/** 地图摘要的演示分页（票 08）：契约允许任意页大小，演示用 2 —— 三页翻完，看得出来是渐进加载。 */
const MAP_SNAPSHOT_PAGE_SIZE = 2

/**
 * 票 09 的点位状态样例：**后端六态各一个**，全部坐标合法（都该上图），
 * 外加一个后端新增、前端不认识的第九个状态 —— 它必须落「状态未发布」而不是被猜成正常。
 *
 * 为什么要单独一份而不是改上面那三个点位：票 07/08 的走查把 `2,4,5` / 可上图 2 · 不上图 3
 * 这些数写成了断言，改默认样例就会改掉那两张票的证据。所以状态演示走**独立场景**
 * （`__COCKPIT_MOCK_SCENARIO__ = 'point-statuses'`），默认样例一个字节不动。
 */
const STATUS_SAMPLE_POINTS = [
    { pointCode: 'MP-ST-ALARM', pointName: '燃气调压站报警监测点', pointStatus: 'ALARM' },
    { pointCode: 'MP-ST-WARNING', pointName: '污水排口预警监测点', pointStatus: 'WARNING' },
    { pointCode: 'MP-ST-WORKORDER', pointName: '供水干管工单处置监测点', pointStatus: 'WORK_ORDER' },
    { pointCode: 'MP-ST-NORMAL', pointName: '排水泵站正常监测点', pointStatus: 'NORMAL' },
    { pointCode: 'MP-ST-OFFLINE', pointName: '井盖离线监测点', pointStatus: 'OFFLINE' },
    { pointCode: 'MP-ST-EMPTY', pointName: '预留无设备监测点', pointStatus: 'EMPTY' },
    // 后端将来新增的状态：前端不认识，必须如实说「状态未发布」，不得落到任何真实状态上。
    { pointCode: 'MP-ST-UNKNOWN', pointName: '未知状态监测点', pointStatus: 'MAINTENANCE' },
].map((item, index) => ({
    ...item,
    statusReasons: [],
    // 沿经纬度铺开一点，免得标记叠在一起看不出形状差异。
    longitude: 110.141 + index * 0.002,
    latitude: 28.452 + index * 0.001,
    coordinateValidation: { state: 'VALID', reason: null, renderable: true, crs: 'WGS84' },
}))

/** 状态样例里的未关联设备（第六态「无关联设备」的落点，形状是十字）。 */
const STATUS_SAMPLE_EQUIPMENT = [
    {
        deviceCode: 'EQ-ST-FREE',
        deviceName: '未关联设备-001',
        longitude: 110.155,
        latitude: 28.459,
        coordinateValidation: { state: 'VALID', reason: null, renderable: true, crs: 'WGS84' },
    },
]

/**
 * 按后端**真实语义**造一页地图摘要（票 08）。
 *
 * 照抄 `CockpitMapSnapshotService.load()` 的三条行为，而不是造一份"理想载荷"：
 *   1. 分页窗口是「监测点 + 未关联设备」这**一条总序列**：先排满监测点，再排未关联设备
 *      （所以后一页可能整页都是设备，或两类混在一页）；
 *   2. 第 2 页起**必须**带 `snapshotAt`，且与当前快照一致，否则抛 `SNAPSHOT_EXPIRED`；
 *   3. `complete` 只在「本页末尾已到总数」时为真。
 *
 * 票 07 起另有一条**必须照抄**：响应带 `coordinateValidation` **全量**汇总
 * （后端用整份 points/equipment 算完再切片分页，所以它不随页码变化）。
 *
 * @param {object} options
 * @param {number} [options.page] 页码（1 起）
 * @param {number} [options.pageSize] 每页条数
 * @param {string} [options.snapshotAt] 客户端带的快照标记（第 1 页不带）
 * @param {string} [options.currentSnapshot] 本次请求后端当前快照（固定值，见 `planMapSnapshot`）
 * @param {Array} [options.points] 覆盖监测点集合（票 09 的状态样例用）
 * @param {Array} [options.equipment] 覆盖未关联设备集合
 */
function mapSnapshotPage({
    page = 1,
    pageSize = MAP_SNAPSHOT_PAGE_SIZE,
    snapshotAt = '',
    currentSnapshot = SNAPSHOT_AT,
    points = MAP_POINTS,
    equipment = MAP_EQUIPMENT,
} = {}) {
    if (page > 1 && !snapshotAt) {
        const error = new Error('mock: 第 2 页起必须带 snapshotAt')
        error.reason = REQUEST_REASON.SNAPSHOT_EXPIRED
        throw error
    }
    if (snapshotAt && snapshotAt !== currentSnapshot) {
        const error = new Error('mock: 快照标记与当前快照不一致')
        error.reason = REQUEST_REASON.SNAPSHOT_EXPIRED
        throw error
    }

    const all = [...points, ...equipment]
    const from = Math.max(0, (page - 1) * pageSize)
    const to = from + pageSize
    const slice = all.slice(from, to)

    return {
        page,
        pageSize,
        snapshotAt: currentSnapshot,
        batchUpdatedAt: currentSnapshot,
        total: all.length,
        complete: to >= all.length,
        monitoringPoints: slice.filter((item) => 'pointCode' in item),
        unassociatedEquipment: slice.filter((item) => 'deviceCode' in item),
        // 全量口径：与 `CockpitMapSnapshotService.coordinateValidation(points, equipment)` 一致。
        coordinateValidation: coordinateValidationSummary(all),
    }
}

/**
 * 坐标校验汇总（票 07）：照抄后端 `CockpitCoordinateValidationSummary` 的字段名与判据。
 *
 * 后端的分法是**三桶**：`renderable` 优先，其余里 `state === 'INVALID'` 记非法，
 * 剩下的一律记「未校验」（`CockpitMapSnapshotService` 第 205-231 行）。
 * 这里照抄同一个分法 —— 换一套算法就会让前端显示的数与后端对不上。
 */
function coordinateValidationSummary(objects) {
    let renderableCount = 0
    let invalidCount = 0
    let unverifiedCount = 0

    for (const item of objects) {
        const validation = item.coordinateValidation || {}
        if (validation.renderable === true) renderableCount += 1
        else if (validation.state === 'INVALID') invalidCount += 1
        else unverifiedCount += 1
    }

    return {
        crs: 'WGS84',
        totalObjectCount: objects.length,
        renderableCount,
        invalidCount,
        unverifiedCount,
    }
}

/**
 * 从请求路径的查询串里取一个整数参数。
 * 走查与演示要能现场改页大小（`window.__COCKPIT_MOCK_MAP_PAGE_SIZE__`），
 * 所以分页参数必须真的从请求上读，而不是写死一份。
 */
function queryInteger(path, key, fallback) {
    const query = String(path || '').split('?')[1] || ''
    const value = new URLSearchParams(query).get(key)
    const parsed = Number(value)
    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback
}

/** 查询串里的快照标记（第 1 页不带）。 */
function querySnapshot(path) {
    const query = String(path || '').split('?')[1] || ''
    return new URLSearchParams(query).get('snapshotAt') || ''
}

/**
 * 地图摘要样例（票 08）：**按后端真实分页语义**造，而不是只给一页。
 *
 * 场景（`overrides` 由走查现场给，见 `mocks/index.js`）：
 *   · `success`  —— 正常分页，后端当前快照固定；
 *   · `empty`    —— 后端说总数 0（不是「这一页恰好没有」）；
 *   · `degraded` —— 保持票 05 的字段缺失样例（单页、`complete: false`）；
 *   · `stale`    —— **取完第 1 页后后端换了快照**（`expireAfterPage`），第 2 页带着旧标记回来即失效；
 *   · `failed`   —— 由统一出口抛出，不在这里给载荷。
 *
 * @param {string} scenario 五类样例
 * @param {string} path 请求路径（分页参数在这里）
 * @param {object} [overrides] `{ pageSize, snapshotAt, expireAfterPage }`
 */
function mapSnapshotPayload(scenario, path, overrides = {}) {
    const pageSize = overrides.pageSize || MAP_SNAPSHOT_PAGE_SIZE
    const page = queryInteger(path, 'page', 1)
    const baseSnapshot = overrides.snapshotAt || SNAPSHOT_AT

    if (scenario === 'empty') {
        return {
            page,
            pageSize,
            snapshotAt: baseSnapshot,
            batchUpdatedAt: baseSnapshot,
            total: 0,
            complete: true,
            monitoringPoints: [],
            unassociatedEquipment: [],
            // 真·空快照：全量口径各项都是 0（这里 0 是真实值，不是缺失）。
            coordinateValidation: coordinateValidationSummary([]),
        }
    }

    if (scenario === 'degraded') {
        const degraded = [{ pointCode: 'MP-DEGRADED', pointName: '字段缺失点位', pointStatus: 'NORMAL', statusReasons: [] }]
        return {
            page: 1,
            pageSize: 500,
            snapshotAt: baseSnapshot,
            complete: false,
            monitoringPoints: degraded,
            unassociatedEquipment: [],
            // 后端没给 coordinateValidation 的点位：仍占一个位置，落在「未校验」桶里。
            coordinateValidation: coordinateValidationSummary(degraded),
        }
    }

    // 票 09：后端六态 + 未关联设备 + 一个前端不认识的状态，全部可上图（状态演示用）。
    if (scenario === 'point-statuses') {
        return mapSnapshotPage({
            page,
            pageSize,
            snapshotAt: querySnapshot(path),
            currentSnapshot: baseSnapshot,
            points: STATUS_SAMPLE_POINTS,
            equipment: STATUS_SAMPLE_EQUIPMENT,
        })
    }

    // 过期样例：第 1 页照常给旧快照，之后的请求后端已经换成新快照 —— 客户端带着旧标记回来即失效。
    const expired = scenario === 'stale' && Number.isInteger(overrides.expireAfterPage) && page > overrides.expireAfterPage
    const currentSnapshot = expired ? '2026-09-02T10:30:00+08:00' : baseSnapshot
    return mapSnapshotPage({ page, pageSize, snapshotAt: querySnapshot(path), currentSnapshot })
}

// ---------------------------------------------------------------- 监测点详情

/**
 * 监测点详情的样例载荷（票 05 的默认 + 四类异常样例）。
 *
 * 票 10 追加 `point-detail-order`：设备卡片刻意**逆状态优先级**排列
 * （正常 → 报警 → 预警），后端的返回顺序 ≠ 前端按优先级排出来的顺序 ——
 * 界面若自作主张排序，真机走查里那条「卡片顺序 = 后端顺序」就会当场露馅。
 * 默认样例一个字节未动（票 05 的断言依赖它）。
 */
function pointDetailPayload(scenario) {
    if (scenario === 'empty') {
        return {
            ...pointDetail({ code: 'MP-EMPTY', name: '预留监测点', status: 'EMPTY' }),
            devices: [],
            deviceStatistics: { totalDeviceCount: 0, alarmDeviceCount: 0, warningDeviceCount: 0, workOrderDeviceCount: 0, normalDeviceCount: 0, offlineDeviceCount: 0 },
            statusReasons: [],
        }
    }

    if (scenario === 'degraded') {
        return { monitoringPointCode: 'MP-DEGRADED', monitoringPointName: '字段缺失点位', devices: [], statusReasons: [] }
    }

    if (scenario === 'point-detail-order') {
        const devices = [
            { deviceCode: 'EQ-ORDER-NORMAL', deviceName: '顺序样例-正常设备', deviceTypeName: '压力计', deviceStatus: 'NORMAL', statusLabel: '正常', statusReasons: [], statusTime: '2026-09-02T09:59:30+08:00' },
            { deviceCode: 'EQ-ORDER-ALARM', deviceName: '顺序样例-报警设备', deviceTypeName: '流量计', deviceStatus: 'ALARM', statusLabel: '报警', statusReasons: ['流量超高'], statusTime: '2026-09-02T09:59:40+08:00' },
            { deviceCode: 'EQ-ORDER-WARNING', deviceName: '顺序样例-预警设备', deviceTypeName: '液位计', deviceStatus: 'WARNING', statusLabel: '预警', statusReasons: ['液位偏高'], statusTime: '2026-09-02T09:59:50+08:00' },
        ]
        return {
            ...pointDetail({ code: 'MP-ORDER', name: '顺序样例监测点', status: 'ALARM' }),
            devices,
            deviceStatistics: { totalDeviceCount: 3, alarmDeviceCount: 1, warningDeviceCount: 1, workOrderDeviceCount: 0, normalDeviceCount: 1, offlineDeviceCount: 0 },
            statusReasons: [{ status: 'ALARM', deviceCode: 'EQ-ORDER-ALARM', reason: '流量超高' }],
        }
    }

    return pointDetail()
}

function pointDetail({ code = 'MP-002', name = '燃气调压站监测点', status = 'ALARM' } = {}) {
    const devices = [
        {
            deviceCode: 'EQ-001',
            deviceName: '供水压力计-001',
            deviceTypeName: '压力计',
            deviceStatus: 'ALARM',
            statusLabel: '报警',
            statusReasons: ['压力超高'],
            statusTime: '2026-09-02T09:59:00+08:00',
        },
        {
            deviceCode: 'EQ-002',
            deviceName: '智能井盖-002',
            deviceTypeName: '智能井盖',
            deviceStatus: 'NORMAL',
            statusLabel: '正常',
            statusReasons: [],
            statusTime: '2026-09-02T09:59:30+08:00',
        },
    ]

    return {
        requestId: 'mock-point-detail',
        apiVersion: 'v1',
        readOnly: true,
        monitoringPointCode: code,
        monitoringPointName: name,
        pointStatus: status,
        statusLabel: { ALARM: '报警', WARNING: '预警', WORK_ORDER: '工单处置', NORMAL: '正常', OFFLINE: '离线', EMPTY: '无设备' }[status] || '',
        statusReasons: [{ status, deviceCode: 'EQ-001', reason: '压力超高' }],
        deviceStatistics: {
            totalDeviceCount: devices.length,
            alarmDeviceCount: 1,
            warningDeviceCount: 0,
            workOrderDeviceCount: 0,
            normalDeviceCount: 1,
            offlineDeviceCount: 0,
        },
        devices,
        coordinateValidation: { state: 'VALID', reason: null, renderable: true, crs: 'WGS84' },
        statusDictionary: ['ALARM', 'WARNING', 'WORK_ORDER', 'NORMAL', 'OFFLINE', 'EMPTY'].map((item, index) => ({
            status: item,
            label: { ALARM: '报警', WARNING: '预警', WORK_ORDER: '工单处置', NORMAL: '正常', OFFLINE: '离线', EMPTY: '无设备' }[item],
            priority: index + 1,
        })),
    }
}

// ---------------------------------------------------------------- 设备详情聚合

function aggregateSection(state, reason, data, message) {
    return { state, reason, message: message || null, data }
}

const ARCHIVE = {
    deviceCode: 'TC-PS-WS-202609020012',
    deviceName: '污水环境监测设备',
    deviceModel: 'WS-PRO-2000',
    deviceSpec: '悬浮物/COD/氨氮/电导率/PH',
    manufacturer: '沅陵专用仪表厂',
    deviceTypeName: '污水环境监测设备',
    assetValue: 128000,
    expectedServiceYears: 10,
    equipmentLocation: '太常片区',
    ownershipUnit: '沅陵县排水管理所',
    maintainer: '沅陵运维一组',
    maintainerPhone: '0745-0000000',
    installTime: '2024-03-01T00:00:00+08:00',
    latestImage: { url: '/cockpit/aerial.webp', capturedAt: '2026-08-30T10:20:00+08:00' },
}

const METRICS = {
    deviceCode: ARCHIVE.deviceCode,
    state: 'CURRENT',
    stateReason: 'READY',
    metrics: [
        { metricCode: 'COD', metricName: 'COD', value: 18.2, unit: 'mg/L', status: 'WARNING', sampledAt: '2026-09-02T09:59:30+08:00', freshness: 'CURRENT' },
        // 边界：真实 0 是有效读数，适配层不得当成缺失。
        { metricCode: 'FLOW', metricName: '流量', value: 0, unit: 'm³/h', status: 'NORMAL', sampledAt: '2026-09-02T09:59:30+08:00', freshness: 'CURRENT' },
    ],
}

const WARNING = { warningNo: 'WRN-20260902-001', warningName: '污水COD预警', warningType: 'WS_ENV', level: 2, levelColor: 'YELLOW', status: 'PROCESSING', eventTime: '2026-09-02T09:59:30+08:00', value: 18.2, unit: 'mg/L', deviceCode: ARCHIVE.deviceCode, deviceName: ARCHIVE.deviceName, location: '太常片区' }
const ALARM = { alarmId: 'ALM-20260902-001', warningCode: 'WS_ENV_HIGH', warningName: '污水COD报警', warningType: 'WS_ENV', level: 1, levelColor: 'RED', status: 'UNHANDLED', eventTime: '2026-09-02T10:00:00+08:00', value: 42, thresholdMinValue: 40, thresholdMaxValue: 50, unit: 'mg/L', deviceCode: ARCHIVE.deviceCode, deviceName: ARCHIVE.deviceName, location: '太常片区' }
const RELATION = { relationId: 'REL-001', warningNo: WARNING.warningNo, alarmId: ALARM.alarmId, relatedAt: '2026-09-02T10:00:00+08:00' }
const WORK_ORDER = { workOrderCode: 'WO-2026090200001', deviceCode: ARCHIVE.deviceCode, orderType: 1, orderTypeName: '故障维修', orderLevel: 2, orderDesc: '处理异常', stateCode: 4, stateName: '处理中', createTime: '2026-09-02T09:00:00+08:00', updateTime: '2026-09-02T10:00:00+08:00', planFinishTime: '2026-09-03T09:00:00+08:00', realFinishTime: null, eventAssociation: { eventSource: 'ALARM', eventCode: ALARM.alarmId, associatedAt: '2026-09-02T10:00:00+08:00' } }
const TIMELINE = { workOrder: { ...WORK_ORDER }, timelineEntries: [{ logId: 1, operationName: '创建工单', operationDesc: '待派单', operatorName: '系统', operatedAt: '2026-09-02T09:00:00+08:00' }] }

function equipmentAggregate(scenario, deviceCode = '') {
    const success = aggregateSection('SUCCESS', 'SUCCESS', null)
    // 请求哪台设备就报哪台（与真接口一致，客户端传错编码能看出来）。
    const code = deviceCode || ARCHIVE.deviceCode
    const archive = { ...ARCHIVE, deviceCode: code }

    if (scenario === 'empty') {
        return {
            deviceCode: code,
            aggregateState: 'EMPTY',
            serverTime: SNAPSHOT_AT,
            archive: aggregateSection('EMPTY', 'NO_ARCHIVE', null),
            metrics: aggregateSection('EMPTY', 'NO_METRICS', null),
            warnings: aggregateSection('EMPTY', 'NO_EVENTS', null),
            alarms: aggregateSection('EMPTY', 'NO_EVENTS', null),
            alarmWarningRelations: aggregateSection('EMPTY', 'NO_EVENTS', null),
            workOrders: aggregateSection('EMPTY', 'NO_WORK_ORDERS', null),
            timelines: aggregateSection('EMPTY', 'NO_WORK_ORDERS', null),
            latestImage: aggregateSection('EMPTY', 'NO_IMAGE', null),
        }
    }

    if (scenario === 'degraded') {
        // 字段缺失：档案只剩编码，指标缺 value/unit，工单缺 stateName（靠七态字典补）。
        return {
            deviceCode: code,
            aggregateState: 'READY',
            serverTime: SNAPSHOT_AT,
            archive: aggregateSection('SUCCESS', 'SUCCESS', { deviceCode: code }),
            metrics: aggregateSection('SUCCESS', 'SUCCESS', { deviceCode: code, state: 'CURRENT', stateReason: 'READY', metrics: [{ metricCode: 'COD', metricName: 'COD', sampledAt: '2026-09-02T09:59:30+08:00' }] }),
            warnings: aggregateSection('SUCCESS', 'SUCCESS', [WARNING]),
            alarms: aggregateSection('SUCCESS', 'SUCCESS', [ALARM]),
            alarmWarningRelations: aggregateSection('SUCCESS', 'SUCCESS', [RELATION]),
            workOrders: aggregateSection('SUCCESS', 'SUCCESS', [{ workOrderCode: 'WO-DEGRADED', stateCode: 3 }]),
            timelines: aggregateSection('SUCCESS', 'SUCCESS', [TIMELINE]),
            latestImage: aggregateSection('EMPTY', 'NO_IMAGE', null),
        }
    }

    if (scenario === 'stale') {
        return {
            deviceCode: code,
            aggregateState: 'PARTIAL',
            serverTime: SNAPSHOT_AT,
            archive: aggregateSection('SUCCESS', 'SUCCESS', archive),
            // 过期但保留旧值（票 16：保留最后已知值 + 过期标识）。
            metrics: aggregateSection('STALE', 'SAMPLE_OUTDATED', { ...METRICS, state: 'STALE', stateReason: 'SAMPLE_OUTDATED' }),
            warnings: aggregateSection('SUCCESS', 'SUCCESS', [WARNING]),
            alarms: aggregateSection('SUCCESS', 'SUCCESS', [ALARM]),
            alarmWarningRelations: aggregateSection('SUCCESS', 'SUCCESS', [RELATION]),
            workOrders: aggregateSection('SUCCESS', 'SUCCESS', [WORK_ORDER]),
            timelines: aggregateSection('SUCCESS', 'SUCCESS', [TIMELINE]),
            latestImage: aggregateSection('SUCCESS', 'SUCCESS', archive.latestImage),
        }
    }

    if (scenario === 'equipment-partial') {
        // 票 11 验收第 3 条：任一分区失败不遮盖其它成功分区。
        //
        // 为什么要一个**独立场景名**而不是复用 `failed`：`failed` 在注册层就抛错
        // （整个端点读不到，`data` 为 null），那是"这份详情根本没取到"，
        // 与"取到了、只是其中三块分区各自失败"是两件事。后端契约会把后者原样返回
        // （`aggregateState: PARTIAL` + 每分区自带 state/reason/message），
        // 所以必须有一个能真正走通的样例，否则这条验收在 mock 上无法演示。
        return {
            deviceCode: code,
            aggregateState: 'PARTIAL',
            serverTime: SNAPSHOT_AT,
            archive: aggregateSection('FAILED', 'READ_FAILURE', null, '设备档案数据暂不可用'),
            metrics: aggregateSection('SUCCESS', 'SUCCESS', METRICS),
            warnings: aggregateSection('SUCCESS', 'SUCCESS', [WARNING]),
            alarms: aggregateSection('SUCCESS', 'SUCCESS', [ALARM]),
            alarmWarningRelations: aggregateSection('SUCCESS', 'SUCCESS', [RELATION]),
            workOrders: aggregateSection('FAILED', 'READ_FAILURE', null, '工单数据暂不可用'),
            timelines: aggregateSection('FAILED', 'SOURCE_SECTION_FAILED', null, '工单分区失败，时间线不可用'),
            latestImage: aggregateSection('FAILED', 'SOURCE_SECTION_FAILED', null, '设备档案失败，图片不可用'),
        }
    }

    return {
        deviceCode: code,
        aggregateState: 'READY',
        serverTime: SNAPSHOT_AT,
        archive: { ...success, data: archive },
        metrics: { ...success, data: METRICS },
        warnings: { ...success, data: [WARNING] },
        alarms: { ...success, data: [ALARM] },
        alarmWarningRelations: { ...success, data: [RELATION] },
        workOrders: { ...success, data: [WORK_ORDER] },
        timelines: { ...success, data: [TIMELINE] },
        latestImage: { ...success, data: archive.latestImage },
    }
}

// ---------------------------------------------------------------- 事件与工单

function eventRead(scenario, deviceCode = '') {
    const base = {
        requestId: 'mock-event-read',
        apiVersion: 'v1',
        readOnly: true,
        deviceCode: deviceCode || ARCHIVE.deviceCode,
        deviceType: 'ws_sewage_environment',
        deviceTypeName: '污水环境监测设备',
        startTime: null,
        endTime: null,
        timezone: 'Asia/Shanghai',
        page: 1,
        pageSize: 0,
    }

    if (scenario === 'empty') {
        return { ...base, state: 'EMPTY', stateReason: 'NO_EVENTS', warnings: [], alarms: [], alarmWarningRelations: [], total: 0 }
    }

    if (scenario === 'degraded') {
        // 缺 levelColor 与设备编码：适配层不得猜颜色，也不得伪造归属设备。
        return {
            ...base,
            state: 'READY',
            stateReason: 'READY',
            warnings: [{ warningNo: 'WRN-DEGRADED-001', warningName: '字段缺失预警', level: 2, status: 'PROCESSING', eventTime: '2026-09-02T09:59:30+08:00', unit: 'mg/L' }],
            alarms: [],
            alarmWarningRelations: [],
            total: 1,
        }
    }

    if (scenario === 'stale') {
        return {
            ...base,
            state: 'STALE',
            stateReason: 'SAMPLE_OUTDATED',
            warnings: [{ ...WARNING, freshness: 'STALE' }],
            alarms: [],
            alarmWarningRelations: [],
            total: 1,
        }
    }

    return {
        ...base,
        state: 'READY',
        stateReason: 'READY',
        warnings: [WARNING],
        alarms: [ALARM],
        alarmWarningRelations: [RELATION],
        total: 2,
    }
}

// ---------------------------------------------------------------- 新鲜度

function freshnessPayload(scenario, deviceCode = '') {
    const base = {
        requestId: 'mock-freshness',
        apiVersion: 'v1',
        readOnly: true,
        deviceCode: deviceCode || ARCHIVE.deviceCode,
        serverUpdatedAt: SNAPSHOT_AT,
        calibrationPeriodSeconds: 60,
    }

    if (scenario === 'empty') {
        return { ...base, updatedAt: null, statusTime: null, freshness: 'EMPTY', staleReason: null, missedCycles: 0, dataAgeSeconds: 0, retained: false, message: null }
    }

    if (scenario === 'degraded') {
        // 只给了 freshness，没给任何时间：界面必须显示占位符而不是「0 秒前」。
        return { ...base, freshness: 'CURRENT' }
    }

    if (scenario === 'stale') {
        return { ...base, updatedAt: '2026-09-02T09:58:00+08:00', statusTime: null, freshness: 'EXPIRED', staleReason: 'TWO_UPDATE_CYCLES_MISSED', missedCycles: 2, dataAgeSeconds: 120, retained: true, message: '数据暂不可用/已过期' }
    }

    return { ...base, updatedAt: '2026-09-02T09:59:50+08:00', statusTime: '2026-09-02T09:59:55+08:00', freshness: 'CURRENT', staleReason: null, missedCycles: 0, dataAgeSeconds: 5, retained: false, message: null }
}

// ---------------------------------------------------------------- 注册

/** 各接口在五类样例下的载荷（`failed` 由处理器抛出，不在这里给载荷）。 */
const PAYLOADS = {
    // 票 08：地图摘要按**真实分页语义**给（分页窗口横跨监测点与未关联设备、第 2 页起要求快照一致）。
    '/map-snapshot': (s, _requested, context) => mapSnapshotPayload(s, context.path, context.mapSnapshot),
    '/monitoring-points/*': (s) => pointDetailPayload(s),
    '/equipments/*/detail-aggregate': (s, requested) => equipmentAggregate(s, requested),
    '/equipments/*/events/current': (s, requested) => eventRead(s, requested),
    '/equipments/*/events/history': (s, requested) => eventRead(s, requested),
    '/equipments/*/work-orders': (s) => ({
        requestId: 'mock-work-orders',
        apiVersion: 'v1',
        readOnly: true,
        deviceCode: ARCHIVE.deviceCode,
        eventSource: null,
        eventCode: null,
        state: s === 'empty' ? 'EMPTY' : 'READY',
        stateReason: s === 'empty' ? 'NO_WORK_ORDERS' : 'READY',
        stateDictionary: [
            { code: 1, name: '待派单' },
            { code: 2, name: '待接单' },
            { code: 3, name: '已接单' },
            { code: 4, name: '处理中' },
            { code: 5, name: '待验收' },
            { code: 6, name: '已结案' },
            { code: 7, name: '已取消' },
        ],
        workOrders: s === 'empty' ? [] : [WORK_ORDER],
    }),
    '/work-orders/*/timeline': (s) => (s === 'empty' ? { workOrder: null, timelineEntries: [] } : TIMELINE),
    '/equipments/*/freshness': (s, requested) => freshnessPayload(s, requested),
    '/equipments/*/archive': (s) => (s === 'empty' ? null : ARCHIVE),
}

/**
 * 从请求路径里取出模板 `*` 命中的那一段（即路径参数）。
 * `('/equipments/TC-1/detail-aggregate', '/equipments/' + '*' + '/detail-aggregate')` → `TC-1`。
 * 模板里有多个 `*` 时只取第一个——当前接口最多一个路径参数，够用且不猜。
 */
function pathParameter(requestPath, template) {
    const star = template.indexOf('*')
    if (star === -1) return ''

    const prefix = template.slice(0, star)
    const suffix = template.slice(star + 1)
    const bare = String(requestPath || '').split('?')[0]

    if (!bare.startsWith(prefix)) return ''
    const rest = bare.slice(prefix.length)
    const end = suffix ? rest.indexOf(suffix) : rest.length
    if (end === -1) return ''
    return decodeURIComponent(rest.slice(0, end))
}

/**
 * 注册全部契约化 mock。
 * @param {object} [options]
 * @param {string} [options.scenario] `success`（默认）/`empty`/`degraded`/`stale`/`failed`/`unauthorized`
 * @param {string} [options.onlyPath] 只让这一个路径走「异常样例」，其余保持 `success`
 *        —— 票 05 验收第 6 条要的正是「只把**受影响分区**标为数据不可用」，
 *        所以必须能只让一个分区坏掉、其余照常成功。
 * @param {(path: string) => boolean} [options.only] 同上，函数形式（便于按前缀选中一族接口）
 * @param {string} [options.prefix] 同上，按路径前缀选中一族接口（`/equipments/`）
 * @param {object} [options.mapSnapshot] 地图摘要分页的现场覆盖（票 08 走查用）：
 *        `{ pageSize, snapshotAt, expireAfterPage }`
 * @param {object} handlers services/cockpitApi.js 的三个注册函数（注入以便单测）
 */
export function registerCockpitMocks(options = {}) {
    const { scenario = 'success', onlyPath = '', prefix = '', handlers } = options
    const mapSnapshot = options.mapSnapshot || {}
    // `prefix` 是 `only` 的便捷写法：两者都给时以 `only` 为准。
    const only = options.only || (prefix ? (path) => path.startsWith(prefix) : null)
    const register = (handlers && handlers.registerMockTransport) || null
    if (!register) {
        throw new Error('registerCockpitMocks 需要注入 registerMockTransport')
    }
    const reset = (handlers && handlers.resetMockTransportsForTest) || null

    if (reset) reset()

    const targets = new Set()

    for (const [path, build] of Object.entries(PAYLOADS)) {
        const applies = !onlyPath && !only ? true : only ? !!only(path) : path === onlyPath
        const active = applies ? scenario : 'success'

        register(path, async (context) => {
            // `failed`：抛出让统一出口归类成「不可用」，模拟分区自己读取失败。
            if (active === 'failed') {
                throw new Error(`mock: ${path} 读取失败`)
            }
            if (active === 'unauthorized') {
                // 401 不是载荷：把凭据类失败原因交给统一出口归类，
                // 由它回 `{ok:false, reason:'unauthorized'}`（服务层只认白名单里的原因）。
                const error = new Error('mock: 凭据未通过校验')
                error.reason = REQUEST_REASON.UNAUTHORIZED
                throw error
            }

            // 带路径参数的接口回显请求里的编码：这样「按编码取数」的行为与真接口一致
            // （客户端传错编码时能看出来，而不是永远拿到同一台设备）。
            const requested = pathParameter(context.path, path)
            const payload = build(active, requested, { path: context.path, mapSnapshot })
            if (!requested) return payload

            if (path === '/monitoring-points/*') {
                return { ...payload, monitoringPointCode: requested }
            }
            // 设备族接口：统一把请求的设备编码写回载荷（设备详情/事件/工单/新鲜度/档案都一样）。
            if (typeof payload === 'object' && payload !== null && 'deviceCode' in payload) {
                return { ...payload, deviceCode: requested }
            }
            return payload
        })

        targets.add(path)
    }

    return { scenario, paths: [...targets], isolated: onlyPath || prefix || (only ? 'predicate' : '') }
}