# Dịch Vụ MKT X/Twitter

## Tổng Quan

Dịch Vụ Marketing X/Twitter cung cấp ba khả năng cốt lõi cho marketing trên mạng xã hội X/Twitter:

- **CHATBOT Tự Động** - Gửi tin nhắn dựa trên template với workflows và lịch trình
- **CHATBOT AI** - Trò chuyện được hỗ trợ AI sử dụng tích hợp OpenAI  
- **Quản Lý Khách Hàng** - 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

### 🤖 Automation Messenger

- ✅ Thư viện mẫu tin nhắn
- ✅ Thiết kế workflow trực quan
- ✅ Tin nhắn kích hoạt sự kiện
- ✅ Chiến dịch theo lịch
- ✅ Kiểm thử A/B
- ✅ Tuân thủ giới hạn tốc độ

### 🧠 AI Messenger

- ✅ Hiểu ngôn ngữ tự nhiên
- ✅ Trò chuyện theo ngữ cảnh  
- ✅ Phát hiện ý định
- ✅ Tích hợp dữ liệu merchant
- ✅ Tự động chuyển cho người
- ✅ Phân tích cảm xúc

### 👥 Customer Management

- ✅ Quản lý hồ sơ liên hệ
- ✅ Lịch sử trò chuyện
- ✅ Phân khúc khách hàng
- ✅ Quản lý nhãn
- ✅ Thuộc tính tùy chỉnh
- ✅ Phân tích tương tác

---

## Yêu Cầu

| Yêu Cầu | Phiên Bản | Ghi Chú |
|----------|-----------|---------|
| **.NET SDK** | 8.0+ | [Tải xuống](https://dotnet.microsoft.com/download) |
| **PostgreSQL** | 15+ | Để lưu trữ dữ liệu |
| **Redis** | 7+ | Để cache |
| **RabbitMQ** | 3.12+ | Để message bus |
| **Tài Khoản Twitter Developer** | - | Cần cho API |
| **OpenAI API Key** | - | Tùy chọn cho AI |

---

## Bắt Đầu Nhanh

### 1. Clone Repository

```bash
cd services/mkt-x-service-net
```

### 2. Cấu Hình

Tạo `appsettings.Development.json`:

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=mkt_x_service;Username=postgres;Password=postgres"
  },
  "Twitter": {
    "ApiKey": "your_twitter_api_key",
    "ApiKeySecret": "your_twitter_api_secret",
    "BearerToken": "your_bearer_token",
    "WebhookUrl": "https://your-domain.com/api/v1/mkt-x/webhooks/twitter"
  },
  "OpenAI": {
    "ApiKey": "your_openai_api_key",
    "Model": "gpt-4"
  },
  "RabbitMQ": {
    "Host": "localhost",
    "Username": "guest",
    "Password": "guest"
  },
  "Redis": {
    "ConnectionString": "localhost:6379"
  }
}
```

### 3. Chạy Migrations

```bash
dotnet ef database update --project src/MktXService.Infrastructure
```

### 4. Chạy Service

```bash
dotnet run --project src/MktXService.API
```

**Điểm Truy Cập**:
- API: http://localhost:5000
- Swagger: http://localhost:5000/swagger

---

## Tài Liệu

### Tài Liệu Tiếng Việt

- **[Kiến Trúc](ARCHITECTURE.md)** - Kiến trúc hệ thống và mô hình domain
- **[Tài Liệu API](API.md)** - Tài liệu API đầy đủ với ví dụ
- **[Hướng Dẫn Thiết Lập Twitter](TWITTER_SETUP.md)** - Hướng dẫn thiết lập Twitter API từng bước

### English Documentation

- **[Architecture](../en/ARCHITECTURE.md)** - System architecture and domain model
- **[API Reference](../en/API.md)** - Complete API documentation with examples
- **[Twitter Setup Guide](../en/TWITTER_SETUP.md)** - Step-by-step Twitter API setup

---

## API Endpoints

### Core Endpoints

```
# Quản Lý Tài Khoản
POST   /api/v1/mkt-x/accounts              # Kết nối tài khoản Twitter
GET    /api/v1/mkt-x/accounts              # Danh sách tài khoản
DELETE /api/v1/mkt-x/accounts/{id}         # Ngắt kết nối

