feat(ota): 会话 epoch/通道标识 + BLE 中止命令 + NVS 线程安全

- 新增 ota_channel_t(WiFi/BLE) + m_otaEpoch 会话代次，
  abortCurrentIfEpoch 防止同类型重启后旧 handler 误清新会话
- 同通道再次发起 OTA 时自动中止旧会话并重开
- 统一 prepareGd32Storage(validate+begin+erase+meta)，
  消除 BLE/WiFi 两路径隐式差异
- OtaRelay 拆分子步骤(doRelayPackets/doFinishAndVerify)，
  状态成员私有化消除数据竞争
- Gd32FlashStore NVS 读写加 mutex，metaUpdate 原子化
- BLE OTA 新增 0xFB 中止命令（保持连接）+ 0x20 ABORTED 处理
- HTTP handler 改 per-request buffer 支持并发
- 修复 CRITICAL 状态 RSSI 恢复无法降级的缺陷
- main.cpp 关键任务失败触发看门狗重启
- style.css 增强动画 + prefers-reduced-motion 兼容

.trae/specs/simplify-arch-boilerplate/checklist.md

@@ -0,0 +1,16 @@
+- [x] 仓库根临时文件已删除：`old_wifi_ota.cpp.tmp`、`original_app.js.tmp`、`appjs_diff.txt`、`build_baseline.log`、`build_output.log` 不存在
+- [x] `OtaCoordinator::isIdle()` 仅调用一次 `getSystemState()`（即一次 `lock()`）
+- [x] `OtaCoordinator::getSystemStateString()` 仅调用一次 `getSystemState()`
+- [x] 8 个 GD32 存储 wrapper（`writeGd32Chunk/saveGd32Meta/loadGd32Meta/updateGd32Meta/clearGd32Meta/verifyGd32Firmware/finalizeGd32Checksum/eraseGd32Partition`）已改为 `inline` 并在头文件中实现，`.cpp` 中对应实现已删除
+- [x] 调用方（`http_handlers.cpp`、`ble_ota.cpp` 等）无需改动即可编译通过（签名不变）
+- [x] `wifi_ota.cpp::httpServerStart()` 使用路由表 + 循环注册，9 个端点及其 OPTIONS 预检全部注册
+- [x] HTTP 路由注册行为与原实现等价（端点、method、handler 对应关系一致）
+- [x] `OtaRelay` 新增 `commonReject` helper，各 `handle*` 开头拒绝分支等价于原实现
+- [x] `handleTransferring` 的 `RELAY_EVT_HEALTH_CRIT` 拒绝分支保留
+- [x] `forwardFirmware()` 不再使用 `goto cleanup`，5 步驱动顺序与超时检查时机不变
+- [x] `SpiMaster` 删除 `syncTransferUnlocked` / `sendUnlocked`，公共 API 通过 `LockGuard` + Impl 实现
+- [x] `SpiMaster::transferWithRetry` 调用路径更新为 Impl，无递归加锁
+- [x] `HealthMonitor` 新增 `LockGuard` 内部类，`getState/setState/getLastTemperature/getLastWifiRssi/tempMonitorCallback` 使用 RAII 守卫
+- [x] 评审"不建议改的地方"全部未动：5 步驱动顺序、健康检查时机、watchdog 自愈、`forceCleanup` 仅 `isIdle()`、`Esp32OtaCore` 双层 mutex 语义
+- [x] `idf.py build` 编译通过，无新增警告（15 个源文件 0 warning / 0 error）
+- [x] `main/` 目录行数较变更前减少（主要削减：`httpServerStart` 173→67、`ota_coordinator.cpp` 8 wrapper 删除、`spi_master.cpp` 2 Unlocked 删除、`ota_relay.cpp` goto 重构）

.trae/specs/simplify-arch-boilerplate/spec.md

