Files

Ho Ngoc Hai de013ce183 refactor: Rename Vietnamese architecture and Twitter setup documentation files and update all relevant links.

2026-01-18 23:22:44 +07:00

11 KiB

Raw Blame History

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
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

cd services/mkt-x-service-net

2. Cấu Hình

Tạo appsettings.Development.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

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

4. Chạy Service

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 - Kiến trúc hệ thống và mô hình domain
Tài Liệu API - Tài liệu API đầy đủ với ví dụ
Hướng Dẫn Thiết Lập Twitter - Hướng dẫn thiết lập Twitter API từng bước

English Documentation

Architecture - System architecture and domain model
API Reference - Complete API documentation with examples
Twitter Setup Guide - 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

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

dotnet build

Chạy Tests

dotnet test

Tạo Migration

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

Triển Khai Docker

# 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

Cấu Hình

Biến Môi Trường

# 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

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:

{
  "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

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

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

Giấy Phép

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

Dịch Vụ Liên Quan

MKT Facebook Service - Facebook Messenger marketing
MKT Zalo Service - Zalo OA marketing
MKT WhatsApp Service - 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	-

11 KiB Raw Blame History

Dịch Vụ MKT X/Twitter

Tổng Quan

Tính Năng

🤖 Automation Messenger

🧠 AI Messenger

👥 Customer Management

Yêu Cầu

Bắt Đầu Nhanh

1. Clone Repository

2. Cấu Hình

3. Chạy Migrations

4. Chạy Service

Tài Liệu

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

English Documentation

API Endpoints

Core Endpoints

Cấu Trúc Dự Án

Phát Triển

Build

Chạy Tests

Tạo Migration

Triển Khai Docker

Kiến Trúc

Các Tầng Clean Architecture

Patterns Chính

Cấu Hình

Biến Môi Trường

Giám Sát

Health Check

Metrics

Logging

Xử Lý Sự Cố

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

1. Twitter API 401 Unauthorized

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

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

Hiệu Năng

Mục Tiêu

Caching

Bảo Mật

Đóng Góp

Hỗ Trợ

Giấy Phép

Dịch Vụ Liên Quan

Công Nghệ

Tham Khảo

11 KiB

Raw Blame History