实现前端P0订单任务查询接口
This commit is contained in:
andy
@@ -0,0 +1,284 @@
|
||||
# 前端提醒后端待补接口
|
||||
|
||||
## 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 原文读取在前端页面中的入口和权限方案仍待用户 / 权限体系确认。
|
||||
Reference in New Issue
Block a user