openapi: 3.0.3
info:
  title: Brisk Game Service API
  version: 0.2.0
  description: Current implemented Brisk server API for internal integration.
servers:
  - url: /api
tags:
  - name: time
  - name: bootstrap
  - name: auth
  - name: player
  - name: config
  - name: announcements
  - name: ranks
  - name: archives
  - name: spaces
  - name: admin-auth
  - name: admin-audit
  - name: admin-projects
  - name: admin-configs
  - name: admin-announcements
  - name: admin-rank-groups
  - name: admin-ranks
  - name: admin-archives
  - name: admin-players
  - name: admin-spaces
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
  schemas:
    SuccessEnvelope:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: ok
        data:
          type: object
    ErrorEnvelope:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          nullable: true
    ClientTimePayload:
      type: object
      properties:
        server_time:
          type: string
          format: date-time
          example: 2026-04-11T08:12:30Z
        server_unix:
          type: integer
          format: int64
          example: 1775895150
        server_unix_ms:
          type: integer
          format: int64
          example: 1775895150123
    ExchangeRequest:
      type: object
      required: [game_key, login_provider]
      properties:
        game_key:
          type: string
        login_provider:
          type: string
          example: tap
        code:
          type: string
          description: Optional for code-based login.
        login_user_id:
          type: string
          description: Stable user identifier from client-verified provider login.
        device_id:
          type: string
        client_version:
          type: string
        nickname:
          type: string
          description: Optional profile nickname to sync into project account.
        avatar_url:
          type: string
          description: Optional profile avatar URL to sync into project account.
        profile_json:
          type: object
          additionalProperties: true
          description: Optional extra profile payload to sync into project account.
    AdminLoginRequest:
      type: object
      required: [username, password]
      properties:
        username:
          type: string
        password:
          type: string
    CreateProjectRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        current_version:
          type: string
        status:
          type: string
        maintenance_mode:
          type: boolean
        maintenance_message:
          type: string
        min_client_version:
          type: string
        max_archive_size_bytes:
          type: integer
          format: int64
        max_archive_slots:
          type: integer
    UpdateProjectRequest:
      type: object
      properties:
        name:
          type: string
        current_version:
          type: string
        status:
          type: string
        maintenance_mode:
          type: boolean
        maintenance_message:
          type: string
        min_client_version:
          type: string
        max_archive_size_bytes:
          type: integer
          format: int64
        max_archive_slots:
          type: integer
    UpsertCurrentConfigRequest:
      type: object
      required: [project_id]
      properties:
        project_id:
          type: integer
          format: int64
        feature_flags:
          type: object
          additionalProperties: true
        dynamic_config:
          type: object
          additionalProperties: true
        status:
          type: string
    CreateAnnouncementRequest:
      type: object
      required: [project_id, title, content, start_at, end_at]
      properties:
        project_id:
          type: integer
          format: int64
        title:
          type: string
        content:
          type: string
        content_type:
          type: string
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        status:
          type: string
    UpdateAnnouncementRequest:
      type: object
      properties:
        title:
          type: string
        content:
          type: string
        content_type:
          type: string
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        status:
          type: string
    BanPlayerRequest:
      type: object
      properties:
        reason:
          type: string
        ban_until:
          type: string
          format: date-time
        permanent:
          type: boolean
    CreateRankRequest:
      type: object
      required: [project_id, name]
      properties:
        project_id:
          type: integer
          format: int64
        name:
          type: string
        status:
          type: string
        group_id:
          type: integer
          format: int64
        rank_mode:
          type: string
        timezone:
          type: string
        snapshot_enabled:
          type: boolean
        update_strategy:
          type: string
        sort_order:
          type: string
        reset_hour:
          type: integer
        reset_minute:
          type: integer
        weekly_reset_day:
          type: integer
        monthly_reset_day:
          type: integer
        blacklist_player_ids:
          type: array
          items:
            type: string
    UpdateRankRequest:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
        group_id:
          type: integer
          format: int64
        clear_group:
          type: boolean
        rank_mode:
          type: string
        timezone:
          type: string
        snapshot_enabled:
          type: boolean
        update_strategy:
          type: string
        sort_order:
          type: string
        reset_hour:
          type: integer
        reset_minute:
          type: integer
        weekly_reset_day:
          type: integer
        monthly_reset_day:
          type: integer
        blacklist_player_ids:
          type: array
          items:
            type: string
    AdminRankLeaderboardItem:
      type: object
      properties:
        rank:
          type: integer
          format: int64
        player_id:
          type: string
        project_account_id:
          type: string
        login_provider:
          type: string
        login_user_id:
          type: string
        score:
          type: integer
          format: int64
        nickname:
          type: string
        avatar_url:
          type: string
    AdminRankLeaderboardResult:
      type: object
      properties:
        rank_key:
          type: string
        leaderboard_key:
          type: string
        total:
          type: integer
          format: int64
        page:
          type: integer
        page_size:
          type: integer
        filter_player_id:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/AdminRankLeaderboardItem'
    AdminRankDeletePlayerRecordResult:
      type: object
      properties:
        rank_key:
          type: string
        player_id:
          type: string
        leaderboard_key:
          type: string
        removed:
          type: integer
          format: int64
    AdminRankResetLeaderboardResult:
      type: object
      properties:
        rank_key:
          type: string
        leaderboard_key:
          type: string
        removed:
          type: integer
          format: int64
    CreateRankGroupRequest:
      type: object
      required: [project_id, name]
      properties:
        project_id:
          type: integer
          format: int64
        name:
          type: string
        sort_order:
          type: integer
    UpdateRankGroupRequest:
      type: object
      properties:
        name:
          type: string
        sort_order:
          type: integer
    ScoreRequest:
      type: object
      required: [score]
      properties:
        score:
          type: integer
          format: int64
    SpaceContentUploadRequest:
      type: object
      required: [file]
      properties:
        base_version:
          type: integer
          format: int64
          description: Optimistic lock base version. Use 0 for the first upload.
        content_type:
          type: string
          description: Optional MIME type. Defaults to application/octet-stream when omitted.
        checksum:
          type: string
          description: Optional SHA-256 hex checksum. When provided, the server validates it before saving.
        file:
          type: string
          format: binary
    SpaceMetadata:
      type: object
      properties:
        project_account_id:
          type: string
        player_id:
          type: string
        login_provider:
          type: string
        login_user_id:
          type: string
        nickname:
          type: string
        avatar_url:
          type: string
        content_exists:
          type: boolean
        content_version:
          type: integer
          format: int64
        content_type:
          type: string
        content_size_bytes:
          type: integer
          format: int64
        content_checksum:
          type: string
        like_count:
          type: integer
          format: int64
        today_like_count:
          type: integer
          format: int64
        visit_count:
          type: integer
          format: int64
        liked_by_me:
          type: boolean
        like_reset_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
    SpaceStats:
      type: object
      properties:
        project_account_id:
          type: string
        player_id:
          type: string
        login_provider:
          type: string
        login_user_id:
          type: string
        nickname:
          type: string
        avatar_url:
          type: string
        content_exists:
          type: boolean
        content_version:
          type: integer
          format: int64
        content_type:
          type: string
        content_size_bytes:
          type: integer
          format: int64
        content_checksum:
          type: string
        like_count:
          type: integer
          format: int64
        today_like_count:
          type: integer
          format: int64
        visit_count:
          type: integer
          format: int64
        like_reset_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
    SpaceContentUpdateResult:
      type: object
      properties:
        player_id:
          type: string
        content_version:
          type: integer
          format: int64
        content_type:
          type: string
        content_size_bytes:
          type: integer
          format: int64
        content_checksum:
          type: string
        updated_at:
          type: string
          format: date-time
    SpaceLikeResult:
      type: object
      properties:
        liked:
          type: boolean
        created:
          type: boolean
        liked_by_me:
          type: boolean
        like_count:
          type: integer
          format: int64
        today_like_count:
          type: integer
          format: int64
        like_reset_at:
          type: string
          format: date-time
    SpaceVisitItem:
      type: object
      properties:
        visitor_player_id:
          type: string
        nickname:
          type: string
        avatar_url:
          type: string
        visited_at:
          type: string
          format: date-time
    SpaceLikeItem:
      type: object
      properties:
        player_id:
          type: string
        nickname:
          type: string
        avatar_url:
          type: string
        created_at:
          type: string
          format: date-time
    SpaceLikeListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SpaceLikeItem'
