实现酒店上下文单酒店收口

docs/project/frontend-backend/backend-to-frontend-notes.md

@@ -71,6 +71,8 @@
 | `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 调试接口，并补齐独立 Debug 外部消息 ID、原始 Message-ID 保留、安全 HTML 字段和 S000/S999 识别。 | 只用于调试页面；请求为 multipart/form-data；必须传 `X-TH-Hotel-Debug-Upload-Key`，但该 key 不能写进前端源码、构建产物、URL、localStorage 或错误上报；SuperAgent 返回 S000/S999 时不是 JSON 解析失败。 |
 
+酒店上下文注意：Reservation 列表、订单详情、任务列表和 Debug EML 上传的 `hotel_id` 第一版都是可选参数。前端默认可以不传；后端会按当前登录用户酒店上下文或平台酒店表唯一 `ACTIVE` 酒店解析。如果前端传了当前选中酒店，后端会校验该酒店是否可访问。
+
 ### 5.2 登录权限接入注意
 
 后端已提供 M003 登录和权限底座第一版接口：
@@ -109,7 +111,7 @@ POST /api/auth/logout
 ### 5.4 邮件会话详情接入注意
 
 - `GET /api/source-messages/{sourceMessageId}/conversation` 只接收路径参数 `sourceMessageId`；第一版不接收 `hotelId`、`includeBody`、`includeRelated`。
-- 前端当前通过 `VITE_RESERVATION_HOTEL_ID` 统一配置 Reservation 默认酒店上下文，并会在订单列表、任务列表和订单详情查询中传 `hotel_id`；任务详情、任务写操作和邮件会话详情当前后端接口不接收该参数。
+- Reservation 列表、任务列表和订单详情默认不需要前端传 `hotel_id`；如果前端已经接入酒店选择器，可以把当前选中酒店作为可选 `hotel_id` 传给后端。任务详情、任务写操作和邮件会话详情当前仍按对象 ID 定位，不接收该参数。
 - 后端会根据 `sourceMessageId` 定位 `external_conversation_id`，并返回同一会话下全部邮件；如果来源消息没有外部会话 ID，会降级返回当前单封邮件。
 - `messages[]` 按后端接收时间正序返回，前端不要重新按创建时间或任务时间排序。
 - 返回内容包含完整 `text_body`、`html_body`、`inline_images[]`、`attachments[]`、`related_orders[]`、`related_tasks[]`。
@@ -140,7 +142,6 @@ Header: X-TH-Hotel-Demo-Data-Key: <本地演示数据访问口令>
 Content-Type: application/json
 
 {
-  "hotel_id": "HOTEL-TEST",
   "run_label": "frontend-smoke"
 }
 ```
@@ -186,7 +187,7 @@ Header: X-TH-Hotel-Debug-Upload-Key: <调试访问口令>
 Content-Type: multipart/form-data
 
 file: .eml 文件
