huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8a196f14ed7a7c3691225eed2a5de95b86fbef36
th-hotel-simple/docs/project/frontend-backend/frontend-to-backend-api-requests.md
andy 936a5921b0 实现前端P0订单任务查询接口
2026-07-08 14:18:57 +08:00

7.9 KiB
Raw Blame History

前端提醒后端待补接口

1. 文档定位

本文记录前端页面开发时希望后端新增、补齐或稳定的接口草案。本文中的路径、入参和返参是前端视角的最小诉求，不代表后端已经承诺实现；进入开发前需要后端按当前包结构、权限、安全和业务规则二次确认。

2. 当前待补接口总览

优先级 接口 页面 / 场景 状态
P0 任务列表 / 工作台接口 任务列表页、首页工作台 已实现第一版
P0 订单详情与任务时间线接口 订单详情页 已实现第一版
P1 订单列表接口 订单检索、订单入口 待后端设计
P1 Message Notification 列表 / 详情接口 信息提醒页或订单详情只读卡片 待后端设计
P1 任务卡前端字段白名单元数据接口 任务详情动态渲染 待确认是否需要后端提供
后置 普通任务切换订单接口 任务详情订单归属调整 已确认后置

3. 任务列表 / 工作台接口

建议路径：

GET /api/reservation/tasks

当前状态：后端已按 P0 最小诉求实现第一版。接口只返回任务摘要、订单展示键、来源消息主题和实时可处理状态，不返回完整 AI payload、邮件正文或附件 URL。

建议入参：

参数 必填 说明
hotel_id 否 酒店 ID。第一版如果只有单酒店，可为空。
order_id 否 按订单过滤。
task_type 否 NEW_BOOKING、UPDATE_BOOKING、CANCEL_BOOKING、MANUAL_REVIEW、INFORMATIONAL_MESSAGE。
task_status 否 任务状态过滤。
task_subtype 否 任务卡 subtype 过滤。
queue_participation 否 是否参与订单执行队列。
keyword 否 Group Code、Confirmation No、临时订单号、来源消息安全摘要关键词。
page_num 否 页码，建议从 1 开始。
page_size 否 每页条数。

建议返参：

{
  "items": [
    {
      "task_id": "10001",
      "order_id": "20001",
      "hotel_id": "HOTEL-TEST",
      "display_order_key": "GRP-001",
      "temporary_order_no": "TMP-20260708-001",
      "task_type": "UPDATE_BOOKING",
      "task_subtype": "RATE_CHANGE",
      "task_status": "PENDING_CONFIRM",
      "card_name": "Rate Change",
      "queue_sequence": 2,
      "queue_participation": true,
      "can_process": false,
      "readonly_reason_code": "PREVIOUS_TASK_NOT_FINISHED",
      "source_message_id": "30001",
      "source_subject": "Booking Update",
      "created_at": "2026-07-08T03:00:00Z",
      "updated_at": "2026-07-08T03:10:00Z"
    }
  ],
  "page": {
    "page_num": 1,
    "page_size": 20,
    "total": 1
  }
}

4. 订单详情与任务时间线接口

建议路径：

GET /api/reservation/orders/{orderId}

当前状态：后端已按 P0 最小诉求实现第一版。接口返回订单摘要和同订单任务时间线；include_tasks=false 时只返回订单摘要。include_source_summary 第一版保留入参但订单时间线暂不展开来源摘要，来源主题请优先从任务列表接口读取。

建议入参：

参数 必填 说明
orderId 是 订单 ID。
include_tasks 否 是否返回任务时间线，默认 true。
include_source_summary 否 是否返回来源消息摘要，默认 true。

建议返参：

{
  "order": {
    "order_id": "20001",
    "hotel_id": "HOTEL-TEST",
    "order_status": "ACTIVE",
    "temporary_order_no": "TMP-20260708-001",
    "confirmation_number": "CNF123456",
    "group_code": "GRP-001",
    "block_code": null,
    "allotment_code": null,
    "display_name": "GRP-001",
    "created_at": "2026-07-08T03:00:00Z",
    "updated_at": "2026-07-08T03:10:00Z"
  },
  "tasks": [
    {
      "task_id": "10001",
      "task_type": "NEW_BOOKING",
      "task_subtype": "NEW_BOOKING",
      "task_status": "COMPLETED",
      "card_name": "New Booking",
      "queue_sequence": 1,
      "queue_participation": true,
      "can_process": false,
      "readonly_reason_code": "TASK_FINISHED",
      "created_at": "2026-07-08T03:00:00Z"
    }
  ],
  "warnings": []
}

