huangting/th-hotel-simple

Fork 0

Files

andy 9fa608f602 提交一次全量代码

2026-07-09 11:59:34 +08:00

15 KiB

Raw Blame History

后端提醒前端注意事项

1. 文档定位

本文记录后端侧提醒前端开发时必须注意的项目规范、业务规则、接口边界和安全要求。当前内容服务于 Reservation 任务详情、订单详情、任务列表、Message Notification 等第一版页面。

2. 项目开发注意事项

前端只调用本项目后端接口，不直接调用 SuperAgent、AgentBus、OPERA、OHIP 或数据库。
API 调用应统一放在前端 src/services，页面组件不要直接拼接后端 URL。
业务判断必须使用后端返回的稳定 code，不使用中文或英文展示文案做判断。
后端返回的时间点字段统一是带 Z 的 ISO 8601 UTC 时间，例如 created_at、updated_at、received_at、last_updated_at；前端展示时再按用户或酒店时区格式化。
入住日期、离店日期、酒店营业日属于酒店本地业务日期，不要按 UTC 时间点自动换算日期。
前端不得保存或传递后端 Secret、replay access key、Provider API Key、Oracle 凭证、AgentBus Token。
后端数据库 ID 未来应尽量以字符串形式给前端，避免 JavaScript 长整型精度问题；如果当前接口仍返回数字，前端不要自行做数学运算。
接口字段发生变化前，需要先更新本目录沟通文档或对应需求文档。

3. 字段来源注意事项

docs/import/20260708/任务卡前端展示字段表 3.0.xlsx 是前端展示 / 编辑白名单。
docs/import/20260706/任务卡展示编辑矩阵.xlsx 是后端校验、最终确认写入、OPERA 映射和展示条件的完整规则来源。
前端不要直接把整个 ai_task_results[] 渲染成表单，只展示白名单允许的字段。
如果 3.0 白名单与旧矩阵冲突，应记录为前后端待确认问题，不由前端单方面放宽必填、枚举或校验规则。

4. 业务规则注意事项

任务详情页里，保存草稿和最终确认是两个独立动作，不能合并。
用户可以修改任务字段内容；最终确认后，后端使用 confirmed_payload_json 作为 OPERA 模拟输入来源。
同一订单下，前置任务未结束时，后续任务只能查看，不能编辑、确认或执行 OPERA 模拟操作。
任务状态 FAILED 第一版视为结束状态，不阻塞后续任务；但失败的 OPERA 操作不能跳过，必须展示失败原因并允许重试。
Message Notification 挂临时订单，只读展示，不参与订单任务执行队列，不阻塞其他任务，也不被其他任务阻塞。
Fallback / manual_review 转为 New / Update / Cancel 时需要展示审计轨迹；当前 actor 仍是本地占位，正式用户身份后置。
普通任务切换订单接口已确认后置，前端第一版不要把普通任务拖拽或切换订单做成可提交能力。

5. 当前前端可用接口注意事项

接口	用途	前端注意
`GET /api/reservation/orders`	查询订单列表	默认返回全部订单状态；`open_task_count` 排除 `COMPLETED` 和 `FAILED`；用 `next_processable_task_id` 引导用户继续处理。
`GET /api/reservation/tasks`	查询任务列表 / 工作台	用 `can_process` 和 `readonly_reason_code` 控制入口按钮；列表不返回 AI 原始 payload、邮件正文或附件 URL；已返回来源邮件会话摘要字段，并支持 `order_status` 按任务所属订单状态筛选。
`GET /api/reservation/orders/{orderId}`	查询订单详情与任务时间线	`include_tasks=false` 可只取订单摘要；时间线按后端队列顺序返回，前端不要自行按创建时间重排；`tasks[]` 已返回来源邮件会话摘要字段。
`GET /api/reservation/tasks/{taskId}`	查询任务详情	以返回的可处理状态和只读原因控制按钮，不只看任务状态；`fields[]` 已包含 P0 字段元数据。
`PUT /api/reservation/tasks/{taskId}/draft`	保存任务草稿	只保存草稿，不代表用户最终确认。
`POST /api/reservation/tasks/{taskId}/confirm`	最终确认任务	后端会做第一版字段校验，通过后进入 `READY`。
`POST /api/reservation/tasks/{taskId}/manual-review-conversions`	Fallback 人工转换	只用于 manual_review / fallback，不用于普通任务切换订单。
`POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/execute`	执行 OPERA 模拟操作	当前是模拟，不调用真实 OPERA。
`POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/retry`	重试失败 OPERA 模拟操作	重试会追加 attempt 历史，前端不要覆盖旧失败记录。
`GET /api/reservation/tasks/{taskId}/audits`	查询任务审计流水	用于展示人工确认、转换、模拟操作等轨迹。
`GET /api/source-messages`	查询来源消息安全摘要	列表不返回邮件正文、HTML、附件 URL 或原始 payload。
`GET /api/source-messages/{id}`	查询来源消息安全详情	只用于安全摘要详情。
`GET /api/source-messages/{id}/original`	读取来源消息原文	需要受控访问头，返回 HTML 时前端展示前必须 sanitize。
`GET /api/source-messages/{sourceMessageId}/conversation`	读取邮件会话详情	返回同一外部会话全部邮件的完整 text/html、`html_body_sanitized`、附件外链、内联图片和关联订单 / 任务摘要；前端不传原文读取 key，展示 HTML 时优先使用 `html_body_sanitized`。

