City-Lifeline-Cockpit/src/modules/cockpit/services/cockpitConfig.js

/**
 * 驾驶舱配置服务（票 04）：后端地址、天地图、Cesium、WebSocket 与凭据的唯一读入口。
 *
 * 为什么要有这一层（spec 第 13/14 条、ADR 0005）：
 * 前端不硬编码账号、密钥或环境地址；配置由部署层注入；页面与 store 只读归一化后的结果。
 *
 * 分层（后者覆盖前者，深合并）：
 *   1. 内置默认        —— `dataSource: mock`（spec：默认 mock，真接口必须显式开启）
 *   2. 构建期环境变量  —— `import.meta.env.VITE_COCKPIT_*`（本机联调写 `.env.local`，已 gitignore）
 *   3. 运行时配置文件  —— `<base>cockpit/config.json`（部署时放/改，同一个构建多环境）
 *   4. 宿主注入对象    —— `globalThis.__COCKPIT_CONFIG__`（qiankun 主应用 / 网关注入；给了就不再拉文件）
 *
 * 三态：`ready`（载入成功）/ `missing`（没有任何配置来源，用内置默认）/ `failed`（拿到了但不可用）。
 *
 * 运行时文件**不会**在每次加载时盲试：没有显式配置 URL 就不发请求（否则每页都会刷一个 404，
 * 生产日志也会变脏）。要启用文件层，二选一：
 *   · 宿主页加一行 `window.__COCKPIT_CONFIG_URL__ = 'auto'`（`auto` = 按应用基址取 `cockpit/config.json`，
 *     qiankun / 子目录部署下都对）；给绝对 URL 则直接从后端或别处拉配置；给空串 = 这个页面不要配置文件；
 *   · 构建期设 `VITE_COCKPIT_CONFIG_URL`（同样接受 `auto` 或具体 URL）。宿主页的键优先于构建期。
 * 文件不存在（404）或载荷是 HTML（静态服务器的错误页）都判为缺失态，不当作故障。
 */
import { CONFIG_STATE, CREDENTIAL, DATA_SOURCE } from '../domain/configStatus.js'
import { BASEMAP_SOURCE } from '../domain/basemap.js'
import { planPrimaryArea, PRIMARY_AREA_OFF_SUFFIX } from '../domain/primaryArea.js'
import { parseHexColor } from '../domain/fog.js'

/** 部署把配置文件放在这个相对路径下：`public/cockpit/config.json` → 产物 `cockpit/config.json`。 */
export const CONFIG_FILE_PATH = 'cockpit/config.json'

/** 显式 URL 的特殊取值：按应用基址取约定路径（qiankun / 子目录部署下也正确）。 */
export const CONFIG_URL_AUTO = 'auto'

/** 宿主注入用的全局键。 */
export const INJECTED_CONFIG_KEY = '__COCKPIT_CONFIG__'
export const INJECTED_CONFIG_URL_KEY = '__COCKPIT_CONFIG_URL__'

/** 构建期环境变量键（Vite 只把 `VITE_` 前缀暴露给客户端）。 */
export const ENV_KEYS = {
    dataSource: 'VITE_COCKPIT_DATA_SOURCE',
    apiBaseUrl: 'VITE_COCKPIT_API_BASE_URL',
    apiToken: 'VITE_COCKPIT_API_TOKEN',
    wsUrl: 'VITE_COCKPIT_WS_URL',
    wsToken: 'VITE_COCKPIT_WS_TOKEN',
    tiandituToken: 'VITE_COCKPIT_TIANDITU_TOKEN',
    cesiumBaseUrl: 'VITE_COCKPIT_CESIUM_BASE_URL',
    basemapSource: 'VITE_COCKPIT_BASEMAP_SOURCE',
    basemapUrl: 'VITE_COCKPIT_BASEMAP_URL',
    configUrl: 'VITE_COCKPIT_CONFIG_URL',
}

function isPlainObject(value) {
    return !!value && typeof value === 'object' && !Array.isArray(value)
}