paths:
  /client/time:
    get:
      tags: [time]
      summary: Get platform server time
      responses:
        '200':
          description: Current platform UTC time
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 0
                  message:
                    type: string
                    example: ok
                  data:
                    $ref: '#/components/schemas/ClientTimePayload'
        '429': { description: Rate limited }
        '500': { description: Rate limit unavailable }
  /client/bootstrap:
    get:
      tags: [bootstrap]
      summary: Get startup config
      parameters:
        - in: query
          name: game_key
          required: true
          schema: { type: string }
        - in: query
          name: client_version
          required: false
          schema: { type: string }
        - in: query
          name: device_id
          schema: { type: string }
      responses:
        '200': { description: Bootstrap payload }
  /auth/login/exchange:
    post:
      tags: [auth]
      summary: Exchange login provider identity for Brisk token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeRequest'
      responses:
        '200': { description: Login success }
        '403': { description: Player banned }
        '429': { description: Rate limited }
  /auth/logout:
    post:
      tags: [auth]
      security: [{ bearerAuth: [] }]
      summary: Logout current session
      responses:
        '200': { description: Logout success }
  /player/me:
    get:
      tags: [player]
      security: [{ bearerAuth: [] }]
      summary: Get current player
      responses:
        '200': { description: Player info }
  /config/current:
    get:
      tags: [config]
      summary: Get current dynamic config
      parameters:
        - in: query
          name: game_key
          required: true
          schema: { type: string }
        - in: query
          name: client_version
          required: false
          schema: { type: string }
      responses:
        '200': { description: Config payload }
  /announcements:
    get:
      tags: [announcements]
      security: [{ bearerAuth: [] }]
      summary: List active announcements
      responses:
        '200': { description: Announcement list }
  /announcements/{id}/read:
    post:
      tags: [announcements]
      security: [{ bearerAuth: [] }]
      summary: Mark announcement read
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Read recorded }
  /ranks/{rank_key}/top:
    get:
      tags: [ranks]
      security: [{ bearerAuth: [] }]
      summary: Get top ranking list
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Top ranking list }
  /ranks/{rank_key}/me:
    get:
      tags: [ranks]
      security: [{ bearerAuth: [] }]
      summary: Get current player rank
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
      responses:
        '200': { description: Player rank }
  /ranks/{rank_key}/around-me:
    get:
      tags: [ranks]
      security: [{ bearerAuth: [] }]
      summary: Get nearby ranking items
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: range
          schema: { type: integer }
      responses:
        '200': { description: Nearby ranks }
  /ranks/{rank_key}/score:
    post:
      tags: [ranks]
      security: [{ bearerAuth: [] }]
      summary: Submit score, keep only best
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScoreRequest'
      responses:
        '200': { description: Score result }
        '429': { description: Rate limited }
  /ranks/{rank_key}/season/current:
    get:
      tags: [ranks]
      security: [{ bearerAuth: [] }]
      summary: Get current season info for rank
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
      responses:
        '200': { description: Current season info }
  /ranks/{rank_key}/history:
    get:
      tags: [ranks]
      security: [{ bearerAuth: [] }]
      summary: Get rank season history
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Rank season history }
  /ranks/{rank_key}/history/{season_id}:
    get:
      tags: [ranks]
      security: [{ bearerAuth: [] }]
      summary: Get rank history detail by season
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: path
          name: season_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Rank season detail }
  /archives/slot/1/meta:
    get:
      tags: [archives]
      security: [{ bearerAuth: [] }]
      summary: Get single-slot archive metadata
      responses:
        '200': { description: Archive metadata }
  /archives/slots:
    get:
      tags: [archives]
      security: [{ bearerAuth: [] }]
      summary: List archive slots
      responses:
        '200': { description: Archive slot list }
  /archives/slot/{slot_no}/meta:
    get:
      tags: [archives]
      security: [{ bearerAuth: [] }]
      summary: Get archive metadata by slot
      parameters:
        - in: path
          name: slot_no
          required: true
          schema: { type: integer }
      responses:
        '200': { description: Archive metadata }
  /archives/slot/1/upload:
    post:
      tags: [archives]
      security: [{ bearerAuth: [] }]
      summary: Upload single-slot archive
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [base_version, checksum, file]
              properties:
                base_version:
                  type: integer
                checksum:
                  type: string
                file:
                  type: string
                  format: binary
      responses:
        '200': { description: Upload success }
        '409': { description: Version conflict }
        '429': { description: Rate limited }
  /archives/slot/{slot_no}/upload:
    post:
      tags: [archives]
      security: [{ bearerAuth: [] }]
      summary: Upload archive by slot
      parameters:
        - in: path
          name: slot_no
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [base_version, checksum, file]
              properties:
                base_version:
                  type: integer
                checksum:
                  type: string
                file:
                  type: string
                  format: binary
      responses:
        '200': { description: Upload success }
        '409': { description: Version conflict }
        '429': { description: Rate limited }
  /archives/slot/1/download:
    get:
      tags: [archives]
      security: [{ bearerAuth: [] }]
      summary: Download single-slot archive
      responses:
        '200': { description: Binary archive stream }
  /archives/slot/{slot_no}/download:
    get:
      tags: [archives]
      security: [{ bearerAuth: [] }]
      summary: Download archive by slot
      parameters:
        - in: path
          name: slot_no
          required: true
          schema: { type: integer }
      responses:
        '200': { description: Binary archive stream }
  /spaces/{player_id}:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space metadata
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
          description: Optional target login provider. When present, login_user_id is also required and overrides player_id lookup.
        - in: query
          name: login_user_id
          schema: { type: string }
          description: Optional target login user id used with login provider lookup.
      responses:
        '200':
          description: Space metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceMetadata'
  /spaces/{player_id}/content:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Download player space content
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
          description: Optional target login provider. When present, login_user_id is also required and overrides player_id lookup.
        - in: query
          name: login_user_id
          schema: { type: string }
          description: Optional target login user id used with login provider lookup.
      responses:
        '200':
          description: Binary space content stream
          headers:
            X-Space-Version:
              schema:
                type: integer
                format: int64
            X-Space-Checksum:
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /spaces/{player_id}/stats:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space stats
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
        - in: query
          name: login_user_id
          schema: { type: string }
      responses:
        '200':
          description: Space stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceStats'
  /spaces/{player_id}/likes:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space likes
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
        - in: query
          name: login_user_id
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer }
        - in: query
          name: scope
          schema:
            type: string
            enum: [history, cycle]
            default: history
          description: Whether to list historical likes or only likes from the current daily cycle.
      responses:
        '200':
          description: Space likes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceLikeListResponse'
  /spaces/me/content:
    put:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Upload my space content
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SpaceContentUploadRequest'
      responses:
        '200':
          description: Space content updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceContentUpdateResult'
        '409': { description: Version conflict }
  /spaces/{player_id}/like:
    post:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Like player space
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
        - in: query
          name: login_user_id
          schema: { type: string }
      responses:
        '200':
          description: Liked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceLikeResult'
        '429': { description: Rate limited }
    delete:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Unlike player space
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
        - in: query
          name: login_user_id
          schema: { type: string }
      responses:
        '200':
          description: Unliked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceLikeResult'
        '429': { description: Rate limited }
  /spaces/by-login:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space metadata by login identity
      parameters:
        - in: query
          name: login_provider
          required: true
          schema: { type: string }
        - in: query
          name: login_user_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Space metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceMetadata'
  /spaces/by-login/content:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Download player space content by login identity
      parameters:
        - in: query
          name: login_provider
          required: true
          schema: { type: string }
        - in: query
          name: login_user_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Binary space content stream
          headers:
            X-Space-Version:
              schema:
                type: integer
                format: int64
            X-Space-Checksum:
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /spaces/by-login/stats:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space stats by login identity
      parameters:
        - in: query
          name: login_provider
          required: true
          schema: { type: string }
        - in: query
          name: login_user_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Space stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceStats'
  /spaces/by-login/likes:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space likes by login identity
      parameters:
        - in: query
          name: login_provider
          required: true
          schema: { type: string }
        - in: query
          name: login_user_id
          required: true
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer }
        - in: query
          name: scope
          schema:
            type: string
            enum: [history, cycle]
            default: history
          description: Whether to list historical likes or only likes from the current daily cycle.
      responses:
        '200':
          description: Space likes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceLikeListResponse'
  /spaces/by-login/like:
    post:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Like player space by login identity
      parameters:
        - in: query
          name: login_provider
          required: true
          schema: { type: string }
        - in: query
          name: login_user_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Liked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceLikeResult'
        '429': { description: Rate limited }
    delete:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Unlike player space by login identity
      parameters:
        - in: query
          name: login_provider
          required: true
          schema: { type: string }
        - in: query
          name: login_user_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Unliked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceLikeResult'
        '429': { description: Rate limited }
  /spaces/me/visits:
    get:
      tags: [spaces]
      security: [{ bearerAuth: [] }]
      summary: Get recent visitors
      parameters:
        - in: query
          name: limit
          schema: { type: integer, default: 50 }
          description: Optional page size. Defaults to 50 and is capped at 100.
      responses:
        '200':
          description: Visitor list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpaceVisitItem'
  /admin/auth/login:
    post:
      tags: [admin-auth]
      summary: Admin login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminLoginRequest'
      responses:
        '200': { description: Admin login success }
        '429': { description: Rate limited }
  /admin/audit-logs:
    get:
      tags: [admin-audit]
      security: [{ bearerAuth: [] }]
      summary: List audit logs
      parameters:
        - in: query
          name: action
          schema: { type: string }
        - in: query
          name: resource_type
          schema: { type: string }
        - in: query
          name: username
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Audit log list }
  /admin/projects:
    get:
      tags: [admin-projects]
      security: [{ bearerAuth: [] }]
      summary: List projects
      responses:
        '200': { description: Project list }
    post:
      tags: [admin-projects]
      security: [{ bearerAuth: [] }]
      summary: Create project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200': { description: Project created }
  /admin/projects/{id}:
    get:
      tags: [admin-projects]
      security: [{ bearerAuth: [] }]
      summary: Get project detail
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Project detail }
    put:
      tags: [admin-projects]
      security: [{ bearerAuth: [] }]
      summary: Update project
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200': { description: Project updated }
  /admin/projects/{id}/icon:
    get:
      tags: [admin-projects]
      security: [{ bearerAuth: [] }]
      summary: Get project icon
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Project icon stream }
    post:
      tags: [admin-projects]
      security: [{ bearerAuth: [] }]
      summary: Upload project icon
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200': { description: Project icon uploaded }
  /admin/configs/current:
    get:
      tags: [admin-configs]
      security: [{ bearerAuth: [] }]
      summary: Get current dynamic config for project
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Current config }
    put:
      tags: [admin-configs]
      security: [{ bearerAuth: [] }]
      summary: Save current dynamic config for project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCurrentConfigRequest'
      responses:
        '200': { description: Config saved }
  /admin/announcements:
    get:
      tags: [admin-announcements]
      security: [{ bearerAuth: [] }]
      summary: List announcements
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: status
          schema: { type: string }
      responses:
        '200': { description: Announcement list }
    post:
      tags: [admin-announcements]
      security: [{ bearerAuth: [] }]
      summary: Create announcement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnouncementRequest'
      responses:
        '200': { description: Announcement created }
  /admin/announcements/{id}:
    get:
      tags: [admin-announcements]
      security: [{ bearerAuth: [] }]
      summary: Get announcement detail
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Announcement detail }
    put:
      tags: [admin-announcements]
      security: [{ bearerAuth: [] }]
      summary: Update announcement
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAnnouncementRequest'
      responses:
        '200': { description: Announcement updated }
    delete:
      tags: [admin-announcements]
      security: [{ bearerAuth: [] }]
      summary: Delete announcement
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Announcement deleted }
  /admin/rank-groups:
    get:
      tags: [admin-rank-groups]
      security: [{ bearerAuth: [] }]
      summary: List rank groups
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Rank groups }
    post:
      tags: [admin-rank-groups]
      security: [{ bearerAuth: [] }]
      summary: Create rank group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRankGroupRequest'
      responses:
        '200': { description: Rank group created }
  /admin/rank-groups/{id}:
    put:
      tags: [admin-rank-groups]
      security: [{ bearerAuth: [] }]
      summary: Update rank group
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRankGroupRequest'
      responses:
        '200': { description: Rank group updated }
    delete:
      tags: [admin-rank-groups]
      security: [{ bearerAuth: [] }]
      summary: Delete rank group
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Rank group deleted }
  /admin/ranks:
    get:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: List rank definitions
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Rank definitions }
    post:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: Create rank definition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRankRequest'
      responses:
        '200': { description: Rank created }
  /admin/ranks/{rank_key}:
    get:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: Get rank definition detail
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Rank detail }
    put:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: Update rank definition
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRankRequest'
      responses:
        '200': { description: Rank updated }
    delete:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: Delete rank definition
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Rank deleted }
  /admin/ranks/{rank_key}/players/{player_id}:
    delete:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: Delete current leaderboard record by player id
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: Rank player record removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRankDeletePlayerRecordResult'
  /admin/ranks/{rank_key}/leaderboard:
    get:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: Get current live leaderboard with pagination and filters
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: page_size
          schema: { type: integer, default: 20 }
        - in: query
          name: player_id
          schema: { type: string }
        - in: query
          name: project_account_id
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
        - in: query
          name: login_provider
          schema: { type: string }
        - in: query
          name: login_user_id
          schema: { type: string }
      responses:
        '200':
          description: Current leaderboard snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRankLeaderboardResult'
  /admin/ranks/{rank_key}/reset:
    post:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: Reset current live leaderboard data for rank
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: Current leaderboard reset result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRankResetLeaderboardResult'
  /admin/ranks/{rank_key}/seasons:
    get:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: List rank seasons
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Rank seasons }
  /admin/ranks/{rank_key}/seasons/{season_id}/logs:
    get:
      tags: [admin-ranks]
      security: [{ bearerAuth: [] }]
      summary: List rank settlement logs
      parameters:
        - in: path
          name: rank_key
          required: true
          schema: { type: string }
        - in: path
          name: season_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Settlement logs }
  /admin/archives/overview:
    get:
      tags: [admin-archives]
      security: [{ bearerAuth: [] }]
      summary: Get archive overview
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Archive overview }
  /admin/archives:
    get:
      tags: [admin-archives]
      security: [{ bearerAuth: [] }]
      summary: List archive players
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: player_id
          schema: { type: string }
        - in: query
          name: project_account_id
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Archive player list }
  /admin/archives/{player_id}:
    get:
      tags: [admin-archives]
      security: [{ bearerAuth: [] }]
      summary: Get archive slots by player
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Archive detail }
  /admin/archives/{player_id}/slots/{slot_no}/download:
    get:
      tags: [admin-archives]
      security: [{ bearerAuth: [] }]
      summary: Download archive slot
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: path
          name: slot_no
          required: true
          schema: { type: integer }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Archive file stream }
  /admin/archives/{player_id}/slots/{slot_no}:
    delete:
      tags: [admin-archives]
      security: [{ bearerAuth: [] }]
      summary: Delete archive slot
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: path
          name: slot_no
          required: true
          schema: { type: integer }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Archive slot deleted }
  /admin/players:
    get:
      tags: [admin-players]
      security: [{ bearerAuth: [] }]
      summary: List players
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: player_id
          schema: { type: string }
        - in: query
          name: project_account_id
          schema: { type: string }
        - in: query
          name: login_user_id
          schema: { type: string }
      responses:
        '200': { description: Player list }
  /admin/players/{player_id}:
    get:
      tags: [admin-players]
      security: [{ bearerAuth: [] }]
      summary: Get player detail
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Player detail }
  /admin/players/{player_id}/ban:
    post:
      tags: [admin-players]
      security: [{ bearerAuth: [] }]
      summary: Ban player
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BanPlayerRequest'
      responses:
        '200': { description: Player banned }
  /admin/players/{player_id}/unban:
    post:
      tags: [admin-players]
      security: [{ bearerAuth: [] }]
      summary: Unban player
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
      responses:
        '200': { description: Player unbanned }
  /admin/spaces/overview:
    get:
      tags: [admin-spaces]
      security: [{ bearerAuth: [] }]
      summary: Get space module overview
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Space overview }
  /admin/spaces:
    get:
      tags: [admin-spaces]
      security: [{ bearerAuth: [] }]
      summary: List player spaces
      parameters:
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: player_id
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Space list }
  /admin/spaces/{player_id}:
    get:
      tags: [admin-spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space metadata detail
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { description: Space detail }
  /admin/spaces/{player_id}/content:
    get:
      tags: [admin-spaces]
      security: [{ bearerAuth: [] }]
      summary: Download player space content
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: Binary space content stream
          headers:
            X-Space-Version:
              schema:
                type: integer
                format: int64
            X-Space-Checksum:
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /admin/spaces/{player_id}/likes:
    get:
      tags: [admin-spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space likes
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Space likes }
  /admin/spaces/{player_id}/visits:
    get:
      tags: [admin-spaces]
      security: [{ bearerAuth: [] }]
      summary: Get player space visits
      parameters:
        - in: path
          name: player_id
          required: true
          schema: { type: string }
        - in: query
          name: project_id
          required: true
          schema: { type: integer, format: int64 }
        - in: query
          name: limit
          schema: { type: integer }
      responses:
        '200': { description: Space visits }