增加 SuperAgent 邮件会话查询接口

2026-07-09 15:25:26 +08:00
parent 6d2b3e8ccd
commit 0727dfb8d0
10 changed files with 1039 additions and 28 deletions
--- a/server/src/main/java/cn/nianxx/thhotel/platform/message/repository/MybatisSourceMessageInboxRepository.java
+++ b/server/src/main/java/cn/nianxx/thhotel/platform/message/repository/MybatisSourceMessageInboxRepository.java
@@ -110,6 +110,30 @@ public class MybatisSourceMessageInboxRepository implements SourceMessageInboxRe
                .toList();
    }

+    /**
+     * 查询指定来源和渠道下的同一外部会话，避免不同接入方会话 ID 偶然相同导致串数据。
+     */
+    @Override
+    public List<SourceMessageInboxSnapshot> findByExternalConversationId(
+            String hotelId,
+            String provider,
+            String channel,
+            String externalConversationId) {
+        if (!hasText(hotelId) || !hasText(provider) || !hasText(channel) || !hasText(externalConversationId)) {
+            return List.of();
+        }
+        return inboxMapper.selectList(Wrappers.<SourceMessageInboxEntity>lambdaQuery()
+                        .eq(SourceMessageInboxEntity::getHotelId, trim(hotelId))
+                        .eq(SourceMessageInboxEntity::getProvider, trim(provider))
+                        .eq(SourceMessageInboxEntity::getChannel, trim(channel))
+                        .eq(SourceMessageInboxEntity::getExternalConversationId, trim(externalConversationId))
+                        .orderByAsc(SourceMessageInboxEntity::getReceivedAt)
+                        .orderByAsc(SourceMessageInboxEntity::getId))
+                .stream()
+                .map(this::toSnapshot)
+                .toList();
+    }
+
    /**
     * 根据 SourceMessage 幂等键读取已有记录，用于重复投递判断。
     */