/** 内置默认：没有任何配置来源时也必须是可跑的状态（mock + 不伪造凭据）。 */
export function builtinConfig() {
    return {
        version: 1,
        dataSource: DATA_SOURCE.MOCK,
        api: { baseUrl: '', token: '' },
        ws: { url: '', token: '' },
        // 票 16：刷新周期（秒）。`refreshSeconds` = 一个「周期」的长度；轮询与新鲜度判定都读它。
        // 默认 30 秒（决策：前端轮询 + WS 断线也算失败周期）。
        runtime: { refreshSeconds: 30, polling: true },
        map: {
            basemap: {
                source: BASEMAP_SOURCE.NONE,
                url: '',
                subdomains: [],
                minimumLevel: null,
                maximumLevel: null,
                credit: '',
            },
            tianditu: { token: '', layer: 'img' },
            terrain: { url: '', requestVertexNormals: true },
            overlays: [],
            tilesets: [],
            home: { lon: null, lat: null, height: null, heading: null, pitch: null, range: null, label: '' },
            intro: { enabled: true, title: '', subtitle: '', spinSeconds: null },
            locate: {
                point: { heading: null, pitch: null, range: null },
                device: { heading: null, pitch: null, range: null },
            },
            // 票 36：主场景区矩形。`configured=false` = 本部署没给（限位与自建雾随之关闭）；
            // 内置默认里**故意不预置任何地理常量**（决策票 01 Q3=A：兜底由部署期算、不写死源码）。
            primaryArea: { bounds: null, configured: false },
            // 票 21：地面/管线视图的取值覆盖（不配就用 domain/viewModes.js 的默认）
            viewMode: { pitch: null, rangeFactor: null, terrainAlpha: null, tilesetAlpha: null },

            // 票 38：区内视距雾气。null/'' = 用 `domain/fog.js` 的**规格默认**
            // （18,000/42,000 m、#bdcdd6）；即"不配就是规格定的那一套"，与票 21 同一立场。
            fog: {
                enabled: true,
                startDistance: null,
                endDistance: null,
                color: '',
                fadeInMs: null,
                fadeOutMs: null,
                // 相机高度收口（见 `domain/fog.js` 的 `fogAltitudeFactor`）：
                // 不设它，相机升到高空时会把整个地球涂成雾色（维护者 2026-09-29 实报）。
                altitudeFullM: null,
                altitudeZeroM: null,
                // 这层收口的**时间限速**（见 `approachAltitudeFactor`）：不设它，
                // 返回全球时相机头一帧就越过整条雾带 ⇒ 雾"一瞬间就散了"（同日第二次实报）。
                altitudeSlewMs: null,
            },
            // 票 39：粗→精影像交接。null = 用 `domain/imageryHandover.js` 的默认
            // （渐显 380 ms、边缘遮蔽率 ≥0.9、要求瓦片就绪）。`enabled=false` = 精细层常显。
            handover: {
                enabled: true,
                fadeMs: null,
                minEdgeOcclusion: null,
                requireTilesLoaded: null,
            },
            // 一张图调色（科技蓝滤镜）。null/'' = 用 `domain/sceneGrade.js` 的默认
            // （降饱和 0.82 / 亮度 0.96 / 对比 1.08 / #2fa8ff / 阴影混合 0.18）；
            // `enabled=false` = 整级关掉。色彩口径（含"不做双色"红线）全在 domain，这里只透传。
            grade: {
                enabled: true,
                saturation: null,
                brightness: null,
                contrast: null,
                tint: '',
                tintStrength: null,
            },
            // 票 45：重叠设备展开阈值（K>maxFan 降级为聚合符号 + 清单提示）。
            overlap: { maxFan: 10 },
            // 票 47：设备状态动效（决策票 07）。`enabled: null` = 跟随构建形态；
            // `abnormalLimit` = 同屏异常设备上限，超过即动画全停并降级为静态 + 计数。
            effects: { enabled: null, abnormalLimit: 30 },
            // 票 32：UI 形态。null = 跟随构建模式（dev 显示调试信息，生产构建自动收敛）
            ui: { debug: null },
            cesium: { enabled: true, baseUrl: '' },
        },
    }
}

function readString(value, fallback, issues, label) {
    if (value === undefined || value === null || value === '') return fallback
    if (typeof value !== 'string') {
        issues.push(`${label} 应为字符串，收到 ${typeof value}，已退回默认`)
        return fallback
    }
    return value.trim()
}

function readBoolean(value, fallback, issues, label) {
    if (value === undefined || value === null) return fallback
    if (typeof value !== 'boolean') {
        issues.push(`${label} 应为布尔值，收到 ${typeof value}，已退回默认`)
        return fallback
    }
    return value
}

function readStringArray(value, issues, label) {
    if (value === undefined || value === null || value === '') return []
    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
        issues.push(`${label} 应为字符串数组，已忽略`)
        return []
    }
    return value.map((item) => item.trim()).filter(Boolean)
}

function readLevel(value, issues, label) {
    if (value === undefined || value === null || value === '') return null
    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
        issues.push(`${label} 应为非负整数，收到 ${JSON.stringify(value)}，已忽略`)
        return null
    }
    return value
}

function readNumber(value, issues, label) {
    if (value === undefined || value === null || value === '') return null
    if (typeof value !== 'number' || !Number.isFinite(value)) {
        issues.push(`${label} 应为数字，收到 ${JSON.stringify(value)}，已忽略`)
        return null
    }
    return value
}

function readNonNegativeNumber(value, issues, label) {
    const number = readNumber(value, issues, label)
    if (number !== null && number < 0) {
        issues.push(`${label} 应为非负数字，收到 ${JSON.stringify(value)}，已忽略`)
        return null
    }
    return number
}

/**
 * DEV 走查桥（票 76，与 `?overlay=0` 同一入口风格）：`?dataSource=mock|real` 覆盖配置的 dataSource。
 *
 * 为什么放在配置层：dataSource 决定 `planCockpitStartup()` 走哪条启动分支（只有 mock 注册契约样例），
 * 覆盖必须发生在**归一化之后、启动计划之前**；放在页面里会让两处各判一次。
 * 仅 DEV 生效，值只认 mock/real，其余原样返回（不猜、不改正式路径默认值）。
 *
 * 用法：`http://127.0.0.1:8000/?dataSource=mock&scenario=device-layer-overlap-degraded#/cockpit`
 *   —— `scenario` 由 `mocks/index.js` 的 `readScenario()` 读，用来出 K>1 聚合场景。
 *
 * @param {object} config 已归一化配置
 * @param {Location} [location] 可注入（脱浏览器断言用）
 * @param {boolean} [isDev] 是否开发构建
 */