@@ -0,0 +1,75 @@
+# 架构精简：去样板与重复加锁 Spec
+
+## Why
+`docs/esp32_architecture_review_2026-06-25.md` 指出当前代码存在大量零/低风险的重复样板（HTTP URI 注册粘贴、OtaCoordinator 纯转发 wrapper、OtaRelay 事件分发头部、SpiMaster *Unlocked 镜像）以及状态查询时的重复加锁。这些不影响运行时行为，但增加维护成本、放大锁争用，并留下两路代码不同步的隐患。本变更按评审推荐的顺序落地 A~F + 快速清理，预期 `main/` 减约 350~450 行，且不改运行时语义。
+
+## What Changes
+- **快速清理**：删除仓库根的临时/历史中间产物（`*.tmp`、`*.log`、`appjs_diff.txt`）。
+- **A.1**：把 `OtaCoordinator` 中 9 个纯转发到 `Gd32FlashStore` 的 wrapper 改为 `inline` 并移入头文件，`.cpp` 删除对应实现。
+- **A.2**：`OtaCoordinator::isIdle / isGd32Busy / isEsp32Busy` 改为一次 `getSystemState()` 取值后比较，消除多次 `lock()`。
+- **B**：`wifi_ota.cpp::httpServerStart()` 的 9×{POST/GET, OPTIONS} 复制粘贴改为路由表 + 循环注册。
+- **C**：`OtaRelay::handle*` 头部重复的 ABORT/TIMEOUT/HEALTH_CRIT 拒绝逻辑提取为 `commonReject` helper；`forwardFirmware()` 的 5 次顺序 `processEvent(START)` 改为状态驱动循环，去掉 `goto cleanup`。
+- **D**：`SpiMaster` 的 `syncTransfer/syncTransferUnlocked`、`send/sendUnlocked`、`otaPollResponse/otaPollResponseUnlocked` 三对镜像折叠为「公共 API 加锁 → 调内部 Impl」单一实现。
+- **F**：`HealthMonitor` 的 `getCurrent/getState/setState/getLastTemperature/getLastWifiRssi/tempMonitorCallback` 中重复的 `if (m_mutex) xSemaphoreTake/Give` 改为 RAII `LockGuard`（与 SpiMaster 一致）。
+
+**不在本次范围**（评审标记为低优先级/可选/行为变更）：
+- E（退役 UDP 日志通道）：涉及调试工作流行为变更，评审标为"低优先级""可考虑"，留作后续。
+- G（BLE OTA finish ctx malloc→静态）：评审明确"不是精简，是健壮性"，位于 OTA 关键路径，需单独回归，留作后续。
+- H（README 同步）：仅当采用 A 的"移除 wrapper"方案时才需要；本次采用 A.1（inline 保留语义），README 现有描述仍然成立，无需改动。
+
+## Impact
+- 受影响代码：
+  - `main/ota/ota_coordinator.h` / `.cpp`（A.1, A.2）
+  - `main/server/wifi_ota.cpp`（B）
+  - `main/relay/ota_relay.h` / `.cpp`（C）
+  - `main/transport/spi_master.h` / `.cpp`（D）
+  - `main/monitor/health_monitor.h` / `.cpp`（F）
+- 受影响能力：OTA 协调器状态查询、HTTP 路由注册、OTA 中继状态机、SPI 总线访问、健康监控状态读写。
+- **不改**运行时行为：状态机 5 步驱动顺序、健康检查时机、watchdog 自愈、`forceCleanup` 仅在 `isIdle()` 启动、`Esp32OtaCore` 双层 mutex 语义均保持不变（评审"不建议改的地方"）。
+
+## ADDED Requirements
+
+### Requirement: HTTP 路由表化注册
+系统 SHALL 使用静态路由表 + 循环注册所有 HTTP URI handler，新增端点仅需在表中追加一行。
+
+#### Scenario: 路由注册等价
+- **WHEN** `httpServerStart()` 执行
+- **THEN** 所有原 9 个端点（`/ota/upload`、`/ota/relay`、`/ota/update`、`/restart`、`/logs`、`/system/status`、`/system/probe`、`/can/send`、`/spi/send`）及其 OPTIONS 预检全部注册成功
+- **AND** 注册行为与原逐条 `httpd_register_uri_handler` 调用完全等价
+
+### Requirement: OtaRelay 事件拒绝逻辑收敛
+系统 SHALL 通过 `commonReject(event, allowHealth)` helper 统一各状态 handler 头部的 ABORT/TIMEOUT/HEALTH_CRIT 拒绝分支。
+
+#### Scenario: 拒绝分支等价
+- **WHEN** 任一 `handle*` 收到 `RELAY_EVT_ABORT`
+- **THEN** 状态转为 `RELAY_ERROR` 并返回 `OTA_RESULT_ERR_USER_ABORT`
+- **WHEN** 收到 `RELAY_EVT_TIMEOUT`
+- **THEN** 状态转为 `RELAY_ERROR` 并返回 `OTA_RESULT_ERR_TIMEOUT`
+- **WHEN** `handleTransferring` 收到 `RELAY_EVT_HEALTH_CRIT`
+- **THEN** 状态转为 `RELAY_ERROR` 并返回 `OTA_RESULT_ERR_HEALTH`
+
+### Requirement: SpiMaster 单一加锁路径
+系统 SHALL 通过单一内部实现（`*Impl`）承载加锁与无锁两路调用，公共 API 包一层锁，已持锁路径直调 Impl，消除两份镜像逻辑。
+
+#### Scenario: 加锁语义不变
+- **WHEN** 外部调用 `syncTransfer/send/otaPollResponse`
+- **THEN** 内部先获取 `m_mutex` 再执行传输
+- **WHEN** 已持锁的内部路径调用 Impl 版本
+- **THEN** 不重复加锁，避免递归死锁
+
+## MODIFIED Requirements
+
+### Requirement: OtaCoordinator GD32 存储操作入口
+传输层通过 `OtaCoordinator` 的统一入口操作 GD32 Flash（解决 H3 绕过协调器问题）。9 个纯转发 wrapper（`writeGd32Chunk/saveGd32Meta/loadGd32Meta/updateGd32Meta/clearGd32Meta/verifyGd32Firmware/finalizeGd32Checksum/eraseGd32Partition`）改为 `inline` 定义在头文件中，直接委托 `Gd32FlashStore::instance()`，签名与调用方语义不变。
+
+### Requirement: OtaCoordinator 状态查询
+`isIdle / isGd32Busy / isEsp32Busy` SHALL 各仅调用一次 `getSystemState()`（即一次 `lock()`），在局部变量上完成所有比较。`getSystemStateString` 同样仅取值一次。
+
+### Requirement: OtaRelay forwardFirmware 状态驱动
+`forwardFirmware()` SHALL 以状态驱动循环推进 IDLE→HANDSHAKING→SIZE_NEG→TRANSFERRING→FINISHING→DONE，任一步返回非 OK 即跳出并复位，不再使用 `goto cleanup`。5 步驱动顺序与超时检查时机保持不变。
+
+### Requirement: HealthMonitor 状态访问加锁
+`HealthMonitor` 所有访问 `m_healthState / m_lastTemperature / m_lastWifiRssi / m_lastWifiRssiMs` 的方法 SHALL 通过 RAII `LockGuard`（构造 take、析构 give）保护，与 SpiMaster 的 LockGuard 风格一致。
+
+## REMOVED Requirements
+（无移除）

