Ads Service - Đề Xuất Giải Pháp / Solution Proposal
Mục tiêu / Goal: Xây dựng hệ thống quảng cáo (Ads Service) tương tự Meta Ads, tích hợp vào kiến trúc microservices GoodGo hiện tại.

1. Phân Tích Kiến Trúc Hiện Tại / Current Architecture Analysis
1.1 Điểm Mạnh Có Thể Tái Sử Dụng / Reusable Strengths
Component	Hiện Có / Available	Tái Sử Dụng Cho Ads / Reuse for Ads
IAM Service	✅ User, Organization, Group management	Advertiser accounts, permissions
Wallet Service	✅ Wallet, PointAccount, Transactions	Prepaid/Postpaid billing
Merchant Service	✅ Merchant, Shop management	Advertiser business profiles
Promotion Service	✅ Campaign, Voucher, Redemption	Campaign structure inspiration
Storage Service	✅ File storage	Ad creatives (images, videos)
RabbitMQ/MassTransit	✅ Async messaging	Real-time bidding events
Redis	✅ Caching, Rate limiting	Ad serving cache, frequency capping
1.2 Patterns Hiện Có / Existing Patterns
✅ Clean Architecture (API/Domain/Infrastructure)
✅ CQRS với MediatR
✅ SAGA Pattern cho distributed transactions
✅ Outbox Pattern cho reliable messaging
✅ Repository Pattern với EF Core
✅ Resilient HTTP với Polly
2. Đề Xuất Kiến Trúc Ads Service / Proposed Ads Service Architecture
2.1 Phân Chia Microservices / Microservices Breakdown
Để đáp ứng yêu cầu scale và separation of concerns, đề xuất chia thành 5 microservices:

