City-Lifeline-Cockpit/.scratch/cockpit-shell-panel-layout/verify/t03-camera-contract.mjs

/**
 * T03 逻辑检查：三键相机契约与旋转中心规则（票 03 / ADR 0008）。
 *
 * 仓库没有测试运行器，且项目约定不为验证引入新框架，所以这里用零依赖 Node 断言脚本：
 * 相机语义全在 `domain/camera.js`（纯数学）与 `services/cameraControl.js`（状态迁移，引擎依赖注入），
 * 因此可以用**假引擎**驱动整套交互，不需要浏览器、不需要 cesium。
 * 真机行为（Cesium 默认输入确实被替换、中心确实落在屏幕中心）由 t03-camera-walkthrough.mjs 覆盖。
 *
 * 运行：node .scratch/cockpit-shell-panel-layout/verify/t03-camera-contract.mjs
 */
import assert from 'node:assert/strict'
import { FOCUS_FLIGHT_MS, PITCH_LIMITS, RANGE_LIMITS } from '../../../src/modules/cockpit/domain/camera.js'
import * as camera from '../../../src/modules/cockpit/domain/camera.js'
import { attachCameraInput, createCameraControl } from '../../../src/modules/cockpit/services/cameraControl.js'

const GROUND = { lon: 110.39, lat: 28.46, height: 0 }
const XIANGLING = { lon: 110.396, lat: 28.455, height: 0 } // 沅陵某监测点

function createFakeEngine({ viewport = { width: 1680, height: 900 }, fovY = Math.PI / 3, ground = GROUND } = {}) {
    const applied = []
    let clock = 1000
    let pendingFrame = null

    return {
        applied,
        engine: {
            applyView(pivot, hpr) {
                applied.push({ pivot: { ...pivot }, hpr: { ...hpr } })
            },
            readView() {
                return { heading: 0, pitch: -60, range: 10000 }
            },
            pickGroundAtCenter() {
                return { ...ground }
            },
            projectPivot() {
                return { x: viewport.width / 2, y: viewport.height / 2 }
            },
            inputTarget() {
                return null
            },
            viewport() {
                return { ...viewport }
            },
            fovY() {
                return fovY
            },
            now() {
                return clock
            },
            requestFrame(callback) {
                pendingFrame = callback
            },
            cancelFrame() {
                pendingFrame = null
            },
        },
        get pendingFrame() {
            return pendingFrame
        },
        advance(ms) {
            clock += ms
        },
        runFrame() {
            const callback = pendingFrame
            pendingFrame = null
            if (callback) callback()
        },
        last() {
            return applied[applied.length - 1]
        },
    }
}

function newControl(options) {
    const fake = createFakeEngine(options)
    const control = createCameraControl({ engine: fake.engine })
    control.syncFromEngine()
    fake.applied.length = 0
    return { fake, control }
}

/** 假元素：记录监听器，供 attachCameraInput 的绑定/解绑断言。 */
function createFakeElement() {
    const handlers = new Map()
    return {
        handlers,
        defaultPrevented: 0,
        addEventListener(type, fn) {
            if (!handlers.has(type)) handlers.set(type, new Set())
            handlers.get(type).add(fn)
        },
        removeEventListener(type, fn) {
            if (handlers.has(type)) handlers.get(type).delete(fn)
        },
        setPointerCapture() {},
        releasePointerCapture() {},
        fire(type, payload = {}) {
            const set = handlers.get(type)
            if (!set) return
            const event = {
                preventDefault() {
                    this.defaultPrevented = true
                },
                ...payload,
            }
            set.forEach((fn) => fn(event))
            return event
        },
    }
}

const near = (a, b, tolerance, message) =>
    assert.ok(Math.abs(a - b) <= tolerance, `${message}：期望 ≈${b}（±${tolerance}），实际 ${a}`)

