提交一次全量代码

docs/project/integrations/superagent-agentbus-project-integration-guide.md

@@ -270,6 +270,7 @@ AGENTBUS_MAX_SAMPLES=100
 AGENTBUS_CAPTURE_ENABLED=true
 AGENTBUS_DEFAULT_HOTEL_ID=HOTEL-TEST
 AGENTBUS_REPLY_MODE=NONE
+SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY=
 SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY=
 ```
 
@@ -290,7 +291,10 @@ SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY=
 | `AGENTBUS_CAPTURE_ENABLED` | 否 | 是否写入 SourceMessage Inbox。 |
 | `AGENTBUS_DEFAULT_HOTEL_ID` | 否 | AgentBus 未提供租户上下文时的默认业务上下文。 |
 | `AGENTBUS_REPLY_MODE` | 否 | 调试回复模式。真实客户渠道应保持 `NONE`。 |
-| `SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY` | 是 | 原文读取接口的临时受控访问 key，后续可替换为正式权限体系。 |
+| `SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY` | 是 | dev 原文读取接口的临时受控访问 key，后续可替换为正式权限体系。 |
+| `SOURCE_MESSAGE_TEST_ORIGINAL_READ_ACCESS_KEY` | 是 | test 原文读取接口的临时受控访问 key。 |
+| `SOURCE_MESSAGE_PROD_ORIGINAL_READ_ACCESS_KEY` | 是 | prod 原文读取接口的临时受控访问 key，只能通过生产 Secret 注入。 |
+| `SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY` | 是 | 旧通用原文读取 key，仅作为兼容兜底。 |
 
 ### 5.2 WebSocket 连接
 
@@ -511,6 +515,9 @@ MessageEvent
 - `DEERFLOW_OPEN_API_KEY`
 - `SUPERAGENT_PROBE_ACCESS_KEY`
 - `AGENTBUS_WS_TOKEN`
+- `SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY`
+- `SOURCE_MESSAGE_TEST_ORIGINAL_READ_ACCESS_KEY`
+- `SOURCE_MESSAGE_PROD_ORIGINAL_READ_ACCESS_KEY`
 - `SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY`
 - `SOURCE_MESSAGE_REPLAY_ACCESS_KEY`
 - 数据库密码

docs/project/integrations/superagent-api-contract.md

@@ -10,6 +10,23 @@
 | 适用范围 | SuperAgent 调用本系统查询上下文、提交 AI 任务结果 |
 | 主要读者 | SuperAgent 对接方、后端、测试、运维 |
 
+## 联调参数区
+
+以下参数供 SuperAgent 联调时手动修改。该区块只用于 dev/test 联调，不作为生产 Secret 管理方式。
+
+| 参数 | 当前联调值 | 中文说明 |
+| --- | --- | --- |
+| `TH_HOTEL_API_BASE_URL` | `http://8.138.234.141:18087` | 本系统后端基础地址；本地联调用 8080，部署环境改为实际网关或服务地址。 |
+| `HOTEL_ID` | `HOTEL-DEV` | 当前 dev profile 下 AgentBus 入库默认酒店 ID；调用三个 SuperAgent 接口时均应传入请求体 `hotel_id`。 |
+| `SUPERAGENT_CLIENT_ID` | `superagent-debug` | SuperAgent 调用方 ID，对应 Header `X-TH-Hotel-SuperAgent-Client-Id`。 |
+| `SUPERAGENT_HMAC_SECRET` | `th-hotel-superagent-debug-20260709-change-before-prod` | dev/test 联调临时 HMAC 密钥；生产上线前必须更换为新的高强度随机密钥。 |
+
+生产注意：
+
+- 生产环境必须更换 `SUPERAGENT_HMAC_SECRET`，不得继续使用上述联调临时密钥。
+- 生产密钥不得写入 SuperAgent skill 文件、仓库文档、前端代码、镜像或普通日志，只能通过部署 Secret / 环境变量注入。
+- 本系统后端按 profile 优先读取环境专属密钥：dev 使用 `SUPERAGENT_DEV_TASK_RESULT_HMAC_SECRET`，test 使用 `SUPERAGENT_TEST_TASK_RESULT_HMAC_SECRET`，prod 使用 `SUPERAGENT_PROD_TASK_RESULT_HMAC_SECRET`；旧通用变量 `SUPERAGENT_TASK_RESULT_HMAC_SECRET` 仅作为兼容兜底。当前查询接口和任务结果通知接口共用同一个 HMAC secret。
+
 ## 1. 基础约定
 
 请求地址先使用占位符：
