pos-system/ads.md

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ể.