pos-system/services/ads-manager-service-net/docs/vi/README.md

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

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

2. Chạy Local

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

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

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

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

Triển Khai

Docker Build

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
• Architecture Guide
• API Documentation

Giấy Phép

Độc quyền - GoodGo Platform