5.1 本轮新增 / 修改接口说明

本轮后端新增或补齐了以下前端 P0 查询能力。前端后续开发时，应优先以本节作为接入口径。

接口	本轮变化	前端接入注意
`GET /api/reservation/orders`	新增订单列表接口。	`order_status` 不传时默认查询全部订单状态；`page_num` 从 1 开始；`page_size` 后端有最大值保护；`open_task_count` 排除 `COMPLETED` 和 `FAILED`；`next_processable_task_id` 为空表示当前没有可继续处理的任务。
`GET /api/reservation/tasks`	补齐来源邮件会话摘要字段，并新增 `order_status` 查询参数。	`order_status` 按任务所属订单状态过滤，支持 `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`；列表仍然只返回安全摘要，不返回正文、HTML、附件 URL 或 AI 原始 payload；点击邮件入口时使用 `source_message_id` 调会话详情。
`GET /api/reservation/orders/{orderId}`	补齐 `tasks[]` 每条任务的来源邮件会话摘要字段。	`include_tasks=false` 可只取订单摘要；时间线顺序由后端按订单队列返回，前端不要自行按创建时间重排。`include_source_summary` 第一版不作为前端裁剪字段的强约束，前端暂不要依赖它减少返回字段。
`GET /api/reservation/tasks/{taskId}`	补齐顶层来源邮件字段，并扩展 `fields[]` 元数据。	顶层来源字段用于打开邮件会话；`fields[]` 中的 `result_type`、`task_type`、`task_subtype`、`default_value_source` 用于前端字段分组、调试和白名单对齐。
`GET /api/source-messages/{sourceMessageId}/conversation`	新增邮件会话详情接口，并补齐 `html_body_sanitized` / `html_render_mode`。	当前唯一推荐路径是这个接口；前端渲染邮件 HTML 时优先使用 `html_body_sanitized`；不要调用历史讨论过的 `/api/source-message-conversations/{externalConversationId}`。

5.2 来源邮件会话字段说明

任务列表、订单详情任务时间线、任务详情顶层会返回以下来源邮件字段：

字段	说明	前端使用方式
`source_message_id`	本系统内部 SourceMessage Inbox ID。	打开邮件会话详情时作为路径参数传入 `/api/source-messages/{sourceMessageId}/conversation`。
`source_subject`	来源邮件主题安全摘要。	用于列表或任务详情标题旁展示，不代表完整邮件主题一定无敏感信息。
`source_sender_summary`	来源发件人安全摘要。	用于辅助用户判断邮件来源。
`source_received_at`	本系统接收来源消息时间，UTC。	前端展示时按用户或酒店时区格式化。
`external_conversation_id`	外部邮件会话 ID。	仅用于展示或调试，不作为当前会话详情接口路径参数。
`conversation_message_count`	同一外部会话下的邮件数量。	用于提示用户打开的是整段会话，不是单封邮件。

5.3 邮件会话详情接入注意

GET /api/source-messages/{sourceMessageId}/conversation 只接收路径参数 sourceMessageId；第一版不接收 hotelId、includeBody、includeRelated。
前端当前通过 VITE_RESERVATION_HOTEL_ID 统一配置 Reservation 默认酒店上下文，并会在订单列表、任务列表和订单详情查询中传 hotel_id；任务详情、任务写操作和邮件会话详情当前后端接口不接收该参数。
后端会根据 sourceMessageId 定位 external_conversation_id，并返回同一会话下全部邮件；如果来源消息没有外部会话 ID，会降级返回当前单封邮件。
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。
会话详情接口由后端内部写原文读取审计，前端不传 X-TH-Hotel-Source-Original-Read-Key。
会话详情外层字段主要是 snake_case，但媒体对象沿用原文读取接口字段，当前是 mediaType、fileName、contentType、sizeBytes、externalUrl、externalMediaId 这种 camelCase，前端类型定义需要单独处理。

