# API 目录

API 统一位于 `/api`，内部渠道回调位于 `/internal/webhooks`。除注册、登录、健康检查和签名 Webhook 外，业务接口均要求 `Authorization: Bearer <token>`。

成功响应采用统一数据包装；错误响应包含可展示消息和 HTTP 状态。调用方必须处理 `401`、`403`、`404`、`409`、`429` 和 `5xx`。

## 认证与安全

- `POST /api/auth/register`、`POST /api/auth/login`
- `GET /api/auth/me`
- `POST /api/auth/ws-ticket`：生成短期 WebSocket 票据
- `POST /api/auth/change-password`
- `POST /api/auth/logout-all`
- `GET|POST|DELETE /api/api-keys`

## 消息与会话

- `GET /api/conversations`
- `GET /api/conversations/:id`
- `GET /api/conversations/:id/messages/page`：游标分页
- `POST /api/conversations/:id/messages`：发送文本/回复
- `POST /api/conversations/:id/media`
- `POST /api/conversations/:id/album`
- `POST /api/conversations/:id/read`
- `POST /api/conversations/:id/presence`
- `POST /api/conversations/:id/messages/action`
- `PATCH /api/conversations/:id/messages/:messageId`
- `GET /api/conversations/:id/messages/:messageId/attachment`
- `POST /api/conversations/:id/actions`：归档、静音、清空、删除等会话动作

## 渠道

- `GET /api/channels`
- Telegram：`/api/channels/telegram/start` 以及 `phone`、`code`、`password`、`state`
- WhatsApp：`/api/channels/whatsapp/start`、状态、联系人、代理、设备、资料、指标和备份
- 邮箱：`POST /api/channels/email/connect`
- 通用：设为默认、状态、日志、删除和渠道测试
- 可靠投递：Webhook 投递记录/重放、出站任务/重试

## WhatsApp 群组

- `GET /api/conversations/:id/whatsapp/group`
- `POST /api/conversations/:id/whatsapp/group/action`

动作由服务端白名单控制，包括成员、管理员、名称、描述和邀请链接管理。

## AI

- `POST /api/ai/translate`
- `POST /api/ai/analyze`
- `POST /api/ai/replies`
- `POST /api/ai/summarize`
- `POST /api/ai/text-action`
- `POST /api/ai/adoptions`
- `GET|PATCH /api/ai/translations`
- `GET /api/conversations/:id/ai-status`
- `POST /api/conversations/:id/messages/:messageId/analyze`

AI 接口是业务增强能力。模型超时或限流不应阻断原始消息收发。

## 客户经营与管理

- 客户：列表、详情、导入、导出、查重、合并和基础 CRUD。
- 商机、任务等资源：统一 CRUD 路由。
- 团队：成员、邀请、角色、操作日志和登录记录。
- 设置、通知、知识库、计费、仪表盘、分析与全局搜索。

## Webhook

- `POST /internal/webhooks/telegram/:tenantId/:channelId`
- `POST /internal/webhooks/whatsapp/:tenantId/:channelId`

生产调用必须携带对应签名。处理器同时校验 URL 中租户/渠道与数据库归属，事件应携带稳定 ID 以实现幂等。

## 健康检查

- `GET /health/live`：进程存活。
- `GET /health/ready`：依赖就绪。
- Nginx 暴露 `/health` 供容器健康检查。

接口的请求/响应类型以 `src/services/`、`src/types/` 和 `server/src/index.js` 为当前实现准则。正式对外开放 API 前，应从路由生成 OpenAPI 3 文档并进行契约测试。