修正邮件接收时间和发件人展示

2026-07-10 17:36:56 +08:00
parent 4745e20b9a
commit e76cb80f28
25 changed files with 226 additions and 59 deletions
--- a/docs/import/reusable/integrations/superagent-agentbus-portable-integration-guide.md
+++ b/docs/import/reusable/integrations/superagent-agentbus-portable-integration-guide.md
@@ -308,6 +308,8 @@ GET <AGENTBUS_WS_URL>?ready=1
 - `source.channel`
 - `source.external_message_id`
 - `source.external_conversation_id`
+- payload 或 source 中的 `received_at`
+- `source.sent_at`
 - frame id
 - session id
 - sender
@@ -322,6 +324,9 @@ GET <AGENTBUS_WS_URL>?ready=1
 | `source.channel` | `channel` |
 | `source.external_message_id` | `externalMessageId`，作为幂等键组成部分 |
 | `source.external_conversation_id` | `externalConversationId` |
+| payload 或 source 中的 `received_at` | `receivedAt`，作为消息来源接收时间 |
+| `source.sent_at` | `sourceSentAt`，作为消息来源发送时间 |
+| sender | `senderSummary`，是否打码由项目业务和权限策略决定 |
 | frame id | `providerFrameId` |
 | session id | `providerSessionId` |
 | payload 规范 JSON | `payloadJson` 与 `payloadSha256` |
--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -103,8 +103,8 @@ POST /api/auth/logout
 | --- | --- | --- |
 | `source_message_id` | 本系统内部 SourceMessage Inbox ID。 | 打开邮件会话详情时作为路径参数传入 `/api/source-messages/{sourceMessageId}/conversation`。 |
 | `source_subject` | 来源邮件主题安全摘要。 | 用于列表或任务详情标题旁展示，不代表完整邮件主题一定无敏感信息。 |
-| `source_sender_summary` | 来源发件人安全摘要。 | 用于辅助用户判断邮件来源。 |
-| `source_received_at` | 本系统接收来源消息时间，UTC。 | 前端展示时按用户或酒店时区格式化。 |
+| `source_sender_summary` | 来源发件人展示值，当前不打码。 | 用于辅助用户判断邮件来源。 |
+| `source_received_at` | 邮件来源接收时间，UTC；优先取 AgentBus payload `received_at`，缺失时使用本系统接收时间。 | 前端展示时按用户或酒店时区格式化。 |
 | `external_conversation_id` | 外部邮件会话 ID。 | 仅用于展示或调试，不作为当前会话详情接口路径参数。 |
 | `conversation_message_count` | 同一外部会话下的邮件数量。 | 用于提示用户打开的是整段会话，不是单封邮件。 |

@@ -113,7 +113,7 @@ POST /api/auth/logout
 - `GET /api/source-messages/{sourceMessageId}/conversation` 只接收路径参数 `sourceMessageId`；第一版不接收 `hotelId`、`includeBody`、`includeRelated`。
 - Reservation 列表、任务列表和订单详情默认不需要前端传 `hotel_id`；如果前端已经接入酒店选择器，可以把当前选中酒店作为可选 `hotel_id` 传给后端。任务详情、任务写操作和邮件会话详情当前仍按对象 ID 定位，不接收该参数。
 - 后端会根据 `sourceMessageId` 定位 `external_conversation_id`，并返回同一会话下全部邮件；如果来源消息没有外部会话 ID，会降级返回当前单封邮件。
- `messages[]` 按后端接收时间正序返回，前端不要重新按创建时间或任务时间排序。
+- `messages[]` 按邮件来源接收时间正序返回，前端不要重新按创建时间或任务时间排序。
 - 返回内容包含完整 `text_body`、`html_body`、`inline_images[]`、`attachments[]`、`related_orders[]`、`related_tasks[]`。
 - `html_body` 是原始 HTML 兼容字段；`html_body_sanitized` 是后端第一版清洗结果，已移除脚本标签、事件属性和危险协议链接。前端生产展示必须优先使用 `html_body_sanitized`，并可用 `html_render_mode=SANITIZED_HTML` 判断渲染模式。
 - 第一版仅处理 HTML 内容安全；`inline_images[]` 和 `attachments[]` 的 `externalUrl` 来自本系统 OSS 服务，暂不做额外拦截，但前端仍不得写入普通日志、错误上报、localStorage 或 URL query。
--- a/docs/project/frontend-backend/frontend-to-backend-api-requests.md
+++ b/docs/project/frontend-backend/frontend-to-backend-api-requests.md
@@ -136,8 +136,8 @@ GET /api/reservation/tasks

 | 字段 | 说明 |
 | --- | --- |
-| `source_sender_summary` | 来源消息发件人摘要，用于任务列表快速判断来源。 |
-| `source_received_at` | 来源消息接收时间，用于任务列表排序和展示。 |
+| `source_sender_summary` | 来源消息发件人展示值，当前不打码，用于任务列表快速判断来源。 |
+| `source_received_at` | 邮件来源接收时间，优先取 AgentBus payload `received_at`，用于任务列表排序和展示。 |
 | `external_conversation_id` | 来源消息所属邮件会话 ID，用于打开完整邮件会话详情。 |
 | `conversation_message_count` | 会话内邮件数量，用于提示用户该入口是整段会话，不是单封邮件。 |

