City-Lifeline-Cockpit/.scratch/cockpit-primary-area-guardrails/map.md

主场景区限位、视距与过渡（决策地图）

Status: resolved Labels: wayfinder:map

本 effort 只产出决策，不实现功能（Q6=(a)）。实现票在本图收口后接进 .scratch/cockpit-shell-panel-layout/issues/ 的 30 之后。

Destination

把「进入沅陵县城主场景区之后」的三件事锁成可实现契约，让 agent 不必再发明语义：

1. 区域限位：弹簧臂/相机按主场景区限位 —— 中心点约束 + 相机离地高度上下限 + range 上限（Q2=C）。
2. 视距雾气：机制、曲线、门控与配色（Q4 / Q9 / Q11）。
3. 低精度 → 高精度过渡：从全球飞到县城视角的全过程不出现肉眼可辨的方形色块跳变（Q5=B）。

目的地达成的判据：每张子票都有明确答案，且答案之间的数值互相自洽 —— 限位数值、雾气门控、过渡曲线引用同一个主场景区定义与同一套视距基准。

Notes

• Domain：城市生命线 Web 驾驶舱 /cockpit。词汇以 CONTEXT.md 为准。
• 每次会话先读：CONTEXT.md、docs/adr/0001–0008、src/modules/cockpit/domain/camera.js、domain/viewPresets.js、domain/viewModes.js、domain/mapLayers.js、services/cesiumEngine.js、services/cameraControl.js、public/cockpit/config.json，以及 .scratch/cockpit-shell-panel-layout/issues/21、30。
• 引擎现状：cesium@1.145.0；唯一 import 'cesium' 在 services/cesiumEngine.js；目前零自定义 shader、零 post-process 级、零 fog/atmosphere 配置 —— 但 scene.fog 默认 enabled: true（默认密度在县城尺度几乎不可见）。
• 本图只产出决策，不实现功能。实现票去向：.scratch/cockpit-shell-panel-layout/issues/ 30 之后（Q6=(a)+(c)）。
• 技能：grilling、domain-modeling、research、prototype。
• 决策票状态词是 wayfinder 自己的 open/claimed/resolved，不套 triage 五标签。
• 新增 ADR 0009 记录本图结论（Q7）。
• 验收＝可计算部分走纯逻辑断言，观感部分由维护者目视走查（Q8）。按 AGENTS.md，改代码后不自动跑 build/dev。
• 阻塞关系以 Blocked by: 字段行为准。

已锁定的甲方裁定（2026-09-18 澄清）

1. 主场景区用新配置字段显式给出（Q1=C）。本部署取甲方框定的沅陵县城范围 [110.328749941417, 28.3917230659234, 110.465779226663, 28.4913038992907]（[west, south, east, north]，13.4 km × 11.0 km，147.6 km²）。01 已 resolved（2026-09-18）：兜底改为「部署期准备候选值＋运行时未配置则关闭」；候选值公式＝影像 bounds ∩ DEM valid_bounds 的 B，围绕 map.home 经纬度（＝进入系统默认位置＝归位位置）每边折半。原“内置兜底自动得到 B 收紧 50%”不再适用，详见 01 的 Answer。
2. 限位为三量同夹：中心点、相机离地高度、range（Q2=C）。最低仍须能贴近看设备。02 已 resolved（2026-09-18）：数值口径见 Decisions so far。
3. 进区后锁定，另给显式「返回全球」（Q3=C）。
4. 雾气定位＝氛围 + 遮缝，不承担"限制用户能看多远"的职责 —— 限距由第 1 条的限位承担（Q4）。
5. 过渡判据＝从全球飞到县城视角的全过程无肉眼可辨的方形色块跳变；允许边界羽化/渐变遮罩这类碰 shader 的手段（Q5=B）。
6. 本图只产决策；实现票接在 cockpit-shell-panel-layout 的 30 之后（Q6=(a)+(c)）。
7. 新增 ADR 0009（Q7）。
8. 验收＝纯逻辑断言 + 维护者目视走查（Q8）。
9. 雾气走自建 Cesium depth 后处理级（路线 B），参考 Three.js 增强管线的 shader 写法以提升观感、降低开销（Q9=B）。
10. 早期「垂直视野 ≤15%」口径已由限位与既有相机契约的合成 + 进出状态机取代：最远视野跟随 home.range（本部署 12,000 m）。不得再用 1,651 m 地面跨度直接约束雾的相机到片元距离。
11. 早期要求包含侧视远景及天空处理；维护者经原型已选视距雾气的实现规格的 B，仅处理有效几何深度地物，不采用天空背景染色。无雾降级时业务可用优先并提示，不承诺完全遮缝。
12. 另立调研票评估「把 Cesium 深度喂给 Three」的可行性（Q12=B）。

早期计算记录（历史，不作为现行限位或雾参数）

