# 修复：WiFi 上传阻塞 HTTP 主线程导致日志挤压/内存爆满

## 根本原因

`esp_http_server`（IDF v6.0）是**单线程 select 模型**：一个主线程在 `select()` 循环里依次处理所有 socket。`ota_upload_handler` 在 HTTP 主线程里同步阻塞执行整个上传（GD32 含 Flash 擦除可达数十秒，ESP32 同样）。期间主线程不回 `select()`，导致：

1. 前端 `pausePollingForUpload()` 仍以 2.5–3s 发 `/system/status`、`/logs`，但 HTTP 主线程无法 accept/处理 → 连接在 lwIP 侧堆积，pbuf 占用堆内存 → 内存爆满
2. `/logs` 无法被 drain，日志在 ring buffer（64×256，有上限但前端看不到）→ 体现为"LOG挤压"
3. `max_open_sockets=4` + `lru_purge` 也无效：线程不回 `select()`，LRU 清理不触发

## 方案：异步上传 handler

用 IDF v6.0 的 `httpd_req_async_handler_begin/complete` API（已确认可用，`examples/protocols/http_server/async_handlers` 即此模式），把上传移到独立 worker 任务。HTTP 主线程立即返回 `select()` 循环，继续服务 `/logs`、`/system/status`。

### 改动文件

#### 1. `main/server/http_handlers.h`（新增声明）
- 新增 `esp_err_t ota_upload_handler_async(httpd_req_t *req);`（新的上传入口，注册替代原 `ota_upload_handler`）
- 保留原 `ota_upload_handler` 的实现，但改为 static 内部函数，仅供 async worker 调用

#### 2. `main/server/http_handlers.cpp`（核心改动）
- 新增 async worker 基础设施（文件内 static）：
  - `static QueueHandle_t s_uploadQueue`（长度 1，元素为 `httpd_req_t*`）
  - `static SemaphoreHandle_t s_workerReady`（binary，初值 0）
  - `static TaskHandle_t s_uploadWorker`（栈 8192，优先级 5，固定 core 0 与现有任务一致）
  - `static void uploadWorkerTask(void*)`：循环 `xSemaphoreGive(s_workerReady)` → `xQueueReceive` → 调用原上传逻辑（用 async req 句柄）→ `httpd_req_async_handler_complete()`
  - `static esp_err_t ensureUploadWorker()`：懒启动 worker（首次上传请求时创建，幂等）
- 新增 `ota_upload_handler_async(httpd_req_t *req)`：
  1. `ensureUploadWorker()`
  2. `httpd_req_t *async_req; httpd_req_async_handler_begin(req, &async_req)` —— 把 socket 标记 `for_async_req`，主线程不再处理它
  3. `if (xSemaphoreTake(s_workerReady, 0) == false)` —— worker 忙（已有上传在进行），立即 `httpd_req_async_handler_complete(async_req)` 并返回 503：
     ```
     httpd_resp_set_status(req, "503 Service Unavailable");
     httpd_resp_sendstr(req, "{\"status\":\"error\",\"message\":\"upload in progress\"}");
     return ESP_OK;
     ```
     注意：503 要发在**原 req** 上（begin 之后 async req 才能发响应，但此处用原 req 发错误更简单——实际上 begin 后原 req 的 remaining_len 被清零，发响应需用 async_req。所以错误路径用 async_req 发）。
  4. `xQueueSend(s_uploadQueue, &async_req, portMAX_DELAY)`
  5. 返回 `ESP_OK`（主线程已完成投递，立即回 select）
- 把原 `ota_upload_handler` 改名 `static esp_err_t ota_upload_handler_impl(httpd_req_t *req)`，逻辑不变（它内部已用 `httpd_req_recv`/`httpd_resp_send`，async 句柄完全兼容）
- **保留 CORS 头设置**：`http_set_cors_headers` 在 `ota_upload_handler_async` 里对原 req 设置（begin 之前），async 路径的响应头也需在 worker 里设置——实际上 `httpd_req_async_handler_begin` 会拷贝 resp_hdrs，所以 CORS 头在 begin 前对原 req 设置即可被子拷贝

#### 3. `main/server/wifi_ota.cpp`（路由注册）
- `kHttpRoutes[]` 中 `/ota/upload` 的 handler 从 `ota_upload_handler` 改为 `ota_upload_handler_async`
- OPTIONS 预检不变（仍走 `http_options_handler`）

### 不改动的部分
- **前端 app.js 不改**：`pausePollingForUpload` 仍降速轮询，但现在能真正拿到 `/logs` 和 `/system/status` 响应（主线程不再阻塞）
- **日志系统不改**：ring buffer 已有上限，异步化后 `/logs` 能被正常 drain，不再积压
- **OtaCoordinator 不改**：已有 `ESP_ERR_INVALID_STATE` 拒绝并发会话，worker 的 503 是更早的防线
- **OTA_BLOCK_SIZE、栈大小不改**

### 内存影响
- 新增 1 个 worker 任务栈 8192 字节（从现有 `free_heap` 出，ESP32-C3 内部堆约 200KB+，可接受）
- 队列 1×`sizeof(httpd_req_t*)`=4 字节，信号量 ~80 字节，忽略不计
- **收益**：上传期间不再堆积 lwIP pbuf（每个未 accept 的连接可达数 KB），消除内存爆满主因

### 验证方式
1. 编译通过（`idf.py build`）
2. 功能验证：WiFi 上传 GD32/ESP32 固件，上传期间网页 `/logs` 持续刷新、`/system/status` 能返回（不再超时）
3. 内存验证：`/system/status` 的 `free_heap` 在上传期间不再持续下降
4. 并发验证：上传进行中再发一个 `/ota/upload`，立即返回 503 而非阻塞