06.ranking-analysis

Ranking Analysis

Description

The Ranking Analysis feature provides comprehensive ranking analysis capabilities for categories and search queries within the official wishlist context, enabling users to gain insights into product rankings and performance metrics. This system integrates with the analyzer database to deliver ranking data for category and search query analysis with proper subscription-based filtering.

This feature focuses on production-ready ranking analysis with:

  • Category ranking analysis with subscription-based date filtering
  • Search query ranking analysis with performance metrics
  • Integration with analyzer database for ranking data
  • Subscription-based data access control and filtering
  • Real-time ranking data retrieval and processing
  • Paginated ranking results with proper filtering

The system ensures data accuracy through subscription validation and provides comprehensive ranking information for market analysis and strategic planning.

Activity Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %% Main components
    UserRequest[User Request]
    Database[(Database)]
    
    subgraph Controllers
        CategoryRankingController[ProductCategoryRankingController]
        SearchRankingController[ProductSearchQueryRankingController]
    end
    
    subgraph Services
        CategoryRankingService(ProductCategoryRankingService)
        SearchRankingService(ProductSearchQueryRankingService)
    end
    
    subgraph Repositories
        CategoryRankingRepo[[ProductCategoryRankingRepository]]
        SearchRankingRepo[[ProductSearchQueryRankingRepository]]
        WishlistRepo[[WishlistToGroupRepository]]
        SummaryRepo[[SummaryWishlistCategoryRepository]]
    end
    
    subgraph Middleware
        AuthMiddleware{AuthMiddleware}
    end
    
    UserRequest --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>Authentication & Wishlist Validation</p>
        </div>
    ]
    Step1 --> AuthMiddleware
    AuthMiddleware --> CategoryRankingController
    AuthMiddleware --> SearchRankingController

    CategoryRankingController --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>Ranking Data Retrieval & Processing</p>
        </div>
    ]
    Step2 --> CategoryRankingService
    Step2 --> SearchRankingService
    CategoryRankingService --> WishlistRepo
    CategoryRankingService --> SummaryRepo

    CategoryRankingService --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>Subscription Filtering & Data Processing</p>
        </div>
    ]
    Step3 --> CategoryRankingRepo
    Step3 --> SearchRankingRepo
    CategoryRankingRepo --> Database
    SearchRankingRepo --> Database

    CategoryRankingRepo --- Step4[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
            <p style='margin-top: 8px'>Data Formatting & Response Generation</p>
        </div>
    ]
    Step4 --> CategoryRankingController
    Step4 --> SearchRankingController

    %% Styling
    style UserRequest fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style Database fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style Controllers fill:#e6f3ff
    style Services fill:#f0f8e6
    style Repositories fill:#fff0f5
    style Middleware fill:#f5f0ff
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3 fill:transparent,stroke:transparent,stroke-width:1px
    style Step4 fill:transparent,stroke:transparent,stroke-width:1px

Detail Dataflow Dependency

Step-by-Step Process

Step 1: Authentication & Wishlist Validation

  • Description: Validates user authentication and wishlist access for ranking analysis operations
  • Action: Authenticate user session, validate wishlist ownership, check wishlist existence
  • Input: User credentials, wishlist slug
  • Output: Validated user context with wishlist access confirmation
  • Dependencies: User authentication service, wishlist repository
  • External Services: Authentication provider

Step 2: Ranking Data Retrieval & Processing

  • Description: Retrieves wishlist information and processes ranking parameters with subscription context
  • Action: Load wishlist with subscription, validate category parameters, prepare ranking queries
  • Input: Wishlist slug, category ID, ranking parameters
  • Output: Wishlist data with subscription context and validated parameters
  • Dependencies: Wishlist repository, summary category repository, subscription validation
  • External Services: Database cluster, subscription services

Step 3: Subscription Filtering & Data Processing

  • Description: Applies subscription-based filtering and retrieves ranking data from analyzer database
  • Action: Apply subscription date filters, query ranking data, process latest crawl data
  • Input: Subscription dates, category ranking ID, query parameters
  • Output: Filtered ranking data with subscription compliance
  • Dependencies: Ranking repositories, subscription filtering, date processing
  • External Services: Analyzer database, subscription validation services

Step 4: Data Formatting & Response Generation

  • Description: Formats ranking data for API response with pagination and proper structure
  • Action: Transform data to API format, apply pagination, generate response structure
  • Input: Ranking data, pagination parameters, response format requirements
  • Output: Formatted API response with pagination and metadata
  • Dependencies: Data transformation services, pagination handling, response formatting
  • External Services: API response services, data serialization

Database Related Tables & Fields

Database: gb_console, gb_analyzer

erDiagram
    "gb_console.wishlist_to_groups" {
        bigint id PK
        string name "Name of the wishlist"
        string slug "Slug of the wishlist"
        integer status "0: Inactive, 1: Active, 3: Canceled"
    }
    
    "gb_analyzer.category_rankings" {
        bigint id PK
        string mall_category_id
        string mall_category_name
        integer mall_id
    }
    
    "gb_analyzer.product_category_rankings" {
        bigint id PK
        bigint category_ranking_id FK
        integer ranking
        string mall_product_id
        string product_name
        double price
        string shop_name
        text image
        text product_url
        text shop_url
        integer mall_id
    }
    
    "gb_analyzer.product_category_rankings" }|--|| "gb_analyzer.category_rankings" : "belongs to"