• 主场景区：E-W 13,413 m，N-S 11,008 m；N-S 的 15% = 1,651 m（这是"最高视野下地面垂直覆盖"的预算）。
• Cesium 默认 fov = 60° 是水平视场角，fovy = 2·atan(tan(30°)/aspect)。同一预算下 range 上限随画布宽高比浮动约 2×：aspect 1:1 → 1,430 m；4:3 → 1,906 m；16:9 → 2,542 m（均为正俯视口径）。02 已定：运行时按真实 fovY 反算 range_max = 1651 / (2·tan(fovY/2))，不写死基准。
• 现有 home 预设 pitch −55, range 12000 的垂直覆盖约 9.5 km ≈ 主场景区 N-S 的 86%，是上述预算的 5.8× —— 与票 30 的"12 km 是县域级"直接冲突，03 必须处置。

任务清单

• 01: 主场景区的配置契约 — 已 resolved：字段形状 / 坐标口径 / 兜底来源。
• 02: 相机限位的数值契约 — 已 resolved：h_min / h_max / range 上限与 15% 预算的换算口径。
• 03: 限位与既有相机契约的合成 + 进出状态机 — 已 resolved：限位锚点 / 进出状态机 / 管线合成 / 软回弹 / ADR 0009。
• 04: 调研 —— Cesium 地面视距雾的机制与限制 — 已 resolved，产物 research/cesium-ground-fog-mechanisms.md。
• 05: 调研 —— 精细矩形跳变的成因与可用手段 — 已 resolved，产物 research/overlay-rectangle-pop-mechanisms.md。
• 06: 调研 —— Three.js 雾 shader 可复用面与 Cesium 深度互通可行性 — 已 resolved，产物 research/three-fog-shader-reuse.md；甲方裁定废止深度互通备选。
• 07: 视距雾气的实现规格 — 已 resolved：采用 B 仅地物距离雾，默认 18/42 km、#bdcdd6；进入时序要求“精细影像先隐藏 → 雾先保护 → 影像渐显”，失败时业务可用优先；实施验收保留 ≤15% P95 与透明管线/进出交接检查。
• 08: 低精度 → 高精度过渡的解法 — 已 resolved：维护者在实际场景基本验收 B 过渡方向，三项后续要求已落 Answer；生产零跳变与性能仍待实施验收。

Decisions so far

• 01: 主场景区的配置契约 — map.primaryArea 只设 bounds（[W,S,E,N] 度，与 map.overlays[].bounds 同口径）；配置必须写归一化顺序，运行时校验 west<east/south<north、不自动翻转，非法即记配置问题并进入关闭路径；兜底＝部署期计算候选值（B ＝ 影像 bounds ∩ DEM valid_bounds，围绕 map.home 经纬度＝进入系统默认位置＝归位位置、每边折半）写入同一字段，运行时未配置就关闭依赖主场景区的限位与自建雾并如实报浮标 —— 原「内置兜底自动得 B 收紧 50%」作废；契约不含数据越界校验（配置即权威）；本部署显式值仍为甲方框定县城范围。
• 02: 相机限位的数值契约 — 中心点 ∈ primaryArea.bounds（01）；range ∈ [120, range_max]，range_max = 1651 / (2·tan(fovY/2))（取运行时真实 fovY，随画布 aspect 变：1:1→1,430 / 4:3→1,906 / 16:9→2,542 m）；正俯视只提供参考基准值，pitch 不参与收紧；「垂直覆盖」度量＝屏幕竖直方向地面跨度，只在正俯视定义；02 只保正俯视 ≤15%，侧视露出的范围外由 07 雾遮盖；相机离地高度 h = range·sin|pitch|（h_max 被 range_max 隐式罩住）；防入地＝地形感知下限（h ≥ 正下方地形 + 10 m，margin 暂定可微调，不足时夹 range，机制落 03）。⚠️ 其 range_max 锚点（2,542 m）已被 03 取代（12,000 m = home.range），限位数值以 03 / ADR 0009 为准。
• 03: 限位与既有相机契约的合成 + 进出状态机 — range_max = home.range = 12,000 m（最远视野 = 归位默认视角，取代 02 的 2,542 m 与"15% 垂直覆盖预算"）；显式模式锁（进入系统/归位进、返回全球出，判定与位置无关）；全球态闲置 5 秒回初始态（自转 + 闪烁「点击进入系统」），不重置模式/筛选；区内管线视图 range ∈ [400, min(6000, range_max)] = [400, 6,000]（因 range_max>6000，与现状一致，冲突消解）；边界软回弹（target.pivot 越出 ≤ 框短边 5% ≈ 550 m，松手阻尼弹回）；返回全球目标＝初始全景（h0/p−60/r 2×10⁷）；areaState: 'locked'|'global' 进 filterStore（与 viewMode 同层），mapService 转移、cameraControl 换 limits（setRangeLimits 与 setPitchLimits 对称）、CockpitShell 管 5 秒计时与引导页显隐；intro.enabled=false 按 global 启动；防入地继承 02（三处夹取交集）；ADR 0009 已建、ADR 0008 已补指向。
• 04: 调研 —— Cesium 地面视距雾的机制与限制 — 内置 scene.fog 的密度由相机高度反算并乘 1−|dot(朝向,上)|，正俯视归零、半径随高度漂移，当不了稳定视距限制；引擎无现成雾/霾后处理级，但 PostProcessStage 默认就带 depthTexture，自建 depth 雾可行（Context.depthTexture 运行时存在但不在随包 d.ts 里；06 更正：它实为布尔能力标志，非纹理对象）。
• 05: 调研 —— 精细矩形跳变的成因与可用手段 — 矩形边缘是 GLSL step() 硬切，引擎零羽化、零交叉淡入；配置里的 minimumLevel: 0 是空操作（等于 provider 默认），精细层并非"近了才加载"；跳变有两类（首批瓦片整体出现 + 地形 LOD 牵着影像逐级换挡）；ImageryLayer.alpha 只是整层 uniform，ImageryLayer.rectangle 只读。

