兼容Debug EML SSE断流兜底

docs/project/frontend-backend/debug-eml-page-integration-guide.md

@@ -22,7 +22,8 @@ Debug EML 页面第一版只做一件事：
 - 不调用 SuperAgent 任务结果通知接口。
 - 不触发 AgentBus 实时链路。
 - 不做批量上传。
-- 不提供 Debug run 历史列表或详情查询。
+- 不提供 Debug run 历史列表。
+- 仅提供按 `debug_run_id` 查询单次运行状态和安全结果，用于 SSE 断流后的前端兜底轮询。
 - 不在生产普通业务页面开放。
 
 ## 3. 页面建议结构
@@ -40,6 +41,17 @@ Debug EML 页面第一版只做一件事：
 
 ## 4. 接口
 
+实时 Trace 页面优先使用流式接口：
+
+```text
+POST /api/system/debug/eml-superagent-runs/stream
+Content-Type: multipart/form-data
+Accept: text/event-stream
+Header: X-TH-Hotel-Debug-Upload-Key: <调试上传口令>
+```
+
+同步调试接口仍保留：
+
 ```text
 POST /api/system/debug/eml-superagent-runs
 Content-Type: multipart/form-data
@@ -47,6 +59,16 @@ Accept: application/json
 Header: X-TH-Hotel-Debug-Upload-Key: <调试上传口令>
 ```
 
+SSE 断流兜底查询接口：
+
+```text
+GET /api/system/debug/eml-superagent-runs/{debug_run_id}
+Accept: application/json
+Header: X-TH-Hotel-Debug-Upload-Key: <调试上传口令>
+```
+
+中文说明：前端不直接调用 SuperAgent。上传后如果 SSE 已收到 `debug_run_id`，但浏览器或反向代理提前关闭了流，前端可以用同一个 Debug 上传口令轮询该 GET 接口，直到状态变成 `SUPERAGENT_SUCCEEDED`、`SUPERAGENT_FAILED` 或 `FAILED`。该接口不是历史列表接口，也不允许绕过 Debug 上传口令。
+
 注意：
 
 - 该接口只有在后端 `debug.eml-upload.enabled=true` 时存在；如果后端未开启，前端可能收到 `404`。
@@ -229,7 +251,8 @@ idle
 - 文件未选择或 Debug 上传口令为空时禁用提交按钮；`hotel_id` 为空是允许的，表示使用后端系统酒店。
 - 提交后禁用文件选择和提交按钮，避免重复上传。
 - SuperAgent 调用可能耗时较长，页面 loading 文案不要只写“上传中”，建议写“正在解析邮件并等待 SuperAgent 返回”。
-- 成功后保留本次响应在页面内存中；当前没有 Debug run 查询接口，刷新页面后需要重新上传。
+- 成功后保留本次响应在页面内存中；当前没有 Debug run 历史列表，刷新页面后通常需要重新上传或手动使用已知 `debug_run_id` 排查。
+- 如果 SSE 正常返回 `superagent_result`，以前端收到的最终结果为准；如果 SSE 在最终结果前关闭但已经收到 `debug_run_id`，前端应轮询 GET 兜底接口。
 - 再次上传同一封 `.eml` 会生成新的 `external_message_id` 和新的 SourceMessage，前端不要按原始 `Message-ID` 去重。
 
 ## 8. 安全与日志
@@ -268,8 +291,8 @@ idle
 
 ## 11. 当前后置事项
 
-- Debug run 历史列表 / 详情查询接口未做。
-- Debug run 取消或超时轮询接口未做。
+- Debug run 历史列表未做。
+- Debug run 取消接口未做。
 - 批量上传未做。
 - 前端白名单元数据独立接口未做。
 - 用户身份 / 权限体系未接入；当前依赖调试上传口令保护。

docs/project/go-live-notes.md

@@ -158,6 +158,7 @@
 | `DEBUG_EML_UPLOAD_PROD_ACCESS_KEY` | 是 | prod Debug EML 上传访问口令；生产通常不应启用该接口。 |
 | `DEBUG_EML_UPLOAD_MAX_FILE_BYTES` | 否 | `.eml` 上传大小上限，默认 `10485760`。 |
 | `DEBUG_EML_UPLOAD_SSE_HEARTBEAT_INTERVAL` | 否 | Debug EML 页面到后端的 SSE 心跳间隔，默认 `15s`；测试机如仍遇到空闲断流可调小到 `10s`。 |
+| `DEBUG_EML_UPLOAD_SSE_REQUEST_TIMEOUT` | 否 | Spring MVC 异步请求总超时，默认 `1800s`；当前用于保障 Debug EML SSE 不先于 SuperAgent read timeout 关闭。注意 Spring MVC async timeout 是应用级全局设置，后续如增加其他 async/SSE 接口需一起评估。 |
 | `DEERFLOW_DEV_BASE_URL` / `DEERFLOW_TEST_BASE_URL` / `DEERFLOW_PROD_BASE_URL` | 否 | SuperAgent / DeerFlow Open API 基础地址，未配置时可兜底 `DEERFLOW_BASE_URL`。 |
 | `DEERFLOW_DEV_OPEN_API_KEY` / `DEERFLOW_TEST_OPEN_API_KEY` / `DEERFLOW_PROD_OPEN_API_KEY` | 是 | SuperAgent Open API Key，未配置时可兜底 `DEERFLOW_OPEN_API_KEY`。 |
 | `SUPERAGENT_DEV_OPEN_API_ENABLED` / `SUPERAGENT_TEST_OPEN_API_ENABLED` / `SUPERAGENT_PROD_OPEN_API_ENABLED` | 否 | 是否启用真实 SuperAgent Open API 调用；prod 默认关闭。 |

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 调用，但允许配置后开启。