# 前后端协作入口

## 1. 文档定位

本文用于后端 agent、前端 agent 和测试在开发任务详情、订单详情、任务列表、Message Notification 等页面时统一查找接口契约、字段来源和当前后置事项。

如本文与 `AGENTS.md`、`docs/project/requirements/` 中的业务需求冲突，以 `AGENTS.md` 和对应需求文档为准。

## 2. 沟通文件

| 文件 | 用途 |
| --- | --- |
| `backend-to-frontend-notes.md` | 后端提醒前端的注意事项，包含项目开发、业务规则、接口使用和安全边界。 |
| `frontend-to-backend-api-requests.md` | 前端提醒后端需要增加或补齐的接口，包含建议入参和返参草案。 |

## 3. 当前字段来源分工

| 来源 | 当前用途 |
| --- | --- |
| `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` | 前端任务卡展示 / 编辑白名单。前端页面优先按该表决定哪些字段展示、哪些字段可编辑。 |
| `docs/import/20260706/任务卡展示编辑矩阵.xlsx` | 后端完整规则来源。用于后端校验、最终确认写入、OPERA 映射、展示条件和任务卡完整约束。 |
| `docs/import/20260706/AI输出参数并集字典.xlsx` | AI 输出字段路径、字段含义、建议存储方式和索引参考。 |

约束说明：

- 最新前端 Excel 只作为展示 / 编辑白名单，不替代后端完整规则矩阵。
- 后端不应因为前端白名单缺少字段而自动放宽必填、枚举、校验或 OPERA 映射规则。
- 如果前端白名单与后端完整矩阵冲突，应先记录到 `frontend-to-backend-api-requests.md` 的待确认问题，再由产品 / 后端 / 前端一起确认。

## 4. 当前接口契约来源

| 契约 | 文档 |
| --- | --- |
| SuperAgent 任务结果入站接口 | `docs/project/requirements/M002-superagent-task-result-api-contract.md` |
| SuperAgent 查询上下文接口 1、2 | `docs/project/requirements/M002-ai-query-minimal-fields.md` |
| SuperAgent 对接总契约 | `docs/project/integrations/superagent-api-contract.md` |
| 订单任务主流程 | `docs/project/requirements/M002-order-task-workflow-v2.md` |
| 后端 checkpoint | `docs/project/requirements/M002-backend-checkpoint-plan.md` |

## 5. 当前已明确后置事项

- 普通任务切换订单接口后置。
- 任务列表按订单状态 `order_status` 筛选待后端补充或确认。
- 任务详情 / 任务写操作是否需要显式 `hotel_id` 待后端确认；前端已先统一配置 `VITE_RESERVATION_HOTEL_ID` 并用于列表和订单详情查询。
- 邮件 `html_body` 已标记为需要 sanitize：前端联调阶段临时直渲只用于本地看效果，生产前请后端返回已清洗 HTML 或明确清洗字段，并确认 CSP / 外链图片 / 附件 URL 策略。
- SuperAgent 查询接口 4 后置，当前先不开发。
- SuperAgent 查询接口 3 涉及附件解析、OCR、Excel、voucher、rooming list 等能力，当前系统暂不具备，仍后置。
- 用户身份 / 权限方案后置；当前后端审计 actor 仍是本地占位。
- 真实 OPERA / OHIP 接入后置；当前仅有 OPERA 模拟骨架。

## 6. 前端开发注意事项

- 前端不得直接调用 SuperAgent、AgentBus、OPERA、OHIP 或数据库。
- 前端不得发送后端 Secret、replay access key、Provider API Key 或 Oracle 凭证。
- 页面展示文案可以本地化，但业务判断必须使用接口返回的稳定 code。
- 任务详情页保存草稿和最终确认是两个接口，不能合并成一个前端动作。
- 同一订单下，如果前置任务未结束，后续任务只能查看，不能编辑、确认或执行 OPERA 模拟操作。