/**
* 驾驶舱配置服务(票 04):后端地址、天地图、Cesium、WebSocket 与凭据的唯一读入口。
*
* 为什么要有这一层(spec 第 13/14 条、ADR 0005):
* 前端不硬编码账号、密钥或环境地址;配置由部署层注入;页面与 store 只读归一化后的结果。
*
* 分层(后者覆盖前者,深合并):
* 1. 内置默认 —— `dataSource: mock`(spec:默认 mock,真接口必须显式开启)
* 2. 构建期环境变量 —— `import.meta.env.VITE_COCKPIT_*`(本机联调写 `.env.local`,已 gitignore)
* 3. 运行时配置文件 —— `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'
/** 部署把配置文件放在这个相对路径下:`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: '' },
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 },
// 票 21:地面/管线视图的取值覆盖(不配就用 domain/viewModes.js 的默认)
viewMode: { pitch: null, rangeFactor: null, terrainAlpha: null, tilesetAlpha: null },
// 票 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
}
/**
* 归一化 + 宽松校验:不认识的取值退回默认并记一条 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 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')
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: readNumber(
tileset.maximumScreenSpaceError,
issues,
`map.tilesets[${index}].maximumScreenSpaceError`,
),
credit: readString(tileset.credit, '', issues, `map.tilesets[${index}].credit`),
}
})
}
// 视角预设与进入引导(票 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 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'),
}
// 票 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'),
}
// 票 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