WhatsApp AI Customer Service System

私有化 WhatsApp 智能客服系统 - 使用 OpenAI SDK 与后台可配置凭据 | A private WhatsApp AI customer service platform powered by the OpenAI SDK with backend-managed credentials

本系统是一个功能完整的WhatsApp AI客服平台，支持多语言对话、语音转写、实时翻译、智能标签等功能。

已完成核心功能：

• ✅ 统一实时收件箱 (42 tests, 85% coverage)
• ✅ AI问答与翻译 (25 tests, 87.7% coverage)
• ✅ 核心系统开发 (32 tests, 75% coverage)
• 总计: 99个测试全部通过，平均覆盖率82.6%

• 💬 多条件筛选: 状态、标签、时间区间、全文搜索
• 🔄 会话状态管理: AI自动接待、人工接管、未读消息
• ⏰ Meta 24小时窗口管控: 自动计算窗口状态
• 📝 内部备注: 永久保存，仅内部可见
• ⚡ 快捷操作: 人工接管、切回机器人、查看订单

• 🌍 多语言支持: 10+语言自动识别（EN/ZH/PT/ES/AR/FR/DE/JA/KO/RU）
• 🔄 双向翻译: 客户消息自动中译、客服中文翻译为客户语言
• 🎤 语音转写: 通过 OpenAI SDK 调用 Whisper API
• 📊 三重置信度评分: 转录、翻译、回复置信度
• �� 智能转人工: 低置信度、复杂问题、投诉自动转人工

• 🔐 安全认证: JWT + bcrypt + Zod验证
• 🏷️ 智能标签: AI自动打标签、标签筛选
• 📱 WhatsApp集成: Webhook、自动建客户、消息合并
• 🚀 性能优化: 消息队列、批量翻译、并发处理
• 🔌 WebSocket: 实时通信推送

• Backend: Node.js, TypeScript, Express.js
• Database: PostgreSQL with Prisma ORM
• AI: OpenAI SDK (cloud or private OpenAI-compatible endpoint); credentials managed in backend database
• Authentication: JWT, bcrypt, TOTP (2FA)
• Testing: Vitest, Supertest
• Logging: Winston

• Node.js 18 or higher
• PostgreSQL 14 or higher
• An OpenAI API key or private OpenAI-compatible endpoint configured via backend settings

1. Clone the repository:

git clone <repository-url>
cd whatsapp-ai-customer-service

2. Install dependencies:

npm install

3. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

4. Set up the database:

# Generate Prisma client
npm run db:generate

# Push schema to database
npm run db:push

# Or run migrations
npm run db:migrate

Update the DATABASE_URL in .env:

DATABASE_URL=postgresql://username:password@localhost:5432/whatsapp_ai_service

Set a strong secret for JWT tokens:

JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

OPENAI_API_KEY=sk-your-api-key
OPENAI_MODEL=gpt-4
OPENAI_BASE_URL=https://api.openai.com/v1

These are optional fallbacks; the canonical source is the AiConfig table in the database.

EXTERNAL_API_NAME=product_search
EXTERNAL_API_BASE_URL=https://api.example.com
EXTERNAL_API_KEY=your-external-api-key

npm run dev

npm run build
npm start

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "role": "agent"
}

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "totpToken": "123456"
}

POST /api/auth/2fa/setup
Authorization: Bearer <token>

POST /api/conversations
Authorization: Bearer <token>
Content-Type: application/json

{
  "customerId": "uuid",
  "messages": [],
  "context": {}
}

GET /api/conversations/:id
Authorization: Bearer <token>

GET /api/conversations?page=1&limit=20
Authorization: Bearer <token>

POST /api/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "conversationId": "uuid",
  "content": "Hello!",
  "sender": "agent",
  "tags": ["inquiry"]
}

POST /api/products
Authorization: Bearer <token>
Content-Type: application/json

{
  "sku": "PROD-001",
  "name": "Product Name",
  "details": {}
}

GET /api/products/search?query=keyword
Authorization: Bearer <token>

POST /api/orders
Authorization: Bearer <token>
Content-Type: application/json

{
  "customerId": "uuid",
  "productId": "uuid",
  "orderStatus": "pending"
}

GET /api/orders?page=1&limit=20
Authorization: Bearer <token>

See ARCHITECTURE.md for detailed database schema information.

• Password Hashing: bcrypt with configurable rounds
• JWT Authentication: Secure token-based authentication
• 2FA Support: TOTP-based two-factor authentication
• Input Validation: Zod schema validation on all inputs
• SQL Injection Protection: Prisma ORM parameterized queries
• Rate Limiting: Configurable rate limits per IP
• Audit Logging: All critical operations logged

The system supports multiple languages. All text is externalized to JSON files in the locales/ directory:

• locales/en/ - English
• locales/zh/ - Chinese
• locales/es/ - Spanish
• locales/ar/ - Arabic

├── prisma/
│   └── schema.prisma          # Database schema
├── src/
│   ├── config/                # Configuration files
│   ├── controllers/           # Route controllers
│   ├── middleware/            # Express middleware
│   ├── routes/                # API routes
│   ├── utils/                 # Utility functions
│   └── index.ts               # Application entry point
├── tests/                     # Test files
├── locales/                   # i18n translations
└── docs/                      # Documentation

• TypeScript strict mode enabled
• ESLint for linting
• Prettier for formatting

The project includes comprehensive tests:

• Database schema validation
• API endpoint tests
• Authentication flow tests
• Input validation tests

Run tests with:

npm test

See ARCHITECTURE.md for deployment considerations including:

• Database setup
• File storage configuration
• Environment variables
• Scaling strategies

MIT

For issues and questions, please open an issue on the GitHub repository.