-hotel_id: HOTEL-TEST
+hotel_id: 可选；缺省使用后端系统酒店，显式传值时必须是当前可访问酒店
 run_label: 可选调试标签
 ```
 
@@ -195,6 +196,7 @@ run_label: 可选调试标签
 前端注意：
 
 - 该接口只用于 dev/test 调试页面，不是生产普通业务页面接口。
+- `hotel_id` 第一版可不传；单酒店阶段后端按平台酒店表唯一 `ACTIVE` 酒店解析。只有在调试人员明确要覆盖当前酒店时，前端才传当前选中酒店。
 - 接口会解析 `.eml`，上传原始邮件、内联图片和附件到本系统阿里云 OSS，替换 HTML 内 `cid:` 图片，再写入 SourceMessage Inbox。
 - SourceMessage 来源 provider 固定为 `DEBUG_EML_UPLOAD`，用于和 AgentBus 入库邮件区分。
 - 当前 AgentBus 实时收到邮件后自动推 SuperAgent 还没有做；这个接口是人工 Debug 上传链路，不代表实时生产链路。

docs/project/frontend-backend/debug-eml-page-integration-guide.md

@@ -31,7 +31,7 @@ Debug EML 页面第一版只做一件事：
 
 | 区域 | 展示 / 操作 | 说明 |
 | --- | --- | --- |
-| 上传配置区 | `hotel_id`、Debug 上传口令、`run_label`、`.eml` 文件选择、提交按钮 | Debug 上传口令只能由调试人员临时输入，不能写进前端源码、环境变量、localStorage 或 URL。 |
+| 上传配置区 | 可选酒店覆盖、Debug 上传口令、`run_label`、`.eml` 文件选择、提交按钮 | Debug 上传口令只能由调试人员临时输入，不能写进前端源码、环境变量、localStorage 或 URL；单酒店阶段默认不需要手填酒店。 |
 | 执行状态区 | loading、成功、失败、耗时、本次 `debug_run_id` | 提交后禁用按钮，避免重复点击；失败时展示安全错误摘要。 |
 | SourceMessage 追溯区 | `source_message_id`、`source_provider`、`external_message_id`、`external_conversation_id` | 用于确认已写入 SourceMessage Inbox。 |
 | 邮件内容预览区 | `html_body_sanitized`、纯文本、附件列表、内联图片列表 | HTML 展示必须优先使用 `html_body_sanitized`。 |
@@ -59,7 +59,7 @@ Header: X-TH-Hotel-Debug-Upload-Key: <调试上传口令>
 | 参数 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `file` | File | 是 | `.eml` 邮件文件。前端文件选择器建议 `accept=".eml,message/rfc822"`。 |
-| `hotel_id` | string | 是 | 酒店上下文 ID；本地 / test 可使用当前前端配置的 `VITE_RESERVATION_HOTEL_ID`。 |
+| `hotel_id` | string | 否 | 可选酒店上下文覆盖；缺省由后端按当前登录用户上下文或平台酒店表唯一 `ACTIVE` 酒店解析。 |
 | `run_label` | string | 否 | 调试标签，例如 `frontend-debug-smoke`，方便后端日志和数据库排查。 |
 
 前端调用示例：
@@ -67,14 +67,16 @@ Header: X-TH-Hotel-Debug-Upload-Key: <调试上传口令>
 ```ts
 export async function uploadDebugEml(input: {
   baseUrl: string
-  hotelId: string
+  hotelId?: string | null
   debugUploadKey: string
   file: File
   runLabel?: string
 }) {
   const form = new FormData()
   form.append('file', input.file)
-  form.append('hotel_id', input.hotelId)
+  if (input.hotelId?.trim()) {
+    form.append('hotel_id', input.hotelId.trim())
+  }
   if (input.runLabel?.trim()) {
     form.append('run_label', input.runLabel.trim())
   }
@@ -171,7 +173,7 @@ S000/S999 解析示例：
 
 | HTTP 状态 | `error_code` | 前端建议 |
 | --- | --- | --- |
-| `400` | `REQUEST_FIELD_REQUIRED` | 提示缺少必填字段，检查文件、`hotel_id` 或请求参数。 |
+| `400` | `REQUEST_FIELD_REQUIRED` | 提示缺少必填字段，检查文件或请求参数。 |
 | `400` | `EML_FILE_REQUIRED` | 提示请选择 `.eml` 文件。 |
 | `400` | `EML_FILE_TOO_LARGE` | 提示文件超过后端限制；当前默认上限通常为 10MB，以环境配置为准。 |
 | `400` | `INVALID_FILE_TYPE` | 提示只支持 `.eml`。 |
@@ -204,7 +206,7 @@ idle
 
 实现建议：
 
-- 文件未选择、`hotel_id` 为空、Debug 上传口令为空时禁用提交按钮。
+- 文件未选择或 Debug 上传口令为空时禁用提交按钮；`hotel_id` 为空是允许的，表示使用后端系统酒店。
 - 提交后禁用文件选择和提交按钮，避免重复上传。
 - SuperAgent 调用可能耗时较长，页面 loading 文案不要只写“上传中”，建议写“正在解析邮件并等待 SuperAgent 返回”。
 - 成功后保留本次响应在页面内存中；当前没有 Debug run 查询接口，刷新页面后需要重新上传。
@@ -233,7 +235,7 @@ idle
 前端需要具备：
 
 - 可配置后端 `BASE_URL`。
-- 可配置或输入 `hotel_id`。
+- 可配置或输入可选 `hotel_id`；单酒店联调默认可留空。
 - 调试人员临时输入 Debug 上传口令。
 - 准备一封 `.eml` 样例邮件。
 

docs/project/frontend-backend/frontend-to-backend-api-requests.md

@@ -84,7 +84,7 @@ GET /api/reservation/tasks
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `hotel_id` | 否 | 酒店 ID。第一版如果只有单酒店，可为空。 |
+| `hotel_id` | 否 | 酒店 ID。单酒店阶段默认可为空，由后端按当前用户上下文或平台酒店表唯一 `ACTIVE` 酒店解析；显式传值时后端会校验访问权限。 |
 | `order_id` | 否 | 按订单过滤。 |
 | `task_type` | 否 | `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`MANUAL_REVIEW`、`INFORMATIONAL_MESSAGE`、`SOURCE_MESSAGE_ONLY`。其中 `INFORMATIONAL_MESSAGE` 仅历史兼容，新入口 S000/S999 使用 `SOURCE_MESSAGE_ONLY`。 |
 | `task_status` | 否 | 任务状态过滤。 |
@@ -158,7 +158,7 @@ GET /api/reservation/orders/{orderId}
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
 | `orderId` | 是 | 订单 ID。 |
-| `hotel_id` | 否 | 酒店 ID。第一版如果只有单酒店，可为空。 |
+| `hotel_id` | 否 | 酒店 ID。单酒店阶段默认可为空，由后端解析；显式传值时后端会校验访问权限。 |
 | `include_tasks` | 否 | 是否返回任务时间线，默认 `true`。 |
 | `include_source_summary` | 否 | 是否返回来源消息摘要，默认 `true`；第一版参数保留，前端暂不要依赖它做字段裁剪。 |
 
@@ -228,7 +228,7 @@ GET /api/reservation/orders
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `hotel_id` | 否 | 酒店 ID。 |
+| `hotel_id` | 否 | 酒店 ID。单酒店阶段默认可为空，由后端解析；显式传值时后端会校验访问权限。 |
 | `order_status` | 否 | `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`。 |
 | `group_code` | 否 | 按 Group Code 精确或模糊查询，后端决定。 |
 | `confirmation_number` | 否 | 按 Confirmation No 查询。 |
@@ -285,7 +285,6 @@ POST /api/system/reservation/demo-data
 
 ```json
 {
-  "hotel_id": "HOTEL-TEST",
   "run_label": "frontend-smoke"
 }
 ```
@@ -500,7 +499,7 @@ GET /api/reservation/tasks/{taskId}
 - 如果前端只做“按后端字段直接渲染”，现有 `fields[]` 可以支撑第一版表单展示；本轮已经扩展 `ReservationTaskFieldResult`，避免前端维护第二套字段矩阵。
 - `result_type`、`task_type`、`task_subtype`、`default_value_source` 当前从后端字段矩阵定义透出。
 - 如果后端已有更细的字段来源或适用场景元数据，可后续再扩展 `field_source`、`applicable_scenario`，不作为本轮 P0 阻塞项。
-- 前端已统一配置 `VITE_RESERVATION_HOTEL_ID`，并会在 `GET /api/reservation/orders`、`GET /api/reservation/tasks`、`GET /api/reservation/orders/{orderId}` 自动传 `hotel_id`。当前 `GET /api/reservation/tasks/{taskId}` 以及任务写操作 Controller 不接收 `hotel_id`；第一版先按 ID 定位，后续多酒店隔离 / 权限方案统一补齐。
+- 前端默认不需要为 `GET /api/reservation/orders`、`GET /api/reservation/tasks`、`GET /api/reservation/orders/{orderId}` 自动拼 `hotel_id`；如已接入酒店选择器，可以传当前选中酒店，后端会校验访问权限。当前 `GET /api/reservation/tasks/{taskId}` 以及任务写操作 Controller 不接收 `hotel_id`；第一版先按 ID 定位，后续多酒店隔离 / 权限方案统一补齐。
 
 ## 9. S000/S999 特殊只读任务与历史 Message Notification
 
@@ -529,7 +528,7 @@ GET /api/reservation/message-notifications/{taskId}
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `hotel_id` | 否 | 酒店 ID。 |
+| `hotel_id` | 否 | 酒店 ID。单酒店阶段默认可为空，由后端解析；显式传值时后端会校验访问权限。 |
 | `order_id` | 否 | 按临时订单或真实订单过滤。 |
 | `keyword` | 否 | 邮件主题、摘要、发送人关键词。 |
 | `page_num` | 否 | 页码。 |