5.0 KiB
5.0 KiB
后端提醒前端注意事项
1. 文档定位
本文记录后端侧提醒前端开发时必须注意的项目规范、业务规则、接口边界和安全要求。当前内容服务于 Reservation 任务详情、订单详情、任务列表、Message Notification 等第一版页面。
2. 项目开发注意事项
- 前端只调用本项目后端接口，不直接调用 SuperAgent、AgentBus、OPERA、OHIP 或数据库。
- API 调用应统一放在前端
src/services，页面组件不要直接拼接后端 URL。 - 业务判断必须使用后端返回的稳定 code，不使用中文或英文展示文案做判断。
- 前端不得保存或传递后端 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 接入继续后置。