export function withUrlDataSourceOverride(config, location = null, isDev = false) {
    if (!isDev || !config) return config
    const loc = location || (typeof globalThis !== 'undefined' ? globalThis.location : null)
    if (!loc) return config
    let value = ''
    try {
        const hashQuery = String(loc.hash || '').split('?')[1] || ''
        value = new URLSearchParams(loc.search || '').get('dataSource')
            || new URLSearchParams(hashQuery).get('dataSource')
            || ''
    } catch (error) {
        value = ''
    }
    const next = String(value || '').toLowerCase()
    if (next !== DATA_SOURCE.MOCK && next !== DATA_SOURCE.REAL) return config
    return { ...config, dataSource: next }
}

/**
 * 归一化 + 宽松校验：不认识的取值退回默认并记一条 issue，不因为一个错字段整份配置作废。
 * @param {object} raw 合并后的原始配置
 * @returns {{config: object, issues: string[]}}
 */
export function normalizeConfig(raw) {
    const config = builtinConfig()
    const issues = []
    if (!isPlainObject(raw)) {
        if (raw !== undefined && raw !== null) issues.push('配置不是对象，已全部退回内置默认')
        return { config, issues }
    }

    if (raw.dataSource !== undefined && raw.dataSource !== null) {
        if (raw.dataSource === DATA_SOURCE.REAL || raw.dataSource === DATA_SOURCE.MOCK) {
            config.dataSource = raw.dataSource
        } else {
            issues.push(`dataSource 只认 mock/real，收到 ${JSON.stringify(raw.dataSource)}，已退回 mock`)
        }
    }

    const api = isPlainObject(raw.api) ? raw.api : {}
    const ws = isPlainObject(raw.ws) ? raw.ws : {}
    const map = isPlainObject(raw.map) ? raw.map : {}
    const runtime = isPlainObject(raw.runtime) ? raw.runtime : {}
    const basemap = isPlainObject(map.basemap) ? map.basemap : {}
    const tianditu = isPlainObject(map.tianditu) ? map.tianditu : {}
    const cesium = isPlainObject(map.cesium) ? map.cesium : {}

    config.api.baseUrl = readString(api.baseUrl, config.api.baseUrl, issues, 'api.baseUrl')
    config.api.token = readString(api.token, config.api.token, issues, 'api.token')
    config.ws.url = readString(ws.url, config.ws.url, issues, 'ws.url')
    config.ws.token = readString(ws.token, config.ws.token, issues, 'ws.token')

    // 票 16：刷新周期（秒）。必须是正数 —— 0 或负数会让「连续两个周期」永远不成立。
    const refreshSeconds = readNumber(runtime.refreshSeconds, issues, 'runtime.refreshSeconds')
    if (refreshSeconds !== null) {
        if (refreshSeconds > 0) config.runtime.refreshSeconds = refreshSeconds
        else issues.push(`runtime.refreshSeconds 应为正数，收到 ${JSON.stringify(runtime.refreshSeconds)}，已退回 ${config.runtime.refreshSeconds}`)
    }
    config.runtime.polling = readBoolean(runtime.polling, config.runtime.polling, issues, 'runtime.polling')

    const knownSources = Object.values(BASEMAP_SOURCE)
    if (basemap.source !== undefined && basemap.source !== null && basemap.source !== '') {
        if (knownSources.includes(basemap.source)) {
            config.map.basemap.source = basemap.source
        } else {
            issues.push(`map.basemap.source 只认 ${knownSources.join('/')}，收到 ${JSON.stringify(basemap.source)}，已退回 none`)
        }
    }
    config.map.basemap.url = readString(basemap.url, '', issues, 'map.basemap.url')
    config.map.basemap.credit = readString(basemap.credit, '', issues, 'map.basemap.credit')
    config.map.basemap.subdomains = readStringArray(basemap.subdomains, issues, 'map.basemap.subdomains')
    config.map.basemap.minimumLevel = readLevel(basemap.minimumLevel, issues, 'map.basemap.minimumLevel')
    config.map.basemap.maximumLevel = readLevel(basemap.maximumLevel, issues, 'map.basemap.maximumLevel')

    config.map.tianditu.token = readString(tianditu.token, '', issues, 'map.tianditu.token')
    if (tianditu.layer !== undefined && tianditu.layer !== null && tianditu.layer !== '') {
        if (['img', 'vec', 'ter'].includes(tianditu.layer)) {
            config.map.tianditu.layer = tianditu.layer
        } else {
            issues.push(`map.tianditu.layer 只认 img/vec/ter，收到 ${JSON.stringify(tianditu.layer)}，已退回 img`)
        }
    }
    config.map.cesium.enabled = readBoolean(cesium.enabled, config.map.cesium.enabled, issues, 'map.cesium.enabled')
    config.map.cesium.baseUrl = readString(cesium.baseUrl, '', issues, 'map.cesium.baseUrl')

    // 票 21：地形（本地/甲方 DEM）与叠加影像（本地精细切片）
    const terrain = isPlainObject(map.terrain) ? map.terrain : {}
    config.map.terrain.url = readString(terrain.url, '', issues, 'map.terrain.url')
    config.map.terrain.requestVertexNormals = readBoolean(
        terrain.requestVertexNormals,
        config.map.terrain.requestVertexNormals,
        issues,
        'map.terrain.requestVertexNormals',
    )

    if (map.overlays !== undefined && map.overlays !== null && !Array.isArray(map.overlays)) {
        issues.push('map.overlays 应为数组，已忽略')
    } else {
        config.map.overlays = (map.overlays || []).map((item, index) => {
            const overlay = isPlainObject(item) ? item : {}
            const bounds = Array.isArray(overlay.bounds) && overlay.bounds.length === 4 && overlay.bounds.every((n) => typeof n === 'number')
            if (overlay.bounds !== undefined && overlay.bounds !== null && !bounds) {
                issues.push(`map.overlays[${index}].bounds 应为 [west, south, east, north] 四个数字，已忽略`)
            }
            return {
                url: readString(overlay.url, '', issues, `map.overlays[${index}].url`),
                minimumLevel: readLevel(overlay.minimumLevel, issues, `map.overlays[${index}].minimumLevel`),
                maximumLevel: readLevel(overlay.maximumLevel, issues, `map.overlays[${index}].maximumLevel`),
                bounds: bounds ? overlay.bounds.slice() : null,
                credit: readString(overlay.credit, '', issues, `map.overlays[${index}].credit`),
            }
        })
    }

    // 3D Tiles / 倾斜摄影入口（票 21）：每项一个 tileset URL
    if (map.tilesets !== undefined && map.tilesets !== null && !Array.isArray(map.tilesets)) {
        issues.push('map.tilesets 应为数组，已忽略')
    } else {
        config.map.tilesets = (map.tilesets || []).map((item, index) => {
            const tileset = isPlainObject(item) ? item : {}
            return {
                url: readString(tileset.url, '', issues, `map.tilesets[${index}].url`),
                maximumScreenSpaceError: readNonNegativeNumber(
                    tileset.maximumScreenSpaceError,
                    issues,
                    `map.tilesets[${index}].maximumScreenSpaceError`,
                ),
                maximumDistance: readNonNegativeNumber(
                    tileset.maximumDistance,
                    issues,
                    `map.tilesets[${index}].maximumDistance`,
                ),
                loadDistance: readNonNegativeNumber(
                    tileset.loadDistance,
                    issues,
                    `map.tilesets[${index}].loadDistance`,
                ),
                eager: readBoolean(tileset.eager, true, issues, `map.tilesets[${index}].eager`),
                role: readString(tileset.role, '', issues, `map.tilesets[${index}].role`),
                credit: readString(tileset.credit, '', issues, `map.tilesets[${index}].credit`),
                regionManifest: readString(tileset.regionManifest, '', issues, `map.tilesets[${index}].regionManifest`),
                progressiveRefinement: readBoolean(tileset.progressiveRefinement, false, issues, `map.tilesets[${index}].progressiveRefinement`),
                ...(tileset.lighting === undefined ? {} : { lighting: readBoolean(tileset.lighting, false, issues, `map.tilesets[${index}].lighting`) }),
            }
        })
    }

    // 视角预设与进入引导（票 30）：坐标/开关都由配置给，组件不硬编码
    const home = isPlainObject(map.home) ? map.home : {}
    config.map.home = {
        lon: readNumber(home.lon, issues, 'map.home.lon'),
        lat: readNumber(home.lat, issues, 'map.home.lat'),
        height: readNumber(home.height, issues, 'map.home.height'),
        heading: readNumber(home.heading, issues, 'map.home.heading'),
        pitch: readNumber(home.pitch, issues, 'map.home.pitch'),
        range: readNumber(home.range, issues, 'map.home.range'),
        label: readString(home.label, '', issues, 'map.home.label'),
    }

    const locate = isPlainObject(map.locate) ? map.locate : {}
    for (const tier of ['point', 'device']) {
        const source = isPlainObject(locate[tier]) ? locate[tier] : {}
        config.map.locate[tier] = {
            heading: readNumber(source.heading, issues, `map.locate.${tier}.heading`),
            pitch: readNumber(source.pitch, issues, `map.locate.${tier}.pitch`),
            range: readNumber(source.range, issues, `map.locate.${tier}.range`),
        }
        if (config.map.locate[tier].range !== null && config.map.locate[tier].range <= 0) {
            issues.push(`map.locate.${tier}.range 应为正数，已退回默认`)
            config.map.locate[tier].range = null
        }
    }

    const intro = isPlainObject(map.intro) ? map.intro : {}
    config.map.intro = {
        enabled: readBoolean(intro.enabled, config.map.intro.enabled, issues, 'map.intro.enabled'),
        title: readString(intro.title, '', issues, 'map.intro.title'),
        subtitle: readString(intro.subtitle, '', issues, 'map.intro.subtitle'),
        spinSeconds: readNumber(intro.spinSeconds, issues, 'map.intro.spinSeconds'),
    }

    // 票 36：主场景区（`map.primaryArea.bounds` = `[west, south, east, north]` 度）。
    //
    // 判定收在 `domain/primaryArea.js`（形状 / `west<east`、`south<north`），这里只做两件事：
    //   ① 原样收下部署给的数组 —— **绝不自动翻转**（决策票 01 Q2=A：写好顺序是部署的责任，
    //      运行时翻转会让「配置抄错」在运行期隐身）；
    //   ② 不可用时记进配置问题清单并**保留原因**，运行期据此走关闭路径（限位与自建雾一起关）。
    // 没给 `map.primaryArea` 时维持内置默认的 `configured: false`（= 未配置，同样关闭）。
    if (map.primaryArea !== undefined && map.primaryArea !== null && !isPlainObject(map.primaryArea)) {
        issues.push('map.primaryArea 应为对象，已忽略（主场景区限位与雾气关闭）')
    } else if (isPlainObject(map.primaryArea)) {
        const bounds = map.primaryArea.bounds
        config.map.primaryArea = { bounds: Array.isArray(bounds) ? bounds.slice() : null, configured: true }
        const areaPlan = planPrimaryArea(config.map)
        if (!areaPlan.enabled) {
            issues.push(`map.primaryArea.bounds ${areaPlan.reason}，已按关闭处理（${PRIMARY_AREA_OFF_SUFFIX}）`)
        }
    }

    // 票 38：区内视距雾气（不配就用 `domain/fog.js` 的规格默认）。
    // 只做「宽松归一化」：数值/色值不合法就置空 → 由计划层退回规格默认并留原因，
    // **不在这里判业务口径**（曲线端点语义、色相判据都在 domain，只有一处）。
    const fog = isPlainObject(map.fog) ? map.fog : {}
    config.map.fog = {
        enabled: readBoolean(fog.enabled, true, issues, 'map.fog.enabled'),
        startDistance: readNumber(fog.startDistance, issues, 'map.fog.startDistance'),
        endDistance: readNumber(fog.endDistance, issues, 'map.fog.endDistance'),
        color: readString(fog.color, '', issues, 'map.fog.color'),
        fadeInMs: readNumber(fog.fadeInMs, issues, 'map.fog.fadeInMs'),
        fadeOutMs: readNumber(fog.fadeOutMs, issues, 'map.fog.fadeOutMs'),
        altitudeFullM: readNumber(fog.altitudeFullM, issues, 'map.fog.altitudeFullM'),
        altitudeZeroM: readNumber(fog.altitudeZeroM, issues, 'map.fog.altitudeZeroM'),
        altitudeSlewMs: readNumber(fog.altitudeSlewMs, issues, 'map.fog.altitudeSlewMs'),
    }
    // 色值写法错了要报出来（否则会静默用默认色，维护者以为改生效了）。
    if (config.map.fog.color && !parseHexColor(config.map.fog.color)) {
        issues.push(`map.fog.color 应为 #rrggbb，收到 ${JSON.stringify(config.map.fog.color)}，已退回默认色`)
        config.map.fog.color = ''
    }
    if (Number.isFinite(config.map.fog.startDistance) && Number.isFinite(config.map.fog.endDistance)
        && config.map.fog.endDistance <= config.map.fog.startDistance) {
        issues.push('map.fog.endDistance 必须大于 map.fog.startDistance，已退回规格默认端点')
        config.map.fog.startDistance = null
        config.map.fog.endDistance = null
    }
    // 相机高度收口的**两端也必须同向**：`altitudeZeroM` 必须大于 `altitudeFullM`。
    // 写反（例如 full=160000 / zero=2000）会让 `fogAltitudeFactor` 恒为 1 —— 等于**关掉**这层保护，
    // 而它正是"退出时整个地球变白"的防护（见 `FOG_DEFAULTS.altitudeFullM` 的注释）。
    //
    // 与上面那对不同，这里**只报不改**：`full` 与 `zero` 两个数各自都是合法的（不像
    // endDistance 写小了就是退化），"要不要在某个高度之上保留雾"是部署的取舍，
    // 替它选一边就是拿假值覆盖真意图。但**绝不能静默**：不然维护者会以为保护还在。
    if (Number.isFinite(config.map.fog.altitudeFullM) && Number.isFinite(config.map.fog.altitudeZeroM)
        && config.map.fog.altitudeZeroM <= config.map.fog.altitudeFullM) {
        issues.push(
            'map.fog.altitudeZeroM 必须大于 map.fog.altitudeFullM，'
            + '否则相机高度收口恒为 1（等于关闭该保护，退出时可能出现整个地球变白）',
        )
    }

    // 票 39：粗→精影像交接（不配就用 `domain/imageryHandover.js` 的默认）。
    const handover = isPlainObject(map.handover) ? map.handover : {}
    config.map.handover = {
        enabled: readBoolean(handover.enabled, true, issues, 'map.handover.enabled'),
        fadeMs: readNumber(handover.fadeMs, issues, 'map.handover.fadeMs'),
        minEdgeOcclusion: readNumber(handover.minEdgeOcclusion, issues, 'map.handover.minEdgeOcclusion'),
        requireTilesLoaded: readBoolean(handover.requireTilesLoaded, null, issues, 'map.handover.requireTilesLoaded'),
    }
    // 遮蔽率是 0–1 的比例；给个 >1 或负数会静默让闸门永远（不）通过 —— 退回默认并记 issue。
    if (Number.isFinite(config.map.handover.minEdgeOcclusion)
        && (config.map.handover.minEdgeOcclusion < 0 || config.map.handover.minEdgeOcclusion > 1)) {
        issues.push('map.handover.minEdgeOcclusion 应在 0–1 之间，已退回默认（0.9）')
        config.map.handover.minEdgeOcclusion = null
    }

    // 一张图调色（科技蓝滤镜）：宽松归一化（同雾/交接）—— 数值/色值不合法就置空，
    // 由 `domain/sceneGrade.js` 的计划层退回默认；"不做双色"等口径全在 domain，只此一份。
    const gradeConf = isPlainObject(map.grade) ? map.grade : {}
    config.map.grade = {
        enabled: readBoolean(gradeConf.enabled, true, issues, 'map.grade.enabled'),
        saturation: readNumber(gradeConf.saturation, issues, 'map.grade.saturation'),
        brightness: readNumber(gradeConf.brightness, issues, 'map.grade.brightness'),
        contrast: readNumber(gradeConf.contrast, issues, 'map.grade.contrast'),
        tint: readString(gradeConf.tint, '', issues, 'map.grade.tint'),
        tintStrength: readNumber(gradeConf.tintStrength, issues, 'map.grade.tintStrength'),
    }
    // 色值写法错了要报出来（否则会静默用默认色，维护者以为改生效了）—— 与 map.fog.color 同款。
    if (config.map.grade.tint && !parseHexColor(config.map.grade.tint)) {
        issues.push(`map.grade.tint 应为 #rrggbb，收到 ${JSON.stringify(config.map.grade.tint)}，已退回默认色`)
        config.map.grade.tint = ''
    }

    // 票 21：地面/管线视图的取值覆盖（缺省用 domain/viewModes.js 的默认；脏值忽略）
    const viewMode = isPlainObject(map.viewMode) ? map.viewMode : {}
    const pipeline = isPlainObject(viewMode.pipeline) ? viewMode.pipeline : {}
    config.map.viewMode = {
        pitch: readNumber(pipeline.pitch, issues, 'map.viewMode.pipeline.pitch'),
        rangeFactor: readNumber(pipeline.rangeFactor, issues, 'map.viewMode.pipeline.rangeFactor'),
        terrainAlpha: readNumber(pipeline.terrainAlpha, issues, 'map.viewMode.pipeline.terrainAlpha'),
        tilesetAlpha: readNumber(pipeline.tilesetAlpha, issues, 'map.viewMode.pipeline.tilesetAlpha'),
    }

    // 片区采用正式编码，旧 regionMap 部署映射已退役。

    // 票 47：设备状态动效开关（决策票 07 的问题 6）。
    // 与票 32 的 `map.ui.debug` **完全同构**：缺省 `null` = 跟随构建形态
    // （开发构建开特效、生产构建关，正式环境不该有动画压满屏）；
    // 现场要在生产包里看特效就显式写 `true`。脏值退回默认并记 issue，不静默吞掉。
    const effects = isPlainObject(map.effects) ? map.effects : {}
    const abnormalLimit = effects.abnormalLimit
    config.map.effects = {
        enabled: readBoolean(effects.enabled, null, issues, 'map.effects.enabled'),
        // 同屏异常设备上限（决策票 07 定 30）：超过则动画全停、降级为静态异常标记 + 计数。
        abnormalLimit: abnormalLimit === undefined || abnormalLimit === null
            ? 30
            : (Number.isInteger(abnormalLimit) && abnormalLimit >= 1
                ? abnormalLimit
                : (issues.push(`map.effects.abnormalLimit 应为正整数，收到 ${JSON.stringify(abnormalLimit)}，已退回 30`), 30)),
    }

    const overlap = isPlainObject(map.overlap) ? map.overlap : {}
    const maxFan = overlap.maxFan
    if (maxFan === undefined || maxFan === null) {
        config.map.overlap = { maxFan: 10 }
    } else if (Number.isInteger(maxFan) && maxFan >= 1) {
        config.map.overlap = { maxFan }
    } else {
        issues.push(`map.overlap.maxFan 应为正整数，收到 ${JSON.stringify(maxFan)}，已退回 10`)
        config.map.overlap = { maxFan: 10 }
    }

    // 票 32：UI 形态开关。缺省 null = 跟随构建模式（`import.meta.env.DEV`），
    // 生产构建自动收敛为「干净模式」；要在地产现场调试生产包时可显式写 true。
    const ui = isPlainObject(map.ui) ? map.ui : {}
    config.map.ui = {
        debug: readBoolean(ui.debug, null, issues, 'map.ui.debug'),
    }

    return { config, issues }
}

