wmq
af49d22ca7
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.
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
# 系统架构
|
|
|
|
## 1. 架构目标
|
|
|
|
灵犀跨境以“租户隔离、渠道可扩展、消息实时、AI 异步化”为核心。浏览器只访问统一 Web/API 入口；Telegram、WhatsApp、邮箱和模型凭据只保存在服务端环境与加密存储中。
|
|
|
|
```text
|
|
Browser
|
|
│ HTTPS / WebSocket
|
|
▼
|
|
Nginx (web:80)
|
|
├── React SPA
|
|
└── /api, /internal, /health ──► Node.js API (:3100)
|
|
├── PostgreSQL 16
|
|
├── DeepSeek Anthropic API
|
|
├── Telegram Gateway / TDLib
|
|
├── WhatsApp Gateway / Baileys
|
|
├── IMAP + SMTP
|
|
└── Stripe
|
|
```
|
|
|
|
## 2. 仓库结构
|
|
|
|
| 路径 | 职责 |
|
|
| --- | --- |
|
|
| `src/` | React 页面、组件、状态、API 客户端、国际化与类型 |
|
|
| `server/src/index.js` | 认证、租户业务、消息、AI、渠道、Webhook、WebSocket 与数据初始化 |
|
|
| `whatsapp-gateway/` | 普通 WhatsApp 多账号连接、消息/媒体/群组/联系人操作 |
|
|
| `tests/e2e/` | Playwright 桌面与移动端验收 |
|
|
| `docker/` | Nginx 与邮件协议测试辅助镜像 |
|
|
| `docs/` | 架构、部署、接口、测试与运维文档 |
|
|
|
|
## 3. 核心数据流
|
|
|
|
### 入站消息
|
|
|
|
1. Telegram/WhatsApp 网关向带租户和渠道标识的内部 Webhook 投递事件；邮箱轮询器从 IMAP 拉取邮件。
|
|
2. API 校验签名、渠道归属与事件幂等标识。
|
|
3. 消息、会话、联系人和状态写入 PostgreSQL。
|
|
4. API 向当前租户的 WebSocket 客户端广播增量事件。
|
|
5. 文本消息进入 AI 高优先级队列；较早历史进入低优先级补齐队列。
|
|
6. 翻译、意图、情感、风险和会话记忆完成后再次广播更新。
|
|
|
|
### 出站消息
|
|
|
|
1. 前端提交渠道、会话、正文、媒体、回复目标和客户端幂等标识。
|
|
2. API 验证 RBAC、租户归属、渠道状态与限流。
|
|
3. 先落库发送任务，再调用对应网关或 SMTP。
|
|
4. 网关状态事件持续对账已发送、已送达、已读和失败状态。
|
|
5. 可恢复错误进入持久化重试；超过阈值进入死信等待人工重放。
|
|
|
|
### 上下文 AI
|
|
|
|
- 最近消息优先处理，以保证实时聊天速度。
|
|
- 每个会话维护独立上下文；超过长度阈值后压缩为结构化记忆。
|
|
- 历史消息按游标后台补齐，避免首次打开阻塞。
|
|
- 翻译目标可自动识别，也可由坐席指定；智能回复保持人工确认发送。
|
|
|
|
## 4. 隔离与权限
|
|
|
|
- JWT 含用户、租户和角色信息；业务查询必须带 `tenant_id`。
|
|
- 渠道、会话、消息、客户、任务与管理资源均在服务端校验租户归属。
|
|
- WebSocket 使用短期票据，不把长期 JWT 放入 URL。
|
|
- API Key 仅在创建时返回明文，持久化摘要并支持撤销。
|
|
- 邮箱密码使用 `EMAIL_CREDENTIAL_KEY` 加密；网关登录态位于独立持久卷。
|
|
|
|
## 5. 可靠性边界
|
|
|
|
- PostgreSQL 是平台业务数据的事实来源。
|
|
- Telegram/WhatsApp 平台状态由异步事件最终一致对账。
|
|
- WebSocket 只用于加速展示；断线后客户端必须通过 REST 游标补齐。
|
|
- Webhook 接收快速确认，耗时处理异步化；失败投递可查询和重放。
|
|
- AI 失败不能阻断原始消息收发，任务可独立重试。
|
|
|
|
## 6. 当前约束
|
|
|
|
- Telegram Gateway 为独立仓库和独立部署，本仓库只保存适配与配置。
|
|
- 普通 WhatsApp 接入依赖非官方 Web 多设备协议，生产使用前必须评估账号风控和平台条款。
|
|
- API 目前集中在单入口文件，业务增长后应按领域拆分路由、服务、仓储和迁移文件。
|