65 lines
5.4 KiB
Markdown
65 lines
5.4 KiB
Markdown
# 后端提醒前端注意事项
|
||
|
||
## 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/tasks` | 查询任务列表 / 工作台 | 用 `can_process` 和 `readonly_reason_code` 控制入口按钮；列表不返回 AI 原始 payload、邮件正文或附件 URL。 |
|
||
| `GET /api/reservation/orders/{orderId}` | 查询订单详情与任务时间线 | `include_tasks=false` 可只取订单摘要；时间线按后端队列顺序返回，前端不要自行按创建时间重排。 |
|
||
| `GET /api/reservation/tasks/{taskId}` | 查询任务详情 | 以返回的可处理状态和只读原因控制按钮，不只看任务状态。 |
|
||
| `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。 |
|
||
|
||
## 6. 不给前端直接调用的接口
|
||
|
||
- `POST /api/integrations/superagent/task-results` 是 SuperAgent 到后端的服务到服务入站接口。
|
||
- `POST /api/ai-query/v1/case-context` 和 `POST /api/ai-query/v1/object-detail` 是 SuperAgent 查询上下文接口，不是前端页面接口。
|
||
- AgentBus probe、fixture、replay、system 类接口不应放到普通业务前端页面。
|
||
|
||
## 7. 需要持续提醒的后置事项
|
||
|
||
- SuperAgent 查询接口 3 文件解析当前不能做。
|
||
- SuperAgent 查询接口 4 已确认继续后置。
|
||
- 普通任务切换订单接口继续后置。
|
||
- 用户 / 权限方案继续后置。
|
||
- 真实 OPERA / OHIP 接入继续后置。
|