• 06: 调研 —— Three.js 雾 shader 可复用面与 Cesium 深度互通可行性 — Three haze 的密度曲线与闭式光深积分是纯数学，可搬进 Cesium PostProcessStage；太阳耦合全在颜色项，常量雾色即可剥离；默认密度的距离估算仅适用于原研究的特定高度假设；旧 1,651 m 预算及倍率推导已失效，现行参数以雾规格最终决策为准。「Cesium 深度喂给 Three」评级极难（Context.depthTexture 仅是布尔能力标志、纹理不可跨 context、社区实测俯视遮挡错乱、且须推翻 ADR 0004）—— 甲方裁定废止该备选，雾锁定单一 Cesium 渲染器走路线 B。

• 视距雾气的实现规格 — 采用 B 地物距离雾及原型默认参数；提前准备/撤除与影像交接协调，异常时业务可用优先；按决策范围收口，进入遮挡失败记录、透明场景检查和 ≤15% P95 验收仍归下游原型/实施，不表示运行验收通过。

• 08: 低精度 → 高精度过渡的解法 — 维护者在实际场景基本验收「藏精细影像 → 雾保护 → 渐显影像；返回反向交接」。正式实施需让进出雾变换稍快、采用冷白灰且不发绿、返回时镜头高度与雾气模糊同步变化并保持影像保护。原型决策通过不等于生产全程零跳变或 ≤15% P95 已达标。

Not yet specified

• 正式交付若矩形内部 LOD 换级仍肉眼可辨，再评估局部过渡、shader 羽化或预烘焙中精度影像层（成本高）作为兜底；本次原型观感通过不代表已经修复内部换级。
• 运维自检「限位与雾气已生效」的操作口径 —— 已由实现票 36: 主场景区配置 落地：docs/cockpit-deployment.md 新增 2.9 节（顺序是硬要求 + 三种浮标读数对照表 + 矩形怎么定）， 运行期读数为引擎浮标 主场景区：… 与宿主 data-map-primary-area(-reason)。雾气本身的可视验收仍归实施票 38。

Out of scope

• 让 Three.js 接管 Cesium 场景或承担全场大气 —— ADR 0004 / ADR 0007 已锁死；Q12 已由 06 调研后裁定废止（极难，且须推翻 ADR 0004），不再作为备选。
• 重做地球自转与进入引导动画本身（票 30 已交付并验收；本图只处理进入途中的过渡瑕疵）。
• 甲方本地 3D Tiles 模型数据补齐（属 .scratch/cockpit-shell-panel-layout/issues/21）。
• 后处理通用框架化或其它后处理效果（本图只做视距雾一个）。
• 改 mode / panelId / 面板语义与布局。

进度：100%

8/8 张决策票已 resolved。08：低精度 → 高精度过渡的解法经维护者在真实场景基本验收，方案方向和三条后续实施约束已落票；雾气决策另见07。本图按「锁定可实现的决策」范围收口，不代表原型直接入生产、全程零方块跳变或性能合格。

下一步：按地图约定在 .scratch/cockpit-shell-panel-layout/issues/ 的 30 之后承接正式实现。进出雾速度稍快、冷白灰不发绿、返回高度与雾气同步且边缘持续受保护均须在真实画面复核；另检查目标瓦片、内部 LOD 换级、异常降级、管线可读性及 P95 帧耗时增幅 ≤15%。雾气与相机规格继续分别以spec-fog.md和spec.md为准，新的实施约束以 08 的最终 Answer 优先。

历史 1,651 m 预算及旧雾密度推导不可作现行验收标准；本轮依 AGENTS.md 未运行 build/dev 或浏览器调试。