前缀为 /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。
GET /ai-supervision/rules|events：员工查看监督规则与可审计事件。POST /ai-supervision/check-message：发送前检查提醒、重要警告和强制确认。POST /ai-supervision/events/{id}/actions：保存确认、采纳、修改与关闭结果。GET/POST /finance/service-ledger：读取或登记真实关联的售后运营流水。GET /finance/service-analysis?days=7|30|90：按真实流水聚合收入、成本、退款补偿与毛收益。PATCH /service-requests/{id}/repair-costs：以 Decimal 更新备件、人工、物流成本并同步流水。GET /portal/overview、GET /portal/service/{id}/progress：仅返回当前客户可见的会话、工单和真实服务阶段。
附件下载/删除复用既有 /attachments/{id}，后端按 ticket、conversation 或 dispatch 实体重新校验权限。完整接口以 Swagger 为准。