┌─────────────────────────────────────────────────────────────────────┐
│                        ADS SERVICES ECOSYSTEM                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐      │
│  │  ads-manager    │  │  ads-serving    │  │  ads-billing    │      │
│  │    service      │  │    service      │  │    service      │      │
│  │                 │  │                 │  │                 │      │
│  │ • Campaigns     │  │ • RTB Engine    │  │ • Prepaid       │      │
│  │ • Ad Sets       │  │ • Ad Selection  │  │ • Credit Lines  │      │
│  │ • Ads           │  │ • Pacing        │  │ • Invoicing     │      │
│  │ • Targeting     │  │ • Frequency     │  │ • Thresholds    │      │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘      │
│           │                    │                    │                │
│           └──────────────┬─────┴────────────────────┘                │
│                          │                                           │
│                    ┌─────▼─────┐                                     │
│                    │  RabbitMQ │                                     │
│                    │ Event Bus │                                     │
│                    └─────┬─────┘                                     │
│                          │                                           │
│  ┌─────────────────┐     │     ┌─────────────────┐                  │
│  │  ads-tracking   │◄────┴────►│  ads-analytics  │                  │
│  │    service      │           │    service      │                  │
│  │                 │           │                 │           │
│  │ • Pixel/SDK     │           │ • Reporting     │                  │
│  │ • Attribution   │           │ • Dashboard     │                  │
│  │ • Conversions   │           │ • ROAS          │                  │
│  └─────────────────┘           └─────────────────┘                  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
2.2 Tích Hợp Với Services Hiện Có / Integration with Existing Services
┌─────────────────────────────────────────────────────────────────────┐
│                     INTEGRATION ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  EXISTING SERVICES              ADS SERVICES                         │
│                                                                      │
│  ┌─────────────┐               ┌─────────────┐                       │
│  │ IAM Service │◄─────────────►│ ads-manager │  Advertiser Auth      │
│  └─────────────┘               └─────────────┘                       │
│                                       │                              │
│  ┌─────────────┐                      │                              │
│  │ Merchant    │◄─────────────────────┤  Business Profile            │
│  │ Service     │                      │                              │
│  └─────────────┘                      │                              │
│                                       ▼                              │
│  ┌─────────────┐               ┌─────────────┐                       │
│  │ Wallet      │◄─────────────►│ ads-billing │  Payment Processing   │
│  │ Service     │               └─────────────┘                       │
│  └─────────────┘                      │                              │
│                                       │                              │
│  ┌─────────────┐               ┌─────────────┐                       │
│  │ Storage     │◄─────────────►│ ads-manager │  Creative Assets      │
│  │ Service     │               └─────────────┘                       │
│  └─────────────┘                                                     │
│                                                                      │
│  ┌─────────────┐               ┌─────────────┐                       │
│  │ Social      │◄─────────────►│ ads-serving │  User Interest Data   │
│  │ Service     │               └─────────────┘                       │
│  └─────────────┘                                                     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
3. Domain Model Chi Tiết / Detailed Domain Model
3.1 Ads Manager Service - Campaign Aggregates
┌─────────────────────────────────────────────────────────────────────┐
│                     ads-manager-service                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  AggregatesModel/                                                    │
│  ├── AdvertiserAggregate/                                            │
│  │   ├── Advertiser.cs          (Root - links to IAM User)          │
│  │   ├── AdvertiserSettings.cs  (Timezone, Currency, etc.)          │
│  │   └── AdvertiserStatus.cs    (Active, Suspended, etc.)           │
│  │                                                                   │
│  ├── CampaignAggregate/                                              │
│  │   ├── Campaign.cs            (Root)                               │
│  │   ├── CampaignObjective.cs   (ValueObject: Awareness, Traffic...) │
│  │   ├── CampaignStatus.cs      (Draft, Active, Paused, Completed)  │
│  │   └── CampaignBudget.cs      (Daily/Lifetime, Amount)            │
│  │                                                                   │
│  ├── AdSetAggregate/                                                 │
│  │   ├── AdSet.cs               (Root)                               │
│  │   ├── Targeting.cs           (Core + Interest + Custom)          │
│  │   ├── Placement.cs           (ValueObject: Feed, Story, etc.)    │
│  │   ├── Schedule.cs            (Start/End dates, dayparting)       │
│  │   ├── BidStrategy.cs         (CPC, CPM, OCPM, Target Cost)       │
│  │   └── AdSetBudget.cs         (Daily/Lifetime, Pacing)            │
│  │                                                                   │
│  ├── AdAggregate/                                                    │
│  │   ├── Ad.cs                  (Root)                               │
│  │   ├── AdFormat.cs            (Image, Video, Carousel, etc.)      │
│  │   ├── AdCreative.cs          (Media, Headline, CTA)              │
│  │   ├── AdReviewStatus.cs      (Pending, Approved, Rejected)       │
│  │   └── AdDestination.cs       (URL, App Deep Link)                │
│  │                                                                   │
│  └── AudienceAggregate/                                              │
│      ├── CustomAudience.cs      (Uploaded lists, Retargeting)       │
│      ├── LookalikeAudience.cs   (Similarity %, Source audience)     │
│      └── SavedAudience.cs       (Reusable targeting templates)      │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
3.2 Ads Serving Service - RTB Aggregates
┌─────────────────────────────────────────────────────────────────────┐
│                     ads-serving-service                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  AggregatesModel/                                                    │
│  ├── AdRequestAggregate/                                             │
│  │   ├── AdRequest.cs           (User context, placement, etc.)     │
│  │   └── UserContext.cs         (Demographics, interests, device)   │
│  │                                                                   │
│  ├── AuctionAggregate/                                               │
│  │   ├── Auction.cs             (Root - single ad auction)          │
│  │   ├── Bid.cs                 (Entity - each candidate ad)        │
│  │   ├── AuctionResult.cs       (Winner, final price)               │
│  │   └── eCPMCalculator.cs      (Bid × Predicted CTR + Quality)     │
│  │                                                                   │
│  ├── PacingAggregate/                                                │
│  │   ├── BudgetPacer.cs         (Smooth vs Accelerated spending)    │
│  │   └── SpendTracker.cs        (Real-time budget consumption)      │
│  │                                                                   │
│  └── FrequencyAggregate/                                             │
│      ├── FrequencyCap.cs        (Max impressions per user/day)      │
│      └── UserAdHistory.cs       (Redis-backed user ad views)        │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
3.3 Ads Billing Service - Financial Aggregates
┌─────────────────────────────────────────────────────────────────────┐
│                     ads-billing-service                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  AggregatesModel/                                                    │
│  ├── BillingAccountAggregate/                                        │
│  │   ├── BillingAccount.cs      (Root - links to Wallet)            │
│  │   ├── PaymentMethod.cs       (Credit Card, Bank, Wallet)         │
│  │   └── BillingThreshold.cs    (Auto-charge at $25, $50, etc.)     │
│  │                                                                   │
│  ├── CreditLineAggregate/                                            │
│  │   ├── CreditLine.cs          (Postpaid limit)                    │
│  │   ├── CreditEvaluation.cs    (Trust score calculation)           │
│  │   └── PaymentHistory.cs      (Track payment reliability)         │
│  │                                                                   │
│  ├── InvoiceAggregate/                                               │
│  │   ├── Invoice.cs             (Root)                               │
│  │   ├── InvoiceLineItem.cs     (Per-campaign charges)              │
│  │   └── TaxCalculation.cs      (VAT by region)                     │
│  │                                                                   │
│  └── ChargeAggregate/                                                │
│      ├── AdCharge.cs            (Individual impression/click cost)  │
│      └── DailySpendSummary.cs   (Aggregated daily charges)          │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
3.4 Ads Tracking Service - Attribution Aggregates
┌─────────────────────────────────────────────────────────────────────┐
│                     ads-tracking-service                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  AggregatesModel/                                                    │
│  ├── TrackingPixelAggregate/                                         │
│  │   ├── TrackingPixel.cs       (Root - unique pixel per advertiser)│
│  │   └── PixelEvent.cs          (PageView, AddToCart, Purchase)     │
│  │                                                                   │
│  ├── ConversionAggregate/                                            │
│  │   ├── Conversion.cs          (Root - actual conversion event)    │
│  │   ├── ConversionValue.cs     (Revenue amount)                    │
│  │   └── ConversionWindow.cs    (1-day, 7-day, 28-day)              │
│  │                                                                   │
│  └── AttributionAggregate/                                           │
│      ├── Attribution.cs         (Links conversion to ad)            │
│      ├── AttributionModel.cs    (Last-click, First-click, Linear)   │
│      └── TouchPoint.cs          (Each ad interaction in journey)    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
3.5 Ads Analytics Service - Reporting Aggregates
┌─────────────────────────────────────────────────────────────────────┐
│                     ads-analytics-service                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  AggregatesModel/                                                    │
│  ├── MetricsAggregate/                                               │
│  │   ├── CampaignMetrics.cs     (Impressions, Clicks, CTR, etc.)    │
│  │   ├── AdSetMetrics.cs        (Per-targeting performance)         │
│  │   └── AdMetrics.cs           (Per-creative performance)          │
│  │                                                                   │
│  ├── ReportAggregate/                                                │
│  │   ├── Report.cs              (Root - scheduled/custom reports)   │
│  │   ├── ReportSchedule.cs      (Daily, Weekly, Monthly)            │
│  │   └── ReportExport.cs        (CSV, Excel, PDF)                   │
│  │                                                                   │
│  └── InsightAggregate/                                               │
│      ├── AudienceInsight.cs     (Demographics of reached users)     │
│      └── PerformanceInsight.cs  (Recommendations, trends)           │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
4. Data Flow & Communication Patterns
4.1 Ad Serving Flow (< 100ms target)
┌─────────────────────────────────────────────────────────────────────┐
│                     AD SERVING FLOW (< 100ms)                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   User App/Web                                                       │
│       │                                                              │
│       │ 1. Request ad slot                                           │
│       ▼                                                              │
│   ┌─────────────────┐                                                │
│   │ Traefik Gateway │                                                │
│   └────────┬────────┘                                                │
│            │ 2. Route to ads-serving                                 │
│            ▼                                                         │
│   ┌─────────────────┐    3. Check cache    ┌─────────────────┐      │
│   │  ads-serving    │◄────────────────────►│     Redis       │      │
│   │    service      │    (user freq, ads)  │  (< 5ms cache)  │      │
│   └────────┬────────┘                      └─────────────────┘      │
│            │                                                         │
│            │ 4. Run RTB auction (in-memory)                          │
│            │    • Filter by targeting                                │
│            │    • Calculate eCPM for each candidate                  │
│            │    • Apply pacing & frequency caps                      │
│            │    • Select winner                                      │
│            │                                                         │
│            │ 5. Return winning ad                                    │
│            ▼                                                         │
│   User sees ad                                                       │
│       │                                                              │
│       │ 6. Fire impression/click events (async)                      │
│       ▼                                                              │
│   ┌─────────────────┐                                                │
│   │    RabbitMQ     │                                                │
│   └────────┬────────┘                                                │
│            │                                                         │
│   ┌────────┴────────┬─────────────────┐                              │
│   ▼                 ▼                 ▼                              │
│ ads-tracking    ads-billing     ads-analytics                        │
│ (attribution)   (charge $)      (metrics)                            │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
4.2 Integration Events
// ads-serving → ads-billing
public record AdImpressionChargedEvent(
    Guid AdId, Guid CampaignId, Guid AdvertiserId,
    decimal Cost, DateTime ChargedAt);
