411 lines
33 KiB
Markdown
411 lines
33 KiB
Markdown
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ể. |