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

/**
 * 契约化 mock 的注册入口（票 05）。
 *
 * 为什么要有这一层而不是让页面直接 import `contractMocks.js`：
 * 「注册」与「样例数据」分开——页面只调用 `ensureCockpitMocks()`，
 * 换样例（走查要演示 401/空/过期）不改页面代码。
 *
 * 场景覆盖（走查与人工演示都用同一套开关，无需改代码重新构建）：
 *   `window.__COCKPIT_MOCK_SCENARIO__` = `success`（默认）| `empty` | `degraded` | `stale` | `failed` | `unauthorized`
 *       票 09 追加 `point-statuses`：后端六态 + 未关联设备 + 一个前端不认识的状态，全部可上图。
 *       它只影响 `/map-snapshot` 的样例内容，不改默认场景的任何数字（票 07/08 的断言依赖那些数）。
 *       票 10 追加 `point-detail-order`：设备卡片逆状态优先级排列，验「顺序由后端返回顺序决定」。
 *       票 11 追加 `equipment-partial`：设备详情**分区级部分失败**（档案/工单/图片各自 FAILED，
 *       指标/预警/报警照常 SUCCESS），验「任一分区失败不遮盖其它成功分区」。它与 `failed` 不同：
 *       `failed` 是端点整体读不到（`data` 为 null），那是"详情没取到"而不是"取到了但有坏块"。
 *       票 12 追加 `work-order-timeline`：四张工单各一条独立时间线（一路推进 / 待验收回退处理中 /
 *       延期中旁路 / 已取消四种形状都齐），验状态时间线与「验收驳回是回退动作而不是独立终态」。
 *       追加 `work-order-timeline-failed`：**只有时间线分区失败**、工单列表照常成功 ——
 *       验「轨迹没取到」与「这张工单没有动作记录」是两句不同的话。
 *       票 45 追加 `device-layer-overlap-degraded`：11 台设备同坐标（K=11 > maxFan=10），
 *       验「本屏显示 10 台 / 其余见清单」降级形态与预警模式的状态过滤。
 *       票 17 追加 `infrastructure-partial`：应急保障的「防护目标」段没取到，其余段照常画 ——
 *       验「一段没取到」与「这一段确实没有对象」是两句不同的话。
 *       票 18 追加 `monitoring-no-devices`：运行监测的在线率**分母为 0**
 *       （后端回 `state=EMPTY` + `value="0.0000"`）—— 验「没有可算的设备」不被画成「在线率 0.0%」。
 *       注意这些场景名只被**它自己那族的 builder** 认；别的端点认不出就照 `success` 走
 *       （所以 `monitoring-no-devices` 不会把地图或基础设施打空）。
 *   `window.__COCKPIT_MOCK_ONLY__`     = 只让这一个路径走上面的异常样例，其余保持成功
 *        （票 05 验收第 6 条要的正是「只把**受影响分区**标为数据不可用」）
 *   `window.__COCKPIT_MOCK_PREFIX__`   = 同上，按路径前缀选中一族接口（如 `/equipments/`）
 *   `window.__COCKPIT_MOCK_MAP__`      = 地图摘要分页的现场覆盖（票 08）：
 *        `{ pageSize, snapshotAt, expireAfterPage }`
 *        —— 例如 `{ pageSize: 2, expireAfterPage: 1 }` 演示「取完第 1 页后快照失效」
 *
 * 注册是幂等的：重复调用只覆盖，不叠加。
 */
import {
    getMockTransportPaths,
    registerMockTransport,
    resetMockTransportsForTest,
} from '../services/cockpitApi.js'
import { registerCockpitMocks } from './contractMocks.js'

/** 只读全局开关（走查用；生产不会设这些键）。 */
function readScenario() {
    if (typeof globalThis === 'undefined') return {}
    return {
        scenario: globalThis.__COCKPIT_MOCK_SCENARIO__ || 'success',
        onlyPath: globalThis.__COCKPIT_MOCK_ONLY__ || '',
        prefix: globalThis.__COCKPIT_MOCK_PREFIX__ || '',
        mapSnapshot: globalThis.__COCKPIT_MOCK_MAP__ || {},
        // 票 18：运行监测的现场覆盖（`{ pageSize }`）。后端页大小默认 500，而样例只有 8 条，
        // 压不小就演示不出台账的渐进加载（走查 B 组靠它）。
        monitoring: globalThis.__COCKPIT_MOCK_MONITORING__ || {},
    }
}

/** 注册全部契约化 mock（幂等）。返回本次生效的场景，便于走查/排查。 */
export function ensureCockpitMocks(overrides = {}) {
    const global = readScenario()
    const scenario = overrides.scenario || global.scenario
    const onlyPath = overrides.onlyPath || global.onlyPath
    const prefix = overrides.prefix || global.prefix
    const mapSnapshot = overrides.mapSnapshot || global.mapSnapshot
    const monitoring = overrides.monitoring || global.monitoring

    const result = registerCockpitMocks({
        scenario,
        onlyPath,
        prefix,
        mapSnapshot,
        monitoring,
        handlers: { registerMockTransport, getMockTransportPaths, resetMockTransportsForTest },
    })

    return result
}