lingxi-web/docs/ARCHITECTURE.md

系统架构

1. 架构目标

灵犀跨境以“租户隔离、渠道可扩展、消息实时、AI 异步化”为核心。浏览器只访问统一 Web/API 入口；Telegram、WhatsApp、邮箱和模型凭据只保存在服务端环境与加密存储中。

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 与数据初始化
telegram-gateway/	NestJS + TDLib 多租户 Telegram 普通账号网关，独立部署
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 源码随本仓库版本化，但使用独立 Compose、数据库、Redis 和 TDLib 数据卷部署。
• 普通 WhatsApp 接入依赖非官方 Web 多设备协议，生产使用前必须评估账号风控和平台条款。
• API 目前集中在单入口文件，业务增长后应按领域拆分路由、服务、仓储和迁移文件。