pos-system/services/mkt-x-service-net/docs/vi/ARCHITECTURE.md

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

Mục Lục

1. Tổng Quan
2. Kiến Trúc Hệ Thống
3. Mô Hình Domain
4. Thiết Kế Component
5. Kiến Trúc Dữ Liệu
6. Kiến Trúc Tích Hợp
7. Kiến Trúc Bảo Mật
8. 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

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

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

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

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

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

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

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

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

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
• OpenAI API Documentation
• Clean Architecture
• Domain-Driven Design by Eric Evans