[DDD] Thiết kế Chi tiết Modal Quảng bá Video

Tóm tắt tài liệu

Tài liệu này mô tả thiết kế kỹ thuật chi tiết cho Modal Quảng bá Video (Boost Video Modal). Component này cho phép người dùng tạo campaign quảng bá cho video bất động sản của họ với các tùy chọn về ngân sách, thời gian, vị trí hiển thị, và phương thức thanh toán. Modal được thiết kế với 3 bước chính: cấu hình campaign, xem lại và thanh toán.

1. Tổng quan (Overview)

1.1. Bối cảnh và Vấn đề

Trong hệ sinh thái bất động sản, khả năng tiếp cận khách hàng tiềm năng là yếu tố quyết định thành công của mỗi video quảng cáo. Người tạo nội dung cần một công cụ hiệu quả để tăng tầm nhìn (visibility) cho các video bất động sản của họ.

Các thách thức cụ thể:

Cạnh tranh khốc liệt: Hàng ngàn video bất động sản được tải lên hàng ngày, việc nổi bật trong feeds trở nên khó khăn
Tối ưu ngân sách quảng cáo: Người dùng cần công cụ để tối ưu ROI từ việc boost video với ngân sách hạn chế
Targeting chính xác: Cần nhắm đúng đối tượng quan tâm đến loại BDS cụ thể (Villa, Apartment, Shophouse) tại địa điểm phù hợp
Đo lường hiệu quả: Thiếu insight về performance của campaign boost để điều chỉnh strategy
Thanh toán đa dạng: Cần hỗ trợ nhiều phương thức thanh toán phù hợp với thị trường Việt Nam
Trải nghiệm đơn giản: Process boost phải đơn giản, nhanh chóng để không cản trở workflow của content creator

1.2. Mục tiêu & Phi mục tiêu (Goals and Non-Goals)

Mục tiêu (Goals)

Cấu hình Campaign:

Thiết lập ngân sách campaign với các gói được định nghĩa sẵn và custom budget
Chọn thời gian chạy campaign (1 ngày, 3 ngày, 7 ngày, custom)
Target theo vị trí địa lý (thành phố, quận/huyện, bán kính)
Targeting audience theo độ tuổi, sở thích, hành vi

Hiển thị và Preview:

Preview video trong modal với player functionality
Ước tính reach và impression dựa trên budget
Hiển thị expected performance metrics
Timeline dự kiến của campaign

Thanh toán và Xác nhận:

Hỗ trợ multiple payment methods (Credit Card, PayPal, Crypto)
Tích hợp hệ thống credit/wallet nội bộ
Xác nhận và launch campaign ngay lập tức
Receipt và tracking campaign sau khi thanh toán thành công

Quản lý và Theo dõi:

Campaign status tracking (Active, Paused, Completed)
Real-time performance metrics
Pause/Resume campaign functionality
Budget adjustment capabilities

Phi mục tiêu (Non-Goals)

Advanced audience analytics (sẽ có trong analytics dashboard riêng)
A/B testing multiple creative versions (phase 2)
Scheduling campaign start time (launch immediately only)
Detailed competitor analysis
Custom audience creation từ CSV upload

2. Kiến trúc Tổng thể (Overall Architecture)

Modal được thiết kế theo pattern multi-step wizard với state management tập trung và API integration points rõ ràng.

3. Thiết kế Chi tiết (Detailed Design)

3.1. Thiết kế Giao diện & Luồng người dùng (UI & User Flow)

Header:

Close button (X)
Progress indicator (Step 1/3, 2/3, 3/3)
Title: "Boost Your Video" với subtitle dynamic theo step

Body Content (varies by step):

Step 1: Campaign Configuration
Step 2: Review & Estimation
Step 3: Payment & Confirmation

Footer:

Back button (trừ step 1)
Cancel button
Next/Continue/Confirm button
Loading states khi process

Step 1: Campaign Setup Layout

Header Section

Title: "Boost Your Video - Step 1 of 3"
Close Button: [X] positioned top-right

Main Content Area (Two-Column Layout)

Left Column: Video Preview

Video Player Component
- Thumbnail display
- Play button overlay (▶️)
- Video dimensions: responsive
Video Information
- Title: "Villa..." (truncated)
- Price: "2.3B VND"

Right Column: Campaign Configuration

