10. Codebase Overview (中文)

Codebase Overview

语言： English 版：10. Codebase Overview

Trail Mate 已经不是一个“只有几个 .ino 和几个页面文件”的项目。它同时覆盖设备端固件、协议兼容、离线地图、Team、HostLink、多硬件适配和共享 UI，因此仓库结构本身就是系统设计的一部分。

这一页的目标不是逐文件讲解，而是回答一个更实际的问题：如果你要找某类逻辑，应该先去哪里。

顶层目录怎么看

当前主仓库里最重要的几个目录如下：

apps/
boards/
docs/
modules/
platform/
tools/
variants/
src/

apps/

这里放的是应用壳层和入口点。当前能看到的主要子目录包括：

esp_pio/
esp_idf/
gat562_mesh_evb_pro/
linux_sim/
linux_rpi/
linux_unoq/

其中最值得先理解的是：

• apps/esp_pio/：当前 Arduino / PlatformIO 主路径壳层
• apps/esp_idf/：共享 ESP-IDF shell 根目录
• apps/gat562_mesh_evb_pro/：nRF52 单色目标的独立 app 壳层

如果你想找程序从哪里启动、什么时候初始化板子、什么时候绑定 AppContext，这里是第一入口。

boards/

这里放的是“板级真相”和板级运行时，而不是纯配置名册。当前目录包括：

gat562_mesh_evb_pro/
tab5/
tdeck/
tdeck_pro/
tlora_pager/
twatchs3/
t_display_p4/

如果你要找：

• 引脚事实
• 板子初始化顺序
• GPS / LoRa / SD / 输入设备 bring-up
• 某块板子为什么行为和别的板子不一样

优先看这里，而不是先去共享 UI 或协议层里猜。

modules/

这里是共享逻辑的主要承载层，当前包括：

core_chat/
core_gps/
core_hostlink/
core_sys/
core_team/
ui_mono_128x64/
ui_shared/

可以大致这样理解：

• core_chat/：聊天、联系人、协议共享逻辑、自身份等
• core_gps/：GPS 运行时配置、滤波、状态和运动策略
• core_hostlink/：HostLink 协议和相关共享模型
• core_sys/：应用配置和系统级共享结构
• core_team/：Team 领域、协议和用例
• ui_shared/：大多数共享页面和菜单逻辑
• ui_mono_128x64/：单色屏专用 UI 运行时

如果你要改的是“项目通用行为”，这里通常比 boards/ 更值得先看。

platform/

这里放的是平台适配层。当前有：

esp/
linux/
nrf52/
shared/

它的职责不是定义业务，而是把业务接到具体平台能力上，例如：

• BLE
• LoRa 传输
• GPS 硬件
• 文件系统
• 定时器和时钟
• 显示与输入适配

如果你看到一段共享业务逻辑直接依赖 Arduino、ESP-IDF 或某个板级头文件，通常说明边界已经开始变乱了。

variants/

这里主要服务 PlatformIO 路线。构建环境、屏幕尺寸、射频变体和调试宏等差异，很多都在这里定义，而不是写死在根 platformio.ini。

如果你要查：

• 某个目标的 SCREEN_WIDTH / SCREEN_HEIGHT
• 当前目标启用了哪些调试宏
• 某个射频变体是否单独有 env

这里是高频入口。

docs/

这里不是随便堆说明文档的地方，而是很多边界事实和设计意图的存放处。当前尤其值得看的包括：

• ARCHITECTURE.md
• MULTI_PROTOCOL_SUPPORT.md
• TEAM.md
• map/SD_CARD_MAP_STRUCTURE_CN.md
• devices/*

如果你只读代码，不读这些文档，很容易把“当前实现细节”误判成“项目长期边界”。

src/

这个目录在当前仓库里仍然存在，但从架构方向文档可以看出，项目正持续把可共享的逻辑往 modules/ 和更清晰的平台边界上迁移。也就是说，当前仓库还处在过渡阶段，不应简单把 src/ 当成唯一主战场。

从启动到主菜单的大致流程

以当前 PlatformIO 主路径为例，启动过程大致是：

1. apps/esp_pio/startup_runtime.cpp 启动串口和基础时钟提供者。
2. 板级初始化通过 platform/.../startup_support 进入具体 board runtime。
3. 显示和 LVGL 初始化。
4. AppContext 绑定板子、协议、GPS、Team、背景任务等运行时。
5. ui::startup_shell 和 app_catalog_builder 生成当前设备可见的菜单结构。

这条链路说明：主菜单并不是静态写死页面表，而是和设备能力、app shell、平台绑定一起装配出来的。

如果你想找某类问题，先去哪里

协议兼容或消息路径

优先看：

• modules/core_chat/
• platform/esp/.../chat/infra/
• platform/nrf52/.../chat/infra/
• docs/MULTI_PROTOCOL_SUPPORT.md

地图、轨迹和 GPS

优先看：

• modules/core_gps/
• platform/esp/.../gps/
• platform/.../ui/...map...
• docs/map/SD_CARD_MAP_STRUCTURE_CN.md

Team

优先看：

• modules/core_team/
• platform/esp/.../team/
• docs/TEAM.md

板级适配

优先看：

• boards/<target>/
• variants/<target>/
• 对应设备文档页

菜单和页面

优先看：

• modules/ui_shared/
• modules/ui_mono_128x64/
• modules/ui_shared/src/ui/app_catalog_builder.cpp

对维护者最重要的一点

当前仓库不是完全重构完成后的终态。docs/ARCHITECTURE.md 已经明确指出，项目正在往“一个共享核心，多平台壳层”的方向演进，同时避免再复制完整源码树。

因此，维护时最需要警惕的不是“目录看起来有点多”，而是：

• 不要把本该共享的业务逻辑再次塞回某个板级壳层
• 不要把平台细节偷偷带进共享模块
• 不要为了某块板子快点跑起来，又复制出一整套平行实现

这三件事比某个函数名字起得好不好更影响项目长期可维护性。