// ads-serving → ads-tracking
public record AdImpressionTrackedEvent(
    Guid AdId, Guid UserId, string Placement,
    Dictionary<string, string> UserContext, DateTime TrackedAt);
// ads-tracking → ads-analytics
public record ConversionAttributedEvent(
    Guid ConversionId, Guid AdId, Guid CampaignId,
    decimal ConversionValue, string AttributionModel);
// ads-billing → wallet-service (existing)
public record WalletDebitRequestedEvent(
    Guid WalletId, decimal Amount, string Description,
    Guid ReferenceId, string ReferenceType);
5. Phân Giai Đoạn Triển Khai / Implementation Phases
Phase 1: MVP (4-6 tuần / weeks)
Domain	Features
ads-manager	Campaign/AdSet/Ad CRUD, Basic targeting (location, age, gender)
ads-billing	Prepaid only, Simple charge per impression/click
ads-serving	Basic ad selection, CPC/CPM fixed bidding, No RTB
ads-tracking	Click tracking only, Simple attribution
ads-analytics	Basic metrics (impressions, clicks, CTR)
Tech Focus:

Clean Architecture như services hiện có
MediatR commands/queries
EF Core với PostgreSQL
Basic Redis caching
Phase 2: Core Features (6-8 tuần / weeks)
Domain	Features
ads-manager	Interest targeting, Custom Audiences, Lookalike (basic)
ads-billing	Postpaid với Credit Lines, Threshold billing
ads-serving	Real-time bidding engine, Pacing algorithm, Frequency capping
ads-tracking	Pixel tracking, Server-side conversions, Multi-touch attribution
ads-analytics	Real-time dashboard, Campaign insights
Tech Focus:

