实现 Debug EML 上传到 SuperAgent 链路

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 与当前代码一致。