diff --git a/ads.md b/ads.md deleted file mode 100644 index 77c7055b..00000000 --- a/ads.md +++ /dev/null @@ -1,411 +0,0 @@ -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 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ể. \ No newline at end of file