# Quản Lý Liên Hệ
GET    /api/v1/mkt-x/contacts              # Danh sách liên hệ
POST   /api/v1/mkt-x/contacts/{id}/tags    # Thêm nhãn
PUT    /api/v1/mkt-x/contacts/{id}/attributes # Cập nhật thuộc tính

# Hội Thoại
GET    /api/v1/mkt-x/conversations         # Danh sách hội thoại
POST   /api/v1/mkt-x/conversations/{id}/messages # Gửi tin nhắn

# Chiến Dịch
POST   /api/v1/mkt-x/campaigns             # Tạo chiến dịch
POST   /api/v1/mkt-x/campaigns/{id}/start  # Bắt đầu chiến dịch
GET    /api/v1/mkt-x/campaigns/{id}/metrics # Xem số liệu

# Tự Động Hóa
POST   /api/v1/mkt-x/automation/flows      # Tạo workflow
POST   /api/v1/mkt-x/automation/flows/{id}/activate # Kích hoạt

# AI Chatbot
POST   /api/v1/mkt-x/ai/conversations/{id}/message # Trò chuyện AI
GET    /api/v1/mkt-x/analytics/overview    # Phân tích dashboard
```

**Tài liệu API đầy đủ**: Xem [API.md](API.md)

---

## Cấu Trúc Dự Án

```
mkt-x-service-net/
├── src/
│   ├── MktXService.API/              # Controllers, Swagger
│   │   ├── Controllers/              # API Controllers
│   │   └── Application/              # Commands, Queries, DTOs
│   ├── MktXService.Domain/           # Mô hình domain
│   │   ├── AggregatesModel/          # Aggregates
│   │   ├── Events/                   # Domain events
│   │   └── SeedWork/                 # Base classes
│   └── MktXService.Infrastructure/   # EF Core, Repositories
│       ├── Data/                     # DbContext
│       ├── Repositories/             # Truy cập dữ liệu
│       ├── Services/                 # External clients
│       └── BackgroundJobs/           # Background workers
├── tests/
│   ├── MktXService.UnitTests/
│   └── MktXService.IntegrationTests/
├── docs/                             # Tài liệu
├── Dockerfile
└── docker-compose.yml
```

---

## Phát Triển

### Build

```bash
dotnet build
```

### Chạy Tests

```bash
dotnet test
```

### Tạo Migration

```bash
dotnet ef migrations add MigrationName --project src/MktXService.Infrastructure
```

### Triển Khai Docker

```bash
# Build
docker-compose -f deployments/local/docker-compose.yml build mkt-x-service-net

# Chạy
docker-compose -f deployments/local/docker-compose.yml up -d mkt-x-service-net

# Logs
docker-compose -f deployments/local/docker-compose.yml logs -f mkt-x-service-net
```

---

## Kiến Trúc

### Các Tầng Clean Architecture

```
┌─────────────────────────────────────┐
│         Tầng API (Controllers)      │
├─────────────────────────────────────┤
│  Tầng Application (CQRS + MediatR)  │
├─────────────────────────────────────┤
│      Tầng Domain (Aggregates)       │
├─────────────────────────────────────┤
│  Infrastructure (EF Core, Twitter)   │
└─────────────────────────────────────┘
```

### Patterns Chính

- **CQRS** với MediatR để tách command/query
- **DDD** với 9 aggregate roots
- **Repository Pattern** cho truy cập dữ liệu
- **Event-Driven** với RabbitMQ

**Chi tiết**: Xem [ARCHITECTURE.md](ARCHITECTURE.md)

---

## Cấu Hình

### Biến Môi Trường

```bash
# Database
ConnectionStrings__DefaultConnection="Host=localhost;Database=mkt_x_service"

# Twitter API
Twitter__ApiKey="your_api_key"
Twitter__ApiKeySecret="your_api_secret"
Twitter__WebhookUrl="https://your-domain.com/api/v1/mkt-x/webhooks/twitter"

