实现 Debug EML 上传到 SuperAgent 链路

2026-07-09 14:22:24 +08:00
parent 9fa608f602
commit fcb30d460a
50 changed files with 3527 additions and 1 deletions
--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -50,6 +50,7 @@
 | `GET /api/source-messages/{id}` | 查询来源消息安全详情 | 只用于安全摘要详情。 |
 | `GET /api/source-messages/{id}/original` | 读取来源消息原文 | 需要受控访问头，返回 HTML 时前端展示前必须 sanitize。 |
 | `GET /api/source-messages/{sourceMessageId}/conversation` | 读取邮件会话详情 | 返回同一外部会话全部邮件的完整 text/html、`html_body_sanitized`、附件外链、内联图片和关联订单 / 任务摘要；前端不传原文读取 key，展示 HTML 时优先使用 `html_body_sanitized`。 |
+| `POST /api/system/debug/eml-superagent-runs` | Debug 页面上传 `.eml` 并调用 SuperAgent | 仅 dev/test 受控调试使用；会写入 SourceMessage Inbox，但不创建订单和任务。 |

 ### 5.1 本轮新增 / 修改接口说明

@@ -62,6 +63,7 @@
 | `GET /api/reservation/orders/{orderId}` | 补齐 `tasks[]` 每条任务的来源邮件会话摘要字段。 | `include_tasks=false` 可只取订单摘要；时间线顺序由后端按订单队列返回，前端不要自行按创建时间重排。`include_source_summary` 第一版不作为前端裁剪字段的强约束，前端暂不要依赖它减少返回字段。 |
 | `GET /api/reservation/tasks/{taskId}` | 补齐顶层来源邮件字段，并扩展 `fields[]` 元数据。 | 顶层来源字段用于打开邮件会话；`fields[]` 中的 `result_type`、`task_type`、`task_subtype`、`default_value_source` 用于前端字段分组、调试和白名单对齐。 |
 | `GET /api/source-messages/{sourceMessageId}/conversation` | 新增邮件会话详情接口，并补齐 `html_body_sanitized` / `html_render_mode`。 | 当前唯一推荐路径是这个接口；前端渲染邮件 HTML 时优先使用 `html_body_sanitized`；不要调用历史讨论过的 `/api/source-message-conversations/{externalConversationId}`。 |
+| `POST /api/system/debug/eml-superagent-runs` | 新增 Debug EML 上传到 SuperAgent 调试接口。 | 只用于调试页面；请求为 multipart/form-data；必须传 `X-TH-Hotel-Debug-Upload-Key`，但该 key 不能写进前端源码、构建产物、URL、localStorage 或错误上报。 |

 ### 5.2 来源邮件会话字段说明

@@ -143,9 +145,35 @@ Content-Type: application/json
 - 前端保存草稿时不要自行按 `write_path` 重组 OPERA 参数；第一版按任务详情返回的字段和值提交即可，真实 OPERA 参数组装后续由后端 adapter / 转换层处理。
 - 任务详情页控制按钮时以 `availability.editable`、`availability.confirmable`、`availability.executable`、`availability.read_only` 和 `availability.blocked` 为准；`can_process` 和 `readonly_reason_code` 只出现在任务列表 / 订单时间线摘要里。

+### 5.7 Debug EML 上传接口接入注意
+
+后端已提供 Debug 页面专用的 `.eml` 上传和 SuperAgent 调试入口：
+
+```text
+POST /api/system/debug/eml-superagent-runs
+Header: X-TH-Hotel-Debug-Upload-Key: <调试访问口令>
+Content-Type: multipart/form-data
+
+file: .eml 文件
+hotel_id: HOTEL-TEST
+run_label: 可选调试标签
+```
+
+前端注意：
+
+- 该接口只用于 dev/test 调试页面，不是生产普通业务页面接口。
+- 接口会解析 `.eml`，上传原始邮件、内联图片和附件到本系统阿里云 OSS，替换 HTML 内 `cid:` 图片，再写入 SourceMessage Inbox。
+- SourceMessage 来源 provider 固定为 `DEBUG_EML_UPLOAD`，用于和 AgentBus 入库邮件区分。
+- `agentbus_like_payload.schema_version` 固定为 `debug-eml-upload-v1`，前端可用于调试展示和版本判断。
+- 第一版只返回 SuperAgent 结果，不创建订单、不创建任务、不调用任务结果通知接口。
+- `X-TH-Hotel-Debug-Upload-Key` 只能由调试人员在受控环境手动提供，不能放入 `VITE_*`、源码、构建产物、URL query、localStorage、错误上报或普通日志。
+- 返回的 `uploaded_media[]`、`original_eml_oss_url`、`html_body_with_oss_urls` 可能包含 OSS URL；前端不要写入普通日志、埋点、错误上报或 URL query。
+- `superagent_parsed_json` 为空时，前端展示 `superagent_raw_answer` 和 `warnings[]`，不要假定 SuperAgent 总能返回 JSON。
+
 ## 6. 不给前端直接调用的接口

 - `POST /api/system/reservation/demo-data` 只用于 dev/test 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。