// ---------- 1. 左键拖拽只平移 ----------
{
    const { fake, control } = newControl()
    const before = control.getState()
    control.beginDrag({ button: 0, x: 0, y: 0 })
    control.moveDrag({ x: 100, y: 0 })

    const after = control.getState()
    assert.deepEqual(after.hpr, before.hpr, '平移不得改 heading / pitch / range')
    assert.equal(fake.last().hpr.range, before.hpr.range, '平移不得改弹簧臂长度')

    // 期望位移：range*tan(fov/2)*2/viewportH 米/像素 × 100 像素，heading=0 时应落在正东。
    const metersPerPx = camera.metersPerPixel({ range: 10000, fovYRad: Math.PI / 3, viewportHeight: 900 })
    const expectedLon = before.pivot.lon + (100 * metersPerPx) / (111320 * Math.cos((GROUND.lat * Math.PI) / 180))
    near(after.pivot.lon, expectedLon, Math.abs(expectedLon - before.pivot.lon) * 0.02, 'heading=0 时右拖应把中心按像素比例移到正东')
    near(after.pivot.lat, before.pivot.lat, 1e-6, 'heading=0 时右拖不应产生南北位移')
    console.log('PASS  1 左键拖拽只平移（heading/pitch/range 原样，中心按像素比例东移）')
}

// ---------- 2. 平移方向 = 相机移动方向（PAN_FOLLOWS_DRAG 的语义钉子） ----------
{
    const { control } = newControl()
    control.beginDrag({ button: 0, x: 0, y: 0 })
    control.moveDrag({ x: 0, y: 100 })
    const down = control.getState()
    assert.ok(down.pivot.lat < GROUND.lat, `heading=0 时下拖应把中心往南带（朝相机方向）：${JSON.stringify(down.pivot)}`)

    const { control: control2 } = newControl()
    control2.beginDrag({ button: 2, x: 0, y: 0 })
    // 先把 heading 拖到 90°（向东看）：像素数按灵敏度反算，不写死倍数。
    control2.moveDrag({ x: 90 / camera.ORBIT_SENSITIVITY.heading, y: 0 })
    control2.endDrag()
    near(control2.getState().hpr.heading, 90, 1e-6, '轨道旋转应把 heading 拖到 90°')

    const beforePan = control2.getState()
    control2.beginDrag({ button: 0, x: 0, y: 0 })
    control2.moveDrag({ x: 100, y: 0 })
    const afterPan = control2.getState()
    assert.ok(
        afterPan.pivot.lat < beforePan.pivot.lat,
        `heading=90°（向东看）时右拖应把中心往南带（相机的右手方向）：${JSON.stringify(afterPan.pivot)}`,
    )
    near(afterPan.pivot.lon, beforePan.pivot.lon, 1e-6, 'heading=90° 时右拖不应产生东西位移')
    console.log('PASS  2 平移方向 = 相机移动方向（ADR 0008 的「拖拽方向映射为摄像机移动方向」，heading=0/90 两点验证）')
}

// ---------- 3. 右键拖拽只做轨道旋转 ----------
{
    const { fake, control } = newControl()
    const before = control.getState()
    control.beginDrag({ button: 2, x: 0, y: 0 })
    control.moveDrag({ x: 100, y: 50 })
    const after = control.getState()

    near(after.hpr.heading, 28, 1e-6, 'heading 变化 = dx × 灵敏度')
    near(after.hpr.pitch, -60 - 50 * 0.22, 1e-6, 'pitch 变化 = -dy × 灵敏度')
    assert.equal(after.hpr.range, before.hpr.range, '轨道旋转不得改弹簧臂长度')
    assert.deepEqual(after.pivot, before.pivot, '轨道旋转不得移动中心')
    assert.equal(fake.last().hpr.range, before.hpr.range, '下发给引擎的 range 也必须原样')
    console.log('PASS  3 右键拖拽只做轨道旋转（heading/pitch 按像素变化，range 与中心不动）')
}

// ---------- 4. pitch 夹在上下限内 ----------
{
    const { control } = newControl()
    control.beginDrag({ button: 2, x: 0, y: 0 })
    control.moveDrag({ x: 0, y: 5000 })
    near(control.getState().hpr.pitch, PITCH_LIMITS.ground.min, 1e-9, '一直下拖应夹在下限')
    control.moveDrag({ x: 0, y: -10000 })
    near(control.getState().hpr.pitch, PITCH_LIMITS.ground.max, 1e-9, '一直上拖应夹在上限')
    console.log(`PASS  4 pitch 夹在 [${PITCH_LIMITS.ground.min}, ${PITCH_LIMITS.ground.max}]（地面视图）`)
}