# OpenAI
OpenAI__ApiKey="sk-..."
OpenAI__Model="gpt-4"

# RabbitMQ
RabbitMQ__Host="localhost"

# Redis
Redis__ConnectionString="localhost:6379"
```

---

## Giám Sát

### Health Check

```bash
curl http://localhost:5000/health
```

### Metrics

- **Prometheus**: `http://localhost:5000/metrics`
- **Grafana Dashboard**: Có sẵn trong production

### Logging

Structured logging với Serilog, gửi đến Loki:

```json
{
  "timestamp": "2026-01-18T10:00:00Z",
  "level": "Information",
  "message": "Chiến dịch đã bắt đầu",
  "properties": {
    "campaignId": "...",
    "merchantId": "..."
  }
}
```

---

## Xử Lý Sự Cố

### Vấn Đề Thường Gặp

#### 1. Twitter API 401 Unauthorized

**Giải pháp**:
- Xác minh API credentials trong cấu hình
- Kiểm tra OAuth token expiration
- Đảm bảo app có quyền Direct Messages

#### 2. Lỗi Kết Nối Database

**Giải pháp**:
- Kiểm tra PostgreSQL đang chạy
- Xác minh connection string
- Đảm bảo database tồn tại: `createdb mkt_x_service`

#### 3. Không Nhận Được Webhook Events

**Giải pháp**:
- Xác minh webhook đã đăng ký trong Twitter
- Kiểm tra HTTPS certificate hợp lệ
- Đảm bảo firewall cho phép inbound traffic
- Xem xét webhook signature validation

**Chi tiết**: Xem [TWITTER_SETUP.md](TWITTER_SETUP.md)

---

## Hiệu Năng

### Mục Tiêu

| Chỉ Số | Mục Tiêu |
|--------|----------|
| API Response (P95) | < 500ms |
| Xử Lý Tin Nhắn | 100 msg/giây |
| Thông Lượng Campaign | 10,000 liên hệ/phút |
| Database Query (P95) | < 100ms |

### Caching

```
Hồ Sơ Liên Hệ: 1 giờ TTL
Templates: 10 phút TTL
Segments: 5 phút TTL
```

---

## Bảo Mật

- ✅ OAuth tokens được mã hóa khi lưu trữ
- ✅ JWT authentication cho API
- ✅ RBAC cho cô lập merchant
- ✅ Xác thực đầu vào với FluentValidation
- ✅ Tuân thủ GDPR (lưu trữ dữ liệu, xóa dữ liệu)

---

## Đóng Góp

Xem [GoodGo Contributing Guide](../../docs/CONTRIBUTING.md)

---

## Hỗ Trợ

- **Vấn Đề Tài Liệu**: Mở issue trên GitHub
- **Hỗ Trợ API**: api-support@goodgo.com
- **Tích Hợp Twitter**: Xem [TWITTER_SETUP.md](TWITTER_SETUP.md)

---

## Giấy Phép

MIT License - Xem file LICENSE để biết chi tiết

---

## Dịch Vụ Liên Quan

- [MKT Facebook Service](../../mkt-facebook-service-net) - Facebook Messenger marketing
- [MKT Zalo Service](../../mkt-zalo-service-net) - Zalo OA marketing
- [MKT WhatsApp Service](../../mkt-whatsapp-service-net) - WhatsApp Business marketing

---

## Công Nghệ

| Component | Technology | Version |
|-----------|-----------|---------|
| Runtime | .NET | 8.0+ |
| Framework | ASP.NET Core | 8.0+ |
| ORM | Entity Framework Core | 8.0+ |
| Database | PostgreSQL | 15+ |
| Cache | Redis | 7+ |
| Message Broker | RabbitMQ | 3.12+ |
| Mediator | MediatR | 12+ |
| API Gateway | Traefik | 2.10+ |
| Monitoring | Prometheus + Grafana | - |

---

## 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/modern-web-apps-azure/common-web-application-architectures)
- [Domain-Driven Design](https://domainlanguage.com/ddd/)
