前后端协作入口
1. 文档定位
本文用于后端 agent、前端 agent 和测试在开发任务详情、订单详情、任务列表、Message Notification 等页面时统一查找接口契约、字段来源和当前后置事项。
如本文与 AGENTS.md、docs/project/requirements/ 中的业务需求冲突，以 AGENTS.md 和对应需求文档为准。
2. 沟通文件
| 文件 | 用途 |
|---|---|
backend-to-frontend-notes.md |
后端提醒前端的注意事项，包含项目开发、业务规则、接口使用和安全边界。 |
frontend-to-backend-api-requests.md |
前端提醒后端需要增加或补齐的接口，包含建议入参和返参草案。 |
debug-eml-page-integration-guide.md |
Debug EML 页面前端对接指南，包含页面结构、上传接口、响应展示、错误处理和安全注意事项。 |
../backend-time-design.md |
时间设计说明，包含数据库 UTC、API Z 时间、酒店时区展示和本地日期筛选规则。 |
../security-access-control-boundary.md |
接口暴露、权限和审计边界总表，前端判断普通业务、系统管理、Debug 和第三方接口边界时必须参考。 |
3. 当前字段来源分工
| 来源 | 当前用途 |
|---|---|
docs/import/20260711/开发交付_P0冻结基线_2026-07-11/01_Adapter_Frontend/任务卡前端字段变更与路由说明_3.0_to_current.md |
0711 P0 前端 / Adapter 路由说明。Parent split / 42 路由部分已被 0712 P0.1 覆盖；前端后续按 40 路由、S10/S99、type-known manual review 和 fail-closed 口径调整页面。 |
docs/import/20260711/开发交付_P0冻结基线_2026-07-11/01_Adapter_Frontend/任务卡前端字段变更说明_3.0_to_当前版_2026-07-10.xlsx |
最新前端任务卡展示 / 编辑白名单和三元组路由表。文件名保留 7 月 10 日，内部基线为 7 月 11 日。 |
docs/import/20260712/前端字段控件修改说明_给信息系统小伙伴Codex_2026-07-12.md |
字段控件、人工复核编辑和只读证据输入资料；当前项目落地口径以 requirements/M002-task-field-control-contract-v1.md 为准。 |
docs/project/requirements/M002-task-field-control-contract-v1.md |
任务详情 fields[] 控件契约 V1，后续后端先扩展控件元数据，前端再按契约渲染字段和同卡复核输入。 |
docs/import/20260708/任务卡前端展示字段表 3.0.xlsx |
历史前端字段白名单，已被 0711 P0 冻结基线承接。 |
docs/import/20260706/任务卡展示编辑矩阵.xlsx |
后端完整规则来源。用于后端校验、最终确认写入、OPERA 映射、展示条件和任务卡完整约束。 |
docs/import/20260706/AI输出参数并集字典.xlsx |
AI 输出字段路径、字段含义、建议存储方式和索引参考。 |
约束说明：
- 最新前端 Excel 和 0711 路由说明只作为展示 / 编辑白名单、P0 路由和前后端验收基线，不替代后端完整规则矩阵。
- 后端不应因为前端白名单缺少字段而自动放宽必填、枚举、校验或 OPERA 映射规则。
- 如果前端白名单与后端完整矩阵冲突，应先记录到
frontend-to-backend-api-requests.md的待确认问题，再由产品 / 后端 / 前端一起确认。
4. 当前接口契约来源
| 契约 | 当前文档 | 中文说明 |
|---|---|---|
| SuperAgent HTTP 对外总契约 | docs/project/integrations/superagent-api-contract.md |
权威契约，包含查询上下文、对象详情、邮件会话任务、邮件会话正文、任务结果通知和统一 HMAC 规则。 |
| SuperAgent MCP tools | docs/project/integrations/superagent-mcp/README.md |
MCP 对外交付资料包，tools 字段语义应跟随 SuperAgent HTTP 对外总契约。 |
| 接口暴露、权限和审计边界 | docs/project/security-access-control-boundary.md |
前端判断普通业务、系统管理、Debug、第三方接口、权限码和敏感数据边界的总表。 |
| SuperAgent 任务结果入站接口 | docs/project/requirements/M002-superagent-task-result-api-contract.md |
阶段记录，用于理解 M002 接收 AI 结果的落地细节；如与总契约冲突，以总契约为准。 |
| SuperAgent 查询上下文接口 1、2 | docs/project/requirements/M002-ai-query-minimal-fields.md |
阶段记录，用于理解接口 1、2 的最小字段实现；如与总契约冲突，以总契约为准。 |
| 订单任务主流程 V3 | docs/project/requirements/M002-order-task-workflow-v3.md |
当前开发基线，基于 0711 P0 冻结基线和 0712 P0.1 Parent Group 修订，覆盖 S10/S99、40 路由、方案 C、type-known manual review 同卡解阻和 fail-closed。 |
| 任务卡字段控件契约 V1 | docs/project/requirements/M002-task-field-control-contract-v1.md |
后端已返回 fields[] 控件元数据，规定人工复核控件复用和前后端边界；前端待接入。 |
| 订单任务多卡模型 V4 | docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md |
当前 V4 主入口；后端已开放工作台统一列表、V4 订单任务列表 / 详情、卡片确认、复核解阻、S10/S99 来源通知详情和 ack；前端已完成 V4 页面第一版、目录 lookup 接入、订单详情 V4 时间线消费和系统设置目录管理 CP1。 |
| Manual Invoice 手工开票生成 | docs/project/requirements/M009-manual-invoice-generation-v1.md |
当前有效；后端 CP2 已支持无订单 / 无任务手工填写字段、填 Excel 模板、转 PDF、OSS 输出和生成记录。 |
| Rooming List Excel 生成 | docs/project/requirements/M010-rooming-list-excel-generation-v1.md |
当前有效；后端 CP1 已支持前端上传来源名单并填写目标字段，同步生成 .xlsx 直接下载；前端 V1 已新增 /reservation/rooming-lists/new，按 Blob 下载处理，不落库、不上传 OSS。 |
| Booking Excel 附件预处理 | docs/project/requirements/M011-booking-excel-pre-superagent-enrichment-v1.md |
当前有效；Debug EML 和 AgentBus dispatch 已支持调 SuperAgent 前排除人员名单类 Excel、抽取 Booking / 附加费类 Excel 高亮行并生成 attachment_extractions[]；生产 AgentBus 增强默认关闭。 |
| 订单任务主流程 V2 | docs/project/requirements/M002-order-task-workflow-v2.md |
已实现阶段记录，保留用于理解当前代码中的 S000/S999、订单任务流转和 OPERA 模拟骨架。 |
| 后端 checkpoint | docs/project/requirements/M002-backend-checkpoint-plan.md |
阶段记录，用于理解后端拆分和验收。 |
| 前端可用接口与待补接口 | docs/project/frontend-backend/frontend-to-backend-api-requests.md |
前后端协作清单，已区分可用、后置和历史候选路径，不替代后端权威契约。 |
5. 当前已明确后置事项
- 普通任务切换订单接口后置。
- M002 V3 已确认采用 0711 P0：新数据迁移到结构化
S10/S99；旧S000/S999继续在任务列表可见；后端已完成 P0 fixtures 回归基线。 - type-known manual review 已按同一张业务卡解阻，不再统一做成 Fallback；复核场景第一版支持确认当前订单归属，但普通任务任意切换订单仍后置。
- 任务详情 / 任务写操作是否需要显式
hotel_id已确认后置；第一版先按 ID 定位，后续多酒店隔离 / 权限方案统一补齐。 - 邮件会话详情已返回
html_body_sanitized和html_render_mode；前端展示 HTML 时优先使用清洗字段，html_body只作为原始内容兼容字段。 - 用户 / 权限底座后端 CP1 已完成；前端登录页、动态菜单、管理后台和业务审计 actor 全量迁移仍后置。
- 真实 OPERA / OHIP 接入后置；当前仅有 OPERA 模拟骨架。
- 任务卡字段控件契约 V1 后端第一版已完成，任务详情
fields[]已返回control_type/edit_scope/write_target/options_source/raw_readonly/control_hint；前端后续按契约接入，不要硬编码 PMS 房型、Rate Code 或未冻结枚举。 - Manual Invoice 第一阶段按 M009 推进：后端已提供
POST /api/reservation/invoices/manual-generations，前端已新增/reservation/invoices/new手工开票页面，并已按invoice.html原型的三段式业务结构对齐；页面可以不依赖订单或任务，用户手工填写 / 选择字段后由后端业务接口填充 Excel 模板并生成 PDF；前端不得直接调用 M008 的调试上传转换接口来完成业务开票。侧边栏入口仍以登录后端返回的 menus 为准，建议后续在菜单管理中配置RESERVATION_MANUAL_INVOICE//reservation/invoices/new/RESERVATION_INVOICE_GENERATE。 - Rooming List Excel 后端 CP1 和前端 V1 已按 M010 落地：接口为
POST /api/reservation/rooming-lists/generations，前端页面为/reservation/rooming-lists/new，上传来源名单、填写每房人数和目标列字段，后端同步返回.xlsx下载；该能力不依赖订单或任务，第一版不落库、不上传 OSS，权限码为RESERVATION_ROOMING_LIST_GENERATE。 - Booking Excel 附件预处理已按 M011 落地 CP1/CP2/CP3：Debug EML 和 AgentBus dispatch 调用 SuperAgent 前由后端解析 Excel 附件，排除人员名单类文件，只把 Booking Update / 附加费表的高亮行业务摘要追加为
attachment_extractions[]；第一版不新增前端普通业务入口，AgentBus 增强生产默认关闭。 - Reservation V4 目录管理后台 CP1 已前后端接入：系统设置下新增
/system/reservation-catalogs，需要登录用户具备RESERVATION_CATALOG_MANAGE；前端可维护 Account、Room Type、Rate Code 的列表、新增、启用 / 停用，并明确提示停用目录不再进入普通 V4 任务卡 lookup。
6. 前端开发注意事项
- 前端不得直接调用 SuperAgent、AgentBus、OPERA、OHIP 或数据库。
- 前端不得发送后端 Secret、replay access key、Provider API Key 或 Oracle 凭证。
- 页面展示文案可以本地化，但业务判断必须使用接口返回的稳定 code。
- 任务详情页保存草稿和最终确认是两个接口，不能合并成一个前端动作。
- 同一订单下，如果前置任务未结束，后续任务只能查看，不能编辑、确认或执行 OPERA 模拟操作。