Budget Selection Section

Radio button options:
- ○ Basic - 500K VND (1-3 days)
- ○ Standard - 1M VND (3-7 days)
- ○ Premium - 2M VND (7-14 days)
- ○ Custom Budget: [Input field] VND

Duration Section

Dropdown selector: "7 days▼"
Options: 1, 3, 7, 14, 30 days

Location Targeting Section

Current selection: 📍 Đà Nẵng
Add more button: "+ Add more locations"
Supports multiple location selection

Cancel Button: Left-aligned
Next Step Button: Right-aligned, primary style

Step 2: Review & Preview Layout

Header Section

Title: "Boost Your Video - Step 2 of 3"
Close Button: [X] positioned top-right

Main Content Area (Single Column Layout)

Campaign Summary Section

Budget: 1,000,000 VND
Duration: 7 days (July 23 - July 30, 2025)
Location: Đà Nẵng, Hội An
Audience: 25-45 years old, Real Estate Interest

Expected Performance Section

Estimated Reach: 👥 15,000 - 25,000 people
Expected Views: 👀 3,000 - 5,000 views
Predicted Engagement: 💬 150 - 300 interactions
Metrics: 📊 CPM: ~40 VND | CPC: ~200 VND

Important Notice

Warning: ⚠️ Your campaign will start immediately after payment

Back Button: Left-aligned
Continue Button: "Continue to Payment" - Right-aligned, primary style

Step 3: Payment Layout

Header Section

Title: "Boost Your Video - Step 3 of 3"
Close Button: [X] positioned top-right

Main Content Area (Single Column Layout)

Payment Method Section

Radio button options:
- ○ Credit/Debit Card 💳
- ○ PayPal 💙
- ○ Account Balance 💰 (Current: 2,500,000 VND)
- ○ Crypto Payment ₿

Payment Details Section

Campaign Budget: 1,000,000 VND
Platform Fee (5%): 50,000 VND
Total Amount: 1,050,000 VND

Conditional Form Section

Credit Card Form: Displays when card payment selected
Form Fields: Card number, expiry, CVC, name

Back Button: Left-aligned
Confirm Button: "Confirm & Pay" - Right-aligned, primary style

State Management Interface:

interface BoostVideoModalState {
// Modal control
isOpen: boolean;
currentStep: 1 | 2 | 3;
isProcessing: boolean;

// Campaign configuration
campaignConfig: {
videoId: string;
budget: {
type: 'basic' | 'standard' | 'premium' | 'custom';
amount: number;
currency: 'VND';
};
duration: {
value: number;
unit: 'days';
startDate: Date;
endDate: Date;
};
targeting: {
locations: Array<{
id: string;
name: string;
type: 'city' | 'district' | 'radius';
}>;
audience: {
ageRange: { min: number; max: number };
interests: string[];
behaviors: string[];
};
};
};

// Performance estimation
estimation: {
reach: { min: number; max: number };
views: { min: number; max: number };
engagement: { min: number; max: number };
cpm: number;
cpc: number;
} | null;

// Payment
payment: {
method: 'card' | 'paypal' | 'balance' | 'crypto';
totalAmount: number;
platformFee: number;
cardDetails?: {
number: string;
expiry: string;
cvc: string;
name: string;
};
};

// Error handling
errors: {
[field: string]: string;
};
}

User Flow Chi tiết:

Khởi tạo Modal:
- User click "Boost" button từ video card/row
- Modal open với video info pre-loaded
- Default values cho budget (Standard), duration (7 days)
- Fetch user's location và available balance
Step 1 - Configuration:
- User chọn budget preset hoặc custom amount
- Select duration từ dropdown
- Configure location targeting với autocomplete
- Optional: Advanced audience targeting
- Validation real-time cho required fields
- Next button enable khi có minimum config
Step 2 - Review:
- Display campaign summary với computed values
- Call estimation API với current config
- Show loading skeleton cho estimates
- Display performance predictions với range values
- User có thể back để adjust settings
- Continue button navigate đến payment
Step 3 - Payment:
- Display payment methods với current balance
- Form validation cho payment details
- Real-time total calculation với fees
- Process payment qua gateway
- Show success/error states
- Auto-close modal sau successful payment

3.2. Thiết kế API (API Design)

Campaign Estimation API

Endpoint: POST /api/v1/campaigns/estimate

