68 lines
3.4 KiB
Markdown
68 lines
3.4 KiB
Markdown
# Earth Presentation Decoupled Architecture Plan
|
||
|
||
## Goal
|
||
|
||
把 Earth 页面里的“详情卡片、连接器、隐藏策略、跟随更新”从具体业务交互里拆出来，形成统一的 Presentation 层。第一阶段只迁 Motion 动捕展示，修复卡片被鼠标移动误隐藏、连接器 interactable 端不贴合本体的问题；BGP/News 巡航保持现状，避免改变原有轮播体验。
|
||
|
||
## Current Issues
|
||
|
||
- Motion 展示复用了巡航卡片，但隐藏判断仍散落在 `main.js` 的 hover/mousemove 分支里，导致鼠标移动时卡片可能被 `hideInfoCard()` 清掉。
|
||
- Motion 连接器 source 端目前主要使用屏幕点坐标，缺少本体视觉边界，线无法稳定贴住 marker、卫星或海缆本体。
|
||
- 卡片、连接器、目标本体和生命周期策略耦合在 adapter 内，不利于后续把点击详情、动捕、巡航统一管理。
|
||
|
||
## Phase 1 Scope
|
||
|
||
- 新增 `PresentationController`。
|
||
- Motion 使用 `PresentationController` 管理卡片、连接器和 persistent 生命周期。
|
||
- BGP/News adapter 不迁移，继续使用现有 `CruiseSequencer`、卡片位置、线动画和 dwell/advance 行为。
|
||
- InfoCard 和 CalloutConnector 继续作为底层 renderer，不重写 UI。
|
||
|
||
## Presentation Interface
|
||
|
||
`PresentationController.present(request)` 接收：
|
||
|
||
- `id`: presentation 唯一 id。
|
||
- `owner`: `motion | cruise | click | hover`。
|
||
- `card`: 提供 `render({ reveal })` 和 `hide()`。
|
||
- `connector`: 提供 `sourceProvider`、`targetProvider`、`options`，由 controller 调用 `createConnectorPath()` 和 `connector.render()`。
|
||
- `lifetime`: `persistent | timeout | sequenced`，Motion 默认 `persistent`。
|
||
- `onDismiss(reason)`: 替换、关闭、停止等清理回调。
|
||
|
||
`PresentationController.update()` 每帧重算 active connector 的 source/target anchor。`dismiss(reason)` 统一清理卡片、连接器和计时器。
|
||
|
||
## Motion Integration
|
||
|
||
- Motion adapter 不再直接管理 `showInfoCard + connector.render + hideInfoCard`。
|
||
- Motion request 使用 `owner: "motion"` 和 `lifetime: { mode: "persistent" }`。
|
||
- Motion 切目标时替换当前 presentation。
|
||
- Motion 关闭、页面销毁或用户关闭展示时 dismiss。
|
||
- Motion source anchor 使用视觉近似矩形：
|
||
- BGP / compute / vessel marker: 投影中心 + marker 尺寸近似。
|
||
- satellite: 当前卫星位置 + point size 近似。
|
||
- cable: localCenter + 小矩形近似。
|
||
|
||
## Cruise Compatibility
|
||
|
||
- BGP/News 第一阶段不迁移。
|
||
- `CruiseSequencer` 的 `auto_advance` 不改。
|
||
- 原巡航的 dwell、hide、advance、卡片固定锚点、连接器动画时序不改。
|
||
- 后续迁移 BGP/News 前必须先补回归测试，再只替换渲染层，不改排序、聚焦和时序。
|
||
|
||
## Test Plan
|
||
|
||
- `presentation-controller.test.js`
|
||
- `persistent` 不自动隐藏。
|
||
- `timeout` 按配置隐藏。
|
||
- 新 presentation 替换旧 presentation，并触发旧 `onDismiss("replace")`。
|
||
- `dismiss(reason)` 清理卡片、连接器、计时器。
|
||
- `update()` 重新获取 source/target anchor 并重绘 connector。
|
||
- Motion 手动验证：
|
||
- Motion 展示后移动鼠标，卡片不消失。
|
||
- Motion 切目标后旧卡片和旧线被替换。
|
||
- 卡片拖动、窗口 resize、地球旋转、卫星移动时 connector 两端跟随。
|
||
- source 端贴近 interactable 视觉边缘。
|
||
- 巡航回归：
|
||
- BGP/News 自动轮播、dwell、隐藏、进入下一条不变。
|
||
- 移动端 popup/drawer 行为不变。
|
||
|