实现 Debug EML 上传到 SuperAgent 链路
This commit is contained in:
andy
@@ -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}` 是历史讨论过的候选路径，当前后端不提供，前端不要接入。
|
||||
|
||||
@@ -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 元数据，可后置。 |
|
||||
|
||||
Reference in New Issue
Block a user