5.4 订单列表接入注意

GET /api/reservation/orders 默认返回全部订单状态，包括 TEMPORARY、ACTIVE、ENDED、LOGIC_DELETED。
keyword 会匹配订单业务号、临时订单号、展示名、订单状态，也会匹配来源消息安全摘要命中的 SourceMessage ID；前端可以用邮件主题、外部消息 ID 或会话 ID 辅助查订单。
open_task_count 只统计未关闭任务，排除 COMPLETED 和 FAILED。
next_processable_task_id 是后端按同订单队列实时计算出的下一条可处理任务；前端可以用它做“继续处理”入口。
display_order_key 是前端优先展示的订单业务号或临时订单号；group_code 和 confirmation_number 只有在当前订单业务号类型匹配时返回。
订单 ID、任务 ID、SourceMessage ID 在这些前端接口中按字符串返回，前端不要转换成 JavaScript number。

5.5 前端联调演示数据 seed 接口

后端提供一个受控的 dev/test 演示数据入口，方便前端在空库或本地环境快速看到页面效果。

POST /api/system/reservation/demo-data
Header: X-TH-Hotel-Demo-Data-Key: <本地演示数据访问口令>
Content-Type: application/json

{
  "hotel_id": "HOTEL-TEST",
  "run_label": "frontend-smoke"
}

启用方式：

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 联调，不允许放进生产普通页面，也不要把访问口令写进前端仓库、浏览器环境变量或构建产物。

返回内容：

demo_run_id：本次 seed 的唯一关键词，可用于任务列表 / 订单列表搜索。
source_messages[]：本次生成的 SourceMessage ID、外部消息 ID 和会话 ID。
orders[]：本次生成的订单 ID、订单状态和展示键。
tasks[]：本次生成的任务 ID、任务类型、任务 subtype 和任务状态。
entrypoints：可直接访问的后端查询入口，包括任务列表、订单列表、队列订单详情、失败任务详情和邮件会话详情。

当前 seed 覆盖的页面效果：

同订单前置任务未完成，后续任务只读不可处理。
已完成 New Booking 任务和两条 OPERA 模拟成功记录。
OPERA 模拟失败任务，可在任务详情看到失败 attempt 和重试入口。
Fallback / manual_review 任务。
Message Notification 只读任务。
同一邮件会话下多封邮件、完整 HTML、附件外链和内联图片外链。

5.6 任务详情字段元数据接入注意

fields[] 第一版服务于任务详情动态展示，字段来源与白名单规则以 docs/import/20260708/任务卡前端展示字段表 3.0.xlsx 为准。
result_type、task_type、task_subtype、default_value_source 已透出给前端，用于和最新前端白名单对齐。
后端校验、最终确认写入、OPERA 映射和展示条件仍以 docs/import/20260706/任务卡展示编辑矩阵.xlsx 为完整规则来源。
前端保存草稿时不要自行按 write_path 重组 OPERA 参数；第一版按任务详情返回的字段和值提交即可，真实 OPERA 参数组装后续由后端 adapter / 转换层处理。
任务详情页控制按钮时以 availability.editable、availability.confirmable、availability.executable、availability.read_only 和 availability.blocked 为准；can_process 和 readonly_reason_code 只出现在任务列表 / 订单时间线摘要里。

6. 不给前端直接调用的接口

POST /api/system/reservation/demo-data 只用于 dev/test 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。
POST /api/integrations/superagent/task-results 是 SuperAgent 到后端的服务到服务入站接口。
POST /api/ai-query/v1/case-context 和 POST /api/ai-query/v1/object-detail 是 SuperAgent 查询上下文接口，不是前端页面接口。
GET /api/source-message-conversations/{externalConversationId} 是历史讨论过的候选路径，当前后端不提供，前端不要接入。
AgentBus probe、fixture、replay、system 类接口不应放到普通业务前端页面。

7. 需要持续提醒的后置事项

SuperAgent 查询接口 3 文件解析当前不能做。
SuperAgent 查询接口 4 已确认继续后置。
普通任务切换订单接口继续后置。
用户 / 权限方案继续后置。
真实 OPERA / OHIP 接入继续后置。

15 KiB Raw Blame History Unescape Escape