兼容Debug EML SSE断流兜底

docs/project/requirements/M004-debug-eml-superagent-upload-v1.md

@@ -426,6 +426,7 @@ DEBUG_EML_UPLOAD_ENABLED=true
 DEBUG_EML_UPLOAD_ACCESS_KEY=
 DEBUG_EML_UPLOAD_MAX_FILE_BYTES=10485760
 DEBUG_EML_UPLOAD_SSE_HEARTBEAT_INTERVAL=15s
+DEBUG_EML_UPLOAD_SSE_REQUEST_TIMEOUT=1800s
 
 ALIYUN_OSS_ENDPOINT=
 ALIYUN_OSS_BUCKET=
@@ -441,6 +442,12 @@ SUPERAGENT_DEBUG_EML_CONNECT_TIMEOUT=15s
 SUPERAGENT_DEBUG_EML_READ_TIMEOUT=180s
 ```
 
+中文说明：
+
+- `DEBUG_EML_UPLOAD_SSE_HEARTBEAT_INTERVAL` 控制 Debug EML SSE 在等待 SuperAgent Open API 返回期间的心跳事件间隔，用于避免中间链路按空闲连接断开。
+- `DEBUG_EML_UPLOAD_SSE_REQUEST_TIMEOUT` 目前映射到 Spring MVC async request timeout。Spring MVC 对 `StreamingResponseBody` 使用全局异步超时，因此该变量虽然为 Debug EML 设置，但会影响同一 Spring MVC 应用内其他异步请求；如后续增加其他 SSE / async 接口，需要统一评估该全局值。
+- 前端实时页面优先调用 `POST /api/system/debug/eml-superagent-runs/stream`。如果 SSE 在最终 `superagent_result` 前断开但已收到 `debug_run_id`，前端可通过 `GET /api/system/debug/eml-superagent-runs/{debug_run_id}` 轮询运行状态和安全结果；该 GET 接口不是历史列表接口，仍必须携带 `X-TH-Hotel-Debug-Upload-Key`。
+
 分环境建议：
 
 - dev 可以默认关闭真实 SuperAgent 调用，但允许配置后开启。