+- `POST /api/system/debug/eml-superagent-runs` 只用于 dev/test Debug 页面，不是生产普通业务页面接口；访问口令不能进入前端代码或构建产物。
 - `POST /api/integrations/superagent/task-results` 是 SuperAgent 到后端的服务到服务入站接口。
 - `POST /api/ai-query/v1/case-context` 和 `POST /api/ai-query/v1/object-detail` 是 SuperAgent 查询上下文接口，不是前端页面接口。
 - `GET /api/source-message-conversations/{externalConversationId}` 是历史讨论过的候选路径，当前后端不提供，前端不要接入。
--- a/docs/project/frontend-backend/frontend-to-backend-api-requests.md
+++ b/docs/project/frontend-backend/frontend-to-backend-api-requests.md
@@ -15,6 +15,7 @@
 | P0 | 任务详情操作接口 | 任务详情保存、确认、OPERA、审计 | 已完成；前端可直接接入 |
 | P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
 | 联调 | 演示数据 seed 接口 `POST /api/system/reservation/demo-data` | 本地 / test 前端页面看效果 | 已完成；仅 dev/test 受控使用 |
+| 联调 | Debug EML 上传接口 `POST /api/system/debug/eml-superagent-runs` | Debug 页面上传 `.eml` 看 SuperAgent 结果 | 已完成第一版；仅 dev/test 受控使用 |
 | P1 | Message Notification 列表 / 详情接口 | 信息提醒页或订单详情只读卡片 | 未完成独立接口；可先通过任务列表 / 任务详情展示 `INFORMATIONAL_MESSAGE` |
 | P1 | 任务卡前端字段白名单元数据接口 | 字段白名单调试、版本对齐 | 未完成；若任务详情已透出完整元数据，可后置 |
 | 后置 | 普通任务切换订单接口 | 任务详情订单归属调整 | 未完成；已确认后置 |
@@ -40,6 +41,7 @@
 | `GET /api/reservation/orders` | 已完成第一版 | 可以 | 默认查询全部订单状态；`open_task_count` 排除 `COMPLETED` 和 `FAILED`。 |
 | `GET /api/source-messages/{sourceMessageId}/conversation` | 已完成第一版，已补 `html_body_sanitized` 和 `html_render_mode` | 可以 | 返回完整 text/html、后端清洗后的 HTML、媒体外链和关联订单 / 任务摘要；前端不传原文读取 key，页面展示优先使用 `html_body_sanitized`。 |
 | `POST /api/system/reservation/demo-data` | 已完成 | 仅本地 / test 联调可用 | 默认关闭，必须后端配置访问口令；不能作为生产页面接口。 |
+| `POST /api/system/debug/eml-superagent-runs` | 已完成第一版 | 仅 dev/test Debug 页面可用 | 默认关闭，必须后端配置访问口令、阿里云 OSS 和 SuperAgent Open API；第一版只展示 SuperAgent 结果，不创建订单和任务。 |
 | `GET /api/source-message-conversations/{externalConversationId}` | 未发现后端实现 | 不可以 | 历史讨论过的候选路径，当前不提供；前端统一使用 `GET /api/source-messages/{sourceMessageId}/conversation`。 |
 | `GET /api/reservation/message-notifications` | 未发现后端实现 | 不可以 | 如需独立信息提醒页再新增；第一版可先用任务接口过滤。 |
 | `GET /api/reservation/task-card-field-whitelist` | 未发现后端实现 | 不可以 | 若任务详情 `fields[]` 已补齐 3.0 元数据，可后置。 |
--- a/docs/project/go-live-notes.md
+++ b/docs/project/go-live-notes.md
@@ -17,6 +17,7 @@
 - Reservation 任务草稿保存和最终确认接口：按任务卡矩阵做第一版后端校验，确认后生成 `confirmed_payload_json`。
 - Reservation OPERA 模拟骨架：已确认任务固定生成两条模拟操作，支持执行、失败重试、attempt 记录和任务审计列表。
 - SuperAgent 查询上下文接口 1、2：支持 HMAC 鉴权的订单上下文查询和对象详情查询。
+- Debug EML 上传到 SuperAgent 调试链路：受控上传 `.eml`、转存阿里云 OSS、写入 SourceMessage Inbox、调用 SuperAgent Open API 并返回调试结果。

 当前不要把以下能力当作已上线：

@@ -28,6 +29,7 @@
 - SuperAgent 查询上下文接口 3、4。
 - 普通任务切换订单接口。
 - 用户身份、权限和真实审计 actor。
+- Debug EML 上传链路不属于生产普通业务页面能力，生产默认关闭；未接入正式用户权限前不要开放给普通用户。

 ## 2. 上线前必须确认

@@ -106,6 +108,37 @@
 - 任务结果通知接口里的 `source_message_id` 是外部来源消息 ID，对应 AgentBus `source.external_message_id`；正式请求必须带 `hotel_id`，后端用 `hotel_id + provider + channel + external_message_id` 反查内部 SourceMessage Inbox。
 - SuperAgent 查询上下文接口中的 `source_message_id`、`source_event_index` 第一版仅兼容接收，不参与查询和校验；不要依赖它们限制查询范围。