/** 构建期环境变量 → 原始配置形状（纯函数，便于单测直接喂一个 env 对象）。 */
export function readEnvConfig(env) {
    if (!isPlainObject(env)) return {}
    const out = {}

    if (env[ENV_KEYS.dataSource]) out.dataSource = env[ENV_KEYS.dataSource]

    const api = {}
    if (env[ENV_KEYS.apiBaseUrl]) api.baseUrl = env[ENV_KEYS.apiBaseUrl]
    if (env[ENV_KEYS.apiToken]) api.token = env[ENV_KEYS.apiToken]
    if (Object.keys(api).length) out.api = api

    const ws = {}
    if (env[ENV_KEYS.wsUrl]) ws.url = env[ENV_KEYS.wsUrl]
    if (env[ENV_KEYS.wsToken]) ws.token = env[ENV_KEYS.wsToken]
    if (Object.keys(ws).length) out.ws = ws

    const map = {}
    if (env[ENV_KEYS.tiandituToken]) map.tianditu = { token: env[ENV_KEYS.tiandituToken] }
    if (env[ENV_KEYS.cesiumBaseUrl]) map.cesium = { baseUrl: env[ENV_KEYS.cesiumBaseUrl] }

    const basemap = {}
    if (env[ENV_KEYS.basemapSource]) basemap.source = env[ENV_KEYS.basemapSource]
    if (env[ENV_KEYS.basemapUrl]) basemap.url = env[ENV_KEYS.basemapUrl]
    if (Object.keys(basemap).length) map.basemap = basemap

    if (Object.keys(map).length) out.map = map

    return out
}

