兼容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 取消接口未做。
 - 批量上传未做。
 - 前端白名单元数据独立接口未做。
 - 用户身份 / 权限体系未接入；当前依赖调试上传口令保护。