# Dịch Vụ MKT X/Twitter - Kiến Trúc Hệ Thống

## Mục Lục

1. [Tổng Quan](#tổng-quan)
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. [Thiết Kế Component](#thiết-kế-component)
5. [Kiến Trúc Dữ Liệu](#kiến-trúc-dữ-liệu)
6. [Kiến Trúc Tích Hợp](#kiến-trúc-tích-hợp)
7. [Kiến Trúc Bảo Mật](#kiến-trúc-bảo-mật)
8. [Kiến Trúc Triển Khai](#kiến-trúc-triển-khai)

---

## Tổng Quan

### Mục Đích Dịch Vụ

Dịch Vụ Marketing X/Twitter (`mkt-x-service-net`) là nền tảng marketing truyền thông xã hội toàn diện được xây dựng trên .NET 8, cung cấp ba khả năng cốt lõi:

1. **CHATBOT Automation Messenger** - Gửi tin nhắn tự động dựa trên template với điều phối workflow
2. **CHATBOT AI Messenger** - Giao diện trò chuyện được hỗ trợ AI sử dụng tích hợp OpenAI
3. **Customer Management** - CRM hoàn chỉnh cho liên hệ Twitter với phân khúc và phân tích

### Tính Năng Chính

- ✅ Tích hợp đa tài khoản Twitter với OAuth 1.0a
- ✅ Trình thiết kế workflow trực quan cho tự động hóa tin nhắn
- ✅ Trò chuyện ngôn ngữ tự nhiên được hỗ trợ AI
- ✅ Phân khúc khách hàng nâng cao
- ✅ Quản lý chiến dịch với kiểm thử A/B
- ✅ Phân tích và báo cáo thời gian thực
- ✅ Xử lý sự kiện dựa trên webhook
- ✅ Quản lý giới hạn tốc độ và quota

---

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

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

```
┌─────────────────────────────────────────────────────────┐
│                Load Balancer (Traefik)                   │
└─────────────┬───────────────────────────┬───────────────┘
              │                           │
    ┌─────────▼─────────┐       ┌────────▼────────┐
    │   API Instance 1   │       │  API Instance 2  │
    │  (Web API + Jobs)  │       │ (Web API + Jobs) │
    └─────────┬─────────┘       └────────┬────────┘
              │                           │
              └──────────┬────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
  ┌─────▼─────┐    ┌────▼────┐    ┌─────▼─────┐
  │PostgreSQL │    │  Redis   │    │ RabbitMQ  │
  │(Primary)  │    │ (Cache)  │    │(Event Bus)│
  └───────────┘    └──────────┘    └───────────┘
        │
  ┌─────▼─────────────┐
  │ Dịch Vụ Bên Ngoài │
  │ - Twitter API     │
  │ - OpenAI API      │
  └───────────────────┘
```

### Các Tầng Clean Architecture

```
┌──────────────────────────────────────────────┐
│         Tầng API (Presentation)              │
│  - Controllers                               │
│  - Middleware (Auth, Exception, Logging)     │
│  - Swagger/OpenAPI                           │
└──────────────────┬───────────────────────────┘
                   │
┌──────────────────▼───────────────────────────┐
│      Tầng Application (Use Cases)            │
│  - Commands (MediatR)                        │
│  - Queries (MediatR)                         │
│  - DTOs                                      │
│  - Validators (FluentValidation)             │
│  - Pipeline Behaviors                        │
└──────────────────┬───────────────────────────┘
                   │
┌──────────────────▼───────────────────────────┐
│      Tầng Domain (Business Logic)            │
│  - Aggregates (TwitterAccount, Contact...)   │
│  - Entities                                  │
│  - Value Objects                             │
│  - Domain Events                             │
│  - Domain Services                           │
└──────────────────┬───────────────────────────┘
                   │
┌──────────────────▼───────────────────────────┐
│   Tầng Infrastructure (External Concerns)    │
│  - EF Core DbContext                         │
│  - Repositories                              │
│  - External API Clients (Twitter, OpenAI)    │
│  - Background Jobs                           │
│  - Event Bus Integration                     │
└──────────────────────────────────────────────┘
```

---

## Mô Hình Domain

### Aggregate Roots

#### 1. TwitterAccount Aggregate

**Mục đích**: Quản lý tài khoản Twitter đã kết nối với thông tin xác thực OAuth

```csharp
public class TwitterAccount : Entity, IAggregateRoot
{
    public Guid MerchantId { get; private set; }
    public string TwitterUserId { get; private set; }
    public string Username { get; private set; }
    public TwitterAccountStatus Status { get; private set; }
    
    public void ConnectAccount(string oauthToken, string oauthSecret);
    public void Disconnect();
    public void UpdateCredentials(string token, string secret);
}
```

**Quy Tắc Nghiệp Vụ**:
- Một merchant có thể có nhiều tài khoản Twitter
- OAuth tokens phải được mã hóa khi lưu trữ
- Tài khoản phải vượt qua xác minh Twitter trước khi kích hoạt

#### 2. Contact Aggregate

**Mục đích**: Đại diện cho người dùng Twitter tương tác với tài khoản merchant

```csharp
public class Contact : Entity, IAggregateRoot
{
    public Guid AccountId { get; private set; }
    public string TwitterUserId { get; private set; }
    public List<ContactTag> Tags { get; private set; }
    public Dictionary<string, object> Attributes { get; private set; }
    
    public void AddTag(string tagName);
    public void RemoveTag(string tagName);
    public void UpdateAttribute(string key, object value);
}
```

**Quy Tắc Nghiệp Vụ**:
- Mỗi người dùng Twitter là duy nhất cho mỗi merchant account
- Tags phải là duy nhất cho mỗi contact
- Thuộc tính tùy chỉnh hỗ trợ các kiểu dữ liệu linh hoạt (string, number, boolean, date)

#### 3. Conversation Aggregate

**Mục đích**: Quản lý chuỗi tin nhắn giữa contacts và merchants

```csharp
public class Conversation : Entity, IAggregateRoot
{
    public Guid ContactId { get; private set; }
    public Guid AccountId { get; private set; }
    public ConversationStatus Status { get; private set; }
    public List<Message> Messages { get; private set; }
    
    public void AddMessage(Message message);
    public void Close();
    public void AssignToAgent(Guid userId);
}
```

**Quy Tắc Nghiệp Vụ**:
- Conversations tự động đóng sau 24 giờ không hoạt động
- Tin nhắn không thể xóa, chỉ lưu trữ
- Tin nhắn từ bot được đánh dấu rõ ràng

#### 4. Template Aggregate

**Mục đích**: Mẫu tin nhắn có thể tái sử dụng với thay thế biến

```csharp
public class Template : Entity, IAggregateRoot
{
    public Guid MerchantId { get; private set; }
    public string Name { get; private set; }
    public string Content { get; private set; }
    public List<string> Variables { get; private set; }
    
    public string Render(Dictionary<string, object> values);
    public void Validate();
}
```

**Quy Tắc Nghiệp Vụ**:
- Nội dung template không được vượt quá giới hạn Twitter DM (10,000 ký tự)
- Biến sử dụng cú pháp {{variable_name}}
- Tất cả biến đã khai báo phải được cung cấp khi render

#### 5. Campaign Aggregate

**Mục đích**: Điều phối chiến dịch gửi tin nhắn hàng loạt với lịch trình

```csharp
public class Campaign : Entity, IAggregateRoot
{
    public Guid MerchantId { get; private set; }
    public Guid TemplateId { get; private set; }
    public List<Guid> SegmentIds { get; private set; }
    public Schedule Schedule { get; private set; }
    public CampaignMetrics Metrics { get; private set; }
    
    public void Start();
    public void Pause();
    public void Resume();
    public void Complete();
}
```

**Quy Tắc Nghiệp Vụ**:
- Campaign không thể bắt đầu nếu không có ít nhất một segment
- Tuân thủ giới hạn tốc độ Twitter (500 DMs/24 giờ)
- Không thể sửa đổi campaign sau khi đã bắt đầu
- Campaigns đã lên lịch tự động thực thi vào thời gian chỉ định

---

## Thiết Kế Component

### Commands (Thao Tác Ghi)

**Quản Lý Tài Khoản**
- `ConnectTwitterAccountCommand` - Kết nối tài khoản Twitter mới
- `DisconnectAccountCommand` - Ngắt kết nối tài khoản
- `UpdateAccountSettingsCommand` - Cập nhật cấu hình tài khoản

**Quản Lý Liên Hệ**
- `CreateContactCommand` - Tạo liên hệ mới
- `UpdateContactCommand` - Cập nhật chi tiết liên hệ
- `AddContactTagCommand` - Thêm tag vào liên hệ
- `RemoveContactTagCommand` - Xóa tag
- `UpdateContactAttributesCommand` - Cập nhật hàng loạt thuộc tính

**Quản Lý Chiến Dịch**
- `CreateCampaignCommand` - Tạo chiến dịch
- `StartCampaignCommand` - Bắt đầu thực thi chiến dịch
- `PauseCampaignCommand` - Tạm dừng chiến dịch đang chạy
- `ResumeCampaignCommand` - Tiếp tục chiến dịch đã tạm dừng

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

**Analytics Queries**
- `GetOverviewAnalyticsQuery` - Số liệu dashboard
- `GetContactAnalyticsQuery` - Thống kê liên hệ
- `GetConversationAnalyticsQuery` - Số liệu hội thoại
- `GetCampaignAnalyticsQuery` - Hiệu suất chiến dịch

---

## Kiến Trúc Dữ Liệu

### Database Schema

#### Bảng Chính

**twitter_accounts**
```sql
CREATE TABLE twitter_accounts (
    id UUID PRIMARY KEY,
    merchant_id UUID NOT NULL,
    twitter_user_id VARCHAR(100) NOT NULL UNIQUE,
    username VARCHAR(100) NOT NULL,
    display_name VARCHAR(200),
    status VARCHAR(20) NOT NULL,
    oauth_token TEXT NOT NULL, -- được mã hóa
    oauth_token_secret TEXT NOT NULL, -- được mã hóa
    webhook_id VARCHAR(100),
    connected_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

**contacts**
```sql
CREATE TABLE contacts (
    id UUID PRIMARY KEY,
    account_id UUID NOT NULL REFERENCES twitter_accounts(id),
    twitter_user_id VARCHAR(100) NOT NULL,
    username VARCHAR(100) NOT NULL,
    display_name VARCHAR(200),    attributes JSONB DEFAULT '{}',
    first_interaction_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(account_id, twitter_user_id)
);

CREATE INDEX idx_contacts_account ON contacts(account_id);
CREATE INDEX idx_contacts_attributes ON contacts USING GIN(attributes);
```

### Chiến Lược Caching

**Cấu Trúc Redis Cache**

```
Hồ Sơ Liên Hệ: "contact:{contactId}" - TTL: 1 giờ
Templates: "template:{templateId}" - TTL: 10 phút
Segments: "segment:{segmentId}:contacts" - TTL: 5 phút
Số Liệu Campaign: "campaign:{campaignId}:metrics" - TTL: 1 phút
Giới Hạn Tốc Độ: "ratelimit:twitter:{accountId}" - TTL: 24 giờ
```

---

## Kiến Trúc Tích Hợp

### Tích Hợp Twitter API

#### OAuth 1.0a Flow

```
1. Merchant khởi tạo kết nối
2. Service yêu cầu request token từ Twitter
3. Chuyển hướng merchant đến URL ủy quyền Twitter
4. Twitter chuyển hướng lại với verifier
5. Service trao đổi verifier để lấy access token
6. Lưu trữ tokens đã mã hóa trong database
7. Đăng ký webhooks cho tài khoản
```

#### Webhook Events

**Sự Kiện Được Hỗ Trợ**:
- `direct_message_events` - Nhận DM mới
- `direct_message_indicate_typing_events` - Người dùng đang gõ
- `direct_message_mark_read_events` - Tin nhắn đã đọc
- `follow_events` - Người theo dõi mới
- `favorite_events` - Tweet được thích

### Tích Hợp OpenAI

#### Luồng AI Conversation

```
1. Người dùng gửi tin nhắn
2. Trích xuất ngữ cảnh hội thoại (10 tin nhắn cuối)
3. Gọi OpenAI API với ngữ cảnh và tin nhắn
4. Phân tích intent và entities
5. Nếu intent cần dữ liệu, gọi dịch vụ nội bộ
6. Tạo phản hồi sử dụng OpenAI
7. Gửi phản hồi cho người dùng
8. Lưu trữ ngữ cảnh hội thoại
```

---

## Kiến Trúc Bảo Mật

### Xác Thực & Ủy Quyền

**Xác Thực API**
- JWT Bearer tokens cho truy cập API
- OAuth 1.0a cho kết nối tài khoản Twitter
- Xoay vòng refresh token

**Ủy Quyền**
- Kiểm soát truy cập dựa trên vai trò (RBAC)
- Cô lập dữ liệu cấp merchant
- Kiểm tra quyền ở tầng API và domain

### Bảo Vệ Dữ Liệu

**Mã Hóa Dữ Liệu Lưu Trữ**
- OAuth tokens được mã hóa bằng AES-256
- Khóa mã hóa lưu trong Azure Key Vault / AWS KMS
- Mã hóa database cho các trường nhạy cảm

**Mã Hóa Truyền Tải**
- TLS 1.3 cho tất cả giao tiếp HTTP
- Certificate pinning cho gọi Twitter API

---

## Kiến Trúc Triển Khai

### Cấu Hình Container

**Dockerfile**
```dockerfile
FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
WORKDIR /src
COPY . .
RUN dotnet restore
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine
WORKDIR /app
COPY --from=build /app .
RUN adduser -D appuser && chown -R appuser /app
USER appuser
EXPOSE 8080
ENTRYPOINT ["dotnet", "MktXService.API.dll"]
```

### Triển Khai Kubernetes

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mkt-x-service
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: mkt-x-service:latest
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
```

---

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

| Chỉ Số | Mục Tiêu | Ghi Chú |
|--------|----------|---------|
| Thời Gian Phản Hồi API (P95) | < 500ms | Không bao gồm gọi API bên ngoài |
| Xử Lý Tin Nhắn | 100 msg/giây | Mỗi tài khoản Twitter |
| Thông Lượng Campaign | 10,000 liên hệ/phút | Với giới hạn tốc độ |
| Truy Vấn Database (P95) | < 100ms | Truy vấn bảng đơn |
| Cache Hit Ratio | > 80% | Cho tra cứu liên hệ |

---

## Monitoring & Observability

### Metrics (Prometheus)

```
# API Metrics
http_requests_total{method, endpoint, status}
http_request_duration_seconds{method, endpoint}

# Business Metrics
twitter_messages_sent_total{account_id}
twitter_campaigns_active{merchant_id}
twitter_conversations_active{account_id}
```

---

## Tài Liệu Tham Khảo

- [Twitter API v2 Documentation](https://developer.twitter.com/en/docs/twitter-api)
- [OpenAI API Documentation](https://platform.openai.com/docs)
- [Clean Architecture](https://docs.microsoft.com/en-us/dotnet/architecture/microservices/)
- [Domain-Driven Design by Eric Evans](https://domainlanguage.com/ddd/)