5. 订单列表接口

建议路径：

GET /api/reservation/orders

建议入参：

参数 必填 说明
hotel_id 否 酒店 ID。
order_status 否 TEMPORARY、ACTIVE、ENDED、LOGIC_DELETED。
group_code 否 按 Group Code 精确或模糊查询，后端决定。
confirmation_number 否 按 Confirmation No 查询。
keyword 否 前端搜索框统一关键词。
page_num 否 页码。
page_size 否 每页条数。

建议返参：

{
  "items": [
    {
      "order_id": "20001",
      "hotel_id": "HOTEL-TEST",
      "order_status": "ACTIVE",
      "temporary_order_no": null,
      "confirmation_number": "CNF123456",
      "group_code": "GRP-001",
      "display_name": "GRP-001",
      "open_task_count": 2,
      "next_processable_task_id": "10002",
      "updated_at": "2026-07-08T03:10:00Z"
    }
  ],
  "page": {
    "page_num": 1,
    "page_size": 20,
    "total": 1
  }
}

6. Message Notification 列表 / 详情接口

建议路径：

GET /api/reservation/message-notifications
GET /api/reservation/message-notifications/{taskId}

列表建议入参：

参数 必填 说明
hotel_id 否 酒店 ID。
order_id 否 按临时订单或真实订单过滤。
keyword 否 邮件主题、摘要、发送人关键词。
page_num 否 页码。
page_size 否 每页条数。

详情建议返参：

{
  "task_id": "10009",
  "order_id": "20009",
  "task_type": "INFORMATIONAL_MESSAGE",
  "task_status": "COMPLETED",
  "queue_participation": false,
  "readonly": true,
  "visible_reason": "FYI message without booking operation",
  "relevant_message_excerpt": "Noted with thanks.",
  "informational_message": "该消息仅作信息提醒，不需要执行 OPERA 操作。",
  "attachments": [],
  "source_message_id": "30009",
  "created_at": "2026-07-08T03:00:00Z"
}

7. 任务卡前端字段白名单元数据接口

是否需要该接口待确认。如果前端直接读取或内置 docs/import/20260708/任务卡前端展示字段表 3.0.xlsx 转换后的配置，则第一版可以不做。

建议路径：

GET /api/reservation/task-card-field-whitelist

建议入参：

参数 必填 说明
task_type 否 按系统主任务类型过滤。
task_subtype 否 按任务卡 subtype 过滤。
version 否 字段白名单版本，例如 20260708-3.0。

建议返参：

{
  "version": "20260708-3.0",
  "items": [
    {
      "task_type": "UPDATE_BOOKING",
      "task_subtype": "RATE_CHANGE",
      "field_path": "rate.rate_code",
      "display_name": "Rate Code",
      "visible": true,
      "editable": true,
      "input_type": "select",
      "options": []
    }
  ]
}

8. 已确认后置接口

普通任务切换订单接口继续后置，前端暂不开发提交能力。后续如果恢复开发，建议另行确认：

POST /api/reservation/tasks/{taskId}/order-binding

待确认入参：

{
  "target_order_id": "20002",
  "reason": "人工确认该任务属于另一个订单"
}

待确认返参：

{
  "task_id": "10001",
  "previous_order_id": "20001",
  "target_order_id": "20002",
  "task_status": "PENDING_CONFIRM",
  "audit_id": "90001"
}

9. 待确认问题

  • 任务列表和订单列表是否统一使用同一个分页结构。
  • 前端字段白名单由后端接口提供，还是由前端从 Excel 转成静态配置。
  • Message Notification 是否独立成页面，还是只在订单详情中展示。
  • SourceMessage 原文读取在前端页面中的入口和权限方案仍待用户 / 权限体系确认。