+### 3.5 Debug EML / SuperAgent Open API / 阿里云 OSS
+
+| 变量 | 是否 Secret | 上线注意事项 |
+| --- | --- | --- |
+| `DEBUG_EML_UPLOAD_DEV_ENABLED` | 否 | dev 是否启用 Debug EML 上传接口，未配置时可兜底 `DEBUG_EML_UPLOAD_ENABLED`。 |
+| `DEBUG_EML_UPLOAD_TEST_ENABLED` | 否 | test 是否启用 Debug EML 上传接口，默认关闭。 |
+| `DEBUG_EML_UPLOAD_PROD_ENABLED` | 否 | prod 默认必须保持 `false`；未接入正式用户权限前不要开放。 |
+| `DEBUG_EML_UPLOAD_DEV_ACCESS_KEY` | 是 | dev Debug EML 上传访问口令，未配置时可兜底 `DEBUG_EML_UPLOAD_ACCESS_KEY`。 |
+| `DEBUG_EML_UPLOAD_TEST_ACCESS_KEY` | 是 | test Debug EML 上传访问口令，未配置时可兜底 `DEBUG_EML_UPLOAD_ACCESS_KEY`。 |
+| `DEBUG_EML_UPLOAD_PROD_ACCESS_KEY` | 是 | prod Debug EML 上传访问口令；生产通常不应启用该接口。 |
+| `DEBUG_EML_UPLOAD_MAX_FILE_BYTES` | 否 | `.eml` 上传大小上限，默认 `10485760`。 |
+| `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 默认关闭。 |
+| `SUPERAGENT_DEBUG_EML_EXTERNAL_SUBJECT_ID` | 否 | Debug EML 创建 SuperAgent session 的 external subject id。 |
+| `SUPERAGENT_DEBUG_EML_CONNECT_TIMEOUT` | 否 | SuperAgent Open API 建连超时，默认 `15s`。 |
+| `SUPERAGENT_DEBUG_EML_READ_TIMEOUT` | 否 | SuperAgent SSE 读取超时，默认 `180s`。 |
+| `ALIYUN_OSS_DEV_ENDPOINT` / `ALIYUN_OSS_TEST_ENDPOINT` / `ALIYUN_OSS_PROD_ENDPOINT` | 否 | 阿里云 OSS Endpoint，未配置时可兜底 `ALIYUN_OSS_ENDPOINT`。 |
+| `ALIYUN_OSS_DEV_BUCKET` / `ALIYUN_OSS_TEST_BUCKET` / `ALIYUN_OSS_PROD_BUCKET` | 否 | 阿里云 OSS Bucket，未配置时可兜底 `ALIYUN_OSS_BUCKET`。 |
+| `ALIYUN_OSS_DEV_ACCESS_KEY_ID` / `ALIYUN_OSS_TEST_ACCESS_KEY_ID` / `ALIYUN_OSS_PROD_ACCESS_KEY_ID` | 是 | 阿里云 OSS AccessKey ID，未配置时可兜底 `ALIYUN_OSS_ACCESS_KEY_ID`。 |
+| `ALIYUN_OSS_DEV_ACCESS_KEY_SECRET` / `ALIYUN_OSS_TEST_ACCESS_KEY_SECRET` / `ALIYUN_OSS_PROD_ACCESS_KEY_SECRET` | 是 | 阿里云 OSS AccessKey Secret，未配置时可兜底 `ALIYUN_OSS_ACCESS_KEY_SECRET`。 |
+| `ALIYUN_OSS_DEV_PUBLIC_BASE_URL` / `ALIYUN_OSS_TEST_PUBLIC_BASE_URL` / `ALIYUN_OSS_PROD_PUBLIC_BASE_URL` | 否 | OSS 对外访问基础 URL，未配置时可兜底 `ALIYUN_OSS_PUBLIC_BASE_URL`。 |
+| `ALIYUN_OSS_DEBUG_EML_PREFIX` | 否 | Debug EML 上传对象路径前缀，默认 `debug/eml/`。 |
+
+注意：
+
+- Debug EML 上传接口会接收原始邮件、上传 OSS 并调用 SuperAgent，风险和成本高于普通查询接口。
+- Debug EML 上传 key、SuperAgent Open API Key、阿里云 OSS AccessKey 都不得进入前端源码、`VITE_*`、镜像、普通日志或文档真实值。
+- Debug EML 写入 SourceMessage Inbox 时 `provider=DEBUG_EML_UPLOAD`，不能伪装为 AgentBus 来源。
+- Debug EML 第一版只展示 SuperAgent 结果，不创建订单、不创建任务、不调用任务结果通知接口。
+
 ## 4. 数据库上线注意事项

 当前 SourceMessage 相关 migration：
@@ -120,6 +153,10 @@
 - `server/src/main/resources/db/migration/V5__add_reservation_task_draft_and_confirmation.sql`
 - `server/src/main/resources/db/migration/V6__create_reservation_opera_simulation_tables.sql`

+当前 M004 Debug EML 相关 migration：
+
+- `server/src/main/resources/db/migration/V7__create_debug_eml_superagent_run.sql`
+
 上线前确认：

 - 目标数据库为空库或 Flyway history 与当前代码一致。
--- a/docs/project/requirements/M004-debug-eml-superagent-upload-v1.md
+++ b/docs/project/requirements/M004-debug-eml-superagent-upload-v1.md
@@ -0,0 +1,477 @@
+# M004 Debug EML SuperAgent Upload 调试邮件上传链路 V1
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档版本 | 0.1 |
+| 日期 | 2026-07-09 |
+| 状态 | 第一版后端已实现 |
+| 适用范围 | Debug 页面上传 `.eml` 邮件、转存阿里云 OSS、写入 SourceMessage Inbox、调用 SuperAgent Open API 并展示结果 |
+| 主要读者 | 产品、后端、前端、测试、运维、后续协作 agent |
+
+## 1. 文档定位
+
+本文记录 Debug EML 上传链路的第一版后端设计。该能力用于在没有 AgentBus 实时入口的情况下，
+由调试页面上传 `.eml` 邮件文件，后端解析邮件、转存附件和内联图片到本系统阿里云 OSS，
+再组装成 SuperAgent 可处理的邮件输入并调用 SuperAgent Open API。
+
+该能力是平台调试能力，不属于 `workflows.reservation` 主业务流。第一版必须写入 SourceMessage
+Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任务结果通知接口，也不执行 OPERA。
+
+## 2. 已确认决策
+
+- Debug 页面上传的邮件文件格式为 `.eml`。
+- 第一版通过 SuperAgent Open API 调用 SuperAgent，不走 SuperAgent 调用本系统的任务结果通知接口。
+- 第一版只展示 SuperAgent 生成结果，不落业务订单和任务。
+- 上传邮件仍要写入 SourceMessage Inbox。
+- Debug 上传来源必须和 AgentBus 来源区分，建议 `provider=DEBUG_EML_UPLOAD`。
+- 使用真实阿里云 OSS，不使用本地 mock OSS。
+- 原始 `.eml` 文件本身也上传到阿里云 OSS，便于后续调试追溯。
+- 内联图片和普通附件都上传到阿里云 OSS。
+- HTML 正文中的 `cid:` 图片引用需要替换成本系统 OSS 图片地址。
+- Debug 上传接口第一版使用内部调试访问 key 保护，不等待完整用户权限体系。
+- 用户 / 权限体系和管理后台仍是后续能力，本功能不依赖 M003 完成。
+
+## 2.1 第一版实现记录
+
+当前后端已完成：
+
+- `POST /api/system/debug/eml-superagent-runs`。
+- `.eml` MIME 解析：邮件头、纯文本正文、HTML 正文、内联图片和附件。
+- 阿里云 OSS 上传端口和适配器：原始 `.eml`、内联图片和附件。
+- HTML `cid:` 图片替换为 OSS URL。
+- AgentBus-like payload 组装。
+- SourceMessage Inbox 写入，`provider=DEBUG_EML_UPLOAD`，`schema_version=debug-eml-upload-v1`。
+- SourceMessage 写入成功后先把 debug run 标记为 `SOURCE_CAPTURED`；即使后续 SuperAgent 调用失败，也保留 SourceMessage 和 OSS 原文追溯信息。
+- SuperAgent Open API client：创建 session、发送 `messages/stream`、解析 SSE 最终回答。
+- `platform_debug_eml_superagent_run` 持久化。
+- Controller / Service / ServiceImpl / Repository / Mapper / Entity / DTO / Result 按当前后端目录规范落位。
+- 单元测试和集成测试覆盖 EML 解析、cid 替换、SourceMessage 写入参数、OSS mock、SuperAgent mock 和接口鉴权。
+
+## 3. 核心目标
+
+第一版要解决以下问题：
+
+- 前端 Debug 页面可以上传一封 `.eml` 邮件。
+- 后端可以解析邮件头、纯文本正文、HTML 正文、内联图片和附件。
+- 后端可以把原始 `.eml`、内联图片和附件上传到阿里云 OSS。
+- 后端可以把 HTML 正文中的 `cid:` 引用替换成 OSS URL。
+- 后端可以组装 AgentBus-like 邮件 payload，保持和当前 SourceMessage Inbox / SuperAgent 输入口径接近。
+- 后端可以写入 SourceMessage Inbox，并明确标记来源为 Debug EML Upload。
+- 后端可以调用 SuperAgent Open API 并解析最终返回。
+- 前端可以看到 SourceMessage ID、上传媒体、处理后的 HTML、发送给 SuperAgent 的 payload、SuperAgent 原始回答和解析后的 JSON。
+
+## 4. 非目标范围
+
+第一版不做以下能力：
+
+- 不创建 Reservation 订单。
+- 不创建 Reservation 任务。
+- 不写 `workflow_reservation_*` 表。
+- 不调用 `POST /api/integrations/superagent/task-results`。
+- 不做真实 OPERA / OHIP 接入。
+- 不做邮件多封批量上传。
+- 不做 ZIP、MSG、PDF、图片 OCR 或 Excel 解析。
+- 不做 SourceMessage Replay 到 MessageEvent / Evidence。
+- 不做普通任务切换订单。
+- 不做 SuperAgent 查询接口 3、4。
+- 不接入完整用户 / 权限体系。
+- 不在前端保存或暴露 SuperAgent Open API Key、阿里云 OSS Secret 或调试上传 key。
+
+## 5. 总体流程
+
+```text
+Debug 页面上传 .eml
+→ 后端校验 X-TH-Hotel-Debug-Upload-Key
+→ 解析 MIME 邮件结构
+→ 上传原始 .eml 到阿里云 OSS
+→ 上传内联图片到阿里云 OSS
+→ 上传普通附件到阿里云 OSS
+→ 替换 HTML 正文中的 cid: 图片引用
+→ 组装 AgentBus-like payload
+→ 调用 SourceMessageCaptureService 写入 SourceMessage Inbox
+→ debug run 标记为 SOURCE_CAPTURED
+→ 调用 SuperAgent Open API 创建 session
+→ 调用 messages/stream 发送邮件 payload
+→ 解析 SSE 最终回答
+→ 保存 debug run 记录
+→ 返回 debug 结果给前端展示
+```
+
+中文说明：
+
+- SourceMessage Inbox 仍然只表达来源事实，不表达 AI 结论、订单归属或任务状态。
+- Debug 上传链路不能伪装成 AgentBus；必须在 `provider`、`schema_version` 或 debug run 中留下可追溯来源。
+- SuperAgent 返回内容第一版只作为调试展示，不进入 M002 订单任务主流程。
+
+## 6. 后端接口设计
+
+### 6.1 上传并调用 SuperAgent
+
+```text
+POST /api/system/debug/eml-superagent-runs
+Content-Type: multipart/form-data
+Header: X-TH-Hotel-Debug-Upload-Key: <DEBUG_EML_UPLOAD_ACCESS_KEY>
+```
+
+请求参数：
+
+| 参数 | 是否必填 | 中文说明 |
+| --- | --- | --- |
+| `file` | 是 | `.eml` 邮件文件 |
+| `hotel_id` | 是 | 酒店上下文 ID，用于 SourceMessage Inbox 幂等键和后续排查 |
+| `run_label` | 否 | 前端传入的调试标签，例如 `frontend-debug-smoke` |
+
+响应字段：
+
+| 字段 | 中文说明 |
+| --- | --- |
+| `debug_run_id` | 本次 Debug 运行 ID |
+| `source_message_id` | 本系统内部 SourceMessage Inbox ID |
+| `source_provider` | 固定建议为 `DEBUG_EML_UPLOAD` |
+| `external_message_id` | Debug 链路生成的外部消息 ID，用于 SourceMessage 幂等 |
+| `external_conversation_id` | Debug 链路生成或解析出的邮件会话 ID |
+| `original_eml_oss_url` | 原始 `.eml` 文件 OSS 地址 |
+| `original_eml_sha256` | 原始 `.eml` 文件 SHA-256 |
+| `uploaded_media[]` | 已上传 OSS 的内联图片和附件 |
+| `html_body_with_oss_urls` | 替换 `cid:` 后的 HTML 正文 |
+| `agentbus_like_payload` | 发送给 SuperAgent 的结构化邮件 payload，包含 `schema_version=debug-eml-upload-v1` |
+| `superagent_session_id` | SuperAgent Open API session ID，失败时为空 |
+| `superagent_run_id` | SuperAgent 返回的 run ID，失败时为空 |
+| `superagent_raw_answer` | SuperAgent 最终文本回答 |
+| `superagent_parsed_json` | 后端尝试解析出的 JSON 对象，无法解析时为空 |
+| `warnings[]` | 可展示的安全警告，例如缺失 HTML、无法替换某个 cid、SuperAgent 返回非 JSON |
+| `status` | Debug 运行状态 |
+
+### 6.2 状态码建议
+
+| 场景 | HTTP 状态 | 中文说明 |
+| --- | --- | --- |
+| 调试 key 缺失或错误 | `401` | 不执行解析和外部调用 |
+| 文件缺失或非 `.eml` | `400` | 参数错误 |
+| 邮件解析失败 | `422` | 文件存在但 MIME 结构无法解析 |
+| OSS 上传失败 | `502` | 外部存储失败 |
+| SuperAgent 调用失败 | `502` | 外部 AI Provider 失败 |
+| 写入 SourceMessage 失败 | `500` | 本系统持久化失败 |
+
+错误响应不得返回 Secret、完整邮件正文、完整 HTML、附件 URL 中的签名参数或原始 Provider 报文。
+
+## 7. SourceMessage 写入口径
+
+Debug 链路调用现有 `SourceMessageCaptureService.capture`，建议映射如下：
+
+| Capture 字段 | Debug EML 来源 |
+| --- | --- |
+| `hotelId` | 请求参数 `hotel_id` |
+| `provider` | `DEBUG_EML_UPLOAD` |
+| `channel` | `EMAIL` |
+| `externalMessageId` | 优先邮件 `Message-ID` 的规范化值；缺失时使用 `debug-eml-{sha256前缀}` |
+| `externalConversationId` | 优先邮件 `In-Reply-To` / `References` / `Thread-Index` 可解析会话值；缺失时使用 `debug-eml-thread-{externalMessageId}` |
+| `providerFrameId` | `debug_run_id` |
+| `providerSessionId` | 可使用 `debug-eml-upload` 或后续当前用户 session 摘要 |
+| `sourceSentAt` | 邮件 `Date` 头，解析失败则为空 |
+| `senderIdentifier` | 邮件 `From` |
+| `subject` | 邮件 `Subject` |
+| `textBody` | 解析出的纯文本正文 |
+| `htmlBody` | 已替换 OSS URL 的 HTML 正文 |
+| `payloadJson` | AgentBus-like payload JSON |
+| `schemaVersion` | `debug-eml-upload-v1` |
+| `mediaItems` | 上传到 OSS 后的内联图片、附件和原始 `.eml` 引用 |
+
+媒体类型建议：
+
+| 类型 | 中文说明 |
+| --- | --- |
+| `INLINE_IMAGE` | HTML 正文内联图片 |
+| `ATTACHMENT` | 普通邮件附件 |
+| `ORIGINAL_EMAIL` | Debug 链路上传的原始 `.eml` 文件，若当前枚举不支持，需要新增枚举或作为附件类型加 `external_media_id` 区分 |
+
+若新增 `ORIGINAL_EMAIL` 媒体类型，需要同步更新 SourceMessage 媒体枚举、接口文档和前端展示说明。
+
+## 8. AgentBus-like Payload 结构建议
+
+第一版 payload 目标是让 SuperAgent 获得接近 AgentBus 邮件输入的结构，而不是完整复刻 AgentBus 协议。
+
+```json
+{
+  "source": {
+    "channel": "EMAIL",
+    "provider": "DEBUG_EML_UPLOAD",
+    "external_message_id": "debug-eml-4f2c9a8b7d6e",
+    "external_conversation_id": "debug-eml-thread-4f2c9a8b7d6e",
+    "sender": "sender@example.com",
+    "subject": "Booking Request",
+    "sent_at": "2026-07-09T01:30:00Z"
+  },
+  "body": {
+    "content_type": "MIXED",
+    "text": "plain text body",
+    "html": "<html>...</html>"
+  },
+  "inline_images": [],
+  "attachments": [],
+  "reply_policy": {
+    "mode": "debug_only",
+    "final_only": true
+  },
+  "debug_context": {
+    "debug_run_id": "1900000000000000001",
+    "run_label": "frontend-debug-smoke",
+    "original_eml_oss_url": "https://oss.example/debug/eml/..."
+  }
+}
+```
+
+中文说明：
+
+- `inline_images[]` 和 `attachments[]` 中的 URL 必须是本系统 OSS URL。
+- `reply_policy.mode=debug_only` 表示本链路只用于调试，不允许 SuperAgent 或本系统发送客户回复。
+- 如果后续 AgentBus 正式 payload 有字段变化，本 Debug 链路可以通过 schema version 单独升级。
+
+## 9. SuperAgent Open API 调用口径
+
+项目现有文档已验证的 SuperAgent Open API 形态为：
+
+```text
+POST /api/open/agent-sessions
+POST /api/open/agent-sessions/{sessionId}/messages/stream
+```
+
+第一版建议：
+
+- 后端使用 `DEERFLOW_BASE_URL` 和 `DEERFLOW_OPEN_API_KEY` 调用 SuperAgent。
+- 状态变更请求使用 CSRF double-submit：`X-CSRF-Token` 和 `Cookie: csrf_token=<same-token>`。
+- 创建 session 时使用 `SUPERAGENT_DEBUG_EML_EXTERNAL_SUBJECT_ID` 作为 `external_subject_id`。
+- `idempotency_key` 使用 `debug_run_id` 派生，保证同一次 Debug 运行不会重复创建不可追溯请求。
+- 发送消息时把 AgentBus-like payload 序列化为 JSON 文本，并附加中文指令，要求 SuperAgent 输出结构化 JSON。
+- SSE 解析仍按项目现有经验，从后期 `values.messages[]` 中寻找 `type=ai` 且 `finish_reason=stop` 的最终回答。
+
+当前未确认项：
+
+- SuperAgent 是否需要指定具体 agent、profile 或 prompt。
+- SuperAgent 邮件处理 Open API 是否有比“发送 JSON 文本消息”更稳定的专用入参。
+
+第一版实现时应把 profile / prompt 相关内容做成配置或低耦合适配，不写死在业务流程里。
+
+## 10. 阿里云 OSS 设计
+
+后端新增对象存储端口，业务层不直接依赖阿里云 SDK：
+
+```text
+integrations.storage
+└── aliyunoss
+    ├── adapter
+    ├── common.request
+    ├── common.result
+    └── service / service.impl
+```
+
+对象路径建议：
+
+```text
+debug/eml/{yyyyMMdd}/{debugRunId}/raw/{originalFileName}.eml
+debug/eml/{yyyyMMdd}/{debugRunId}/inline/{index}-{safeFileName}
+debug/eml/{yyyyMMdd}/{debugRunId}/attachments/{index}-{safeFileName}
+```
+
+配置建议：
+
+```text
+ALIYUN_OSS_ENDPOINT
+ALIYUN_OSS_BUCKET
+ALIYUN_OSS_ACCESS_KEY_ID
+ALIYUN_OSS_ACCESS_KEY_SECRET
+ALIYUN_OSS_PUBLIC_BASE_URL
+ALIYUN_OSS_DEBUG_EML_PREFIX
+```
+
+安全要求：
+
+- 阿里云 OSS AccessKey 不得进入前端代码、文档真实值或普通日志。
+- 上传文件名必须清洗，避免路径穿越和日志污染。
+- Content-Type 以解析结果为准，但不能信任邮件原始文件名。
+- 第一版可以使用长期可访问的 OSS URL；如果后续改为私有 bucket，需要补签名 URL 或后端代理读取方案。
+
+## 11. 数据模型建议
+
+新增 debug run 表：
+
+```text
+platform_debug_eml_superagent_run
+```
+
+字段建议：
+
+| 字段 | 中文说明 |
+| --- | --- |
+| `id` | Debug 运行 ID |
+| `hotel_id` | 酒店上下文 ID |
+| `run_label` | 前端调试标签 |
+| `source_message_id` | 内部 SourceMessage Inbox ID |
+| `external_message_id` | Debug 链路外部消息 ID |
+| `external_conversation_id` | Debug 链路外部会话 ID |
+| `original_file_name` | 原始上传文件名安全摘要 |
+| `original_eml_oss_url` | 原始 `.eml` OSS URL |
+| `original_eml_sha256` | 原始 `.eml` SHA-256 |
+| `payload_json` | AgentBus-like payload JSON |
+| `superagent_session_id` | SuperAgent session ID |
+| `superagent_run_id` | SuperAgent run ID |
+| `superagent_raw_answer` | SuperAgent 最终文本回答 |
+| `superagent_parsed_json` | 后端解析出的 JSON |
+| `run_status` | `CREATED`、`SOURCE_CAPTURED`、`SUPERAGENT_SUCCEEDED`、`SUPERAGENT_FAILED`、`FAILED` |
+| `safe_error_summary` | 安全错误摘要，不包含正文、Secret 或附件签名 URL |
+| `created_at` / `updated_at` | 创建和更新时间，按 UTC 写入 |
+
+说明：
+
+- Debug run 表用于调试追溯，不替代 SourceMessage Inbox。
+- 大字段是否长期保存需结合库容量评估；第一版可以保存 payload 和 SuperAgent answer，禁止保存 Secret。
+- 如果后续需要调试历史列表，可基于该表新增只读查询接口。
+
+## 12. 后端模块建议
+
+```text
+platform.debug
+├── control
+├── service
+│   └── impl
+├── domain
+├── mapper
+├── repository
+└── common
+    ├── dto
+    ├── request
+    ├── result
+    └── enums
+
+platform.message
+└── service / service.impl
+    // EML 解析和 SourceMessage 捕获命令组装
+
+integrations.storage.aliyunoss
+└── adapter / service / service.impl
+    // 阿里云 OSS 上传适配
+
+integrations.ai.superagent
+└── service / service.impl / adapter
+    // SuperAgent Open API 和 SSE 解析
+```
+
+中文说明：
+
+- `platform.debug` 负责编排 Debug 运行，不直接解析厂商协议。
+- `platform.message` 可承接 EML 到 SourceMessage 捕获命令的转换，因为 EML 是消息来源处理能力。
+- `integrations.storage.aliyunoss` 隔离阿里云 OSS SDK。
+- `integrations.ai.superagent` 隔离 SuperAgent Open API、CSRF、SSE 和 Provider DTO。
+- `workflows.reservation` 不参与第一版 Debug 上传链路。
+
+## 13. 依赖建议
+
+后端实现可能需要新增依赖：
+
+| 依赖 | 用途 | 说明 |
+| --- | --- | --- |
+| Jakarta Mail / Angus Mail | 解析 `.eml` MIME 邮件 | 需要确认 Spring Boot 3.5 兼容版本 |
+| 阿里云 OSS Java SDK | 上传原始邮件、附件和内联图片 | 只在 integration adapter 使用 |
+
+新增依赖前必须验证：
+
+- Java 17 兼容。
+- Spring Boot 3.5 兼容。
+- 测试环境无需真实 OSS 时可以通过端口 mock 或禁用真实上传。
+- 不引入和现有 MyBatis / Spring Boot starter 冲突的依赖。
+
+## 14. 安全与审计
+
+- Debug 上传接口必须校验 `X-TH-Hotel-Debug-Upload-Key`。
+- `DEBUG_EML_UPLOAD_ACCESS_KEY` 必须按环境变量或部署 Secret 注入。
+- 上传文件大小需要配置上限，避免误传超大邮件。
+- 日志不得输出完整邮件正文、完整 HTML、附件 URL 签名参数、SuperAgent API Key、阿里云 OSS Secret。
+- SourceMessage 原文读取仍按既有受控读取和审计规则处理。
+- Debug run 错误摘要必须是安全摘要。
+- 前端不得把 debug 上传 key、OSS Secret、SuperAgent Open API Key 放入构建产物。
+
+## 15. 配置建议
+
+```text
+DEBUG_EML_UPLOAD_ENABLED=true
+DEBUG_EML_UPLOAD_ACCESS_KEY=
+DEBUG_EML_UPLOAD_MAX_FILE_BYTES=10485760
+
+ALIYUN_OSS_ENDPOINT=
+ALIYUN_OSS_BUCKET=
+ALIYUN_OSS_ACCESS_KEY_ID=
+ALIYUN_OSS_ACCESS_KEY_SECRET=
+ALIYUN_OSS_PUBLIC_BASE_URL=
+ALIYUN_OSS_DEBUG_EML_PREFIX=debug/eml/
+
+DEERFLOW_BASE_URL=
+DEERFLOW_OPEN_API_KEY=
+SUPERAGENT_DEBUG_EML_EXTERNAL_SUBJECT_ID=th-hotel-debug-eml-upload
+SUPERAGENT_DEBUG_EML_CONNECT_TIMEOUT=15s
+SUPERAGENT_DEBUG_EML_READ_TIMEOUT=180s
+```
+
+分环境建议：
+
+- dev 可以默认关闭真实 SuperAgent 调用，但允许配置后开启。
+- test 需要真实 OSS 和真实 SuperAgent 时，必须由部署环境注入 Secret。
+- prod 默认不建议开放 Debug 上传；如必须开放，应先接入正式用户权限和审计策略。
+
+## 16. 验收标准
+
+第一版完成后应满足：
+
+- 上传 `.eml` 后，原始 `.eml`、附件和内联图片均能在阿里云 OSS 找到。
+- HTML 正文中的 `cid:` 图片被替换为 OSS URL。
+- SourceMessage Inbox 中可以查到 `provider=DEBUG_EML_UPLOAD` 的来源消息。
+- SourceMessage 媒体引用中可以查到内联图片、附件和原始 `.eml` 引用。
+- Debug run 表记录 SourceMessage ID、原始文件 hash、OSS URL、SuperAgent session / run 和运行状态。
+- SuperAgent 成功时，接口返回最终 answer 和可解析 JSON。
+- SuperAgent 返回非 JSON 时，接口不报业务成功伪结果，而是返回原始 answer 和 warning。
+- OSS 或 SuperAgent 失败时，接口返回安全错误，不泄漏 Secret 和邮件原文。
+- 现有 Reservation 任务列表、订单详情、任务详情接口不受影响。
+
+## 17. 建议目标模式提示词
+
+```text
+进入目标模式，目标：实现 M004 Debug EML 上传到 SuperAgent 调试链路。
+
+范围：
+1. 实现 POST /api/system/debug/eml-superagent-runs。
+2. 支持上传 .eml，解析邮件头、text/html 正文、内联图片和附件。
+3. 接入阿里云 OSS，上传原始 .eml、内联图片和附件。
+4. 替换 HTML 正文中的 cid: 图片为 OSS URL。
+5. 组装 AgentBus-like payload。
+6. 写入 SourceMessage Inbox，provider 使用 DEBUG_EML_UPLOAD，schema_version 使用 debug-eml-upload-v1。
+7. 调用 SuperAgent Open API 创建 session 并发送 messages/stream。
+8. 解析 SuperAgent SSE 最终回答，返回 raw answer 和 parsed json。
+9. 新增 debug run 表、Entity、Mapper、Repository、Service、Controller。
+10. 按当前后端代码规范放置 control、service、service.impl、domain、mapper、repository、common.request、common.result、common.dto、common.enums。
+11. Controller、Service、ServiceImpl 方法加中文注释；新增 Entity 字段和 DTO/Result 字段注释符合规范。
+12. 补充测试，覆盖 eml 解析、cid 替换、SourceMessage 写入参数、OSS adapter mock、SuperAgent client mock 和接口鉴权。
+13. 更新前后端沟通文档、上线注意事项和相关配置文档。
+
+不做：
+1. 不创建订单。
+2. 不创建任务。
+3. 不调用 SuperAgent 任务结果通知接口。
+4. 不做真实 OPERA / OHIP。
+5. 不做批量上传。
+6. 不做 SourceMessage Replay。
+7. 不做普通任务切换订单。
+8. 不做 SuperAgent 查询接口 3、4。
+9. 不接入完整用户 / 权限体系。
+
+完成后：
+code review，运行测试，中文提交。
+```
+
+## 18. 仍需后续关注
+
+- SuperAgent 是否会提供邮件处理专用 Open API 入参、profile 或 prompt 配置。
+- `ORIGINAL_EMAIL` 是否作为 SourceMessage 媒体新类型，还是第一版复用 `ATTACHMENT` 并用 `external_media_id` 标记。
+- Debug 上传是否需要历史列表和单次详情查询接口。
+- 私有 OSS bucket 场景下，前端展示附件和图片是否改为短时签名 URL 或后端代理。
+- 正式用户 / 权限体系上线后，Debug 上传接口需要从调试 key 迁移到权限码控制。