// ---------- 5. 右键按下锁定中心：拖拽中不重新拾取 ----------
{
    const { fake, control } = newControl()
    const locked = control.getState().pivot
    control.beginDrag({ button: 2, x: 0, y: 0 })

    // 拖拽进行中来了「选中某对象」：中心不许被改，飞行也不许插进来。
    control.setFocus(XIANGLING)
    control.moveDrag({ x: 40, y: 0 })
    assert.deepEqual(fake.last().pivot, locked, '拖拽中下发的中心必须仍是按下时锁定的那个')

    control.endDrag()
    assert.equal(control.getState().flying, true, '松手后应开始平滑换中心')
    let guard = 0
    while (control.getState().flying && guard++ < 200) {
        fake.advance(50)
        fake.runFrame()
    }
    const final = control.getState().pivot
    near(final.lon, XIANGLING.lon, 1e-6, '飞行结束后中心应为选中对象')
    near(final.lat, XIANGLING.lat, 1e-6, '飞行结束后中心应为选中对象')
    console.log('PASS  5 右键按下锁定中心（拖拽中的选中不插队；松手后才开始换中心）')
}

// ---------- 6. 滚轮只改弹簧臂长度 ----------
{
    const { control } = newControl()
    const before = control.getState()
    const handled = control.wheel({ deltaY: -100 })
    const after = control.getState()

    assert.equal(handled, true, '滚轮应被相机契约接管（调用方据此 preventDefault）')
    near(after.hpr.range, 10000 * Math.exp(-100 * 0.0012), 1e-6, '上滚拉近：range 按指数缩')
    assert.equal(after.hpr.heading, before.hpr.heading, '滚轮不得转 heading')
    assert.equal(after.hpr.pitch, before.hpr.pitch, '滚轮不得改 pitch')
    assert.deepEqual(after.pivot, before.pivot, '滚轮不得移动中心')

    control.wheel({ deltaY: -1e6 })
    near(control.getState().hpr.range, RANGE_LIMITS.min, 1e-9, '拉近到极限应夹住下限')
    control.wheel({ deltaY: 1e6 })
    near(control.getState().hpr.range, RANGE_LIMITS.max, 1e-9, '推远到极限应夹住上限')
    console.log(`PASS  6 滚轮只改弹簧臂长度（并夹在 [${RANGE_LIMITS.min}, ${RANGE_LIMITS.max}] 米）`)
}

// ---------- 7. 中心规则：选中优先 / 取消不回退 / 平移才回退 ----------
{
    const { fake, control } = newControl()
    assert.deepEqual(control.getState().pivot, GROUND, '未选中时中心 = 屏幕中心的地面拾取点')

    control.setFocus(XIANGLING)
    let guard = 0
    while (control.getState().flying && guard++ < 200) {
        fake.advance(60)
        fake.runFrame()
    }
    assert.deepEqual(control.getState().pivot, XIANGLING, '选中后中心 = 对象地表点')

    control.setFocus(null)
    assert.deepEqual(control.getState().pivot, XIANGLING, '取消选中不得回退中心')
    assert.equal(control.getState().focus, null, '取消选中应清掉选中态')

    control.beginDrag({ button: 0, x: 0, y: 0 })
    control.moveDrag({ x: 10, y: 0 })
    control.endDrag()
    assert.deepEqual(control.getState().pivot, GROUND, '左键平移后中心回到地面拾取点')
    console.log('PASS  7 中心规则：选中优先 → 取消不回退 → 平移才更新为地面拾取点')
}

