Implement leaderboard service and POC HTTP handlers with Swagger documentation

server/docs/swagger.yaml

@@ -252,6 +252,58 @@ definitions:
       type:
         $ref: '#/definitions/transport.MessageType'
     type: object
+  transport.LeaderboardEntry:
+    properties:
+      avatar_url:
+        example: https://cdn.example.com/u/ace.png
+        type: string
+      best_pos:
+        description: Only populated for track-specific leaderboard
+        example: 1
+        type: integer
+      best_time_ms:
+        example: 15000
+        type: integer
+      clan_id:
+        example: clan-seed-001
+        type: string
+      clan_tag:
+        example: ACE
+        type: string
+      driver_id:
+        example: driver-seed-001
+        type: string
+      name:
+        example: Alice
+        type: string
+      nickname:
+        example: ACE
+        type: string
+      points:
+        example: 25
+        type: integer
+      rank:
+        example: 1
+        type: integer
+    type: object
+  transport.LeaderboardResponse:
+    properties:
+      current_driver:
+        $ref: '#/definitions/transport.LeaderboardEntry'
+      items:
+        items:
+          $ref: '#/definitions/transport.LeaderboardEntry'
+        type: array
+      limit:
+        example: 50
+        type: integer
+      offset:
+        example: 0
+        type: integer
+      total:
+        example: 8
+        type: integer
+    type: object
   transport.LobbyRace:
     properties:
       created_ms:
@@ -1408,6 +1460,51 @@ paths:
       summary: Get / update / delete a driver by id
       tags:
       - drivers
+  /api/leaderboard:
+    get:
+      description: Returns paginated leaderboard list. Supports overall leaderboard
+        or track-specific leaderboard for the current year.
+      parameters:
+      - description: Track ID. If empty, returns overall leaderboard.
+        in: query
+        name: track_id
+        type: string
+      - description: Year. Defaults to current year.
+        in: query
+        name: year
+        type: integer
+      - description: Limit (1..200, default 50)
+        in: query
+        name: limit
+        type: integer
+      - description: Offset (default 0)
+        in: query
+        name: offset
+        type: integer
+      - description: Current driver ID. Defaults to driver-seed-001 (mock Alice).
+        in: header
+        name: X-Driver-Id
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: Leaderboard page and current driver position
+          schema:
+            $ref: '#/definitions/transport.LeaderboardResponse'
+        "400":
+          description: Invalid input
+          schema:
+            additionalProperties: true
+            type: object
+        "500":
+          description: Internal server error
+          schema:
+            additionalProperties: true
+            type: object
+      summary: Leaderboard
+      tags:
+      - leaderboard
   /api/races:
     get:
       description: |-