--- a/server/src/main/java/cn/nianxx/thhotel/platform/message/repository/SourceMessageInboxRepository.java
+++ b/server/src/main/java/cn/nianxx/thhotel/platform/message/repository/SourceMessageInboxRepository.java
@@ -31,6 +31,15 @@ public interface SourceMessageInboxRepository {
     */
    List<SourceMessageInboxSnapshot> findByExternalConversationId(String hotelId, String externalConversationId);

+    /**
+     * 按酒店、来源、渠道和外部邮件会话 ID 查询同一会话全部 Inbox 安全快照。
+     */
+    List<SourceMessageInboxSnapshot> findByExternalConversationId(
+            String hotelId,
+            String provider,
+            String channel,
+            String externalConversationId);
+
    /**
     * 按酒店、来源、渠道、外部邮件 ID 查询幂等记录。
     */
--- a/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/common/request/ReservationMessageConversationQueryRequest.java
+++ b/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/common/request/ReservationMessageConversationQueryRequest.java
@@ -0,0 +1,26 @@
+package cn.nianxx.thhotel.workflows.reservation.common.request;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * SuperAgent 查询邮件会话请求。可直接按外部会话 ID 查询，也可用外部来源消息 ID 反查会话。
+ *
+ * @param hotelId 酒店上下文 ID，用于隔离不同酒店的 SourceMessage 和任务数据
+ * @param sourceProvider 来源提供方稳定代码，按 source_message_id 反查时使用，缺省为 AGENTBUS
+ * @param sourceChannel 来源渠道稳定代码，按 source_message_id 反查时使用，缺省为 EMAIL
+ * @param externalConversationId 外部邮件会话 ID，对应 AgentBus source.external_conversation_id
+ * @param sourceMessageId 外部来源消息 ID，对应 AgentBus source.external_message_id，不是内部 Inbox ID
+ */
+public record ReservationMessageConversationQueryRequest(
+        @JsonProperty("hotel_id")
+        String hotelId,
+        @JsonProperty("source_provider")
+        String sourceProvider,
+        @JsonProperty("source_channel")
+        String sourceChannel,
+        @JsonProperty("external_conversation_id")
+        String externalConversationId,
+        @JsonProperty("source_message_id")
+        String sourceMessageId
+) {
+}
--- a/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/common/result/ReservationMessageConversationMessagesResult.java
+++ b/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/common/result/ReservationMessageConversationMessagesResult.java
@@ -0,0 +1,61 @@
+package cn.nianxx.thhotel.workflows.reservation.common.result;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.time.OffsetDateTime;
+import java.util.List;
+
+/**
+ * SuperAgent 邮件会话正文查询结果。只返回受控正文，不返回附件 URL 或未清洗 HTML。
+ *
+ * @param hotelId 酒店上下文 ID
+ * @param externalConversationId 外部邮件会话 ID
+ * @param messageCount 当前响应中的邮件数量
+ * @param messages 按邮件接收时间正序排列的受控正文列表
+ */
+public record ReservationMessageConversationMessagesResult(
+        @JsonProperty("hotel_id")
+        String hotelId,
+        @JsonProperty("external_conversation_id")
+        String externalConversationId,
+        @JsonProperty("message_count")
+        Integer messageCount,
+        List<MessageRecord> messages
+) {
+
+    /**
+     * 邮件受控正文。HTML 只返回后端清洗结果，媒体引用由后续受控原文接口另行提供。
+     *
+     * @param externalSourceMessageId 外部来源消息 ID，对应 AgentBus source.external_message_id
+     * @param externalConversationId 外部邮件会话 ID
+     * @param senderSummary 发送人安全摘要
+     * @param subject 邮件主题安全摘要
+     * @param receivedAt 本系统接收该邮件的 UTC 时间
+     * @param sourceSentAt 来源系统发送时间
+     * @param textBody 纯文本正文
+     * @param htmlBodySanitized 后端清洗后的 HTML 正文
+     * @param htmlSanitizeRequired HTML 是否需要按清洗后内容渲染
+     * @param htmlRenderMode HTML 渲染建议，例如 SANITIZED_HTML 或 TEXT_ONLY
+     */
+    public record MessageRecord(
+            @JsonProperty("external_source_message_id")
+            String externalSourceMessageId,
+            @JsonProperty("external_conversation_id")
+            String externalConversationId,
+            @JsonProperty("sender_summary")
+            String senderSummary,
+            String subject,
+            @JsonProperty("received_at")
+            OffsetDateTime receivedAt,
+            @JsonProperty("source_sent_at")
+            OffsetDateTime sourceSentAt,
+            @JsonProperty("text_body")
+            String textBody,
+            @JsonProperty("html_body_sanitized")
+            String htmlBodySanitized,
+            @JsonProperty("html_sanitize_required")
+            Boolean htmlSanitizeRequired,
+            @JsonProperty("html_render_mode")
+            String htmlRenderMode
+    ) {
+    }
+}
--- a/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/common/result/ReservationMessageConversationTasksResult.java
+++ b/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/common/result/ReservationMessageConversationTasksResult.java
@@ -0,0 +1,101 @@
+package cn.nianxx.thhotel.workflows.reservation.common.result;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.time.OffsetDateTime;
+import java.util.List;
+
+/**
+ * SuperAgent 邮件会话任务查询结果。按邮件接收时间正序，再按任务创建时间正序返回任务。
+ *
+ * @param hotelId 酒店上下文 ID
+ * @param externalConversationId 外部邮件会话 ID
+ * @param taskCount 当前响应中的任务数量
+ * @param tasks 会话下关联任务列表
+ */
+public record ReservationMessageConversationTasksResult(
+        @JsonProperty("hotel_id")
+        String hotelId,
+        @JsonProperty("external_conversation_id")
+        String externalConversationId,
+        @JsonProperty("task_count")
+        Integer taskCount,
+        List<TaskRecord> tasks
+) {
+
+    /**
+     * 邮件会话下的任务摘要。source message 字段始终使用外部邮件 ID，避免暴露内部 Inbox 主键。
+     *
+     * @param taskId 本系统任务 ID
+     * @param orderId 任务当前挂靠订单 ID
+     * @param externalSourceMessageId 外部来源消息 ID，对应 AgentBus source.external_message_id
+     * @param externalConversationId 外部邮件会话 ID
+     * @param sourceReceivedAt 本系统接收该邮件的 UTC 时间
+     * @param sourceEventIndex AI transition 来源事件序号
+     * @param catalogCode Skill 目录代码
+     * @param skillId Skill 标识
+     * @param resultType AI 结果类型
+     * @param taskType AI 原始任务类型
+     * @param systemTaskType 系统主任务类型
+     * @param taskCardType 前端任务卡类型
+     * @param taskSubtype 业务动作 subtype
+     * @param taskStatus 任务状态
+     * @param queueParticipation 是否参与订单执行队列
+     * @param executionOrder 同订单执行顺序
+     * @param parentTaskId 父任务 ID
+     * @param parentSourceEventIndex 父事件序号
+     * @param linkedTaskGroupId 联动任务组 ID
+     * @param blockedUntilParentCompleted 是否等待父任务完成
+     * @param completedAt 任务完成时间
+     * @param taskCreatedAt 任务创建时间
+     * @param taskUpdatedAt 任务更新时间
+     */
+    public record TaskRecord(
+            @JsonProperty("task_id")
+            String taskId,
+            @JsonProperty("order_id")
+            String orderId,
+            @JsonProperty("external_source_message_id")
+            String externalSourceMessageId,
+            @JsonProperty("external_conversation_id")
+            String externalConversationId,
+            @JsonProperty("source_received_at")
+            OffsetDateTime sourceReceivedAt,
+            @JsonProperty("source_event_index")
+            Integer sourceEventIndex,
+            @JsonProperty("catalog_code")
+            String catalogCode,
+            @JsonProperty("skill_id")
+            String skillId,
+            @JsonProperty("result_type")
+            String resultType,
+            @JsonProperty("task_type")
+            String taskType,
+            @JsonProperty("system_task_type")
+            String systemTaskType,
+            @JsonProperty("task_card_type")
+            String taskCardType,
+            @JsonProperty("task_subtype")
+            String taskSubtype,
+            @JsonProperty("task_status")
+            String taskStatus,
+            @JsonProperty("queue_participation")
+            Boolean queueParticipation,
+            @JsonProperty("execution_order")
+            Integer executionOrder,
+            @JsonProperty("parent_task_id")
+            String parentTaskId,
+            @JsonProperty("parent_source_event_index")
+            Integer parentSourceEventIndex,
+            @JsonProperty("linked_task_group_id")
+            String linkedTaskGroupId,
+            @JsonProperty("blocked_until_parent_completed")
+            Boolean blockedUntilParentCompleted,
+            @JsonProperty("completed_at")
+            OffsetDateTime completedAt,
+            @JsonProperty("task_created_at")
+            OffsetDateTime taskCreatedAt,
+            @JsonProperty("task_updated_at")
+            OffsetDateTime taskUpdatedAt
+    ) {
+    }
+}
--- a/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/control/ReservationAiQueryController.java
+++ b/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/control/ReservationAiQueryController.java
@@ -6,9 +6,12 @@ import cn.nianxx.thhotel.integrations.ai.superagent.service.impl.SuperAgentTaskR
 import cn.nianxx.thhotel.integrations.ai.superagent.service.impl.SuperAgentTaskResultProperties;
 import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationAiCaseContextQueryRequest;
 import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationAiObjectDetailQueryRequest;
+import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationMessageConversationQueryRequest;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiCaseContextResult;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiObjectDetailResult;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiQueryResponse;
+import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationMessageConversationMessagesResult;
+import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationMessageConversationTasksResult;
 import cn.nianxx.thhotel.workflows.reservation.service.ReservationAiQueryService;
 import cn.nianxx.thhotel.workflows.reservation.service.impl.ReservationAiQueryException;
 import com.fasterxml.jackson.core.JsonProcessingException;
@@ -34,6 +37,8 @@ public class ReservationAiQueryController {

    private static final String CASE_CONTEXT_PATH = "/api/ai-query/v1/case-context";
    private static final String OBJECT_DETAIL_PATH = "/api/ai-query/v1/object-detail";
+    private static final String MESSAGE_CONVERSATION_TASKS_PATH = "/api/ai-query/v1/message-conversation/tasks";
+    private static final String MESSAGE_CONVERSATION_MESSAGES_PATH = "/api/ai-query/v1/message-conversation/messages";

    private final ReservationAiQueryService aiQueryService;
    private final SuperAgentTaskResultSecurityService securityService;
@@ -112,6 +117,70 @@ public class ReservationAiQueryController {
                List.of()));
    }

