37 lines (28 loc) · 2.31 KB

API 指南

前缀为 /api/v1，交互文档位于 /docs。浏览器通过 HttpOnly Access/Refresh Cookie 认证；所有变更请求携带 CSRF 头。401 表示未认证，403 表示角色或数据范围拒绝，409 表示状态机冲突，422 表示字段或业务前置条件不完整。

实时会话

POST/GET /conversations：创建、筛选会话。
GET /conversations/{id}、GET /conversations/{id}/messages：详情与 sequence 增量消息。
POST /conversations/{id}/messages：支持 client_message_id 幂等。
POST /conversations/{id}/attachments：上传图片、日志和文件。
POST /conversations/{id}/read：持久化已读回执。
POST /conversations/{id}/request-human|claim|assign|handoff：转人工、接管和分配。
POST /conversations/{id}/resolve|close|reopen：集中状态机动作。
POST /conversations/{id}/create-ticket：创建并结构化关联正式工单。
POST /conversations/{id}/recommend：客服候选与分数说明。
POST /conversations/{id}/ai-feedback：保存 AI 建议接受、编辑或不准确反馈。
GET /conversations/queue/metrics、GET /service-queues：队列指标和定义。

在线状态与派工

GET/POST /agents/presence：在线状态、心跳、负载和容量。
POST/GET /dispatches、GET /dispatches/{id}：创建、列表和详情。
POST /dispatches/{id}/recommend|offer：推荐候选并由主管发送 Offer。
POST /dispatches/{id}/attachments：现场照片、检测日志、报告。
POST /dispatches/{id}/{action}：accept、reject、schedule、depart、arrive、start、pause、wait-parts、resume、complete、request-confirmation、customer-confirm、fail、cancel。

客户画像、通知和同步

GET /customers/{id}/service-profile、POST .../recalculate。
GET /customers/{id}/service-strategy。
POST /customers/{id}/communication-preferences。
GET /realtime/events?last_event_id={cursor}：掉线后的可见事件增量补齐。
POST /notifications/read-all：批量已读。
WebSocket：/api/v1/realtime/ws，详见 docs/architecture/WEBSOCKET_PROTOCOL.md。

附件下载/删除复用既有 /attachments/{id}，后端按 ticket、conversation 或 dispatch 实体重新校验权限。完整接口以 Swagger 为准。