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

# 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 迁移到权限码控制。