/** 深合并（只对普通对象递归），后面的来源覆盖前面的。 */
export function mergeConfig(base, patch) {
    if (!isPlainObject(patch)) return base
    const out = { ...base }
    for (const [key, value] of Object.entries(patch)) {
        out[key] = isPlainObject(value) && isPlainObject(base[key]) ? mergeConfig(base[key], value) : value
    }
    return out
}

/**
 * 解析配置文件的地址。
 * @param {object} [options]
 * @param {string} [options.base] 应用基址（`import.meta.env.BASE_URL` / qiankun 注入）
 * @param {string} [options.documentBase] `document.baseURI`
 * @param {string} [options.explicitUrl] 显式 URL；`'auto'` 表示按应用基址取约定路径
 * @returns {string} 绝对 URL
 */
export function resolveConfigUrl({ base = './', documentBase = 'http://localhost/', explicitUrl = '' } = {}) {
    const docBase = documentBase || 'http://localhost/'
    if (explicitUrl && explicitUrl !== CONFIG_URL_AUTO) return new URL(explicitUrl, docBase).href
    return new URL(CONFIG_FILE_PATH, new URL(base || './', docBase)).href
}

/** 读一个配置来源的响应体；返回原始对象或一个失败原因。 */
export async function readConfigPayload(response) {
    if (!response || typeof response.text !== 'function') return { ok: false, reason: 'no-response' }

    if (!response.ok) {
        // 404 = 部署没放这个文件；其余非 2xx = 放了但服务端是坏的。
        return { ok: false, reason: response.status === 404 ? 'missing' : `http-${response.status}` }
    }

    const text = await response.text()
    const trimmed = text.trim()
    // dev 的 SPA 回退 / 静态服务器的错误页都会返回 HTML，一律按「文件不存在」处理。
    if (!trimmed || trimmed.startsWith('<')) return { ok: false, reason: 'missing' }

    try {
        const raw = JSON.parse(trimmed)
        if (!isPlainObject(raw)) return { ok: false, reason: 'not-an-object' }
        return { ok: true, raw }
    } catch {
        return { ok: false, reason: 'invalid-json' }
    }
}