Case Documentation

Case 1: Category Ranking Analysis

API: Top Category Rankings

Sequence Diagram

sequenceDiagram
    participant Client
    participant Controller as ProductCategoryRankingController
    participant Service as ProductCategoryRankingService
    participant WishlistRepo as WishlistToGroupRepository
    participant SummaryRepo as SummaryWishlistCategoryRepository
    participant RankingRepo as ProductCategoryRankingRepository
    participant Database
    
    Note over Client,Database: Category Ranking Analysis Flow
    
    rect rgb(255, 255, 200)
    Note right of Client: Authentication Phase
    Client->>Controller: GET /api/v1/wishlist-to-group/{slug}/top-category-ranking
    Controller->>Controller: Authenticate User
    end
    
    rect rgb(200, 230, 255)
    Note right of Controller: Validation Phase
    Controller->>WishlistRepo: findBySlug(slug)
    WishlistRepo->>Database: SELECT from wishlist_to_groups
    Database-->>WishlistRepo: Wishlist Record
    Controller->>Controller: Validate category_id parameter
    end
    
    rect rgb(200, 255, 255)
    Note right of Controller: Service Processing
    Controller->>Service: serverPaginationFilteringFor(params, wishlist)
    Service->>Service: Load subscription data
    Service->>SummaryRepo: getByCategoryId(categoryId)
    SummaryRepo->>Database: SELECT category data
    Database-->>SummaryRepo: Category Record
    end
    
    rect rgb(255, 230, 200)
    Note right of Service: Ranking Data Retrieval
    Service->>Service: Generate unique key for category
    Service->>RankingRepo: Find category ranking by unique_key
    Service->>RankingRepo: Get latest crawl_created_at
    Service->>RankingRepo: Query with subscription filters
    RankingRepo->>Database: SELECT with subscription date filters
    Database-->>RankingRepo: Ranking Records
    end
    
    rect rgb(200, 255, 200)
    Note right of Service: Success Response
    Service->>Service: Apply pagination
    Service-->>Controller: Paginated Rankings
    Controller->>Controller: Transform to Resources
    Controller-->>Client: JSON Response with Rankings
    end

Steps

  1. Authentication: Validate user session
  2. Wishlist Validation: Find wishlist by slug and validate existence
  3. Parameter Validation: Validate required category_id parameter
  4. Service Processing: Load subscription data and category information
  5. Ranking Retrieval: Generate unique key and query ranking data with subscription filters
  6. Response Generation: Apply pagination and transform to API resources

Error Handling

  • 401 Unauthorized: Invalid authentication
  • 404 Not Found: Wishlist not found
  • 400 Bad Request: Missing or invalid category_id parameter
  • 500 Internal Server Error: Database or system errors

Case 2: Search Query Ranking Analysis

API: Top Search Rankings

Sequence Diagram

sequenceDiagram
    participant Client
    participant Controller as ProductSearchQueryRankingController
    participant Service as ProductSearchQueryRankingService
    participant WishlistRepo as WishlistToGroupRepository
    participant RankingRepo as ProductSearchQueryRankingRepository
    participant Database
    
    Note over Client,Database: Search Query Ranking Analysis Flow
    
    rect rgb(255, 255, 200)
    Note right of Client: Authentication Phase
    Client->>Controller: GET /api/v1/wishlist-to-group/{slug}/top-search-ranking
    Controller->>Controller: Authenticate User
    end
    
    rect rgb(200, 230, 255)
    Note right of Controller: Validation Phase
    Controller->>WishlistRepo: findBySlug(slug)
    WishlistRepo->>Database: SELECT from wishlist_to_groups
    Database-->>WishlistRepo: Wishlist Record
    Controller->>Controller: Validate search parameters
    end
    
    rect rgb(200, 255, 255)
    Note right of Controller: Service Processing
    Controller->>Service: serverPaginationFilteringFor(params, wishlist)
    Service->>Service: Load subscription data
    Service->>Service: Validate search query parameters
    end
    
    rect rgb(255, 230, 200)
    Note right of Service: Search Ranking Retrieval
    Service->>RankingRepo: Query search rankings
    Service->>RankingRepo: Apply subscription filters
    Service->>RankingRepo: Get latest crawl data
    RankingRepo->>Database: SELECT with filters
    Database-->>RankingRepo: Search Ranking Records
    end
    
    rect rgb(200, 255, 200)
    Note right of Service: Success Response
    Service->>Service: Apply pagination
    Service-->>Controller: Paginated Search Rankings
    Controller->>Controller: Transform to Resources
    Controller-->>Client: JSON Response with Search Rankings
    end

Steps

  1. Authentication: Validate user session
  2. Wishlist Validation: Find wishlist by slug and validate existence
  3. Parameter Validation: Validate search query parameters
  4. Service Processing: Load subscription data and search parameters
  5. Search Ranking Retrieval: Query search ranking data with subscription filters
  6. Response Generation: Apply pagination and transform to API resources

Error Handling

  • 401 Unauthorized: Invalid authentication
  • 404 Not Found: Wishlist not found
  • 400 Bad Request: Invalid search parameters
  • 500 Internal Server Error: Database or system errors