huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

提交一次全量代码

Browse Source
This commit is contained in:
andy
2026-07-09 11:59:34 +08:00
parent 855396e553
commit 9fa608f602
58 changed files with 8439 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/project/frontend-backend/backend-to-frontend-notes.md
View File

@@ -114,8 +114,8 @@ Content-Type: application/json
启用方式：
- 默认关闭，需要后端环境显式设置 `reservation.demo-data.enabled=true` 或环境变量 `RESERVATION_DEMO_DATA_ENABLED=true`。
- 必须配置 `reservation.demo-data.access-key` 或环境变量 `RESERVATION_DEMO_DATA_ACCESS_KEY`。
- dev profile 默认开启；test 默认关闭，需要后端环境显式设置 `reservation.demo-data.enabled=true` 或环境变量 `RESERVATION_TEST_DEMO_DATA_ENABLED=true`。
- 必须配置 `reservation.demo-data.access-key`；dev 优先使用 `RESERVATION_DEV_DEMO_DATA_ACCESS_KEY`，test 优先使用 `RESERVATION_TEST_DEMO_DATA_ACCESS_KEY`，旧通用变量 `RESERVATION_DEMO_DATA_ACCESS_KEY` 仅作为兼容兜底。
- 该接口只用于 dev/test 联调，不允许放进生产普通页面，也不要把访问口令写进前端仓库、浏览器环境变量或构建产物。
返回内容：

4
docs/project/frontend-backend/frontend-to-backend-api-requests.md
View File

@@ -275,8 +275,8 @@ POST /api/system/reservation/demo-data
| 配置 | 说明 |
| --- | --- |
| `reservation.demo-data.enabled=true` | 显式启用接口，也可用环境变量 `RESERVATION_DEMO_DATA_ENABLED=true`。 |
| `reservation.demo-data.access-key` | 配置访问口令，也可用环境变量 `RESERVATION_DEMO_DATA_ACCESS_KEY`。 |
| `reservation.demo-data.enabled=true` | dev 默认开启；test 需显式启用，也可用环境变量 `RESERVATION_TEST_DEMO_DATA_ENABLED=true`。 |
| `reservation.demo-data.access-key` | 配置访问口令；dev 优先使用 `RESERVATION_DEV_DEMO_DATA_ACCESS_KEY`，test 优先使用 `RESERVATION_TEST_DEMO_DATA_ACCESS_KEY`，旧通用变量 `RESERVATION_DEMO_DATA_ACCESS_KEY` 仅作为兼容兜底。 |
| `X-TH-Hotel-Demo-Data-Key` | 请求头必须携带，与后端配置口令一致。 |
请求示例：

13
docs/project/go-live-notes.md
View File