function readViteEnv() {
    return import.meta && import.meta.env ? import.meta.env : {}
}

function readDocumentBase() {
    return typeof document !== 'undefined' && document.baseURI ? document.baseURI : 'http://localhost/'
}

let cached = null
let inFlight = null

/**
 * 载入配置（幂等、进程内缓存一次）。
 * 所有依赖都可注入，便于脱浏览器断言：`{ scope, env, fetchImpl, base, documentBase, now }`。
 * @returns {Promise<object>} `{ state, source, url, config, issues, error, credential, loadedAt }`
 */
export function loadCockpitConfig(options = {}) {
    if (cached) return Promise.resolve(cached)
    if (inFlight) return inFlight

    inFlight = resolveCockpitConfig(options)
        .then((result) => {
            cached = result
            inFlight = null
            return result
        })
        .catch((error) => {
            // 兜底：任何意外都收敛成 failed，绝不向外抛（页面不该因为配置服务崩掉而白屏）。
            inFlight = null
            cached = {
                state: CONFIG_STATE.FAILED,
                source: 'defaults',
                url: '',
                config: builtinConfig(),
                issues: [],
                error: String((error && error.message) || error),
                credential: CREDENTIAL.NONE,
                loadedAt: new Date().toISOString(),
            }
            return cached
        })

    return inFlight
}