@@ -52,7 +69,7 @@ POST
 签名算法：
 
 ```text
-signature = HMAC_SHA256(SUPERAGENT_TASK_RESULT_HMAC_SECRET, canonical_string)
+signature = HMAC_SHA256(SUPERAGENT_HMAC_SECRET, canonical_string)
 ```
 
 Header 写法：
@@ -102,7 +119,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
 
 ```json
 {
-  "hotel_id": "HOTEL-TEST",
+  "hotel_id": "<HOTEL_ID>",
   "group_code": "GRP-001",
   "confirmation_number": null,
   "reservation_no": null,
@@ -186,7 +203,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
 
 ```json
 {
-  "hotel_id": "HOTEL-TEST",
+  "hotel_id": "<HOTEL_ID>",
   "object_id": "ORDER:1900000000000000100",
   "object_type": "group_block"
 }
@@ -264,7 +281,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
 
 ```json
 {
-  "hotel_id": "HOTEL-TEST",
+  "hotel_id": "<HOTEL_ID>",
   "source_message_id": "mail-20260708-0001",
   "ai_task_results": [
     {
@@ -328,13 +345,14 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
     {
       "source_event_index": 1,
       "array_index": 1,
+      "ai_transition_id": "1900000000000000250",
       "order_id": "1900000000000000300",
       "task_id": "1900000000000000400",
-      "task_status": "PENDING_CONFIRM",
-      "order_status": "TEMPORARY",
       "system_task_type": "NEW_BOOKING",
       "task_card_type": "NEW_BOOKING",
-      "warnings": []
+      "task_status": "PENDING_CONFIRM",
+      "order_status": "TEMPORARY",
+      "execution_order": 1
     }
   ],
   "warnings": []
@@ -385,7 +403,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
 | `REQUEST_BODY_INVALID` | 400 | JSON 不合法 |
 | `QUERY_KEY_REQUIRED` | 400 | 查询接口缺少可用业务 key |
 | `OBJECT_NOT_FOUND` | 404 | 对象详情查询目标不存在 |
-| `HOTEL_ID_REQUIRED` | 400 | 任务结果通知使用外部 `source_message_id` 时缺少 `hotel_id` |
+| `HOTEL_ID_REQUIRED` | 400 | 三个 SuperAgent 接口缺少必填 `hotel_id` |
 | `SOURCE_MESSAGE_NOT_FOUND` | 404 | 任务结果通知引用的外部来源消息尚未写入 SourceMessage Inbox |
 
 ## 8. HMAC 上线配置
@@ -394,7 +412,10 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
 
 | 配置项 | 是否必填 | 中文说明 |
 | --- | --- | --- |
-| `SUPERAGENT_TASK_RESULT_HMAC_SECRET` | 是 | HMAC 共享密钥；查询接口和任务结果通知接口共用 |
+| `SUPERAGENT_DEV_TASK_RESULT_HMAC_SECRET` | dev 必填 | dev HMAC 共享密钥；查询接口和任务结果通知接口共用 |
+| `SUPERAGENT_TEST_TASK_RESULT_HMAC_SECRET` | test 必填 | test HMAC 共享密钥；查询接口和任务结果通知接口共用 |
+| `SUPERAGENT_PROD_TASK_RESULT_HMAC_SECRET` | prod 必填 | prod HMAC 共享密钥；生产不能为空，只能通过 Secret 注入 |
+| `SUPERAGENT_TASK_RESULT_HMAC_SECRET` | 兼容兜底 | 旧通用 HMAC 变量；优先使用环境专属变量 |
 | `SUPERAGENT_TASK_RESULT_CLOCK_SKEW_SECONDS` | 否 | 请求时间允许偏移，默认 `300` 秒 |
 | `SUPERAGENT_TASK_RESULT_NONCE_TTL_SECONDS` | 否 | nonce 防重放保存时间，默认 `600` 秒 |
 | `SUPERAGENT_TASK_RESULT_MAX_BODY_BYTES` | 否 | 请求体最大字节数，默认 `1048576` |
@@ -402,7 +423,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
 上线注意事项：
 
 - 本系统和 SuperAgent 必须配置同一个 HMAC secret。
-- secret 只能放在部署平台 Secret 或环境变量中，不能写入仓库、镜像、前端配置或普通文档。
+- 生产 secret 只能放在部署平台 Secret 或环境变量中，不能写入仓库、镜像、前端配置或普通文档。
 - SuperAgent 必须使用原始请求体计算 SHA-256，不能使用格式化后 JSON。
 - HMAC canonical string 的第二行必须使用 `request_path`，例如 `/api/ai-query/v1/case-context`。
 - SuperAgent 每次请求必须生成全新的 nonce；同一个 `client_id + nonce` 在 TTL 窗口内不能重复使用。