# Dịch Vụ Marketing Facebook

> Dịch vụ Marketing Facebook Messenger với Chatbot Tự Động, Chatbot AI, và Quản Lý Khách Hàng

[![.NET Version](https://img.shields.io/badge/.NET-8.0-512BD4)](https://dotnet.microsoft.com/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## Tính Năng

### 1. 🤖 CHATBOT Automation Messenger

Chatbot dựa trên quy tắc với luồng hội thoại định sẵn:
- Trình tạo flow trực quan với các nodes (Message, Question, Condition, Action)
- Triggers theo từ khóa và xử lý postback
- Quick replies và button templates
- Hỗ trợ đa ngôn ngữ
- A/B testing cho các flows

### 2. 🧠 CHATBOT AI Messenger

Chatbot thông minh được hỗ trợ bởi OpenAI/Azure OpenAI:
- Hiểu và sinh ngôn ngữ tự nhiên
- Hội thoại theo ngữ cảnh
- Tùy chỉnh system prompts
- Hỗ trợ đối thoại nhiều lượt
- Fallback về automation rules
- Theo dõi chi phí và tối ưu hóa

### 3. 👥 Quản Lý Khách Hàng

Quản lý dữ liệu khách hàng toàn diện:
- Hồ sơ khách hàng với thông tin Facebook user
- Theo dõi lịch sử hội thoại
- Custom fields và tags
- Phân khúc theo hành vi
- Xuất dữ liệu khách hàng
- Tuân thủ GDPR

## Bắt Đầu Nhanh

### Yêu Cầu

- .NET 8.0 SDK
- PostgreSQL 15+ (hoặc Neon serverless)
- Redis 7+
- RabbitMQ 3.12+
- Docker & Docker Compose (cho local development)
- **Facebook Page** và **Facebook App** với Messenger Platform
- **OpenAI API Key** hoặc **Azure OpenAI** (cho AI Chatbot)

### Cấu Hình

```bash
# Sao chép template môi trường
cp .env.example .env

# Cập nhật cấu hình
# - DATABASE_URL (PostgreSQL connection string)
# - REDIS_URL
# - RABBITMQ_URL
# - FACEBOOK_VERIFY_TOKEN (webhook verification)
# - FACEBOOK_PAGE_ACCESS_TOKEN (send messages)
# - OPENAI_API_KEY (AI chatbot)
```

### Phát Triển Local

```bash
# Khôi phục dependencies
dotnet restore

# Áp dụng migrations
dotnet ef database update --project src/MktFacebookService.Infrastructure

# Chạy service
dotnet run --project src/MktFacebookService.API

# Service có sẵn tại http://localhost:5000
# Swagger UI: http://localhost:5000/swagger
```

### Triển Khai Docker

```bash
# Build và chạy với Docker Compose
cd deployments/local
docker-compose up -d mkt-facebook-service-net

# Xem logs
docker-compose logs -f mkt-facebook-service-net

# Truy cập qua Traefik
# http://localhost/api/v1/mkt-facebook
```

## Kiến Trúc

```mermaid
graph TD
    subgraph "Bên Ngoài"
        FB[Facebook Messenger Platform]
        OAI[OpenAI / Azure OpenAI]
        User[Người dùng trên Messenger]
    end
    
    subgraph "mkt-facebook-service-net"
        WH[Webhooks Controller]
        API[REST API Controllers]
        APP[Application Layer CQRS]
        DOM[Domain Layer]
        INFRA[Infrastructure Layer]
    end
    
    subgraph "Data Stores"
        PG[(PostgreSQL)]
        RD[(Redis Cache)]
        RMQ[RabbitMQ]
    end
    
    User -->|Gửi Tin nhắn| FB
    FB -->|Webhook Event| WH
    WH -->|Process Message Command| APP
    API -->|Commands/Queries| APP
    APP -->|Business Logic| DOM
    APP -->|Persistence| INFRA
    INFRA -->|EF Core| PG
    INFRA -->|Caching| RD
    INFRA -->|Events| RMQ
    APP -->|Gửi Message| INFRA
    INFRA -->|API Call| FB
    APP -->|AI Completion| INFRA
    INFRA -->|API Call| OAI
    
    style User fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px
    style FB fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
    style OAI fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
    style WH fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
    style API fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
    style APP fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style DOM fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style INFRA fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style PG fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
    style RD fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
    style RMQ fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
```

### Công Nghệ

| Layer | Công Nghệ |
|-------|-----------|
| **Backend** | .NET 8, ASP.NET Core 8 |
| **Architecture** | Clean Architecture, DDD, CQRS |
| **Database** | PostgreSQL 15+, EF Core 8 |
| **Cache** | Redis, StackExchange.Redis |
| **Messaging** | RabbitMQ, MassTransit |
| **HTTP Client** | HttpClient Factory, Polly |
| **AI** | OpenAI SDK, Azure.AI.OpenAI |
| **API Gateway** | Traefik |
| **Documentation** | Swagger/OpenAPI 3.0 |

## API Endpoints

### Public API

| Endpoint | Method | Mô Tả |
|----------|--------|-------|
| `/api/v1/webhooks/facebook` | GET | Facebook webhook verification |
| `/api/v1/webhooks/facebook` | POST | Nhận Facebook Messenger events |
| `/api/v1/conversations` | GET | Danh sách hội thoại |
| `/api/v1/conversations/{id}` | GET | Lấy conversation theo ID |
| `/api/v1/conversations/{id}/messages` | POST | Gửi tin nhắn |
| `/api/v1/customers` | GET | Danh sách khách hàng |
| `/api/v1/customers/{id}` | GET | Chi tiết khách hàng |
| `/api/v1/customers/{id}` | PUT | Cập nhật thông tin khách hàng |

### Admin API

| Endpoint | Method | Mô Tả |
|----------|--------|-------|
| `/api/v1/chatbots/flows` | GET | Danh sách automation flows |
| `/api/v1/chatbots/flows` | POST | Tạo chatbot flow |
| `/api/v1/chatbots/flows/{id}` | PUT | Cập nhật flow |
| `/api/v1/chatbots/flows/{id}` | DELETE | Xóa flow |
| `/api/v1/chatbots/ai-config` | GET | Lấy AI chatbot config |
| `/api/v1/chatbots/ai-config` | PUT | Cập nhật AI config |

### Health & Monitoring

| Endpoint | Mô Tả |
|----------|-------|
| `/health` | Health check endpoint |
| `/swagger` | Swagger UI documentation |

## Tài Liệu

- [Tài Liệu Kiến Trúc](./ARCHITECTURE.md) - System design và domain model
- [Tài Liệu API](./API.md) - API reference đầy đủ với examples
- [Thiết Lập Facebook Messenger](./FACEBOOK_SETUP.md) - Hướng dẫn setup Facebook App
- [Cấu Hình AI Chatbot](./AI_CHATBOT.md) - Hướng dẫn tích hợp AI

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

```
mkt-facebook-service-net/
├── src/
│   ├── MktFacebookService.API/           # API Layer
│   │   ├── Controllers/                  # REST Controllers
│   │   ├── Application/                  # CQRS Commands/Queries
│   │   └── Program.cs                    # Entry point
│   ├── MktFacebookService.Domain/        # Domain Layer
│   │   ├── AggregatesModel/              # Aggregates, Entities
│   │   │   ├── ConversationAggregate/
│   │   │   ├── CustomerAggregate/
│   │   │   └── ChatbotAggregate/
│   │   └── SeedWork/                     # Base classes
│   └── MktFacebookService.Infrastructure/ # Infrastructure Layer
│       ├── Data/                         # EF Core DbContext
│       ├── Repositories/                 # Repository implementations
│       └── ExternalServices/             # Facebook, OpenAI clients
├── tests/
│   ├── MktFacebookService.UnitTests/
│   └── MktFacebookService.FunctionalTests/
├── docs/                                 # Documentation
├── Dockerfile
└── MktFacebookService.slnx
```

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

| Biến | Mô Tả | Mặc Định |
|------|-------|----------|
| `DATABASE_URL` | PostgreSQL connection string | - |
| `REDIS_URL` | Redis connection string | `localhost:6379` |
| `RABBITMQ_URL` | RabbitMQ connection string | `localhost:5672` |
| `FACEBOOK_VERIFY_TOKEN` | Webhook verification token | - |
| `FACEBOOK_PAGE_ACCESS_TOKEN` | Page access token để gửi messages | - |
| `FACEBOOK_API_VERSION` | Facebook API version | `v21.0` |
| `OPENAI_API_KEY` | OpenAI API key | - |
| `OPENAI_MODEL` | Tên OpenAI model | `gpt-4-turbo` |
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint (tùy chọn) | - |
| `ASPNETCORE_ENVIRONMENT` | Môi trường (Development/Production) | `Development` |

## Quy Trình Phát Triển

### Phase 1: Domain Layer
1. Tạo Aggregates (Conversation, Customer, ChatbotFlow, AIChatbotConfig)
2. Định nghĩa Entities và Value Objects
3. Implement business rules trong domain methods
4. Raise Domain Events

### Phase 2: Infrastructure Layer
1. Setup EF Core DbContext và entity configurations
2. Tạo repositories implementing domain interfaces
3. Implement FacebookMessengerClient
4. Implement OpenAIClient với Polly resilience
5. Apply database migrations

### Phase 3: Application Layer (CQRS)
1. Tạo Commands (ProcessIncomingMessage, SendMessage, CreateChatbotFlow)
2. Tạo Queries (GetConversations, GetCustomers)
3. Implement MediatR Handlers
4. Thêm FluentValidation validators
5. Setup Pipeline Behaviors

### Phase 4: API Layer
1. Implement WebhooksController cho Facebook events
2. Tạo REST API Controllers
3. Thêm Swagger annotations
4. Cấu hình authentication & authorization
5. Setup health checks

## Kiểm Thử

```bash
# Chạy tất cả tests
dotnet test

# Chỉ chạy unit tests
dotnet test tests/MktFacebookService.UnitTests/

# Chạy với coverage
dotnet test /p:CollectCoverage=true /p:CoverageReportsFormat=opencover
```

## Đóng Góp

Vui lòng tuân theo [GoodGo Project Rules](../../.agent/skills/project-rules/SKILL.md) và [.NET Microservice Workflow](../../.agent/skills/dotnet-microservice-workflow/SKILL.md).

## License

MIT License

## Tài Nguyên

### Facebook Messenger Platform
- [Tổng Quan Messenger Platform](https://developers.facebook.com/docs/messenger-platform/)
- [Webhook Reference](https://developers.facebook.com/docs/messenger-platform/webhooks)
- [Send API Reference](https://developers.facebook.com/docs/messenger-platform/send-messages)

### OpenAI
- [Tài Liệu OpenAI API](https://platform.openai.com/docs/introduction)
- [Hướng Dẫn Chat Completions](https://platform.openai.com/docs/guides/chat-completions)

### Internal Skills
- [API Design Skill](../../.agent/skills/api-design/SKILL.md)
- [CQRS MediatR Skill](../../.agent/skills/cqrs-mediatr/SKILL.md)
- [Domain-Driven Design Skill](../../.agent/skills/domain-driven-design/SKILL.md)
