Velox System

Purpose: Velox is the backend system used for managing the configuration of Advent Calendars, including CRUD operations

Functional Requirements:

• Calendar Management:
  • Create:
    • Define calendar properties such as name, start/end dates, daily expiration time (caseExpiration), and player tiers.
    • Associate specific rewards (bonusId, quantity, amount) with calendar days.
    • Allow player segmentation via celestaSegmentId.
  • Read:
    • Retrieve calendar configurations for a specific brand or globally.
    • Provide a detailed view of all cases (rewards) within a calendar.
  • Update:
    • Modify existing calendar properties (e.g., change dates, update rewards).
    • Validate changes to ensure no overlapping tiers or dates.
  • Delete:
    • Remove a calendar and all associated data, including player claims and cases.
• Validation:
  • Prevent overlapping calendar configurations:
  • Same tier and brand must not have overlapping start/end dates.
  • Cases must have valid reward definitions (bonusId, quantity, amount).
  • Ensure pvsCurrency matches the brand's requirements.
• Security
  • Role-based access control (RBAC) for admin operations.

Brand System

Purpose: The Brand system delivers calendar data and manages player interactions, including viewing available rewards and claiming them.

Functional Requirements:

• Retrieve Calendar:
  • Provide a player-specific view of one active calendar, including:
    • One Active day (available for claiming).
    • Expired days (no longer claimable).
    • One Opened day (already opened by the player).
    • Exclude locked days (future days not yet available).
  • Active day should be calculated dynamically based on caseExpiration, timepstamp and startDay.
  • Apply eligibility rules based on celestaSegmentId, tier, and pvsCurrency.
  • Handle player-specific time zones for day calculations. Use timezone-aware timestamps (YYYY-MM-DD HH:mm:ss) for all date-related calculations.
• Claim Rewards
  • Validate player actions:
    • Ensure the claim is for the current active day.
    • Prevent duplicate claims for the same day.
    • Assign rewards to the player if validation passes.

Summary of API Requests on Brand side

1. GET /calendar?timestamp=1732098688

Description: Retrieves the current Advent Calendar for the player. Also used to determine the status of a calendar.

• Parameters:

  • timestamp (required): The player's current timestamp in Unix format (e.g., 1732098688).

• Response:

  • 200 OK: Returns the calendar with active, expired, and opened days.

  {
      "data": {
          "id": 1,
          "name": "Xmas 2024",
          "startDay": "2024-11-01 00:00:00",
          "endDay": "2024-11-24 00:00:00",
          "caseExpiration": 1440,
          "pvsCurrency": "EUR",
          "tier": ["tier4","tier3"],
          "celestaSegmentId": 200,
          "days": 21,
          "cases": [
              {"id": 1,"day": 1,"bonusId": 2364,"quantity": 1,"amount": 1,"status": "expired","bonusInfo": null},
              {"id": 2,"day": 23,"bonusId": 2364,"quantity": 1,"amount": 1,"status": "claimed","bonusInfo": null},
              ----------
              {"id": 3,"day": 24,"bonusId": 2364,"quantity": 1,"amount": 1,"status": "active","bonusInfo": null}
          ]
      }
  }
  

  • 404 Not Found: No calendar is available for the player.

1. POST /calendar/claim