# 系统架构

## 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 目前集中在单入口文件，业务增长后应按领域拆分路由、服务、仓储和迁移文件。