+    /**
+     * 查询邮件会话下全部任务，给 SuperAgent 在处理当前邮件前核对历史任务状态。
+     */
+    @PostMapping(
+            value = "/message-conversation/tasks",
+            produces = MediaType.APPLICATION_JSON_VALUE)
+    public ResponseEntity<ReservationAiQueryResponse<ReservationMessageConversationTasksResult>>
+            queryMessageConversationTasks(
+                    @RequestBody(required = false) String rawBody,
+                    @RequestHeader(value = "Content-Type", required = false) String contentType,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Client-Id", required = false) String clientId,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Timestamp", required = false) String timestamp,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Nonce", required = false) String nonce,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Signature", required = false) String signature,
+                    @RequestHeader(value = "X-TH-Hotel-Request-Id", required = false) String requestId,
+                    @RequestHeader(value = "X-Request-Id", required = false) String legacyRequestId,
+                    @RequestHeader(value = "X-AI-Trace-Id", required = false) String traceId,
+                    @RequestHeader(value = "X-TH-Hotel-AI-Trace-Id", required = false) String thHotelTraceId) {
+        String requestBody = rawBody == null ? "" : rawBody;
+        verifyHmac(MESSAGE_CONVERSATION_TASKS_PATH, clientId, timestamp, nonce, signature, requestBody);
+        requireJsonContentType(contentType);
+        ReservationMessageConversationQueryRequest request = readBody(
+                requestBody,
+                ReservationMessageConversationQueryRequest.class);
+        ReservationMessageConversationTasksResult result = aiQueryService.queryMessageConversationTasks(request);
+        return ResponseEntity.ok(ReservationAiQueryResponse.success(
+                firstText(requestId, legacyRequestId),
+                firstText(thHotelTraceId, traceId),
+                result,
+                List.of()));
+    }
+
+    /**
+     * 查询邮件会话下全部受控正文，只返回清洗后的 HTML，不返回附件 URL 或原始 HTML。
+     */
+    @PostMapping(
+            value = "/message-conversation/messages",
+            produces = MediaType.APPLICATION_JSON_VALUE)
+    public ResponseEntity<ReservationAiQueryResponse<ReservationMessageConversationMessagesResult>>
+            queryMessageConversationMessages(
+                    @RequestBody(required = false) String rawBody,
+                    @RequestHeader(value = "Content-Type", required = false) String contentType,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Client-Id", required = false) String clientId,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Timestamp", required = false) String timestamp,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Nonce", required = false) String nonce,
+                    @RequestHeader(name = "X-TH-Hotel-SuperAgent-Signature", required = false) String signature,
+                    @RequestHeader(value = "X-TH-Hotel-Request-Id", required = false) String requestId,
+                    @RequestHeader(value = "X-Request-Id", required = false) String legacyRequestId,
+                    @RequestHeader(value = "X-AI-Trace-Id", required = false) String traceId,
+                    @RequestHeader(value = "X-TH-Hotel-AI-Trace-Id", required = false) String thHotelTraceId) {
+        String requestBody = rawBody == null ? "" : rawBody;
+        verifyHmac(MESSAGE_CONVERSATION_MESSAGES_PATH, clientId, timestamp, nonce, signature, requestBody);
+        requireJsonContentType(contentType);
+        ReservationMessageConversationQueryRequest request = readBody(
+                requestBody,
+                ReservationMessageConversationQueryRequest.class);
+        ReservationMessageConversationMessagesResult result = aiQueryService.queryMessageConversationMessages(request);
+        return ResponseEntity.ok(ReservationAiQueryResponse.success(
+                firstText(requestId, legacyRequestId),
+                firstText(thHotelTraceId, traceId),
+                result,
+                List.of()));
+    }
+
    /**
     * 使用任务结果接收接口同一套 HMAC 规则校验查询请求，校验通过后才允许解析业务 JSON。
     */