Request:

{
"video_id": "3110ddbe-c4f1-4182-ac73-dff7153bb836",
"budget": {
"amount": 1000000,
"currency": "VND"
},
"duration_days": 7,
"targeting": {
"locations": [
{
"id": "city_da_nang",
"name": "Đà Nẵng",
"type": "city"
}
],
"audience": {
"age_range": {
"min": 25,
"max": 45
},
"interests": ["real_estate", "investment", "property"],
"behaviors": ["property_seekers", "investors"]
}
}
}

Response:

{
"success": true,
"message": "Campaign estimation generated successfully",
"data": {
"estimation_id": "est_123456789",
"performance": {
"reach": {
"min": 15000,
"max": 25000
},
"views": {
"min": 3000,
"max": 5000
},
"engagement": {
"min": 150,
"max": 300
}
},
"metrics": {
"cpm": 40.5,
"cpc": 200.0,
"engagement_rate": 0.05
},
"timeline": {
"start_date": "2025-07-23T10:00:00Z",
"end_date": "2025-07-30T10:00:00Z",
"peak_hours": ["18:00-22:00", "12:00-14:00"]
},
"budget_breakdown": {
"campaign_budget": 1000000,
"platform_fee": 50000,
"estimated_daily_spend": 142857
}
}
}

Campaign Creation API

Endpoint: POST /api/v1/campaigns/create

Request:

{
"estimation_id": "est_123456789",
"video_id": "3110ddbe-c4f1-4182-ac73-dff7153bb836",
"campaign_config": {
"name": "Villa Boost Campaign - July 2025",
"budget": {
"amount": 1000000,
"currency": "VND"
},
"duration_days": 7,
"targeting": {
"locations": ["city_da_nang"],
"audience": {
"age_range": { "min": 25, "max": 45 },
"interests": ["real_estate", "investment"],
"behaviors": ["property_seekers"]
}
}
},
"payment": {
"method": "balance",
"amount": 1050000,
"payment_token": "pay_abc123xyz"
}
}

Response:

{
"success": true,
"message": "Campaign created and launched successfully",
"data": {
"campaign_id": "camp_987654321",
"status": "active",
"launch_time": "2025-07-23T10:19:00Z",
"tracking_url": "/dashboard/campaigns/camp_987654321",
"payment": {
"transaction_id": "txn_456789123",
"status": "completed",
"amount_charged": 1050000,
"receipt_url": "https://receipts.example.com/txn_456789123"
}
}
}

Location Targeting API

Endpoint: GET /api/v1/targeting/locations?query={search}

Query Parameters:

interface LocationParams {
query: string; // "da nang", "hoi an"
type?: 'city' | 'district' | 'all';
country?: 'VN';
limit?: number;
}

Response:

{
"success": true,
"message": "Locations retrieved successfully",
"data": {
"locations": [
{
"id": "city_da_nang",
"name": "Đà Nẵng",
"type": "city",
"population": 1134000,
"suggested_budget": {
"min": 500000,
"max": 2000000
}
},
{
"id": "district_hai_chau",
"name": "Hải Châu, Đà Nẵng",
"type": "district",
"population": 350000,
"suggested_budget": {
"min": 200000,
"max": 800000
}
}
]
}
}

Payment Processing API

Endpoint: POST /api/v1/payments/process

Request:

{
"campaign_id": "camp_987654321",
"payment_method": "card",
"amount": 1050000,
"currency": "VND",
"payment_details": {
"card_token": "tok_visa_1234567890123456",
"billing_address": {
"country": "VN",
"city": "Da Nang"
}
}
}

Response:

{
"data": {
"transaction_id": "txn_456789123",
"status": "completed",
"amount_charged": 1050000,
"payment_method": "card_ending_1234",
"receipt": {
"id": "receipt_789123456",
"url": "https://receipts.example.com/receipt_789123456.pdf",
"email_sent": true
},
"campaign_status": "active"
}
}

User Balance API

Endpoint: GET /api/v1/users/balance

Response:

{
"success": true,
"message": "User balance retrieved successfully",
"data": {
"current_balance": 2500000,
"currency": "VND",
"pending_amount": 0,
"last_updated": "2025-07-23T09:30:00Z",
"transactions_count": 45,
"top_up_methods": ["card", "bank_transfer", "paypal"]
}
}

