huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1046e4ef748084b532f111af591c21e807fdb435
th-hotel-simple/docs/project/frontend-backend/README.md
andy 1046e4ef74 整理项目文档索引和规范说明
2026-07-10 23:49:49 +08:00

4.5 KiB
Raw Blame History

前后端协作入口

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 时间、酒店时区展示和本地日期筛选规则。

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 HTTP 对外总契约 docs/project/integrations/superagent-api-contract.md 权威契约，包含查询上下文、对象详情、邮件会话任务、邮件会话正文、任务结果通知和统一 HMAC 规则。
SuperAgent MCP tools docs/project/integrations/superagent-mcp/README.md MCP 对外交付资料包，tools 字段语义应跟随 SuperAgent HTTP 对外总契约。
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 的最小字段实现；如与总契约冲突，以总契约为准。
订单任务主流程 docs/project/requirements/M002-order-task-workflow-v2.md 当前有效需求，M002 V1 只作为历史参考。
后端 checkpoint docs/project/requirements/M002-backend-checkpoint-plan.md 阶段记录，用于理解后端拆分和验收。
前端可用接口与待补接口 docs/project/frontend-backend/frontend-to-backend-api-requests.md 前后端协作清单，已区分可用、后置和历史候选路径，不替代后端权威契约。

5. 当前已明确后置事项

  • 普通任务切换订单接口后置。
  • 任务详情 / 任务写操作是否需要显式 hotel_id 已确认后置；第一版先按 ID 定位，后续多酒店隔离 / 权限方案统一补齐。
  • 邮件会话详情已返回 html_body_sanitized 和 html_render_mode；前端展示 HTML 时优先使用清洗字段，html_body 只作为原始内容兼容字段。
  • 用户 / 权限底座后端 CP1 已完成；前端登录页、动态菜单、管理后台和业务审计 actor 全量迁移仍后置。
  • 真实 OPERA / OHIP 接入后置；当前仅有 OPERA 模拟骨架。

6. 前端开发注意事项

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