--- a/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/service/ReservationAiQueryService.java
+++ b/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/service/ReservationAiQueryService.java
@@ -2,8 +2,11 @@ package cn.nianxx.thhotel.workflows.reservation.service;

 import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationAiCaseContextQueryRequest;
 import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationAiObjectDetailQueryRequest;
+import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationMessageConversationQueryRequest;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiCaseContextResult;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiObjectDetailResult;
+import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationMessageConversationMessagesResult;
+import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationMessageConversationTasksResult;

 /**
 * Reservation AI 查询服务。为 SuperAgent / Main Agent 提供只读上下文，不产生业务写入。
@@ -19,4 +22,16 @@ public interface ReservationAiQueryService {
     * 查询单个对象详情。第一版只支持 ORDER:{orderId} 形式的本系统订单对象。
     */
    ReservationAiObjectDetailResult queryObjectDetail(ReservationAiObjectDetailQueryRequest request);
+
+    /**
+     * 查询邮件会话下全部任务，按邮件接收时间和任务创建时间稳定排序。
+     */
+    ReservationMessageConversationTasksResult queryMessageConversationTasks(
+            ReservationMessageConversationQueryRequest request);
+
+    /**
+     * 查询邮件会话下全部受控正文，返回清洗后的 HTML，不返回附件 URL 或原始未清洗 HTML。
+     */
+    ReservationMessageConversationMessagesResult queryMessageConversationMessages(
+            ReservationMessageConversationQueryRequest request);
 }