4. Các yếu tố phi chức năng (Non-Functional Requirements)

4.1. Hiệu suất (Performance)

Modal Loading: Lazy load payment components, < 200ms modal open time
API Calls: Debounced location search (500ms), cached estimation results
Video Preview: Optimized video loading với quality selection
Form Validation: Real-time validation không block UI
Target Metrics:
- Modal open < 200ms
- Step transition < 100ms
- API responses < 800ms

4.2. Bảo mật (Security)

Payment Security: PCI DSS compliant payment processing
Token Management: Secure payment tokenization, no raw card data storage
API Security: JWT authentication, request signing cho payment APIs
Input Validation: Comprehensive validation cho budget và targeting parameters
Fraud Prevention: Rate limiting cho campaign creation, suspicious activity detection

4.3. Khả năng mở rộng (Scalability)

Campaign Volume: Support batch campaign creation
Payment Processing: Asynchronous payment processing với retry logic
Estimation Caching: Redis caching cho frequently requested estimations
Multi-currency: Extensible design cho additional currencies

4.4. Trải nghiệm người dùng (UX)

Responsive Design: Optimized cho mobile với simplified steps
Progressive Enhancement: Graceful degradation khi JavaScript disabled
Error Recovery: Clear error messages với suggested actions
Loading States: Skeleton loading cho mọi async operations
Accessibility: WCAG 2.1 AA compliance, keyboard navigation
Animation: Smooth transitions giữa steps, microinteractions

4.5. Tương thích (Compatibility)

Browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
Mobile: iOS Safari 14+, Chrome Android 90+
Payment Methods: Support local Vietnamese payment gateways
Video Formats: MP4, WebM, HLS streaming support

5. Rủi ro và Phương án giảm thiểu (Risks and Mitigation)

Rủi ro	Mức độ ảnh hưởng	Khả năng xảy ra	Phương án giảm thiểu
Payment processing failures	Cao	Trung bình	- Multiple payment gateway integration - Retry mechanism với exponential backoff - Fallback payment methods - Real-time payment status monitoring
Estimation accuracy issues	Trung bình	Cao	- Machine learning model improvements - A/B testing cho estimation algorithms - User feedback collection - Regular model retraining
Budget optimization complexity	Trung bình	Trung bình	- Simplified budget tiers - Auto-optimization suggestions - Budget performance tracking - Expert recommendations integration
Campaign performance không đạt dự kiến	Cao	Trung bình	- Conservative estimation ranges - Money-back guarantee policy - Campaign optimization tools - Performance monitoring và alerts
Mobile UX limitations	Trung bình	Thấp	- Mobile-first design approach - Simplified mobile flow - Touch-optimized interactions - Progressive web app features
API rate limiting issues	Trung bình	Thấp	- Client-side caching strategies - Request queuing system - Graceful degradation - User notification system

6. Kế hoạch Testing (Testing Strategy)

6.1. Unit Testing

Components: React Testing Library cho modal components
Hooks: Custom hooks testing cho state management
Utils: Payment calculation, validation utilities
API Mocks: MSW cho API integration testing
Coverage Target: 90% line coverage

6.2. Integration Testing

Payment Flow: End-to-end payment processing testing
API Integration: Real API calls trong test environment
State Management: Complex state transitions testing
Form Validation: Multi-step form validation scenarios

6.3. E2E Testing

Critical Paths: Complete boost campaign flow
Payment Testing: Multiple payment method testing
Cross-browser: Chrome, Firefox, Safari testing
Mobile Testing: iOS và Android device testing

6.4. Performance Testing

Modal Performance: Modal load time và transition performance
API Performance: Payment processing performance testing
Memory Leaks: Long-running modal sessions testing
Network Conditions: Slow network simulation testing

6.5. Security Testing

Payment Security: PCI DSS compliance testing
Input Validation: XSS và injection attack testing
Token Security: Payment token lifecycle testing
Authentication: JWT token validation testing

7. Deployment và Monitoring

7.1. Deployment Strategy

Feature Flags: Gradual rollout với feature toggles
A/B Testing: Different modal designs testing
Canary Deployment: Limited user group testing
Rollback Plan: Quick rollback cho payment issues

7.2. Monitoring và Analytics