@@ -209,8 +209,8 @@ GET /api/reservation/orders/{orderId}
 | --- | --- |
 | `source_message_id` | 任务对应的来源 SourceMessage Inbox ID。 |
 | `source_subject` | 来源消息主题摘要。 |
-| `source_sender_summary` | 来源消息发件人摘要。 |
-| `source_received_at` | 来源消息接收时间。 |
+| `source_sender_summary` | 来源消息发件人展示值，当前不打码。 |
+| `source_received_at` | 邮件来源接收时间，优先取 AgentBus payload `received_at`。 |
 | `external_conversation_id` | 来源消息所属邮件会话 ID。 |
 | `conversation_message_count` | 会话内邮件数量。 |

@@ -322,7 +322,7 @@ GET /api/source-message-conversations/{externalConversationId}
 中文说明：

 - “全部邮件”指同一个 `externalConversationId` 下的历史邮件、当前邮件和后续回复，不是只展示任务对应的单封来源邮件。
- 邮件会话详情页需要展示完整正文或清洗后的 HTML、附件、内联图片、发件人摘要、发送 / 接收时间、主题和关联订单 / 任务。
+- 邮件会话详情页需要展示完整正文或清洗后的 HTML、附件、内联图片、发件人展示值、发送 / 接收时间、主题和关联订单 / 任务。
 - 前端不在页面上做业务截断或隐藏；但仍只调用本项目后端接口，不直接访问邮箱、AgentBus、数据库或外部附件 URL Secret。
 - 如果后端仍需要审计原文读取，应由后端在该业务接口内部处理；前端不保存 `X-TH-Hotel-Source-Original-Read-Key` 一类受控访问 key。
 - 2026-07-08 后端已新增 `html_body_sanitized` 和 `html_render_mode`；前端页面展示邮件 HTML 时应优先使用 `html_body_sanitized`，`html_body` 只作为原始内容兼容字段，不建议生产直渲。
@@ -450,8 +450,8 @@ GET /api/reservation/tasks/{taskId}
 | 位置 | 字段 | 说明 |
 | --- | --- | --- |
 | 顶层 | `source_subject` | 任务来源消息主题摘要。 |
-| 顶层 | `source_sender_summary` | 任务来源消息发件人摘要。 |
-| 顶层 | `source_received_at` | 任务来源消息接收时间。 |
+| 顶层 | `source_sender_summary` | 任务来源消息发件人展示值，当前不打码。 |
+| 顶层 | `source_received_at` | 任务来源邮件接收时间，优先取 AgentBus payload `received_at`。 |
 | 顶层 | `external_conversation_id` | 任务来源消息所属邮件会话 ID。 |
 | 顶层 | `conversation_message_count` | 会话内邮件数量。 |
 | `fields[]` | `result_type` | 3.0 字段表中的结果类型，用于前端调试和字段分组校验。 |
--- a/docs/project/frontend-development-guidelines.md
+++ b/docs/project/frontend-development-guidelines.md
@@ -462,7 +462,7 @@ pnpm test -- SomeSpecName.spec.ts

 - 邮件会话详情页展示同一个 `external_conversation_id` 下的全部邮件，包括历史邮件、当前邮件和后续回复。
 - 页面入口可以来自订单详情任务队列、当前任务卡证据区或任务详情页，但落地页统一为“邮件会话详情”，不是单封邮件详情。
- 每封邮件应展示完整正文或清洗后的 HTML、附件列表、内联图片信息、发送 / 接收时间、发件人摘要、主题和关联订单 / 任务。
+- 每封邮件应展示完整正文或清洗后的 HTML、附件列表、内联图片信息、发送 / 接收时间、发件人展示值、主题和关联订单 / 任务。
 - 前端不在本页展示假数据；后端接口未接入时显示“接口待接入 / 暂无邮件会话数据”。
 - 邮件全文属于用户在邮箱中本来可见的信息，前端页面不做业务层面的截断隐藏；但仍必须通过本项目后端接口读取，不在前端保存外部系统 Secret 或访问 key。

--- a/docs/project/go-live-notes.md
+++ b/docs/project/go-live-notes.md
@@ -211,7 +211,7 @@
 - 表和字段中文注释能正常创建。
 - 数据库业务时间点按 UTC 写入，接口层返回带 `Z` 的 ISO 8601 UTC 时间，例如 `2026-07-08T03:00:00Z`。
 - MySQL JDBC URL 建议明确 `serverTimezone=UTC`；部署容器和 JVM 也应使用 UTC，或至少确认应用代码所有入库时间均通过 UTC 时钟生成。