// ---------- 8. 换中心平滑、且全程保持 heading 与 range ----------
{
    const { fake, control } = newControl()
    const before = control.getState()
    control.setFocus(XIANGLING)

    // 起手第一帧（elapsed = 0）必须仍停在原中心 —— 换中心不许瞬移。
    near(fake.last().pivot.lon, before.pivot.lon, 1e-12, '换中心第一帧应从原中心出发')

    const samples = []
    let guard = 0
    while (control.getState().flying && guard++ < 200) {
        fake.advance(FOCUS_FLIGHT_MS / 10)
        fake.runFrame()
        const now = control.getState()
        assert.equal(now.hpr.heading, before.hpr.heading, '换中心过程中 heading 必须保持')
        assert.equal(now.hpr.range, before.hpr.range, '换中心过程中 range 必须保持')
        samples.push(now.pivot.lon)
    }

    assert.ok(samples.length >= 4, `换中心应有多帧（实际 ${samples.length}）`)
    const monotonic = samples.every((lon, i) => i === 0 || lon >= samples[i - 1] - 1e-12)
    assert.equal(monotonic, true, `中心应朝目标单调推进：${samples.join(' → ')}`)
    assert.ok(samples[0] > before.pivot.lon && samples[0] < XIANGLING.lon, '第一帧应落在起止之间')
    near(samples[samples.length - 1], XIANGLING.lon, 1e-6, '末帧应到达目标中心')
    assert.equal(control.getState().flying, false, '到达后应结束飞行')
    console.log(`PASS  8 换中心平滑（${samples.length} 帧单调推进、heading/range 全程不变）`)
}

// ---------- 9. DOM 绑定：三类输入都接上，右键菜单与滚轮默认行为被吃掉 ----------
{
    const { control } = newControl()
    const element = createFakeElement()
    const detach = attachCameraInput(element, control)

    assert.deepEqual(
        [...element.handlers.keys()].sort(),
        ['contextmenu', 'pointercancel', 'pointerdown', 'pointermove', 'pointerup', 'wheel'],
        '应绑定左右键拖拽与滚轮（并吃掉右键菜单）',
    )

    const menu = element.fire('contextmenu')
    assert.equal(menu.defaultPrevented, true, '右键菜单必须被 preventDefault')

    element.fire('pointerdown', { button: 0, pointerId: 1, clientX: 500, clientY: 400 })
    element.fire('pointermove', { pointerId: 1, clientX: 560, clientY: 400 })
    const dragging = control.getState()
    assert.equal(dragging.dragging, 'pan', '左键按下后应处于平移态')
    element.fire('pointerup', { pointerId: 1, clientX: 560, clientY: 400 })
    assert.equal(control.getState().dragging, null, '松手后应结束拖拽')

    element.fire('pointerdown', { button: 2, pointerId: 2, clientX: 500, clientY: 400 })
    element.fire('pointermove', { pointerId: 2, clientX: 540, clientY: 400 })
    assert.equal(control.getState().dragging, 'orbit', '右键按下后应处于轨道旋转态')
    element.fire('pointerup', { pointerId: 2, clientX: 540, clientY: 400 })

    const wheelEvent = element.fire('wheel', { deltaY: -120 })
    assert.equal(wheelEvent.defaultPrevented, true, '滚轮默认行为（页面滚动）必须被吃掉')

    detach()
    assert.equal(element.handlers.get('pointerdown').size, 0, 'detach 应摘掉监听器')
    assert.equal(element.handlers.get('wheel').size, 0, 'detach 应摘掉滚轮监听器')
    console.log('PASS  9 DOM 绑定：三类输入接上、右键菜单与滚轮默认行为被吃掉、可完整摘除')
}

// ---------- 10. 状态串（走查与人工排查读的那一行） ----------
{
    const { control } = newControl()
    const text = camera.formatCameraState(control.getState())
    ;['h=', 'p=', 'r=', 'pivot=', 'focus=ground', 'drag=none'].forEach((part) =>
        assert.ok(text.includes(part), `状态串应含 ${part}：${text}`),
    )
    assert.equal(camera.formatCameraState({ hpr: { heading: 0, pitch: -60, range: 1 }, pivot: null }), 'h=0.0 p=-60.0 r=1 pivot=none')
    console.log(`PASS  10 状态串可读：${text}`)
}

console.log('\nT03 逻辑检查通过：三键契约、中心规则、换中心动画、DOM 绑定均符合 ADR 0008。')