# 技术选型

## Web

| 技术 | 版本范围 | 选择原因 |
| --- | --- | --- |
| React | 18.3 | 组件生态成熟，适合高交互消息工作台 |
| TypeScript | 5.7 | 为接口、消息事件和页面状态提供静态约束 |
| Vite | 5.4 | 本地启动和生产构建快速 |
| React Router | 7.x | 页面路由和错误边界 |
| TanStack Query | 5.x | 服务端状态缓存、刷新和失败重试 |
| Zustand | 4.x | 轻量跨组件客户端状态 |
| Tailwind CSS | 3.4 | 设计令牌与响应式界面 |
| Recharts | 2.15 | 仪表盘趋势和客户画像雷达图 |
| Zod + React Hook Form | 3.x / 7.x | 表单校验与可维护的输入状态 |
| Lucide React | 0.462 | 一致的线性图标系统 |

## API 与数据

| 技术 | 作用 |
| --- | --- |
| Node.js 20 | 前后端统一运行时，适合 I/O 密集的消息网关 |
| Express 5 | REST、Webhook 与中间件 |
| PostgreSQL 16 | 多租户业务数据、队列和审计的持久化 |
| `pg` | 直接、透明的 SQL 访问 |
| `ws` | 实时消息与状态广播 |
| JWT + bcryptjs | 身份令牌与密码哈希 |
| Helmet + CORS | 基础 HTTP 安全头和来源约束 |
| IMAPFlow + Nodemailer | 企业邮箱收取与发送 |
| Mailparser | MIME 邮件解析 |
| Mammoth + pdf-parse | DOCX/PDF 知识文件抽取 |

## 渠道与 AI

| 组件 | 作用 |
| --- | --- |
| Telegram Gateway + TDLib | 普通 Telegram 账号登录、同步和操作 |
| Baileys 7 | WhatsApp 多设备连接、消息和群组能力 |
| DeepSeek Anthropic-compatible API | 翻译、意图、情感、风险、摘要和回复建议 |
| Stripe | 套餐结算与 Webhook 对账 |

## 交付与质量

| 技术 | 作用 |
| --- | --- |
| Docker Compose | 本地、测试和单机生产编排 |
| Nginx | 静态站点、SPA fallback、API/WebSocket 反向代理 |
| Node Test Runner | API 与网关单元/协议测试 |
| Playwright | Chromium 桌面与移动端视觉/交互 E2E |

## 取舍

- 当前采用模块化单体 API，部署简单、事务边界清晰；代码量继续增长时应优先拆文件而不是立即拆微服务。
- PostgreSQL 同时承载业务和持久任务，减少早期基础设施；高吞吐阶段可引入 Redis 与专用队列。
- WhatsApp 普通账号接入覆盖面高，但稳定性和合规性弱于官方 Business Platform，应为企业客户预留官方适配器。
- AI 采用异步增强而非消息主链路依赖，模型故障时仍可正常沟通。