MassTransit/RabbitMQ cho async events
Redis Sorted Sets cho frequency tracking
SAGA pattern cho billing flows
Grafana dashboards
Phase 3: Advanced Meta-like (8-12 tuần / weeks)
Domain	Features
ads-manager	AI-based Lookalike, Dynamic Ads, A/B testing
ads-billing	Multi-currency, Tax compliance, Invoice automation
ads-serving	OCPM optimization, Predictive CTR models, ML ranking
ads-tracking	Cross-device tracking, SKAdNetwork integration
ads-analytics	Audience insights, Lift studies, Attribution modeling
Tech Focus:

ML pipeline (recommendation, CTR prediction)
Event Sourcing cho audit trails
ClickHouse/TimescaleDB cho analytics
Kubernetes auto-scaling
6. Database Strategy
6.1 Database Per Service
Service	Database	Reason
ads-manager	PostgreSQL (Neon)	ACID for campaign management
ads-serving	Redis (primary) + PostgreSQL (backup)	Speed for real-time bidding
ads-billing	PostgreSQL (Neon)	Financial accuracy, ACID
ads-tracking	TimescaleDB	Time-series data for events
ads-analytics	ClickHouse	OLAP for aggregations
6.2 Caching Strategy
┌─────────────────────────────────────────────────────────────────────┐
│                        REDIS CACHING LAYERS                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Layer 1: Hot Ads Cache                                              │
│  Key: "ads:active:{placementType}"                                   │
│  TTL: 5 minutes                                                      │
│  Type: Sorted Set (by eCPM score)                                    │
│                                                                      │
│  Layer 2: User Frequency                                             │
│  Key: "freq:{userId}:{date}"                                         │
│  TTL: 24 hours                                                       │
│  Type: Hash (adId → impressionCount)                                 │
│                                                                      │
│  Layer 3: Budget Tracker                                             │
│  Key: "budget:{campaignId}:{date}"                                   │
│  TTL: 24 hours                                                       │
│  Type: String (atomic increment)                                     │
│                                                                      │
│  Layer 4: Targeting Index                                            │
│  Key: "target:{targetingCriteria}"                                   │
│  TTL: 1 hour                                                         │
│  Type: Set (eligible adSetIds)                                       │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
7. API Design Overview
7.1 Ads Manager API
# Campaigns
POST   /api/v1/ads-manager/campaigns
GET    /api/v1/ads-manager/campaigns
GET    /api/v1/ads-manager/campaigns/{id}
PATCH  /api/v1/ads-manager/campaigns/{id}
DELETE /api/v1/ads-manager/campaigns/{id}
POST   /api/v1/ads-manager/campaigns/{id}/duplicate
# Ad Sets
POST   /api/v1/ads-manager/campaigns/{campaignId}/adsets
GET    /api/v1/ads-manager/adsets/{id}
PATCH  /api/v1/ads-manager/adsets/{id}
# Ads
POST   /api/v1/ads-manager/adsets/{adSetId}/ads
GET    /api/v1/ads-manager/ads/{id}
PATCH  /api/v1/ads-manager/ads/{id}
# Audiences
POST   /api/v1/ads-manager/audiences/custom
POST   /api/v1/ads-manager/audiences/lookalike
GET    /api/v1/ads-manager/audiences
7.2 Ads Serving API
# Real-time ad request (optimized for speed)
POST   /api/v1/ads/serve  # Returns selected ad for placement
# Event tracking (async, fire-and-forget)
POST   /api/v1/ads/events/impression
POST   /api/v1/ads/events/click
7.3 Ads Analytics API
# Reporting
GET    /api/v1/ads-analytics/campaigns/{id}/metrics
GET    /api/v1/ads-analytics/campaigns/{id}/breakdown?by=age,gender
GET    /api/v1/ads-analytics/insights/audience
POST   /api/v1/ads-analytics/reports/schedule
8. Tóm Tắt Đề Xuất / Summary
8.1 Key Decisions
Decision	Choice	Rationale
Architecture	5 separate microservices	Separation of concerns, independent scaling
Ad Selection	eCPM-based RTB	Industry standard, balances revenue & relevance
Billing	Wallet Service integration	Reuse existing payment infrastructure
Storage	Multi-DB (PostgreSQL + Redis + Time-series)	Optimal for each workload
Events	MassTransit/RabbitMQ	Existing pattern, reliable async processing
8.2 Lợi Ích / Benefits
Tái sử dụng tối đa / Maximum Reuse: Tích hợp với IAM, Wallet, Merchant, Storage đã có
Scale độc lập / Independent Scaling: ads-serving có thể scale riêng cho traffic cao
Nhất quán patterns / Consistent Patterns: Giữ Clean Architecture, CQRS, MediatR như dự án hiện có
Phân giai đoạn rõ ràng / Clear Phases: MVP → Core → Advanced theo lộ trình
8.3 Rủi Ro & Giải Pháp / Risks & Mitigations
Risk	Impact	Mitigation
Ad serving latency > 100ms	Poor UX	Aggressive Redis caching, precomputed scores
Budget overspend	Financial loss	Atomic Redis counters, pessimistic locking
Invalid ad charges	Billing disputes	Event sourcing, comprehensive audit trail
Ad review bottleneck	Slow go-live	AI-first review with human escalation
9. Câu Hỏi Cần Làm Rõ / Questions to Clarify
Targeting data source: Dữ liệu Interest/Behavior sẽ lấy từ đâu? (Social Service, external data providers?)
Payment methods: Ngoài Wallet hiện có, cần hỗ trợ Credit Card, Bank transfer?
Ad placements: Quảng cáo sẽ hiển thị ở đâu? (GoodGo app, partner apps, websites?)
MVV (Minimum Viable Version): MVP nên tập trung vào segment nào? (SMB advertisers, Enterprise?)
Compliance: Có yêu cầu đặc biệt về data privacy (GDPR, local laws)?
Next Step: Sau khi được approve, sẽ tạo implementation plan chi tiết cho Phase 1 (MVP) với task breakdown, domain models, và API specifications cụ thể.