trail-mate/docs/UI_SHARED_IDF_PHASE_PLAN.md

UI Shared / IDF 迁移计划

这份文档用于说明：如何把 UI 逻辑从各个 apps/* 中抽离出来，沉淀到可复用的 shared 层，并同时兼容 PlatformIO 与 ESP-IDF 两套入口。

---

1. 目标

1.1 总目标

1. 把通用 UI 页面、shell、controller、runtime 接口集中到 modules/ui_shared
2. 让 apps/esp_pio 与 apps/esp_idf 只保留各自平台入口、启动流程和适配器
3. 避免 shared UI 直接依赖 Arduino 或 ESP-IDF 具体实现细节

1.2 迁移原则

• 页面结构、交互和状态逻辑优先沉淀到 shared 层
• 平台差异收敛到 platform/* 和 app runtime adapter
• 同一个页面不要在 PIO / IDF 各维护一份实现
• 对暂时无法共享的能力，用 capability-gated fallback 占位

---

2. 分层边界

2.1 modules/ui_shared

承载：

• page shell
• 页面组件
• controller / presenter
• runtime 抽象接口
• 通用 fallback 页面

不应直接依赖：

• <Arduino.h>
• <Preferences.h>
• nvs.h
• 具体板级 API

2.2 apps/esp_pio / apps/esp_idf

承载：

• startup / boot
• menu / app catalog 入口
• loop 驱动
• 生命周期管理
• facade / runtime adapter 装配

2.3 platform/*

承载：

• 设备能力实现
• 屏幕 / 睡眠 / 音频 / GPS / 存储等平台 API
• Arduino 与 IDF 各自的 contract 实现

---

3. 当前状态（截至 2026-03-11）

3.1 已经共享的页面骨架

已经迁到 shared shell + runtime/components/controller 的页面：

• Settings
• Chat
• GPS / Map
• GNSS Sky Plot
• Contacts
• Team
• Tracker
• PC Link
• USB
• SSTV
• Protocol Probe (internal route: energy_sweep)
• Walkie Talkie

3.2 apps 侧现状

apps/esp_pio/src 和 apps/esp_idf/src 已经逐步收敛到以下职责：

• startup_runtime.cpp
• loop_runtime.cpp
• app_runtime_access.cpp
• app_registry.cpp

其中 esp_idf 还包含：

• runtime_config.cpp
• app_facade_runtime.cpp
• idf_entry.cpp
• idf_component_anchor.cpp

3.3 已完成的清理

• 一批旧的 IDF retired stub 已移除
• modules/ui_shared 里的 ui_common_stub.cpp / ui_status_stub.cpp 已显著收缩
• apps/esp_pio/src 下保留的 ui_*.cpp 多数只剩 wrapper 职责

---

4. 分阶段计划

阶段 0：盘点与止血

目标

• 先明确哪些页面已经 shared，哪些还残留 app 私有实现
• 停止新增重复页面实现

交付

• 页面归属清单
• app 私有 wrapper 清单
• shared shell 缺口清单

---

阶段 1：apps 入口收敛

目标

把 apps/esp_pio 和 apps/esp_idf 收敛成“启动 + loop + runtime 接线”。

任务

1. 把 app_catalog / menu / startup / loop 对齐到 shared 模式
2. 清理 apps/esp_pio 中历史页面 wrapper / registry 特例
3. 收敛 app_runtime_access 的生命周期与运行时访问
4. 统一 esp_pio / esp_idf 的 startup / loop / event 驱动模式

完成标准

• 两端 app 目录不再承载具体 UI 逻辑
• app 入口能稳定驱动 shared app catalog / shared shell

---

阶段 2：页面共享完成

目标

把页面层真正统一到 shared：

• shell
• host
• fallback
• components / controller / runtime

任务

1. 补齐 shared shell + components/runtime
2. 移除 app 侧残留页面逻辑
3. 统一 app catalog 与 shared page shell 的接线
4. 对缺失能力使用 capability-gated fallback

完成标准

• 页面结构只在 modules/ui_shared 维护
• fallback 行为一致
• app 侧不再复制页面实现

---

阶段 3：平台能力抽象完成

目标

把 shared UI 依赖的设备能力全部收敛到 adapter contract。

需要抽象的能力

• restart
• kv / config persistence
• screen sleep
• tone / audio preview
• GPS runtime control
• tracker recording hook
• hostlink / USB capability hook
• walkie / sstv / lora support

落点

• Arduino 实现在 platform/esp/arduino_common
• IDF 实现在 platform/esp/idf_common 与 apps/esp_idf/*runtime

完成标准

• modules/ui_shared 不再直接包含 ESP 专有头文件
• shared 只依赖平台 contract

---

阶段 4：配置与 profile 收敛

目标

把设备 profile、视觉尺寸、能力差异统一到 runtime config / page profile。

重点

• tab5
• tdeck
• pager

要求

• topbar、高度、间距、图标卡片等由 shared profile 驱动
• 板级差异不散落在页面代码里

---

5. 风险点

• shared 页面已经完成结构迁移，但 runtime hook 仍可能带有平台耦合
• PIO / IDF 两套入口的生命周期节奏不完全一致，容易出现事件顺序差异
• fallback 如果设计过弱，短期内会掩盖真实缺口
• profile 还未彻底统一前，不同设备上可能继续出现布局分叉

---

6. 验收标准

• modules/ui_shared 成为页面 UI 的唯一事实源
• apps/esp_pio 与 apps/esp_idf 主要负责启动和装配
• 平台差异只出现在 platform/* 与 runtime adapter
• 新页面默认先落到 shared，而不是 app 私有目录