th-hotel-simple/docs/project/frontend-backend/frontend-to-backend-api-requests.md

# 前端提醒后端待补接口

## 1. 文档定位

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

## 2. 当前待补接口总览

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

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

建议路径：

```text
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` | 否 | 每页条数。 |

建议返参：

```json
{
  "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. 订单详情与任务时间线接口

建议路径：

```text
GET /api/reservation/orders/{orderId}
```

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

建议入参：

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

建议返参：

```json
{
  "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. 订单列表接口

建议路径：

```text
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` | 否 | 每页条数。 |

建议返参：

```json
{
  "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 列表 / 详情接口

建议路径：

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

列表建议入参：

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

详情建议返参：

```json
{
  "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` 转换后的配置，则第一版可以不做。

建议路径：

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

建议入参：

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

建议返参：

```json
{
  "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. 已确认后置接口

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

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

待确认入参：

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

待确认返参：

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

## 9. 待确认问题

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