feat: release contextual omnichannel customer platform

Add Telegram, WhatsApp and email account management, realtime messaging, contextual multilingual AI, customer intelligence, knowledge workflows, enterprise controls, a unified design system and complete repository documentation.
2026-07-30 02:29:53 +08:00
parent 9804341463
commit af49d22ca7
66 changed files with 3181 additions and 554 deletions
@@ -0,0 +1,81 @@
+# 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 文档并进行契约测试。