--- a/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/service/impl/ReservationAiQueryServiceImpl.java
+++ b/server/src/main/java/cn/nianxx/thhotel/workflows/reservation/service/impl/ReservationAiQueryServiceImpl.java
@@ -1,6 +1,13 @@
 package cn.nianxx.thhotel.workflows.reservation.service.impl;

 import cn.nianxx.thhotel.platform.common.time.UtcTimeFormatter;
+import cn.nianxx.thhotel.platform.message.common.dto.SourceMessageInboxSnapshot;
+import cn.nianxx.thhotel.platform.message.common.dto.SourceMessageOriginalAccessAuditDraft;
+import cn.nianxx.thhotel.platform.message.common.dto.SourceMessageOriginalContent;
+import cn.nianxx.thhotel.platform.message.common.dto.SourceMessageOriginalMediaItem;
+import cn.nianxx.thhotel.platform.message.common.enums.SourceMessageOriginalAccessResult;
+import cn.nianxx.thhotel.platform.message.repository.SourceMessageInboxRepository;
+import cn.nianxx.thhotel.platform.message.service.SourceMessageHtmlSanitizerService;
 import cn.nianxx.thhotel.workflows.reservation.common.dto.ReservationAiQueryOrderSnapshot;
 import cn.nianxx.thhotel.workflows.reservation.common.dto.ReservationAiQueryTaskSnapshot;
 import cn.nianxx.thhotel.workflows.reservation.common.enums.ReservationOrderKeyType;
@@ -9,12 +16,16 @@ import cn.nianxx.thhotel.workflows.reservation.common.enums.ReservationSystemTas
 import cn.nianxx.thhotel.workflows.reservation.common.enums.ReservationTaskStatus;
 import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationAiCaseContextQueryRequest;
 import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationAiObjectDetailQueryRequest;
+import cn.nianxx.thhotel.workflows.reservation.common.request.ReservationMessageConversationQueryRequest;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiCaseContextResult;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiObjectDetailResult;
 import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationAiQueryWarningResult;
+import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationMessageConversationMessagesResult;
+import cn.nianxx.thhotel.workflows.reservation.common.result.ReservationMessageConversationTasksResult;
 import cn.nianxx.thhotel.workflows.reservation.repository.ReservationAiWorkflowRepository;
 import cn.nianxx.thhotel.workflows.reservation.service.ReservationAiQueryService;
 import java.time.LocalDateTime;
+import java.time.ZoneOffset;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -22,9 +33,11 @@ import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
+import java.util.regex.Pattern;
 import java.util.stream.Stream;
 import org.springframework.http.HttpStatus;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;

 /**
 * Reservation AI 查询服务实现。只读取订单、任务和 AI 过渡层事实，不执行业务状态流转。
@@ -35,6 +48,12 @@ public class ReservationAiQueryServiceImpl implements ReservationAiQueryService
    private static final String OBJECT_ID_PREFIX_ORDER = "ORDER:";
    private static final String SOURCE_TABLE_ORDER = "workflow_reservation_order";
    private static final String WARNING_OPERA_PROJECTION_UNAVAILABLE = "OPERA_PROJECTION_UNAVAILABLE";
+    private static final String DEFAULT_SOURCE_PROVIDER = "AGENTBUS";
+    private static final String DEFAULT_SOURCE_CHANNEL = "EMAIL";
+    private static final String SUPERAGENT_AI_QUERY_ACTOR = "system:superagent-ai-query";
+    private static final String MESSAGE_CONVERSATION_ACCESS_SCENE = "superagent-message-conversation-messages";
+    private static final Pattern HTML_URL_ATTRIBUTE_PATTERN = Pattern.compile(
+            "(?i)\\s+(href|src|xlink:href|formaction|poster|background)\\s*=\\s*(\"[^\"]*\"|'[^']*'|[^\\s>]+)");
    private static final Set<String> OPEN_TASK_STATUSES = Set.of(
            ReservationTaskStatus.PENDING_CONFIRM.name(),
            ReservationTaskStatus.READY.name(),
@@ -44,12 +63,19 @@ public class ReservationAiQueryServiceImpl implements ReservationAiQueryService
            ReservationTaskStatus.COMPLETED.name());

    private final ReservationAiWorkflowRepository repository;
+    private final SourceMessageInboxRepository sourceMessageInboxRepository;
+    private final SourceMessageHtmlSanitizerService htmlSanitizerService;

    /**
-     * 注入 Reservation 工作流持久化边界，Service 不直接依赖 Mapper。
+     * 注入 Reservation 工作流持久化边界、SourceMessage 持久化边界和 HTML 清洗服务。
     */
