# MKT Zalo Service - Kiến Trúc Giải Pháp

## Mục Lục

1. [Ngữ Cảnh Nghiệp Vụ](#ngữ-cảnh-nghiệp-vụ)
2. [Kiến Trúc Hệ Thống](#kiến-trúc-hệ-thống)
3. [Mô Hình Domain](#mô-hình-domain)
4. [CQRS Commands & Queries](#cqrs-commands--queries)
5. [Patterns Tích Hợp](#patterns-tích-hợp)
6. [Luồng Dữ Liệu](#luồng-dữ-liệu)
7. [Bảo Mật & Xác Thực](#bảo-mật--xác-thực)
8. [Hiệu Năng & Mở Rộng](#hiệu-năng--mở-rộng)
9. [Giám Sát & Observability](#giám-sát--observability)

---

## Ngữ Cảnh Nghiệp Vụ

### Vấn Đề

Doanh nghiệp cần tương tác khách hàng trên Zalo, nền tảng nhắn tin hàng đầu Việt Nam với 80M+ người dùng. Yêu cầu:
- Phản hồi tự động cho câu hỏi thường gặp (24/7)
- Hội thoại AI cho nhu cầu phức tạp
- Dữ liệu khách hàng và lịch sử tập trung
- Hạ tầng nhắn tin mở rộng cho chiến dịch

### Mục Tiêu Nghiệp Vụ

1. **Tương Tác Khách Hàng**: 90% tỷ lệ phản hồi trong vòng 1 phút
2. **Tự Động Hóa**: 70% câu hỏi xử lý không cần con người
3. **Cá Nhân Hóa**: Phản hồi nhận biết ngữ cảnh dựa trên lịch sử
4. **Mở Rộng**: Hỗ trợ 10,000+ hội thoại đồng thời

---

## Kiến Trúc Hệ Thống

### Kiến Trúc Tổng Quan

```
┌─────────────────────────────────────────────────────────┐
│                 Zalo Official Account                    │
│          (Khách hàng gửi tin nhắn qua Zalo)             │
└────────────────────┬────────────────────────────────────┘
                     │ Webhook Events
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  mkt-zalo-service-net                    │
│                                                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │       Webhook Handler (API Layer)                │  │
│  │  • Xác thực chữ ký                               │  │
│  │  • Parse events (message, follow, buttons)       │  │
│  │  • Trả về 200 nhanh                              │  │
│  └───────────────┬──────────────────────────────────┘  │
│                  │                                      │
│                  ▼                                      │
│  ┌──────────────────────────────────────────────────┐  │
│  │       Engine Xử Lý Tin Nhắn                      │  │
│  │  ┌────────────────┐  ┌────────────────┐         │  │
│  │  │ Rule Engine    │  │   AI Engine    │         │  │
│  │  │ (Tự động hóa)  │  │  (Dựa LLM)     │         │  │
│  │  └────────────────┘  └────────────────┘         │  │
│  └───────────────┬──────────────────────────────────┘  │
│                  │                                      │
│                  ▼                                      │
│  ┌──────────────────────────────────────────────────┐  │
│  │         Domain Layer                             │  │
│  │  • Conversation Aggregate                        │  │
│  │  • ZaloCustomer Aggregate                        │  │
│  │  • ChatbotRule Entity                            │  │
│  │  • MessageTemplate Entity                        │  │
│  └──────────────────────────────────────────────────┘  │
│                                                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │         Integration Layer                        │  │
│  │  • Zalo OA API Client (Gửi tin nhắn)            │  │
│  │  • LLM Provider (OpenAI, Vertex AI)              │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                     │
                     ▼
              ┌──────────────┐
              │  PostgreSQL  │
              │  (Customer,  │
              │ Conversation,│
              │  Templates)  │
              └──────────────┘
```

### Các Tầng Clean Architecture

```
┌────────────────────────────────────────────────────────────┐
│                        API Layer                            │
│  Controllers → MediatR → Commands/Queries                  │
│  • WebhooksController (public, không auth)                 │
│  • ConversationsController (authenticated)                 │
│  • CustomersController (quản lý CRM)                       │
│  • ChatbotRulesController (cấu hình automation)            │
│  • Admin/* (analytics, broadcast)                          │
└────────────────────────┬───────────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────────┐
│                    Application Layer                        │
│  Commands: ProcessWebhookCommand, SendMessageCommand       │
│  Queries: GetConversationHistoryQuery, GetCustomerQuery    │
│  Handlers: ProcessWebhookCommandHandler (routes to engines)│
│  Behaviors: ValidationBehavior, LoggingBehavior            │
└────────────────────────┬───────────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────────┐
│                     Domain Layer                            │
│  Aggregates:                                                │
│  • Conversation (messages, status, context)                │
│  • ZaloCustomer (profile, tags, segment)                   │
│  • ChatbotRule (conditions, actions)                        │
│  • MessageTemplate (ZNS templates)                          │
│                                                              │
│  Business Rules:                                            │
│  • Conversation.AddMessage() - validate message type        │
│  • ZaloCustomer.UpdateProfile() - enforce data quality     │
│  • ChatbotRule.Evaluate() - match conditions               │
└────────────────────────┬───────────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────────┐
│                 Infrastructure Layer                        │
│  • EF Core DbContext  (persistence)                        │
│  • Repositories (ConversationRepository, CustomerRepository)│
│  • ZaloOfficialAccountClient (HTTP client với Polly)      │
│  • RuleBasedChatbotEngine (keyword matching, regex)       │
│  • AiChatbotEngine (tích hợp LLM)                          │
│  • Redis Caching (conversation context)                    │
└────────────────────────────────────────────────────────────┘
```

---

## Mô Hình Domain

### Tổng Quan Aggregates

**4 Aggregate Roots:**

1. **Conversation** - Quản lý vòng đời hội thoại và tin nhắn
2. **ZaloCustomer** - Hồ sơ khách hàng, tags, và phân khúc
3. **ChatbotRule** - Quy tắc tự động hóa (keyword/regex/intent)
4. **MessageTemplate** - Quản lý template ZNS

Xem [DOMAIN_MODELS.md](./DOMAIN_MODELS.md) để biết chi tiết triển khai.

---

## CQRS Commands & Queries

### Commands (Thao Tác Ghi)

```csharp
// Xử lý webhook từ Zalo
public record ProcessWebhookCommand(
    string EventName,
    string ZaloUserId,
    string MessageText,
    string MessageType,
    DateTime Timestamp) : IRequest<ProcessWebhookResult>;

// Gửi tin nhắn đến khách hàng Zalo
public record SendMessageCommand(
    Guid ConversationId,
    string ZaloUserId,
    string MessageText,
    MessageType Type = MessageType.Text) : IRequest<SendMessageResult>;

// Tạo quy tắc tự động chatbot
public record CreateChatbotRuleCommand(
    string Name,
    RuleType Type,
    List<RuleConditionDto> Conditions,
    RuleActionDto Action,
    int Priority) : IRequest<ChatbotRuleResult>;
```

### Queries (Thao Tác Đọc)

```csharp
// Lấy lịch sử hội thoại
public record GetConversationHistoryQuery(
    Guid ConversationId,
    int Skip = 0,
    int Take = 50) : IRequest<ConversationHistoryResult>;

// Lấy chi tiết khách hàng với tóm tắt tương tác
public record GetCustomerQuery(
    Guid CustomerId) : IRequest<CustomerDetailDto>;

// Tìm kiếm hội thoại
public record SearchConversationsQuery(
    string? ZaloUserId = null,
    ConversationStatus? Status = null,
    DateTime? FromDate = null,
    DateTime? ToDate = null,
    int Skip = 0,
    int Take = 20) : IRequest<PagedResult<ConversationSummaryDto>>;
```

---

## Patterns Tích Hợp

### 1. Tích Hợp Zalo Official Account

**Luồng Xử Lý Webhook:**

```
Zalo → POST /webhooks → Xác thực chữ ký → Parse event → Queue vào RabbitMQ → Trả về 200
                                                                ↓
      RabbitMQ Consumer → Load customer → Route to Engine → Tạo response → Gửi qua Zalo API
```

**Yêu Cầu Quan Trọng:**
- Phải trả về 200 trong vòng 2 giây
- Xác thực chữ ký (HMAC SHA256)
- Xử lý async qua message queue

### 2. Rule-Based Chatbot Engine

```csharp
public class RuleBasedChatbotEngine : IChatbotEngine
{
    public async Task<ChatbotResponse> ProcessAsync(
        string userMessage,
        ConversationContext context,
        CancellationToken ct)
    {
        var rules = await _ruleRepository.GetActiveRulesOrderedByPriorityAsync(ct);
        
        foreach (var rule in rules)
        {
            if (rule.Evaluate(userMessage))
            {
                return new ChatbotResponse(
                    ResponseText: rule.Action.ResponseText,
                    MatchedRuleId: rule.Id,
                    Confidence: 1.0);
            }
        }
        
        return ChatbotResponse.NoMatch;
    }
}
```

### 3. AI Chatbot Engine (LLM)

```csharp
public class AiChatbotEngine : IChatbotEngine
{
    public async Task<ChatbotResponse> ProcessAsync(
        string userMessage,
        ConversationContext context,
        CancellationToken ct)
    {
        // Load lịch sử hội thoại để có context
        var conversationHistory = await _cache.GetOrSetAsync(
            $"conversation:{context.ConversationId}",
            async () => await _conversationRepository.GetMessagesAsync(
                context.ConversationId, take: 10, ct),
            TimeSpan.FromMinutes(30),
            ct);
            
        // Xây dựng prompt LLM với context
        var prompt = BuildPrompt(userMessage, conversationHistory, context.CustomerProfile);
        
        // Gọi LLM provider
        var llmResponse = await _llmService.GenerateResponseAsync(prompt, ct);
        
        return new ChatbotResponse(
            ResponseText: llmResponse.Text,
            Confidence: llmResponse.Confidence);
    }
}
```

---

## Luồng Dữ Liệu

### Luồng Xử Lý Webhook

```
1. Zalo gửi webhook → WebhooksController
2. Xác thực chữ ký (HMAC SHA256)
3. Parse event (user_send_text, follow, etc.)
4. Publish vào RabbitMQ
5. Trả về 200 cho Zalo (< 2s)

6. Consumer xử lý event
7. Load hoặc tạo ZaloCustomer
8. Load hoặc tạo Conversation
9. Route vào Rule Engine hoặc AI Engine
10. Tạo response
11. Lưu vào database
12. Gửi qua Zalo API
13. Cập nhật Redis cache
```

---

## Bảo Mật & Xác Thực

### 1. Xác Thực Chữ Ký Webhook

```csharp
public class ZaloWebhookSignatureValidator
{
    private readonly string _webhookSecret;
    
    public bool ValidateSignature(string body, string signature)
    {
        var computedSignature = ComputeHmac256(body, _webhookSecret);
        return signature.Equals(computedSignature, StringComparison.OrdinalIgnoreCase);
    }
    
    private string ComputeHmac256(string message, string secret)
    {
        var encoding = new UTF8Encoding();
        var keyBytes = encoding.GetBytes(secret);
        using var hmac = new HMACSHA256(keyBytes);
        var hashBytes = hmac.ComputeHash(encoding.GetBytes(message));
        return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
    }
}
```

### 2. Xác Thực API

- **Public APIs** (Webhooks): Chỉ xác thực chữ ký
- **Customer APIs**: JWT Bearer tokens từ IAM service
- **Admin APIs**: JWT + Admin role claim

---

## Hiệu Năng & Mở Rộng

### Mục Tiêu Hiệu Năng

| M ục Tiêu | Target | Chiến Lược |
|-----------|--------|------------|
| Thời gian phản hồi webhook | < 2s | Queue ngay, trả về 200 |
| Thời gian xử lý tin nhắn | < 5s | Xử lý async qua RabbitMQ |
| Tạo phản hồi AI | < 3s | LLM caching, tối ưu prompt |
| Thời gian query database | < 100ms | Indexed queries, read replicas |
| Hội thoại đồng thời | 10,000+ | Xử lý stateless, Redis cache |

### Chiến Lược Caching

```csharp
// Cache conversation context trong Redis
Key: "conversation:{conversationId}"
TTL: 30 phút
Data: 10 tin nhắn cuối, customer profile, active rules

// Cache chatbot rules
Key: "chatbot:rules:active"
TTL: 5 phút
Data: Tất cả rules active sắp theo priority
```

---

## Giám Sát & Observability

### Các Metrics Quan Trọng

```
# Webhook metrics
zalo_webhook_events_total{event_type="user_send_text"} 
zalo_webhook_processing_duration_seconds

# Chatbot metrics
zalo_messages_processed_total{engine="rule_based|ai"}
zalo_chatbot_rule_matches_total{rule_id="..."}
zalo_ai_llm_latency_seconds

# Business metrics
zalo_active_conversations_total
zalo_customer_satisfaction_score
zalo_automation_rate
```

### Chiến Lược Logging

```
INFO:  Nhận tin nhắn user, khớp quy tắc
WARN:  Không khớp quy tắc, fallback sang AI
ERROR: Lỗi gửi tin Zalo, đang retry
```

---

## Cân Nhắc Triển Khai

### Cấu Hình Môi Trường

```yaml
# Production
- Webhook URL: https://api.goodgo.vn/api/v1/zalo/webhooks
- Database: Neon PostgreSQL (multi-region)
- Redis: ElastiCache cluster
- LLM: Vertex AI (gcp-asia-southeast1)

# Staging
- Webhook URL: https://staging-api.goodgo.vn/api/v1/zalo/webhooks
- Zalo OA: Test account
```

### Khôi Phục Thảm Họa

- **Database backups**: Snapshot hàng ngày, giữ 30 ngày
- **Message queue**: Queues bền vững với replication
- **Webhook replay**: Lưu raw webhook events trong 7 ngày

---

## Cải Tiến Tương Lai

1. **Hỗ trợ đa ngôn ngữ** - Chatbot Tiếng Việt + English
2. **Xử lý tin nhắn thoại** - Tích hợp speech-to-text
3. **Phân tích cảm xúc** - Phát hiện cảm xúc khách hàng
4. **A/B testing** - Test các phản hồi chatbot khác nhau
5. **Tích hợp Zalo Mini App** - Deep linking vào mini apps

---

**Phiên Bản Tài Liệu**: 1.0  
**Cập Nhật Lần Cuối**: 2026-01-18  
**Tác Giả**: GoodGo Platform Team
