补充提交：无关紧要的文件修改，不用理会

.vscode/settings.json

@@ -109,7 +109,7 @@
     "random": "cpp",
     "*.obj": "cpp"
   },
-  "idf.port": "/dev/tty.usbmodem834401",
+  "idf.port": "/dev/tty.usbmodem834101",
   "idf.espIdfPath": "/Users/rdzleo/esp/esp-idf/v5.4.2/esp-idf",
   "idf.toolsPath": "/Users/rdzleo/.espressif",
   "idf.pythonInstallPath": "/opt/homebrew/bin/python3",

docs/电子吧唧按键功能规划文档.md

@@ -0,0 +1,476 @@
+# Dzbj_ESP32_S3 纯电子吧唧 — 两键实现三键功能规划
+
+> 更新日期：2026-03-25
+> 目标项目：Dzbj_ESP32_S3（纯电子吧唧，无 AI 对话模式）
+> 参考实现：Baji_Rtc_Toy_Key（宝石角按键版）的 key_nav 模块
+> 硬件平台：ESP32-S3-N16R8，与 Baji_Rtc_Toy 开发板相同
+
+---
+
+## 一、硬件现状
+
+### 1.1 物理按键
+
+| 按键 | GPIO | 电气特性 | 可用于业务控制 |
+|------|------|---------|:---:|
+| **BOOT** | GPIO0 | 低电平有效，内部上拉 | ✅ |
+| **KEY2** | GPIO4 | 低电平有效，内部上拉 | ✅ |
+| **SW1** | — | 物理电源开关，未接 MCU GPIO | ❌ |
+
+> SW1 为纯硬件断电开关，无法被软件检测，不参与业务逻辑。
+
+### 1.2 当前按键驱动（待重构）
+
+当前使用 GPIO ISR + 手动去抖（200ms 时间戳），**只支持"按下"一种事件**：
+
+```c
+// 当前驱动（button.c）
+gpio_isr_handler() → xQueueSend → btn_task() → 200ms去抖 → 回调
+```
+
+**问题**：2 个按键 × 1 种事件 = **只有 2 种操作**，无法覆盖宝石角的全部功能。
+
+---
+
+## 二、宝石角（3 键）功能分析
+
+宝石角按键版有 3 个按键：**BOOT**、**KEY1**、**KEY2**。通过 `iot_button` 组件支持单击/双击/长按，加上 key_nav 导航管理器，实现了完整的无触摸交互。
+
+### 2.1 宝石角各界面按键行为
+
+| 界面 | BOOT 单击 | KEY 单击 | BOOT 双击 | KEY 长按 |
+|------|----------|---------|----------|---------|
+| **Home** | → Set | → Img | — | — |
+| **Img（浏览）** | → Home | 下一张图片 | → Home | — |
+| **Img（删除确认）** | 确认删除 | 取消（退出删除模式） | → Home | — |
+| **Set（无焦点）** | → Home | 选中第一个图标 | → Home | — |
+| **Set（有焦点）** | 执行选中功能 | 切换到下一个焦点 | → Home | — |
+| **Set（亮度调节）** | 亮度 +10% | 亮度 -10% | → Home | 退出调节模式 |
+| **应援灯** | 切换颜色 | 退出 → Set | → Home | — |
+
+### 2.2 宝石角 Set 界面焦点系统
+
+焦点通过蓝色边框高亮（`#2196F3`，3px），KEY 单击循环切换：
+
+```
+节能 → 应援灯 → 删除 → 亮度 → 节能 → ...
+```
+
+BOOT 单击执行当前焦点对应的功能（进入应援灯、进入亮度调节、进入删除模式等）。
+
+---
+
+## 三、两键方案设计
+
+### 3.1 核心思路
+
+用 `iot_button` 组件替换当前 GPIO ISR 驱动，为 2 个按键获得 **6 种事件**：
+
+| 按键 | 单击 | 双击 | 长按 |
+|------|------|------|------|
+| **BOOT (GPIO0)** | ✅ | ✅ | ✅ |
+| **KEY2 (GPIO4)** | ✅ | ✅ | ✅ |
+
+2 键 × 3 种事件 = **6 种操作**，完全覆盖宝石角 3 键的功能需求。
+
+### 3.2 按键角色定义
+
+| 按键 | 角色 | 助记 |
+|------|------|------|
+| **BOOT** | 确认 / 执行 / 返回 | 右手拇指（主操作） |
+| **KEY2** | 导航 / 切换 / 浏览 | 左手拇指（辅助操作） |
+
+### 3.3 iot_button 时间参数
+
+```c
+button_config_t btn_cfg = {
+    .long_press_time = 2000,    // 长按阈值 2 秒
+    .short_press_time = 0,      // 双击检测窗口 180ms（默认值）
+};
+```
+
+| 事件 | 触发条件 |
+|------|---------|
+| 单击 | 按下后 180ms 内无第二次按下 |
+| 双击 | 180ms 内连续按下两次 |
+| 长按 | 持续按住超过 2 秒 |
+
+---
+
+## 四、完整按键映射表
+
+### 4.1 屏幕关闭（低功耗模式）
+
+| 按键 | 任何操作 | 行为 |
+|------|---------|------|
+| BOOT | 按下 | 唤醒屏幕，恢复亮度，不触发业务 |
+| KEY2 | 按下 | 唤醒屏幕，恢复亮度，不触发业务 |
+
+> 唤醒后回到休眠前的界面。
+
+### 4.2 Home 界面
+
+| 按键 | 事件 | 行为 | 说明 |
+|------|------|------|------|
+| BOOT | 单击 | → **Set** 界面 | 进入设置 |
+| KEY2 | 单击 | → **Img** 界面 | 进入图片浏览 |
+| BOOT | 长按 | — | 预留（可用于关机提示/重置等） |
+| KEY2 | 长按 | — | 预留 |
+
+### 4.3 Img 界面（图片浏览）
+
+| 按键 | 事件 | 行为 | 说明 |
+|------|------|------|------|
+| KEY2 | 单击 | **下一张**图片 | 自动跳过解码失败的无效图片 |
+| KEY2 | 双击 | **上一张**图片 | 自动跳过无效图片 |
+| BOOT | 单击 | → **Home** 界面 | 返回主界面 |
+| BOOT | 长按 | 进入 **删除确认** 模式 | 替代宝石角的 Set→删除→Img 路径 |
+
+> 宝石角用左右两个按键分别切换上/下一张。本方案用 KEY2 单击=下一张、双击=上一张，一个按键两个方向。
+
+### 4.4 Img 界面（删除确认模式）
+
+BOOT 长按触发后，显示删除确认 UI（ContainerDle）：
+
+| 按键 | 事件 | 行为 | 说明 |
+|------|------|------|------|
+| BOOT | 单击 | **确认删除**当前图片 | 删除后自动显示下一张 |
+| KEY2 | 单击 | **取消**，退出删除模式 | 隐藏 ContainerDle |
+
+### 4.5 Set 界面（焦点导航模式）
+
+进入 Set 界面后，默认无焦点。KEY2 单击开始焦点循环：
+
+```
+无焦点 → 节能 → 应援灯 → 亮度 → (无焦点) → 节能 → ...
+```
+
+> 注：相比宝石角去掉了"删除"焦点项。删除功能已移到 Img 界面的 BOOT 长按中，避免 Set→Img 的复杂跳转。
+
+| 按键 | 事件 | 行为 | 说明 |
+|------|------|------|------|
+| KEY2 | 单击 | **切换焦点**到下一个图标 | 蓝色边框高亮 |
+| BOOT | 单击（无焦点时） | → **Home** 界面 | 返回 |
+| BOOT | 单击（有焦点时） | **执行**选中功能 | 进入节能/应援灯/亮度调节 |
+| BOOT | 单击（在焦点项上） | → 对应功能 | 详见下方 |
+
+**各焦点项的执行行为**：
+
+| 焦点项 | BOOT 单击执行 |
+|--------|-------------|
+| 节能 | 切换节能模式开/关（亮度降至 10% + 10s 超时熄屏） |
+| 应援灯 | 进入应援灯全屏模式 |
+| 亮度 | 进入亮度调节模式 |
+
+### 4.6 Set 界面（亮度调节模式）
+
+从焦点"亮度"按 BOOT 进入，滑块高亮显示：
+
+| 按键 | 事件 | 行为 | 说明 |
+|------|------|------|------|
+| BOOT | 单击 | 亮度 **+10%** | 上限 100% |
+| KEY2 | 单击 | 亮度 **-10%** | 下限 10% |
+| KEY2 | 长按 | **退出**亮度调节模式 | 回到焦点导航 |
+
+### 4.7 应援灯全屏模式
+
+从焦点"应援灯"按 BOOT 进入：
+
+| 按键 | 事件 | 行为 | 说明 |
+|------|------|------|------|
+| BOOT | 单击 | **切换颜色**（红→绿→蓝→循环） | LCD 硬件级写 GRAM |
+| KEY2 | 单击 | **退出** → Set 界面 | 恢复原亮度 |
+
+### 4.8 ScreenChar 角色动画界面（如有）
+
+| 按键 | 事件 | 行为 | 说明 |
+|------|------|------|------|
+| BOOT | 单击 | 切换动画播放/暂停 | 保持原有逻辑 |
+
+---
+
+## 五、与宝石角功能对照
+
+### 5.1 功能覆盖对比
+
+| 功能 | 宝石角（3 键） | 本方案（2 键） | 实现方式 |
+|------|:---:|:---:|------|
+| 界面导航（Home/Img/Set） | ✅ | ✅ | BOOT=确认/返回，KEY2=切换 |
+| 下一张图片 | ✅ KEY 单击 | ✅ KEY2 单击 | 相同 |
+| 上一张图片 | ✅ 另一个KEY | ✅ KEY2 双击 | 双击替代第三键 |
+| 删除图片 | ✅ Set→删除→Img | ✅ Img 中 BOOT 长按 | 更直接，少一步跳转 |
+| Set 焦点导航 | ✅ | ✅ | 相同 |
+| 亮度调节 | ✅ | ✅ | 相同 |
+| 应援灯 | ✅ | ✅ | 相同 |
+| 节能开关 | ✅ | ✅ | 相同 |
+| 低功耗唤醒 | ✅ | ✅ | 两键均可唤醒 |
+| 跳过无效图片 | ✅ | ✅ | 自动跳过（已实现） |
+
+### 5.2 操作差异
+
+| 操作 | 宝石角 | 本方案 | 差异说明 |
+|------|--------|--------|---------|
+| 上一张图片 | 独立按键单击 | KEY2 双击 | 需要快速双击，操作稍慢 |
+| 删除图片入口 | Set 界面焦点 | Img 界面 BOOT 长按 | 更直接，浏览时即可删除 |
+| 退出亮度调节 | KEY 长按 | KEY2 长按 | 相同 |
+
+---
+
+## 六、界面导航图
+
+```
+                    ┌──────────────────┐
+                    │   Home（主界面）   │
+                    │                  │
+                    │  BOOT→Set        │
+                    │  KEY2→Img        │
+                    └───┬──────────┬───┘
+                        │          │
+              BOOT单击   │          │  KEY2单击
+                        ▼          ▼
+          ┌─────────────────┐  ┌──────────────────────┐
+          │  Set（设置界面）  │  │  Img（图片浏览界面）   │
+          │                 │  │                      │
+          │  KEY2：焦点切换  │  │  KEY2单击：下一张      │
+          │  BOOT：执行/返回 │  │  KEY2双击：上一张      │
+          │                 │  │  BOOT单击：返回Home    │
+          │  ┌────────────┐ │  │  BOOT长按：删除确认    │
+          │  │焦点项：     │ │  │                      │
+          │  │ 节能       │ │  │  ┌──────────────────┐ │
+          │  │ 应援灯 ──┐ │ │  │  │  删除确认模式     │ │
+          │  │ 亮度 ──┐ │ │ │  │  │  BOOT：确认删除   │ │
+          │  └───────┼─┼─┘ │  │  │  KEY2：取消        │ │
+          └──────────┼─┼───┘  │  └──────────────────┘ │
+                     │ │      └──────────────────────┘
+                     │ │
+           ┌─────────┘ └──────────┐
+           ▼                      ▼
+  ┌─────────────────┐   ┌──────────────────┐
+  │  亮度调节模式     │   │  应援灯全屏模式   │
+  │                 │   │                  │
+  │  BOOT：亮度+10% │   │  BOOT：切换颜色   │
+  │  KEY2：亮度-10%  │   │  KEY2：退出→Set  │
+  │  KEY2长按：退出   │   │                  │
+  └─────────────────┘   └──────────────────┘
+```
+
+---
+
+## 七、技术实现要点
+
+### 7.1 按键驱动重构：GPIO ISR → iot_button
+
+**当前**（button.c）：
+```c
+// GPIO 中断 + 手动 200ms 去抖，只支持"按下"
+gpio_isr_handler_add(PIN_BTN_BOOT, gpio_isr_handler, ...);
+```
+
+**目标**（使用 iot_button 组件）：
+```c
+#include "iot_button.h"
+
+button_config_t btn_cfg = {
+    .long_press_time = 2000,
+    .short_press_time = 0,  // 默认 180ms 双击窗口
+};
+button_gpio_config_t gpio_cfg = {
+    .gpio_num = PIN_BTN_BOOT,
+    .active_level = 0,  // 低电平有效
+};
+
+button_handle_t boot_handle;
+iot_button_new_gpio_device(&btn_cfg, &gpio_cfg, &boot_handle);
+
+// 注册三种事件
+iot_button_register_cb(boot_handle, BUTTON_SINGLE_CLICK, NULL, boot_click_cb, NULL);
+iot_button_register_cb(boot_handle, BUTTON_DOUBLE_CLICK, NULL, boot_dblclick_cb, NULL);
+iot_button_register_cb(boot_handle, BUTTON_LONG_PRESS_START, NULL, boot_longpress_cb, NULL);
+```
+
+**依赖添加**（idf_component.yml）：
+```yaml
+dependencies:
+  button: ">=3.2.0"
+```
+
+### 7.2 key_nav 导航管理器
+
+从宝石角移植 key_nav 模块，核心结构：
+
+```c
+// 导航上下文（根据当前界面和模式决定按键行为）
+typedef enum {
+    NAV_CTX_HOME,           // Home 界面
+    NAV_CTX_IMG,            // Img 浏览
+    NAV_CTX_IMG_DELETE,     // Img 删除确认
+    NAV_CTX_SET,            // Set 焦点导航
+    NAV_CTX_SET_BRIGHTNESS, // 亮度调节
+    NAV_CTX_FLASHLIGHT,     // 应援灯
+} nav_context_t;
+
+// Set 焦点项（比宝石角少了"删除"项）
+typedef enum {
+    SET_FOCUS_NONE = -1,
+    SET_FOCUS_LOW_POWER = 0,
+    SET_FOCUS_FLASHLIGHT,
+    SET_FOCUS_BRIGHTNESS,
+    SET_FOCUS_COUNT,
+} set_focus_item_t;
+```
+
+### 7.3 回调中禁止 vTaskDelay（关键约束）
+
+`iot_button` 回调在 `esp_timer` 任务中执行，必须派发到独立任务：
+
+```c
+static void boot_click_cb(void *arg, void *data) {
+    // ❌ 禁止：vTaskDelay(pdMS_TO_TICKS(100));
+    // ✅ 正确：派发到独立任务
+    xTaskCreate(nav_boot_click_task, "nav_boot", 3072, NULL, 5, NULL);
+}
+
+static void nav_boot_click_task(void *arg) {
+    // 这里可以安全地 vTaskDelay、修改 LVGL 等
+    if (sleep_mgr_is_screen_off()) {
+        sleep_mgr_notify_activity();
+    } else {
+        // 根据当前 nav_context 执行对应操作
+        handle_boot_click();
+    }
+    vTaskDelete(NULL);
+}
+```
+
+### 7.4 焦点高亮样式
+
+```c
+#define FOCUS_BORDER_COLOR  0x2196F3  // Material Blue
+#define FOCUS_BORDER_WIDTH  3
+
+static void set_focus_border(lv_obj_t *obj, bool active) {
+    lvgl_port_lock(0);
+    if (active) {
+        lv_obj_set_style_border_color(obj, lv_color_hex(FOCUS_BORDER_COLOR), LV_PART_MAIN);
+        lv_obj_set_style_border_width(obj, FOCUS_BORDER_WIDTH, LV_PART_MAIN);
+        lv_obj_set_style_border_opa(obj, LV_OPA_COVER, LV_PART_MAIN);
+    } else {
+        lv_obj_set_style_border_opa(obj, LV_OPA_TRANSP, LV_PART_MAIN);
+    }
+    lvgl_port_unlock();
+}
+```
+
+### 7.5 应援灯颜色切换优化
+
+绕过 LVGL 分band渲染，直接写 LCD GRAM（瞬间切换，无从上到下刷新感）：
+
+```c
+void flashlight_switch_color(void) {
+    lcd_disp_on_off(false);     // DISPOFF：LCD 停止输出
+    lcd_fill_color(new_color);  // 直接写 GRAM（~35ms）
+    lcd_disp_on_off(true);      // DISPON：瞬间恢复，画面已完整
+}
+```
+
+---
+
+## 八、文件变更清单
+
+### 8.1 需要重构的文件
+
+| 文件 | 变更内容 |
+|------|---------|
+| `main/button/button.c` | GPIO ISR → iot_button 组件，支持单击/双击/长按 |
+| `main/button/include/button.h` | 新增事件类型枚举，回调签名变更 |
+| `main/main.c` | 移除 `boot_btn_handler()`（~65 行），集成 `key_nav_init()` |
+| `main/ui/screens/ui_ScreenHome.c` | 移除手势事件函数 |
+| `main/ui/screens/ui_ScreenImg.c` | 移除手势/点击事件，保留 SCREEN_LOADED |
+| `main/ui/screens/ui_ScreenSet.c` | 移除手势/滑块/点击事件 |
+| `main/sleep_mgr/sleep_mgr.c` | 移除按键回调注册，由 key_nav 统一处理 |
+| `main/CMakeLists.txt` | 添加 key_nav 源文件和头文件路径 |
+| `main/idf_component.yml` | 添加 `button: ">=3.2.0"` 依赖 |
+
+### 8.2 需要新增的文件
+
+| 文件 | 功能 |
+|------|------|
+| `main/key_nav/key_nav.c` | 按键导航管理器（从宝石角移植，适配两键方案） |
+| `main/key_nav/include/key_nav.h` | 导航上下文枚举 + 焦点状态 |
+
+### 8.3 需要新增的函数
+
+| 函数 | 文件 | 功能 |
+|------|------|------|
+| `lcd_fill_color(uint32_t color)` | `main/lcd/lcd.c` | 直接写 GRAM 填充颜色（应援灯优化） |
+| `flashlight_switch_color()` | `ui_ScreenSet.c` | 应援灯颜色切换（调用 lcd_fill_color） |
+
+---
+
+## 九、实施步骤
+
+1. **添加 iot_button 依赖** → `idf_component.yml`
+2. **重构 button 模块** → 替换 GPIO ISR 为 iot_button，支持 6 种事件
+3. **新建 key_nav 模块** → 从宝石角移植，调整为两键方案（KEY2 双击=上一张，BOOT 长按=删除）
+4. **移除触摸事件** → 各 Screen 文件中删除手势/点击回调和 `lv_obj_add_event_cb` 注册
+5. **适配 main.c** → 删除旧的 `boot_btn_handler()`，添加 `key_nav_init()`
+6. **适配 sleep_mgr** → 唤醒逻辑由 key_nav 统一处理
+7. **添加 lcd_fill_color()** → 应援灯硬件级颜色切换
+8. **更新 CMakeLists.txt** → 添加新源文件和头文件路径
+9. **编译测试** → `idf.py build`
+10. **逐功能验证** → 按第十章清单测试
+
+---
+
+## 十、测试验证清单
+
+### 10.1 基础功能
+
+- [ ] BOOT 单击 / 双击 / 长按 事件均可正确触发
+- [ ] KEY2 单击 / 双击 / 长按 事件均可正确触发
+- [ ] 屏幕关闭时任意按键唤醒，不触发业务
+
+### 10.2 Home 界面
+
+- [ ] BOOT 单击 → 进入 Set
+- [ ] KEY2 单击 → 进入 Img
+
+### 10.3 Img 界面
+
+- [ ] KEY2 单击 → 下一张图片（自动跳过无效图片）
+- [ ] KEY2 双击 → 上一张图片（自动跳过无效图片）
+- [ ] BOOT 单击 → 返回 Home
+- [ ] BOOT 长按 → 显示删除确认
+- [ ] 删除确认中 BOOT 单击 → 删除成功
+- [ ] 删除确认中 KEY2 单击 → 取消
+
+### 10.4 Set 界面
+
+- [ ] KEY2 单击 → 焦点循环切换（蓝色边框）
+- [ ] BOOT 单击（无焦点）→ 返回 Home
+- [ ] BOOT 单击（节能焦点）→ 切换节能模式
+- [ ] BOOT 单击（应援灯焦点）→ 进入应援灯
+- [ ] BOOT 单击（亮度焦点）→ 进入亮度调节
+
+### 10.5 亮度调节
+
+- [ ] BOOT 单击 → 亮度 +10%（上限 100%）
+- [ ] KEY2 单击 → 亮度 -10%（下限 10%）
+- [ ] KEY2 长按 → 退出亮度调节模式
+
+### 10.6 应援灯
+
+- [ ] BOOT 单击 → 颜色切换（红→绿→蓝→红）
+- [ ] KEY2 单击 → 退出回到 Set
+
+### 10.7 低功耗
+
+- [ ] 10 秒无操作 → 屏幕熄灭
+- [ ] 任意按键 → 唤醒，显示熄屏前的界面
+- [ ] 唤醒时不闪烁（先渲染再恢复亮度）
+
+### 10.8 稳定性
+
+- [ ] 快速连续按键不崩溃（防抖正常）
+- [ ] 连续切换 20+ 张图片无内存泄漏
+- [ ] 长时间运行 1 小时无崩溃