-    public ReservationAiQueryServiceImpl(ReservationAiWorkflowRepository repository) {
+    public ReservationAiQueryServiceImpl(
+            ReservationAiWorkflowRepository repository,
+            SourceMessageInboxRepository sourceMessageInboxRepository,
+            SourceMessageHtmlSanitizerService htmlSanitizerService) {
        this.repository = repository;
+        this.sourceMessageInboxRepository = sourceMessageInboxRepository;
+        this.htmlSanitizerService = htmlSanitizerService;
    }

    /**
@@ -167,6 +193,234 @@ public class ReservationAiQueryServiceImpl implements ReservationAiQueryService
                        "当前系统尚未接入 OPERA 对象投影，日期、房型、房价等字段无法确认。")));
    }

+    /**
+     * 查询邮件会话下全部任务。排序先看邮件接收时间，再看任务创建时间，避免历史邮件任务乱序。
+     */
+    @Override
+    public ReservationMessageConversationTasksResult queryMessageConversationTasks(
+            ReservationMessageConversationQueryRequest request) {
+        validateConversationRequest(request);
+        String hotelId = trimToNull(request.hotelId());
+        List<SourceMessageInboxSnapshot> messages = findConversationMessages(request);
+        Map<Long, SourceMessageInboxSnapshot> messageIndex = indexMessages(messages);
+        List<ReservationMessageConversationTasksResult.TaskRecord> tasks = repository
+                .findAiQueryTasksBySourceMessageIds(hotelId, messages.stream().map(SourceMessageInboxSnapshot::id).toList())
+                .stream()
+                .filter(task -> messageIndex.containsKey(task.sourceMessageId()))
+                .sorted(Comparator
+                        .comparing(
+                                (ReservationAiQueryTaskSnapshot task) -> sourceReceivedAt(task, messageIndex),
+                                Comparator.nullsLast(LocalDateTime::compareTo))
+                        .thenComparing(
+                                ReservationAiQueryTaskSnapshot::createdAt,
+                                Comparator.nullsLast(LocalDateTime::compareTo))
+                        .thenComparing(ReservationAiQueryTaskSnapshot::id, Comparator.nullsLast(Long::compareTo)))
+                .map(task -> toConversationTask(task, messageIndex.get(task.sourceMessageId())))
+                .toList();
+        return new ReservationMessageConversationTasksResult(
+                hotelId,
+                conversationId(messages, request),
+                tasks.size(),
+                tasks);
+    }
+
+    /**
+     * 查询邮件会话下全部受控正文。读取正文时写审计，只输出清洗后的 HTML 和纯文本正文。
+     */
+    @Override
+    @Transactional
+    public ReservationMessageConversationMessagesResult queryMessageConversationMessages(
+            ReservationMessageConversationQueryRequest request) {
+        validateConversationRequest(request);
+        String hotelId = trimToNull(request.hotelId());
+        List<SourceMessageInboxSnapshot> messages = findConversationMessages(request);
+        List<ReservationMessageConversationMessagesResult.MessageRecord> resultMessages = messages.stream()
+                .map(this::toConversationMessage)
+                .toList();
+        return new ReservationMessageConversationMessagesResult(
+                hotelId,
+                conversationId(messages, request),
+                resultMessages.size(),
+                resultMessages);
+    }
+
+    /**
+     * 根据会话 ID 或外部 SourceMessage ID 找到同一邮件链的全部消息。
+     */
+    private List<SourceMessageInboxSnapshot> findConversationMessages(ReservationMessageConversationQueryRequest request) {
+        String hotelId = trimToNull(request.hotelId());
+        String externalConversationId = trimToNull(request.externalConversationId());
+        if (externalConversationId != null) {
+            List<SourceMessageInboxSnapshot> messages = sourceMessageInboxRepository.findByExternalConversationId(
+                    hotelId,
+                    sourceProvider(request),
+                    sourceChannel(request),
+                    externalConversationId);
+            if (messages.isEmpty()) {
+                throw notFound("MESSAGE_CONVERSATION_NOT_FOUND", "邮件会话不存在");
+            }
+            return messages;
+        }
+
+        SourceMessageInboxSnapshot anchor = sourceMessageInboxRepository.findByIdempotencyKey(
+                        hotelId,
+                        sourceProvider(request),
+                        sourceChannel(request),
+                        trimToNull(request.sourceMessageId()))
+                .orElseThrow(() -> notFound("SOURCE_MESSAGE_NOT_FOUND", "外部来源消息不存在"));
+        String anchorConversationId = trimToNull(anchor.externalConversationId());
+        if (anchorConversationId == null) {
+            return List.of(anchor);
+        }
+        List<SourceMessageInboxSnapshot> messages = sourceMessageInboxRepository.findByExternalConversationId(
+                hotelId,
+                anchor.provider(),
+                anchor.channel(),
+                anchorConversationId);
+        return messages.isEmpty() ? List.of(anchor) : messages;
+    }
+
+    /**
+     * 将邮件列表按内部 SourceMessage ID 建索引，只在服务层内部用于任务关联。
+     */
+    private Map<Long, SourceMessageInboxSnapshot> indexMessages(List<SourceMessageInboxSnapshot> messages) {
+        Map<Long, SourceMessageInboxSnapshot> result = new LinkedHashMap<>();
+        messages.forEach(message -> result.put(message.id(), message));
+        return result;
+    }
+
+    /**
+     * 将任务快照转换为 SuperAgent 会话任务响应，隐藏内部 SourceMessage ID。
+     */
+    private ReservationMessageConversationTasksResult.TaskRecord toConversationTask(
+            ReservationAiQueryTaskSnapshot task,
+            SourceMessageInboxSnapshot message) {
+        return new ReservationMessageConversationTasksResult.TaskRecord(
+                idString(task.id()),
+                idString(task.orderId()),
+                message.externalMessageId(),
+                message.externalConversationId(),
+                UtcTimeFormatter.toUtcOffsetDateTime(message.receivedAt()),
+                task.transitionSourceEventIndex(),
+                task.catalogCode(),
+                task.skillId(),
+                task.resultType(),
+                task.aiTaskType(),
+                task.systemTaskType(),
+                task.taskCardType(),
+                task.taskSubtype(),
+                task.taskStatus(),
+                task.queueParticipation(),
+                task.executionOrder(),
+                idString(task.parentTaskId()),
+                task.parentSourceEventIndex(),
+                task.linkedTaskGroupId(),
+                task.blockedUntilParentCompleted(),
+                UtcTimeFormatter.toUtcOffsetDateTime(task.completedAt()),
+                UtcTimeFormatter.toUtcOffsetDateTime(task.createdAt()),
+                UtcTimeFormatter.toUtcOffsetDateTime(task.updatedAt()));
+    }
+
+    /**
+     * 将邮件原文转换为受控正文响应，不返回附件 URL 或原始未清洗 HTML。
+     */
+    private ReservationMessageConversationMessagesResult.MessageRecord toConversationMessage(
+            SourceMessageInboxSnapshot message) {
+        SourceMessageOriginalContent originalContent = readOriginalAndAudit(message);
+        String htmlBody = originalContent.htmlBody();
+        String sanitizedHtml = htmlSanitizerService.sanitizeHtml(removeMediaUrls(htmlBody, originalContent));
+        return new ReservationMessageConversationMessagesResult.MessageRecord(
+                message.externalMessageId(),
+                message.externalConversationId(),
+                message.senderSummary(),
+                message.subject(),
+                UtcTimeFormatter.toUtcOffsetDateTime(message.receivedAt()),
+                UtcTimeFormatter.toUtcOffsetDateTime(message.sourceSentAt()),
+                removeMediaUrls(originalContent.textBody(), originalContent),
+                removeHtmlUrlAttributes(sanitizedHtml),
+                true,
+                htmlSanitizerService.htmlRenderMode(htmlBody));
+    }
+
+    /**
+     * 移除正文中已知媒体外链，避免 SuperAgent 受控正文接口返回附件或内嵌图片 URL。
+     */
+    private String removeMediaUrls(String body, SourceMessageOriginalContent originalContent) {
+        if (body == null || originalContent.mediaItems() == null || originalContent.mediaItems().isEmpty()) {
+            return body;
+        }
+        String result = body;
+        for (SourceMessageOriginalMediaItem mediaItem : originalContent.mediaItems()) {
+            String externalUrl = trimToNull(mediaItem.externalUrl());
+            if (externalUrl != null) {
+                result = result.replace(externalUrl, "");
+            }
+        }
+        return result;
+    }
+
+    /**
+     * SuperAgent 正文查询不返回任何 HTML URL 属性，图片和附件由后续受控原文接口处理。
+     */
+    private String removeHtmlUrlAttributes(String htmlBody) {
+        if (htmlBody == null) {
+            return null;
+        }
+        return HTML_URL_ATTRIBUTE_PATTERN.matcher(htmlBody).replaceAll("");
+    }
+
+    /**
+     * 受控读取邮件正文并写入审计，便于后续追踪 SuperAgent 原文访问。
+     */
+    private SourceMessageOriginalContent readOriginalAndAudit(SourceMessageInboxSnapshot message) {
+        SourceMessageOriginalContent content = sourceMessageInboxRepository.findOriginalContent(message.id())
+                .orElse(new SourceMessageOriginalContent(message.id(), null, null, List.of()));
+        sourceMessageInboxRepository.insertOriginalAccessAudit(new SourceMessageOriginalAccessAuditDraft(
+                message.id(),
+                SUPERAGENT_AI_QUERY_ACTOR,
+                MESSAGE_CONVERSATION_ACCESS_SCENE,
+                SourceMessageOriginalAccessResult.GRANTED.code(),
+                LocalDateTime.now(ZoneOffset.UTC)));
+        return content;
+    }
+
+    /**
+     * 读取任务来源邮件接收时间，供会话任务排序使用。
+     */
+    private LocalDateTime sourceReceivedAt(
+            ReservationAiQueryTaskSnapshot task,
+            Map<Long, SourceMessageInboxSnapshot> messageIndex) {
+        SourceMessageInboxSnapshot message = messageIndex.get(task.sourceMessageId());
+        return message == null ? null : message.receivedAt();
+    }
+
+    /**
+     * 响应中的会话 ID 优先取实际消息快照，单封无会话 ID 时回显请求值。
+     */
+    private String conversationId(
+            List<SourceMessageInboxSnapshot> messages,
+            ReservationMessageConversationQueryRequest request) {
+        return messages.stream()
+                .map(SourceMessageInboxSnapshot::externalConversationId)
+                .filter(value -> trimToNull(value) != null)
+                .findFirst()
+                .orElse(trimToNull(request.externalConversationId()));
+    }
+
+    /**
+     * 查询外部 source_message_id 时使用来源提供方；缺省按当前 AgentBus 邮件入口处理。
+     */
+    private String sourceProvider(ReservationMessageConversationQueryRequest request) {
+        return Optional.ofNullable(trimToNull(request.sourceProvider())).orElse(DEFAULT_SOURCE_PROVIDER);
+    }
+
+    /**
+     * 查询外部 source_message_id 时使用来源渠道；缺省按当前 EMAIL 邮件入口处理。
+     */
+    private String sourceChannel(ReservationMessageConversationQueryRequest request) {
+        return Optional.ofNullable(trimToNull(request.sourceChannel())).orElse(DEFAULT_SOURCE_CHANNEL);
+    }
+
    private ReservationAiCaseContextResult.MatchedOrderRecord toMatchedOrderRecord(
            ReservationAiQueryOrderSnapshot order) {
        return new ReservationAiCaseContextResult.MatchedOrderRecord(
@@ -309,10 +563,26 @@ public class ReservationAiQueryServiceImpl implements ReservationAiQueryService
        requireText(request.objectId(), "OBJECT_ID_REQUIRED", "object_id 不能为空");
    }

+    private void validateConversationRequest(ReservationMessageConversationQueryRequest request) {
+        if (request == null) {
+            throw badRequest("MISSING_REQUEST_BODY", "请求体不能为空");
+        }
+        requireText(request.hotelId(), "HOTEL_ID_REQUIRED", "hotel_id 不能为空");
+        if (trimToNull(request.externalConversationId()) == null && trimToNull(request.sourceMessageId()) == null) {
+            throw badRequest(
+                    "MESSAGE_CONVERSATION_QUERY_KEY_REQUIRED",
+                    "external_conversation_id、source_message_id 至少需要一个");
+        }
+    }
+
    private ReservationAiQueryException badRequest(String code, String message) {
        return new ReservationAiQueryException(HttpStatus.BAD_REQUEST, code, message);
    }

+    private ReservationAiQueryException notFound(String code, String message) {
+        return new ReservationAiQueryException(HttpStatus.NOT_FOUND, code, message);
+    }
+
    private void requireText(String value, String code, String message) {
        if (trimToNull(value) == null) {
            throw badRequest(code, message);