- AgentBus 邮件来源时间、SuperAgent HMAC timestamp、本系统 `created_at` / `updated_at` / `received_at` 等时间点统一按 UTC 理解；前端展示时再按用户或酒店时区格式化。
+- AgentBus 邮件来源时间、SuperAgent HMAC timestamp、本系统 `created_at` / `updated_at` 等时间点统一按 UTC 理解；SourceMessage `received_at` 优先保存 AgentBus payload `received_at`，缺失时回退本系统接收时间，前端展示时再按用户或酒店时区格式化。
 - 入住日期、离店日期、酒店营业日属于酒店本地业务日期，不应因为 UTC 换算而自动前后偏移。
 - 执行 V4 前，如果目标库已有 M002 试运行数据，必须先检查 ACTIVE 订单业务号重复和同订单任务队列序号重复。
 - 执行 V5 / V6 前，如果目标库已有 M002 试运行数据，必须确认任务草稿、确认 payload 和 OPERA 模拟操作表允许从空数据开始补齐；不要手工伪造已确认 payload 或 attempt 历史。
@@ -255,12 +255,12 @@ HAVING COUNT(*) > 1;
 - Authorization、Cookie、CSRF Token。
 - Provider API Key、AgentBus Token、数据库密码。
 - 邮件正文、HTML、附件 URL、原始 payload。
- 客户姓名、完整邮箱、电话、证件号。
+- 客户姓名、电话、证件号；发件人展示字段因业务识别需要允许返回完整邮箱或名称，但不得写入普通日志、错误响应或调试状态接口。
 - 支付信息。

 SourceMessage 普通列表和普通详情只能返回安全摘要：

- 可以返回：SourceMessage ID、酒店 ID、provider、channel、外部邮件 ID、外部邮件链 ID、状态、时间、发送人摘要、主题摘要、安全短摘要。
+- 可以返回：SourceMessage ID、酒店 ID、provider、channel、外部邮件 ID、外部邮件链 ID、状态、时间、发件人展示值、主题摘要、安全短摘要。
 - 不应返回：完整正文、HTML、附件 URL、原始 payload。

 原文读取接口只允许在明确授权场景下使用：
--- a/docs/project/integrations/superagent-agentbus-project-integration-guide.md
+++ b/docs/project/integrations/superagent-agentbus-project-integration-guide.md
@@ -348,12 +348,14 @@ body.html
 body.text
 inline_images[]
 attachments[]
+received_at
 source.channel
 source.channel_account
 source.external_message_id
 source.external_conversation_id
 source.sender
 source.subject
+source.sent_at
 source.web_link
 reply_policy.mode
 reply_policy.final_only
@@ -366,6 +368,9 @@ reply_policy.final_only
 | `source.channel` | `channel`，例如 `EMAIL` |
 | `source.external_message_id` | `externalMessageId`，作为幂等键组成部分 |
 | `source.external_conversation_id` | `externalConversationId` |
+| `payload.received_at` 或 `source.received_at` | `receivedAt`，作为邮件来源接收时间 |
+| `source.sent_at` | `sourceSentAt`，作为邮件来源发送时间 |
+| `source.sender` | `senderSummary`，当前作为发件人展示值不打码 |
 | frame `id` | `agentbusFrameId` |
 | frame `session_id` | `agentbusSessionId` |
 | `payload` 规范 JSON | `payloadJson` 与 `payloadSha256` |
--- a/docs/project/requirements/M001-source-message-inbox-prd.md
+++ b/docs/project/requirements/M001-source-message-inbox-prd.md
@@ -117,7 +117,7 @@ AgentBus 邮件 JSON
 - 幂等去重：同一酒店、同一 provider、同一 channel、同一外部邮件 ID 不重复建记录。
 - 历史查询：查询本项目已经接收并落库过的邮件。
 - 邮件链查询：按 `externalConversationId` 查询同一邮件链下的记录。
- 安全摘要：列表只返回主题、发送人摘要、时间、状态、短摘要等安全信息。
+- 安全摘要：列表只返回主题摘要、发件人展示值、时间、状态、短摘要等受控展示信息。
 - 原文读取：提供统一受控接口读取 text、HTML、正文图片 URL、附件 URL。
 - 媒体引用保存：保存 AgentBus 已处理好的长期有效媒体 URL，不下载、不转存、不刷新。
 - 扩展来源：后续可以接入 Microsoft Graph、IMAP、Webhook、手工导入等来源。
@@ -152,9 +152,9 @@ source_message_media
 | `providerSessionId` | AgentBus session ID，用于排查连接会话，不作为邮件链 ID |
 | `payloadSha256` | 规范 JSON 的哈希值，用于排查 payload 是否变化 |
 | `captureStatus` | 捕获状态，例如 `RECEIVED`、`FAILED` |
-| `receivedAt` | 本项目接收时间 |
+| `receivedAt` | 邮件来源接收时间，优先取 AgentBus payload `received_at`；缺失时使用本项目接收时间 |
 | `sourceSentAt` | 邮件来源发送时间，如果 payload 提供则保存 |
-| `senderSummary` | 发送人安全摘要，列表可展示，不保存或不返回完整敏感信息 |
+| `senderSummary` | 发件人展示值，业务人员需要识别真实发件人，当前只清理首尾空白不打码 |
 | `subject` | 邮件主题 |
 | `safeSnippet` | 邮件安全摘要，不能包含完整正文、HTML、附件 URL 或敏感凭证 |