# Ads Manager Service - Dịch vụ Quản lý Quảng cáo

> Microservice quản lý chiến dịch, nhóm quảng cáo, và mẫu quảng cáo theo mô hình 3 cấp độ tương tự Meta Ads.

## Tổng Quan

Ads Manager Service là trung tâm quản lý của hệ thống quảng cáo GoodGo, cho phép nhà quảng cáo:

- **Tạo và quản lý Campaigns** - Thiết lập mục tiêu chiến dịch (Awareness, Traffic, Conversion)
- **Cấu hình Ad Sets** - Nhắm mục tiêu, ngân sách, lịch chạy, vị trí hiển thị
- **Thiết kế Ads** - Tải lên creatives, viết nội dung, chọn CTA
- **Quản lý Audiences** - Custom Audiences, Lookalike Audiences

## Yêu Cầu

| Yêu cầu | Phiên bản |
|---------|-----------|
| .NET SDK | 10.0.101+ |
| Docker | 24.0+ |
| PostgreSQL | 15+ |

## Bắt Đầu Nhanh

### 1. Chạy với Docker

```bash
cd services/ads-manager-service-net
docker-compose up -d
```

### 2. Chạy Local

```bash
dotnet restore
dotnet build
dotnet run --project src/AdsManagerService.API
```

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

```
ads-manager-service-net/
├── src/
│   ├── AdsManagerService.API/           # Lớp Presentation
│   │   ├── Controllers/                 # API endpoints
│   │   │   ├── CampaignsController.cs
│   │   │   ├── AdSetsController.cs
│   │   │   ├── AdsController.cs
│   │   │   └── AudiencesController.cs
│   │   └── Application/                 # CQRS Commands/Queries
│   │
│   ├── AdsManagerService.Domain/        # Business logic
│   │   └── AggregatesModel/
│   │       ├── AdvertiserAggregate/     # Nhà quảng cáo
│   │       ├── CampaignAggregate/       # Chiến dịch
│   │       ├── AdSetAggregate/          # Nhóm quảng cáo
│   │       ├── AdAggregate/             # Mẫu quảng cáo
│   │       └── AudienceAggregate/       # Đối tượng mục tiêu
│   │
│   └── AdsManagerService.Infrastructure/ # Data access
│
├── tests/
├── docs/
├── Dockerfile
└── AdsManagerService.slnx
```

## Domain Model

### Cấu Trúc 3 Cấp Độ

```
Campaign (Chiến dịch)
    │
    ├── Objective (Mục tiêu)
    ├── Status (Draft/Active/Paused/Completed)
    └── Budget (Ngân sách tổng)
        │
        ├── AdSet 1 (Nhóm quảng cáo)
        │   ├── Targeting (Nhắm mục tiêu)
        │   ├── Placement (Vị trí)
        │   ├── Schedule (Lịch chạy)
        │   └── BidStrategy (Chiến lược giá thầu)
        │       │
        │       ├── Ad 1 (Mẫu quảng cáo)
        │       │   ├── Creative (Hình/Video)
        │       │   ├── Headline (Tiêu đề)
        │       │   └── CTA (Call-to-Action)
        │       │
        │       └── Ad 2
        │
        └── AdSet 2
            └── ...
```

### Targeting Options

| Loại | Mô tả | Ví dụ |
|------|-------|-------|
| **Core Audience** | Nhân khẩu học | Tuổi 18-35, Nữ, HCM |
| **Interest** | Sở thích | Thể thao, Công nghệ |
| **Behavior** | Hành vi | Mua sắm online |
| **Custom Audience** | Danh sách có sẵn | Email/SĐT khách hàng |
| **Lookalike** | Tương tự | 1% giống khách VIP |

## Các Endpoint API

### Campaigns

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `POST` | `/api/v1/ads-manager/campaigns` | Tạo chiến dịch |
| `GET` | `/api/v1/ads-manager/campaigns` | Danh sách chiến dịch |
| `GET` | `/api/v1/ads-manager/campaigns/{id}` | Chi tiết chiến dịch |
| `PATCH` | `/api/v1/ads-manager/campaigns/{id}` | Cập nhật chiến dịch |
| `DELETE` | `/api/v1/ads-manager/campaigns/{id}` | Xóa chiến dịch |
| `POST` | `/api/v1/ads-manager/campaigns/{id}/duplicate` | Nhân bản |

### Ad Sets

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `POST` | `/api/v1/ads-manager/campaigns/{campaignId}/adsets` | Tạo Ad Set |
| `GET` | `/api/v1/ads-manager/adsets/{id}` | Chi tiết Ad Set |
| `PATCH` | `/api/v1/ads-manager/adsets/{id}` | Cập nhật Ad Set |
| `PATCH` | `/api/v1/ads-manager/adsets/{id}/targeting` | Cập nhật targeting |

### Ads

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `POST` | `/api/v1/ads-manager/adsets/{adSetId}/ads` | Tạo Ad |
| `GET` | `/api/v1/ads-manager/ads/{id}` | Chi tiết Ad |
| `PATCH` | `/api/v1/ads-manager/ads/{id}` | Cập nhật Ad |
| `POST` | `/api/v1/ads-manager/ads/{id}/submit-review` | Gửi duyệt |

### Audiences

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `POST` | `/api/v1/ads-manager/audiences/custom` | Tạo Custom Audience |
| `POST` | `/api/v1/ads-manager/audiences/lookalike` | Tạo Lookalike |
| `GET` | `/api/v1/ads-manager/audiences` | Danh sách audiences |

### Health Endpoints

| Endpoint | Mục Đích |
|----------|----------|
| `/health` | Trạng thái đầy đủ |
| `/health/live` | Kiểm tra sống |
| `/health/ready` | Kiểm tra sẵn sàng |

## Tích Hợp

### Services Liên Quan

| Service | Tích hợp |
|---------|---------|
| **IAM Service** | Xác thực Advertiser |
| **Storage Service** | Lưu trữ creatives (ảnh, video) |
| **ads-billing-service** | Kiểm tra ngân sách |
| **ads-serving-service** | Publish active ads |

### Integration Events

```csharp
// Phát khi campaign được kích hoạt
CampaignActivatedIntegrationEvent

// Phát khi ad được approve
AdApprovedIntegrationEvent

// Phát khi targeting thay đổi
AdSetTargetingUpdatedIntegrationEvent
```

## Cấu Hình

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

| Biến | Mô tả | Mặc định |
|------|-------|----------|
| `DATABASE_URL` | PostgreSQL connection | - |
| `REDIS_URL` | Redis connection | - |
| `STORAGE_SERVICE_URL` | URL của Storage Service | - |
| `IAM_SERVICE_URL` | URL của IAM Service | - |

## Kiểm Thử

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

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

## Triển Khai

### Docker Build

```bash
docker build -t ads-manager-service:latest .
docker run -p 5000:8080 --env-file .env ads-manager-service:latest
```

## Tài Nguyên

- [Ads Services Proposal](../../docs/ads-services-proposal.md)
- [Architecture Guide](./ARCHITECTURE.md)
- [API Documentation](./api/openapi.yaml)

## Giấy Phép

Độc quyền - GoodGo Platform