Payment Monitoring: Real-time payment success rates
User Behavior: Funnel analysis cho conversion rates
Performance Monitoring: Modal load times và API response times
Error Tracking: Payment failures và user errors tracking
Campaign Performance: Boost campaign effectiveness metrics

7.3. Business Metrics

Conversion Rate: Modal open to payment completion
Revenue Impact: Boost campaign revenue tracking
User Satisfaction: Post-campaign satisfaction surveys
Support Tickets: Payment và campaign related issues tracking

Tài liệu tham khảo:

1. Tổng quan (Overview)​

1.1. Bối cảnh và Vấn đề​

1.2. Mục tiêu & Phi mục tiêu (Goals and Non-Goals)​

Mục tiêu (Goals)​

Phi mục tiêu (Non-Goals)​

2. Kiến trúc Tổng thể (Overall Architecture)​

3. Thiết kế Chi tiết (Detailed Design)​

3.1. Thiết kế Giao diện & Luồng người dùng (UI & User Flow)​

Modal Structure:​

Step 1: Campaign Setup Layout​

Header Section​

Main Content Area (Two-Column Layout)​

Left Column: Video Preview​

Right Column: Campaign Configuration​

Footer Actions​

Step 2: Review & Preview Layout​

Header Section​

Main Content Area (Single Column Layout)​

Campaign Summary Section​

Expected Performance Section​

Important Notice​

Footer Actions​

Step 3: Payment Layout​

Header Section​

Main Content Area (Single Column Layout)​

Payment Method Section​

Payment Details Section​

Conditional Form Section​

Footer Actions​

State Management Interface:​

User Flow Chi tiết:​

3.2. Thiết kế API (API Design)​

Campaign Estimation API​

Campaign Creation API​

Location Targeting API​

Payment Processing API​

User Balance API​

4. Các yếu tố phi chức năng (Non-Functional Requirements)​

4.1. Hiệu suất (Performance)​

4.2. Bảo mật (Security)​

4.3. Khả năng mở rộng (Scalability)​

4.4. Trải nghiệm người dùng (UX)​

4.5. Tương thích (Compatibility)​

5. Rủi ro và Phương án giảm thiểu (Risks and Mitigation)​

6. Kế hoạch Testing (Testing Strategy)​

6.1. Unit Testing​

6.2. Integration Testing​

6.3. E2E Testing​

6.4. Performance Testing​

6.5. Security Testing​

7. Deployment và Monitoring​

7.1. Deployment Strategy​

7.2. Monitoring và Analytics​

7.3. Business Metrics​

1. Tổng quan (Overview)

1.1. Bối cảnh và Vấn đề

1.2. Mục tiêu & Phi mục tiêu (Goals and Non-Goals)

Mục tiêu (Goals)

Phi mục tiêu (Non-Goals)

2. Kiến trúc Tổng thể (Overall Architecture)

3. Thiết kế Chi tiết (Detailed Design)

3.1. Thiết kế Giao diện & Luồng người dùng (UI & User Flow)

Modal Structure:

Step 1: Campaign Setup Layout

Header Section

Main Content Area (Two-Column Layout)

Left Column: Video Preview

Right Column: Campaign Configuration

Footer Actions

Step 2: Review & Preview Layout

Header Section

Main Content Area (Single Column Layout)

Campaign Summary Section

Expected Performance Section

Important Notice

Footer Actions

Step 3: Payment Layout

Header Section

Main Content Area (Single Column Layout)

Payment Method Section

Payment Details Section

Conditional Form Section

Footer Actions

State Management Interface:

User Flow Chi tiết:

3.2. Thiết kế API (API Design)

Campaign Estimation API

Campaign Creation API

Location Targeting API

Payment Processing API

User Balance API

4. Các yếu tố phi chức năng (Non-Functional Requirements)

4.1. Hiệu suất (Performance)

4.2. Bảo mật (Security)

4.3. Khả năng mở rộng (Scalability)

4.4. Trải nghiệm người dùng (UX)

4.5. Tương thích (Compatibility)

5. Rủi ro và Phương án giảm thiểu (Risks and Mitigation)

6. Kế hoạch Testing (Testing Strategy)

6.1. Unit Testing

6.2. Integration Testing

6.3. E2E Testing

6.4. Performance Testing

6.5. Security Testing

7. Deployment và Monitoring

7.1. Deployment Strategy

7.2. Monitoring và Analytics

7.3. Business Metrics