@@ -57,7 +57,10 @@
| 变量 | 是否 Secret | 上线注意事项 |
| --- | --- | --- |
| `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。未配置时原文读取默认关闭。 |
| `SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY` | 是 | 旧通用原文读取 key，仅作为兼容兜底。 |
注意：
@@ -87,7 +90,10 @@
| 变量 | 是否 Secret | 上线注意事项 |
| --- | --- | --- |
| `SUPERAGENT_TASK_RESULT_HMAC_SECRET` | 是 | SuperAgent 查询接口 1、2 和任务结果通知接口共用的 HMAC secret。生产不能为空，只能通过 Secret 注入。 |
| `SUPERAGENT_DEV_TASK_RESULT_HMAC_SECRET` | 是 | dev SuperAgent 查询接口 1、2 和任务结果通知接口共用的 HMAC secret。 |
| `SUPERAGENT_TEST_TASK_RESULT_HMAC_SECRET` | 是 | test SuperAgent 查询接口 1、2 和任务结果通知接口共用的 HMAC secret。 |
| `SUPERAGENT_PROD_TASK_RESULT_HMAC_SECRET` | 是 | prod SuperAgent 查询接口 1、2 和任务结果通知接口共用的 HMAC secret。生产不能为空，只能通过 Secret 注入。 |
| `SUPERAGENT_TASK_RESULT_HMAC_SECRET` | 是 | 旧通用 HMAC 变量，仅作为兼容兜底；新环境优先配置环境专属变量。 |
| `SUPERAGENT_TASK_RESULT_CLOCK_SKEW_SECONDS` | 否 | 请求时间允许偏移，默认 `300` 秒。上线前确认本系统、SuperAgent 和 AgentBus 所在机器时间已通过 NTP 同步。 |
| `SUPERAGENT_TASK_RESULT_NONCE_TTL_SECONDS` | 否 | nonce 防重放窗口，默认 `600` 秒。 |
| `SUPERAGENT_TASK_RESULT_MAX_BODY_BYTES` | 否 | SuperAgent 入站请求体最大字节数，默认 `1048576`。 |
@@ -283,6 +289,7 @@ GET /api/source-messages/{id}/original
```text
AGENTBUS_PROBE_ENABLED=false
AGENTBUS_CAPTURE_ENABLED=false
SOURCE_MESSAGE_PROD_ORIGINAL_READ_ACCESS_KEY=
SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY=
```
@@ -290,7 +297,7 @@ SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY=
- 关闭 `AGENTBUS_PROBE_ENABLED` 可以停止 WebSocket 入站连接。
- 关闭 `AGENTBUS_CAPTURE_ENABLED` 可以保留连接但暂停写入 Inbox。
- 清空 `SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY` 可以关闭原文读取接口。
- 清空当前 profile 对应的 `SOURCE_MESSAGE_*_ORIGINAL_READ_ACCESS_KEY`，且不配置旧通用变量，可以关闭原文读取接口。
数据库回滚注意：

9
docs/project/integrations/superagent-agentbus-project-integration-guide.md
View File

@@ -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`
- 数据库密码

41
docs/project/integrations/superagent-api-contract.md
View File

@@ -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 窗口内不能重复使用。

3
docs/project/requirements/M002-backend-data-model-design.md
View File

@@ -393,7 +393,8 @@
- 任务卡字段矩阵配置：先写在代码 Provider 中。
- 任务阻塞状态：实时计算，不落 `BLOCKED`。
- OPERA 真实接口字段映射：后续真实系统接入后在 adapter 层补充。
- 全量 Excel 字段路径：引用 `任务卡展示编辑矩阵.xlsx`，不手抄成数据库。
- 全量 Excel 字段路径：后端引用 `docs/import/20260706/任务卡展示编辑矩阵.xlsx` 作为完整规则来源，不手抄成数据库。
- 前端展示 / 编辑白名单：前端引用 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx`，该白名单不作为后端校验和 OPERA 映射的替代来源。
## 15. 待确认问题

9
docs/project/requirements/M002-superagent-task-result-api-contract.md
View File

@@ -57,12 +57,15 @@ hotel_id + source_provider(默认 AGENTBUS) + source_channel(默认 EMAIL) + sou
| 环境变量 | 是否必填 | 中文说明 |
| --- | --- | --- |
| `SUPERAGENT_TASK_RESULT_HMAC_SECRET` | 是 | SuperAgent 任务结果入站签名密钥，只能通过 Secret 注入 |
| `SUPERAGENT_DEV_TASK_RESULT_HMAC_SECRET` | dev 必填 | dev SuperAgent 任务结果入站签名密钥，只能通过 Secret 注入 |
| `SUPERAGENT_TEST_TASK_RESULT_HMAC_SECRET` | test 必填 | test SuperAgent 任务结果入站签名密钥，只能通过 Secret 注入 |
| `SUPERAGENT_PROD_TASK_RESULT_HMAC_SECRET` | prod 必填 | prod SuperAgent 任务结果入站签名密钥，只能通过 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` |
如果 `SUPERAGENT_TASK_RESULT_HMAC_SECRET` 为空，生产环境应拒绝接口调用。
如果当前 profile 对应的 `SUPERAGENT_*_TASK_RESULT_HMAC_SECRET` 和旧通用变量都为空，生产环境应拒绝接口调用。
### 3.2 请求 Header
@@ -92,7 +95,7 @@ POST
签名算法：
```text
signature = HMAC_SHA256(SUPERAGENT_TASK_RESULT_HMAC_SECRET, canonical_string)
signature = HMAC_SHA256(当前 profile 生效的 SuperAgent HMAC secret, canonical_string)
```
Header 写法：