async function resolveCockpitConfig({ scope, env, fetchImpl, base, documentBase, now } = {}) {
    const globalScope = scope || (typeof globalThis !== 'undefined' ? globalThis : {})
    const viteEnv = env !== undefined ? env : readViteEnv()
    const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null)
    const loadedAt = new Date(now === undefined ? Date.now() : now).toISOString()

    const injected = isPlainObject(globalScope[INJECTED_CONFIG_KEY]) ? globalScope[INJECTED_CONFIG_KEY] : null
    // 宿主页显式给了 URL 键就以它为准 —— 给空串表示「这个页面不要运行时配置文件」，
    // 这样宿主能在构建期开关之外逐页控制（走查的「默认无配置」用例也靠它自隔离）。
    const injectedUrl = globalScope[INJECTED_CONFIG_URL_KEY]
    const explicitUrl =
        injectedUrl === undefined || injectedUrl === null
            ? readString(viteEnv ? viteEnv[ENV_KEYS.configUrl] : '', '', [], 'VITE_COCKPIT_CONFIG_URL')
            : readString(injectedUrl, '', [], 'window.__COCKPIT_CONFIG_URL__')

    // 1) + 2) 内置默认由 normalizeConfig 兜底，这里先叠构建期环境变量。
    const envRaw = readEnvConfig(viteEnv)
    let raw = mergeConfig({}, envRaw)
    // 构建期环境变量也算「有配置」；只有一份来源都没有时才是缺失态（内置默认）。
    const hasEnvConfig = Object.keys(envRaw).length > 0
    let source = hasEnvConfig ? 'env' : 'defaults'
    let state = hasEnvConfig ? CONFIG_STATE.READY : CONFIG_STATE.MISSING
    let url = ''
    let error = ''
    const issues = []

    if (injected) {
        // 4) 宿主注入优先级最高：给了就不再拉文件。
        raw = mergeConfig(raw, injected)
        source = 'window'
        state = CONFIG_STATE.READY
    } else if (!explicitUrl) {
        // 没有显式配置 URL：不发请求（避免每次加载都刷 404），维持在「缺失 / 仅环境变量」态。
        url = ''
    } else {
        // 3) 运行时配置文件（显式 URL，或 'auto' = 应用基址下的约定路径）。
        url = resolveConfigUrl({
            base: base === undefined ? (viteEnv && viteEnv.BASE_URL) || './' : base,
            documentBase: documentBase === undefined ? readDocumentBase() : documentBase,
            explicitUrl,
        })

        if (!doFetch) {
            error = '当前环境没有 fetch，无法加载配置文件'
            state = CONFIG_STATE.FAILED
            issues.push(error)
        } else {
            try {
                const payload = await readConfigPayload(await doFetch(url, { headers: { Accept: 'application/json' }, cache: 'no-store' }))
                if (payload.ok) {
                    raw = mergeConfig(raw, payload.raw)
                    source = 'file'
                    state = CONFIG_STATE.READY
                } else if (payload.reason === 'missing' || payload.reason === 'no-response') {
                    // 文件不在：环境变量层给的配置仍然有效，状态维持原样（缺失 / 已就绪）。
                    if (!hasEnvConfig) state = CONFIG_STATE.MISSING
                } else {
                    state = CONFIG_STATE.FAILED
                    error = `配置文件不可用：${payload.reason}`
                }
            } catch (fetchError) {
                state = CONFIG_STATE.FAILED
                error = `配置文件请求失败：${String((fetchError && fetchError.message) || fetchError)}`
            }
        }
    }

    const { config: normalized, issues: normalizeIssues } = normalizeConfig(raw)
    // 票 76：DEV 走查桥必须落在**全局配置**上 —— `requestCockpitJson()` 读的是
    // `getCockpitConfig()`，只覆盖启动计划那份只会「注册 mock 但请求仍走 real」。
    const config = withUrlDataSourceOverride(normalized, null, !!(import.meta && import.meta.env && import.meta.env.DEV))

    return {
        state,
        source,
        url,
        config,
        issues: issues.concat(normalizeIssues),
        error,
        // ADR 0005（2026-09-28 修订）：驾驶舱 REST 免鉴权，前端不携带任何 REST 凭据；
        // WS token 走 `ws.token`（runtimeStore 直读），不再经由 api.token 兜底。
        credential: CREDENTIAL.NONE,
        loadedAt,
    }
}

/** 同步读归一化后的配置；未载入时给内置默认（页面不必等配置就能渲染骨架）。 */
export function getCockpitConfig() {
    return cached ? cached.config : builtinConfig()
}

/** 同步读完整加载结果；未载入时按「缺失」对待。 */
export function getCockpitConfigState() {
    if (cached) return cached
    return {
        state: CONFIG_STATE.MISSING,
        source: 'defaults',
        url: '',
        config: builtinConfig(),
        issues: [],
        error: '',
        credential: CREDENTIAL.NONE,
        loadedAt: '',
    }
}

/** 仅测试用：清掉缓存，让下一次 loadCockpitConfig 重新解析。 */
export function resetCockpitConfigForTest() {
    cached = null
    inFlight = null
}