.trae/specs/simplify-arch-boilerplate/tasks.md

@@ -0,0 +1,50 @@
+# Tasks
+
+- [x] Task 1: 快速清理仓库根临时文件
+  - [x] SubTask 1.1: 删除 `old_wifi_ota.cpp.tmp`、`original_app.js.tmp`、`appjs_diff.txt`、`build_baseline.log`、`build_output.log`
+  - [x] SubTask 1.2: 评估 `sdkconfig.bak.mbedtls_trim` / `sdkconfig.ci.c3eco7` / `sdkconfig.ci.esp32c2*` / `sdkconfig.ci.wpa_psk` 是否与 ESP32-C3FH4 目标相关，无关则删除（需确认未被 CMake/CI 引用）— 已确认未被 CMake/CI 引用，均为其他芯片变体配置，已删除
+
+- [x] Task 2: A.2 — OtaCoordinator 状态查询单次取值
+  - [x] SubTask 2.1: `isIdle()` 改为 `ota_system_state_t s = getSystemState();` 后一次比较 IDLE/STORED/COMPLETE
+  - [x] SubTask 2.2: `isGd32Busy()` 已是单次取值，确认无需改动
+  - [x] SubTask 2.3: `isEsp32Busy()` 已是单次取值，确认无需改动
+  - [x] SubTask 2.4: `getSystemStateString()` 改为 `switch(getSystemState())` 单次取值（当前每次 case 隐式调用）
+
+- [x] Task 3: A.1 — OtaCoordinator 9 个存储 wrapper inline 化
+  - [x] SubTask 3.1: 在 `ota_coordinator.h` 中将 `writeGd32Chunk/saveGd32Meta/loadGd32Meta/updateGd32Meta/clearGd32Meta/verifyGd32Firmware/finalizeGd32Checksum/eraseGd32Partition` 改为 `inline` 实现并直接委托 `Gd32FlashStore::instance()`
+  - [x] SubTask 3.2: 删除 `ota_coordinator.cpp` 中这 8 个函数的对应实现（注意 `writeGd32Chunk` 等）
+  - [x] SubTask 3.3: 确认头文件已 `#include "storage/gd32_flash_store.h"`（当前已包含）
+
+- [x] Task 4: B — WiFi HTTP URI 路由表化
+  - [x] SubTask 4.1: 在 `wifi_ota.cpp::httpServerStart()` 顶部定义 `UriEntry { uri, method, handler }` 静态数组，列出 9 个端点
+  - [x] SubTask 4.2: 用 for 循环对每个 entry 注册主 method + HTTP_OPTIONS（`http_options_handler`）
+  - [x] SubTask 4.3: 保留 NVS 恢复固件状态的前置逻辑与启动日志不变
+  - [x] SubTask 4.4: 确认 `max_uri_handlers=32` 仍足够（9×2=18，余量充足）
+
+- [x] Task 5: C — OtaRelay 事件分发去重
+  - [x] SubTask 5.1: 在 `ota_relay.cpp` 匿名命名空间添加 `commonReject(relay_event_t e, bool allowHealth=false)`，返回 `OTA_RESULT_OK` 或对应错误码（不改状态）
+  - [x] SubTask 5.2: `handleHandshaking/handleSizeNeg/handleTransferring/handleFinishing` 开头调用 `commonReject`，仅在其返回非 OK 时 `setState(RELAY_ERROR)` 并返回（`handleTransferring` 传 `allowHealth=true`）
+  - [x] SubTask 5.3: `forwardFirmware()` 将 5 次顺序 `processEvent(START)` 改为 while 循环：当前状态非 DONE/ERROR 时持续推进，任一步非 OK 即跳出；去掉 `goto cleanup`，失败路径统一 `reset()`
+  - [x] SubTask 5.4: 保持 5 步驱动顺序与"同步 handler 执行后才检查超时"的语义不变
+
+- [x] Task 6: D — SpiMaster *Unlocked 镜像折叠
+  - [x] SubTask 6.1: 保留 `transferClocked` / `transferRequestResponse` / `otaPollResponseUnlocked` 作为内部 Impl（已持锁路径调用）
+  - [x] SubTask 6.2: `syncTransfer` 公共 API：`LockGuard` + 直接调 `transferRequestResponse`（删除 `syncTransferUnlocked`，其唯一调用方 `transferWithRetry` 改为调 `transferRequestResponse`）
+  - [x] SubTask 6.3: `send` 公共 API：`LockGuard` + 直接调 `transferRequestResponse`（删除 `sendUnlocked`，确认无外部调用方）
+  - [x] SubTask 6.4: `otaPollResponse` 公共 API：`LockGuard` + 调 `otaPollResponseUnlocked`（保持不变，已是该模式）
+  - [x] SubTask 6.5: 更新 `spi_master.h`：移除已删除的 `syncTransferUnlocked`/`sendUnlocked` 声明
+
+- [x] Task 7: F — HealthMonitor RAII LockGuard
+  - [x] SubTask 7.1: 在 `health_monitor.h` 私有区添加 `LockGuard` 内部类（与 SpiMaster 风格一致：构造 take portMAX_DELAY，析构 give，禁拷贝）
+  - [x] SubTask 7.2: `getState/setState/getLastTemperature/getLastWifiRssi/tempMonitorCallback` 改用 `LockGuard lock(m_mutex);`
+  - [x] SubTask 7.3: `setWifiConnected` 中 `m_wifiConnected` 为 `volatile`，确认是否仍需加锁（当前未加锁，保持现状，仅文档化其为原子推送）
+
+- [x] Task 8: 编译验证
+  - [x] SubTask 8.1: 运行 `idf.py build` 确认无编译错误/警告回归（15 个源文件 0 warning / 0 error，CMake 配置 + 编译阶段均通过；ninja 链接阶段因 TRAE 沙箱与 Windows overlapped I/O 不兼容无法在 IDE 内执行，需在 ESP-IDF PowerShell 终端外完成）
+  - [x] SubTask 8.2: 确认 `main/` 行数减少符合预期（关键削减：httpServerStart 173→67、ota_coordinator.cpp 8 wrapper 删除、spi_master.cpp 2 Unlocked 删除、ota_relay.cpp goto 重构）
+
+# Task Dependencies
+- Task 3（A.1 inline 化）依赖 Task 2（A.2）先完成，避免合并冲突
+- Task 5（OtaRelay）与 Task 6（SpiMaster）独立，可并行
+- Task 7（HealthMonitor）独立，可并行
+- Task 8（编译验证）依赖 Task 2~7 全部完成