a301_server/docs/swagger.yaml

basePath: /
definitions:
  bossraid.BossRoom:
    properties:
      bossId:
        type: integer
      completedAt:
        type: string
      createdAt:
        type: string
      id:
        type: integer
      maxPlayers:
        type: integer
      players:
        description: |-
          Players is stored as a JSON text column for simplicity.
          TODO: For better query performance, consider migrating to a junction table
          (boss_room_players with room_id + username columns).
        type: string
      sessionName:
        type: string
      startedAt:
        type: string
      status:
        $ref: '#/definitions/bossraid.RoomStatus'
      updatedAt:
        type: string
    type: object
  bossraid.RoomStatus:
    enum:
    - waiting
    - in_progress
    - completed
    - failed
    type: string
    x-enum-varnames:
    - StatusWaiting
    - StatusInProgress
    - StatusCompleted
    - StatusFailed
  docs.AnnouncementResponse:
    properties:
      content:
        example: 3월 16일 서버 점검이 예정되어 있습니다.
        type: string
      createdAt:
        type: string
      id:
        example: 1
        type: integer
      title:
        example: 서버 점검 안내
        type: string
      updatedAt:
        type: string
    type: object
  docs.BuyFromMarketRequest:
    properties:
      listingId:
        example: listing_001
        type: string
    type: object
  docs.CancelListingRequest:
    properties:
      listingId:
        example: listing_001
        type: string
    type: object
  docs.CompleteRaidRequest:
    properties:
      rewards:
        items:
          $ref: '#/definitions/docs.PlayerReward'
        type: array
      sessionName:
        example: Dedi1_Room0
        type: string
    type: object
  docs.CompleteRaidResponse:
    properties:
      rewardResults:
        items:
          $ref: '#/definitions/docs.RewardResult'
        type: array
      roomId:
        example: 1
        type: integer
      sessionName:
        example: Dedi1_Room0
        type: string
      status:
        example: completed
        type: string
    type: object
  docs.CreateAnnouncementRequest:
    properties:
      content:
        example: 3월 16일 서버 점검이 예정되어 있습니다.
        type: string
      title:
        example: 서버 점검 안내
        type: string
    type: object
  docs.DownloadInfoResponse:
    properties:
      createdAt:
        type: string
      fileHash:
        example: a1b2c3d4e5f6...
        type: string
      fileName:
        example: A301_v1.0.zip
        type: string
      fileSize:
        example: 1.5 GB
        type: string
      id:
        example: 1
        type: integer
      launcherSize:
        example: 25.3 MB
        type: string
      launcherUrl:
        example: https://a301.api.tolelom.xyz/api/download/launcher
        type: string
      updatedAt:
        type: string
      url:
        example: https://a301.api.tolelom.xyz/api/download/file
        type: string
      version:
        example: 1.0.0
        type: string
    type: object
  docs.EquipItemRequest:
    properties:
      assetId:
        example: asset_001
        type: string
      slot:
        example: weapon
        type: string
    type: object
  docs.ErrorResponse:
    properties:
      error:
        example: 오류 메시지
        type: string
    type: object
  docs.GameDataRequest:
    properties:
      attackPower:
        example: 25
        type: number
      attackRange:
        example: 3
        type: number
      experience:
        example: 1200
        type: integer
      lastPosX:
        example: 10.5
        type: number
      lastPosY:
        example: 0
        type: number
      lastPosZ:
        example: 20.3
        type: number
      lastRotY:
        example: 90
        type: number
      level:
        example: 5
        type: integer
      maxHp:
        example: 150
        type: number
      maxMp:
        example: 75
        type: number
      sprintMultiplier:
        example: 1.8
        type: number
      totalPlayTime:
        example: 3600
        type: integer
    type: object
  docs.GrantRewardRequest:
    properties:
      assets:
        items:
          $ref: '#/definitions/docs.MintAssetPayload'
        type: array
      recipientPubKey:
        example: abcdef012345...
        type: string
      tokenAmount:
        example: 1000
        type: integer
    type: object
  docs.HeartbeatRequest:
    properties:
      instanceId:
        example: container_abc
        type: string
    type: object
  docs.InternalGrantRewardRequest:
    properties:
      assets:
        items:
          $ref: '#/definitions/docs.MintAssetPayload'
        type: array
      tokenAmount:
        example: 1000
        type: integer
      username:
        example: player1
        type: string
    type: object
  docs.InternalMintAssetRequest:
    properties:
      properties:
        additionalProperties: {}
        type: object
      templateId:
        example: sword_template
        type: string
      username:
        example: player1
        type: string
    type: object
  docs.InternalRequestEntryResponse:
    properties:
      bossId:
        example: 1
        type: integer
      players:
        items:
          type: string
        type: array
      roomId:
        example: 1
        type: integer
      sessionName:
        example: Dedi1_Room0
        type: string
      status:
        example: waiting
        type: string
      tokens:
        additionalProperties:
          type: string
        type: object
    type: object
  docs.LaunchTicketResponse:
    properties:
      ticket:
        example: ticket_abc123
        type: string
    type: object
  docs.ListOnMarketRequest:
    properties:
      assetId:
        example: asset_001
        type: string
      price:
        example: 500
        type: integer
    type: object
  docs.LoginRequest:
    properties:
      password:
        example: mypassword
        type: string
      username:
        example: player1
        type: string
    type: object
  docs.LoginResponse:
    properties:
      role:
        example: user
        type: string
      token:
        example: eyJhbGciOiJIUzI1NiIs...
        type: string
      username:
        example: player1
        type: string
    type: object
  docs.MessageResponse:
    properties:
      message:
        example: 성공
        type: string
    type: object
  docs.MintAssetPayload:
    properties:
      owner:
        example: abcdef012345...
        type: string
      properties:
        additionalProperties: {}
        type: object
      template_id:
        example: sword_template
        type: string
    type: object
  docs.MintAssetRequest:
    properties:
      ownerPubKey:
        example: abcdef012345...
        type: string
      properties:
        additionalProperties: {}
        type: object
      templateId:
        example: sword_template
        type: string
    type: object
  docs.MyEntryTokenResponse:
    properties:
      entryToken:
        example: token_abc
        type: string
      sessionName:
        example: Dedi1_Room0
        type: string
    type: object
  docs.PlayerProfileResponse:
    properties:
      attackPower:
        example: 25
        type: number
      attackRange:
        example: 3
        type: number
      createdAt:
        type: string
      experience:
        example: 1200
        type: integer
      id:
        example: 1
        type: integer
      lastPosX:
        example: 10.5
        type: number
      lastPosY:
        example: 0
        type: number
      lastPosZ:
        example: 20.3
        type: number
      lastRotY:
        example: 90
        type: number
      level:
        example: 5
        type: integer
      maxHp:
        example: 150
        type: number
      maxMp:
        example: 75
        type: number
      nextExp:
        example: 2000
        type: integer
      nickname:
        example: 용사
        type: string
      sprintMultiplier:
        example: 1.8
        type: number
      totalPlayTime:
        example: 3600
        type: integer
      updatedAt:
        type: string
      userId:
        example: 1
        type: integer
    type: object
  docs.PlayerReward:
    properties:
      assets:
        items:
          $ref: '#/definitions/docs.MintAssetPayload'
        type: array
      experience:
        example: 500
        type: integer
      tokenAmount:
        example: 100
        type: integer
      username:
        example: player1
        type: string
    type: object
  docs.RedeemTicketRequest:
    properties:
      ticket:
        example: ticket_abc123
        type: string
    type: object
  docs.RedeemTicketResponse:
    properties:
      token:
        example: eyJhbGciOiJIUzI1NiIs...
        type: string
    type: object
  docs.RefreshRequest:
    properties:
      refreshToken:
        type: string
    type: object
  docs.RefreshResponse:
    properties:
      token:
        example: eyJhbGciOiJIUzI1NiIs...
        type: string
    type: object
  docs.RegisterRequest:
    properties:
      password:
        example: mypassword
        type: string
      username:
        example: player1
        type: string
    type: object
  docs.RegisterServerRequest:
    properties:
      instanceId:
        example: container_abc
        type: string
      maxRooms:
        example: 10
        type: integer
      serverName:
        example: Dedi1
        type: string
    type: object
  docs.RegisterServerResponse:
    properties:
      instanceId:
        example: container_abc
        type: string
      sessionName:
        example: Dedi1_Room0
        type: string
    type: object
  docs.RegisterTemplateRequest:
    properties:
      id:
        example: sword_template
        type: string
      name:
        example: Sword
        type: string
      schema:
        additionalProperties: {}
        type: object
      tradeable:
        example: true
        type: boolean
    type: object
  docs.RequestEntryAuthRequest:
    properties:
      bossId:
        example: 1
        type: integer
      usernames:
        items:
          type: string
        type: array
    type: object
  docs.RequestEntryRequest:
    properties:
      bossId:
        example: 1
        type: integer
      usernames:
        example:
        - player1
        - player2
        items:
          type: string
        type: array
    type: object
  docs.RequestEntryResponse:
    properties:
      bossId:
        example: 1
        type: integer
      entryToken:
        example: token_abc
        type: string
      players:
        items:
          type: string
        type: array
      roomId:
        example: 1
        type: integer
      sessionName:
        example: Dedi1_Room0
        type: string
      status:
        example: waiting
        type: string
    type: object
  docs.ResetRoomRequest:
    properties:
      sessionName:
        example: Dedi1_Room0
        type: string
    type: object
  docs.ResetRoomResponse:
    properties:
      sessionName:
        example: Dedi1_Room0
        type: string
      status:
        example: ok
        type: string
    type: object
  docs.RewardResult:
    properties:
      error:
        type: string
      success:
        example: true
        type: boolean
      username:
        example: player1
        type: string
    type: object
  docs.RoomStatusResponse:
    properties:
      roomId:
        example: 1
        type: integer
      sessionName:
        example: Dedi1_Room0
        type: string
      status:
        example: in_progress
        type: string
    type: object
  docs.SSAFYCallbackRequest:
    properties:
      code:
        example: auth_code_123
        type: string
      state:
        example: random_state_string
        type: string
    type: object
  docs.SSAFYLoginURLResponse:
    properties:
      url:
        example: https://edu.ssafy.com/oauth/authorize?...
        type: string
    type: object
  docs.SessionNameRequest:
    properties:
      sessionName:
        example: Dedi1_Room0
        type: string
    type: object
  docs.StatusResponse:
    properties:
      status:
        example: ok
        type: string
    type: object
  docs.TransferAssetRequest:
    properties:
      assetId:
        example: asset_001
        type: string
      to:
        example: 1a2b3c4d5e6f...
        type: string
    type: object
  docs.TransferRequest:
    properties:
      amount:
        example: 100
        type: integer
      to:
        example: 1a2b3c4d5e6f...
        type: string
    type: object
  docs.UnequipItemRequest:
    properties:
      assetId:
        example: asset_001
        type: string
    type: object
  docs.UpdateAnnouncementRequest:
    properties:
      content:
        example: 수정된 내용
        type: string
      title:
        example: 수정된 제목
        type: string
    type: object
  docs.UpdateProfileRequest:
    properties:
      nickname:
        example: 용사
        type: string
    type: object
  docs.UpdateRoleRequest:
    properties:
      role:
        example: admin
        type: string
    type: object
  docs.UserResponse:
    properties:
      createdAt:
        type: string
      id:
        example: 1
        type: integer
      role:
        example: user
        type: string
      ssafyId:
        example: ssafy_123
        type: string
      updatedAt:
        type: string
      username:
        example: player1
        type: string
    type: object
  docs.ValidateEntryTokenRequest:
    properties:
      entryToken:
        example: token_abc
        type: string
    type: object
  docs.ValidateEntryTokenResponse:
    properties:
      sessionName:
        example: Dedi1_Room0
        type: string
      username:
        example: player1
        type: string
      valid:
        example: true
        type: boolean
    type: object
  docs.VerifyTokenRequest:
    properties:
      token:
        example: eyJhbGciOiJIUzI1NiIs...
        type: string
    type: object
  docs.VerifyTokenResponse:
    properties:
      username:
        example: player1
        type: string
    type: object
  docs.WalletInfoResponse:
    properties:
      address:
        example: 1a2b3c4d5e6f...
        type: string
      pubKeyHex:
        example: abcdef012345...
        type: string
    type: object
  player.PlayerProfile:
    properties:
      attackPower:
        type: number
      attackRange:
        type: number
      createdAt:
        type: string
      experience:
        type: integer
      id:
        type: integer
      lastPosX:
        description: 마지막 위치
        type: number
      lastPosY:
        type: number
      lastPosZ:
        type: number
      lastRotY:
        type: number
      level:
        description: 레벨 & 경험치
        type: integer
      maxHp:
        description: 전투 스탯
        type: number
      maxMp:
        type: number
      nickname:
        type: string
      sprintMultiplier:
        type: number
      totalPlayTime:
        description: 플레이 시간 (초 단위)
        type: integer
      updatedAt:
        type: string
      userId:
        type: integer
    type: object
host: a301.api.tolelom.xyz
info:
  contact: {}
  description: 멀티플레이어 보스 레이드 게임 플랫폼 백엔드 API
  title: One of the Plans API
  version: "1.0"
paths:
  /api/announcements/:
    get:
      description: 공지사항 목록을 조회합니다
      parameters:
      - default: 0
        description: 시작 위치
        in: query
        name: offset
        type: integer
      - default: 20
        description: 조회 수
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/docs.AnnouncementResponse'
            type: array
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 공지사항 목록 조회
      tags:
      - Announcements
    post:
      consumes:
      - application/json
      description: 새 공지사항을 생성합니다
      parameters:
      - description: 공지사항 내용
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.CreateAnnouncementRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/docs.AnnouncementResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 공지사항 생성 (관리자)
      tags:
      - Announcements
  /api/announcements/{id}:
    delete:
      description: 공지사항을 삭제합니다
      parameters:
      - description: 공지사항 ID
        in: path
        name: id
        required: true
        type: integer
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 공지사항 삭제 (관리자)
      tags:
      - Announcements
    put:
      consumes:
      - application/json
      description: 공지사항을 수정합니다
      parameters:
      - description: 공지사항 ID
        in: path
        name: id
        required: true
        type: integer
      - description: 수정할 내용
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.UpdateAnnouncementRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.AnnouncementResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 공지사항 수정 (관리자)
      tags:
      - Announcements
  /api/auth/launch-ticket:
    post:
      description: 게임 런처용 일회성 티켓을 발급합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.LaunchTicketResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 런처 티켓 발급
      tags:
      - Auth
  /api/auth/login:
    post:
      consumes:
      - application/json
      description: 사용자 인증 후 JWT 토큰을 발급합니다
      parameters:
      - description: 로그인 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.LoginResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 로그인
      tags:
      - Auth
  /api/auth/logout:
    post:
      description: 현재 세션을 무효화합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.MessageResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 로그아웃
      tags:
      - Auth
  /api/auth/redeem-ticket:
    post:
      consumes:
      - application/json
      description: 일회성 티켓을 Access 토큰으로 교환합니다
      parameters:
      - description: 티켓
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.RedeemTicketRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.RedeemTicketResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 런처 티켓 교환
      tags:
      - Auth
  /api/auth/refresh:
    post:
      consumes:
      - application/json
      description: Refresh 토큰으로 새 Access 토큰을 발급합니다 (쿠키 또는 body)
      parameters:
      - description: Refresh 토큰 (쿠키 우선)
        in: body
        name: body
        schema:
          $ref: '#/definitions/docs.RefreshRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.RefreshResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 토큰 갱신
      tags:
      - Auth
  /api/auth/register:
    post:
      consumes:
      - application/json
      description: 새로운 사용자 계정을 생성합니다
      parameters:
      - description: 회원가입 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.RegisterRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/docs.MessageResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 회원가입
      tags:
      - Auth
  /api/auth/ssafy/callback:
    post:
      consumes:
      - application/json
      description: SSAFY 인가 코드를 교환하여 로그인합니다
      parameters:
      - description: 인가 코드
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.SSAFYCallbackRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.LoginResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: SSAFY OAuth 콜백
      tags:
      - Auth
  /api/auth/ssafy/login:
    get:
      description: SSAFY OAuth 로그인 URL을 생성합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.SSAFYLoginURLResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: SSAFY 로그인 URL
      tags:
      - Auth
  /api/bossraid/entry:
    post:
      consumes:
      - application/json
      description: 게임 클라이언트에서 보스 레이드 입장을 요청합니다. 인증된 유저가 입장 목록에 포함되어야 합니다.
      parameters:
      - description: 입장 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.RequestEntryAuthRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/docs.RequestEntryResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 보스 레이드 입장 요청
      tags:
      - Boss Raid
  /api/bossraid/my-entry-token:
    get:
      description: 현재 유저의 대기 중인 입장 토큰을 조회합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.MyEntryTokenResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 내 입장 토큰 조회
      tags:
      - Boss Raid
  /api/chain/admin/mint:
    post:
      consumes:
      - application/json
      description: 새 에셋을 발행합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 발행 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.MintAssetRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 에셋 발행 (관리자)
      tags:
      - Chain - Admin
  /api/chain/admin/reward:
    post:
      consumes:
      - application/json
      description: 유저에게 토큰 및 에셋 보상을 지급합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 보상 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.GrantRewardRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 보상 지급 (관리자)
      tags:
      - Chain - Admin
  /api/chain/admin/template:
    post:
      consumes:
      - application/json
      description: 새 에셋 템플릿을 등록합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 템플릿 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.RegisterTemplateRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 템플릿 등록 (관리자)
      tags:
      - Chain - Admin
  /api/chain/asset/{id}:
    get:
      description: 특정 에셋의 상세 정보를 조회합니다
      parameters:
      - description: 에셋 ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 에셋 상세 조회
      tags:
      - Chain
  /api/chain/asset/transfer:
    post:
      consumes:
      - application/json
      description: 다른 유저에게 에셋을 전송합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 전송 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.TransferAssetRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 에셋 전송
      tags:
      - Chain - Transactions
  /api/chain/assets:
    get:
      description: 현재 유저의 블록체인 에셋 목록을 조회합니다
      parameters:
      - default: 0
        description: 시작 위치
        in: query
        name: offset
        type: integer
      - default: 50
        description: 조회 수
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 에셋 목록 조회
      tags:
      - Chain
  /api/chain/balance:
    get:
      description: 현재 유저의 토큰 잔액을 조회합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 잔액 조회
      tags:
      - Chain
  /api/chain/inventory:
    get:
      description: 현재 유저의 인벤토리를 조회합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 인벤토리 조회
      tags:
      - Chain
  /api/chain/inventory/equip:
    post:
      consumes:
      - application/json
      description: 에셋을 장비 슬롯에 장착합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 장착 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.EquipItemRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 아이템 장착
      tags:
      - Chain - Transactions
  /api/chain/inventory/unequip:
    post:
      consumes:
      - application/json
      description: 에셋의 장비 슬롯 장착을 해제합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 해제 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.UnequipItemRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 아이템 장착 해제
      tags:
      - Chain - Transactions
  /api/chain/market:
    get:
      description: 마켓에 등록된 매물 목록을 조회합니다
      parameters:
      - default: 0
        description: 시작 위치
        in: query
        name: offset
        type: integer
      - default: 50
        description: 조회 수
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 마켓 목록 조회
      tags:
      - Chain
  /api/chain/market/{id}:
    get:
      description: 특정 마켓 매물의 상세 정보를 조회합니다
      parameters:
      - description: 매물 ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 마켓 매물 상세 조회
      tags:
      - Chain
  /api/chain/market/buy:
    post:
      consumes:
      - application/json
      description: 마켓에서 매물을 구매합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 구매 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.BuyFromMarketRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 마켓 구매
      tags:
      - Chain - Transactions
  /api/chain/market/cancel:
    post:
      consumes:
      - application/json
      description: 마켓에 등록한 매물을 취소합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 취소 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.CancelListingRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 마켓 등록 취소
      tags:
      - Chain - Transactions
  /api/chain/market/list:
    post:
      consumes:
      - application/json
      description: 에셋을 마켓에 등록합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 등록 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.ListOnMarketRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 마켓 등록
      tags:
      - Chain - Transactions
  /api/chain/transfer:
    post:
      consumes:
      - application/json
      description: 다른 유저에게 토큰을 전송합니다
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 전송 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.TransferRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 토큰 전송
      tags:
      - Chain - Transactions
  /api/chain/wallet:
    get:
      description: 현재 유저의 블록체인 지갑 정보를 조회합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.WalletInfoResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 지갑 정보 조회
      tags:
      - Chain
  /api/download/file:
    get:
      description: 게임 zip 파일을 다운로드합니다
      produces:
      - application/octet-stream
      responses:
        "200":
          description: OK
          schema:
            type: file
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 게임 파일 다운로드
      tags:
      - Download
  /api/download/info:
    get:
      description: 게임 및 런처 다운로드 정보를 조회합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.DownloadInfoResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 다운로드 정보 조회
      tags:
      - Download
  /api/download/launcher:
    get:
      description: 런처 실행 파일을 다운로드합니다
      produces:
      - application/octet-stream
      responses:
        "200":
          description: OK
          schema:
            type: file
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      summary: 런처 다운로드
      tags:
      - Download
  /api/download/upload/game:
    post:
      consumes:
      - application/octet-stream
      description: 게임 zip 파일을 스트리밍 업로드합니다. Body는 raw binary입니다.
      parameters:
      - default: game.zip
        description: 파일명
        in: query
        name: filename
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.DownloadInfoResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 게임 파일 업로드 (관리자)
      tags:
      - Download
  /api/download/upload/launcher:
    post:
      consumes:
      - application/octet-stream
      description: 런처 실행 파일을 스트리밍 업로드합니다. Body는 raw binary입니다.
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.DownloadInfoResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 런처 업로드 (관리자)
      tags:
      - Download
  /api/internal/auth/verify:
    post:
      consumes:
      - application/json
      description: JWT 토큰을 검증하고 username을 반환합니다
      parameters:
      - description: 검증할 토큰
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.VerifyTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.VerifyTokenResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 토큰 검증 (내부 API)
      tags:
      - Internal - Auth
  /api/internal/bossraid/complete:
    post:
      consumes:
      - application/json
      description: 보스 처치 시 데디케이티드 서버에서 호출합니다. 보상을 분배합니다.
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 완료 정보 및 보상
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.CompleteRaidRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.CompleteRaidResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 레이드 완료 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/entry:
    post:
      consumes:
      - application/json
      description: MMO 서버에서 파티의 보스 레이드 입장을 요청합니다. 모든 플레이어의 entry token을 반환합니다.
      parameters:
      - description: 입장 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.RequestEntryRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/docs.InternalRequestEntryResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 보스 레이드 입장 요청 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/fail:
    post:
      consumes:
      - application/json
      description: 타임아웃 또는 전멸 시 데디케이티드 서버에서 호출합니다
      parameters:
      - description: 세션 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.SessionNameRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.RoomStatusResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 레이드 실패 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/heartbeat:
    post:
      consumes:
      - application/json
      description: 데디케이티드 서버 컨테이너가 주기적으로 호출합니다
      parameters:
      - description: 인스턴스 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.HeartbeatRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.StatusResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 하트비트 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/register:
    post:
      consumes:
      - application/json
      description: 데디케이티드 서버 컨테이너가 시작 시 호출합니다. 룸 슬롯을 자동 할당합니다.
      parameters:
      - description: 서버 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.RegisterServerRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/docs.RegisterServerResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 데디케이티드 서버 등록 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/reset-room:
    post:
      consumes:
      - application/json
      description: 레이드 종료 후 슬롯을 idle 상태로 되돌립니다
      parameters:
      - description: 세션 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.ResetRoomRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.ResetRoomResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 룸 슬롯 리셋 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/room:
    get:
      description: sessionName으로 보스 레이드 방 정보를 조회합니다
      parameters:
      - description: 세션 이름
        in: query
        name: sessionName
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/bossraid.BossRoom'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 방 정보 조회 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/server-status:
    get:
      description: 데디케이티드 서버의 정보와 룸 슬롯 목록을 조회합니다
      parameters:
      - description: 서버 이름
        in: query
        name: serverName
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 서버 상태 조회 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/start:
    post:
      consumes:
      - application/json
      description: Fusion 세션이 시작될 때 데디케이티드 서버에서 호출합니다
      parameters:
      - description: 세션 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.SessionNameRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.RoomStatusResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 레이드 시작 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/bossraid/validate-entry:
    post:
      consumes:
      - application/json
      description: 데디케이티드 서버에서 플레이어의 입장 토큰을 검증합니다. 일회성 소모.
      parameters:
      - description: 토큰
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.ValidateEntryTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.ValidateEntryTokenResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 입장 토큰 검증 (내부 API)
      tags:
      - Internal - Boss Raid
  /api/internal/chain/assets:
    get:
      description: username으로 에셋 목록을 조회합니다 (게임 서버용)
      parameters:
      - description: 유저명
        in: query
        name: username
        required: true
        type: string
      - default: 0
        description: 시작 위치
        in: query
        name: offset
        type: integer
      - default: 50
        description: 조회 수
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 에셋 목록 조회 (내부 API)
      tags:
      - Internal - Chain
  /api/internal/chain/balance:
    get:
      description: username으로 잔액을 조회합니다 (게임 서버용)
      parameters:
      - description: 유저명
        in: query
        name: username
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 잔액 조회 (내부 API)
      tags:
      - Internal - Chain
  /api/internal/chain/inventory:
    get:
      description: username으로 인벤토리를 조회합니다 (게임 서버용)
      parameters:
      - description: 유저명
        in: query
        name: username
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 인벤토리 조회 (내부 API)
      tags:
      - Internal - Chain
  /api/internal/chain/mint:
    post:
      consumes:
      - application/json
      description: username으로 에셋을 발행합니다 (게임 서버용)
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 발행 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.InternalMintAssetRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 에셋 발행 (내부 API)
      tags:
      - Internal - Chain
  /api/internal/chain/reward:
    post:
      consumes:
      - application/json
      description: username으로 유저에게 보상을 지급합니다 (게임 서버용)
      parameters:
      - description: 멱등성 키
        in: header
        name: Idempotency-Key
        required: true
        type: string
      - description: 보상 정보
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.InternalGrantRewardRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 보상 지급 (내부 API)
      tags:
      - Internal - Chain
  /api/internal/player/profile:
    get:
      description: username으로 플레이어 프로필을 조회합니다 (게임 서버용)
      parameters:
      - description: 유저명
        in: query
        name: username
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.PlayerProfileResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 프로필 조회 (내부 API)
      tags:
      - Internal - Player
  /api/internal/player/save:
    post:
      consumes:
      - application/json
      description: username으로 게임 데이터를 저장합니다 (게임 서버용)
      parameters:
      - description: 유저명
        in: query
        name: username
        required: true
        type: string
      - description: 게임 데이터
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.GameDataRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.MessageResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: 게임 데이터 저장 (내부 API)
      tags:
      - Internal - Player
  /api/player/profile:
    get:
      description: 현재 유저의 플레이어 프로필을 조회합니다
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.PlayerProfileResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 내 프로필 조회
      tags:
      - Player
    put:
      consumes:
      - application/json
      description: 현재 유저의 닉네임을 수정합니다
      parameters:
      - description: 수정할 프로필
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.UpdateProfileRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/player.PlayerProfile'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 프로필 수정
      tags:
      - Player
  /api/users/:
    get:
      description: 모든 유저 목록을 조회합니다
      parameters:
      - default: 0
        description: 시작 위치
        in: query
        name: offset
        type: integer
      - default: 50
        description: 조회 수
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/docs.UserResponse'
            type: array
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 전체 유저 목록 (관리자)
      tags:
      - Users
  /api/users/{id}:
    delete:
      description: 유저를 삭제합니다
      parameters:
      - description: 유저 ID
        in: path
        name: id
        required: true
        type: integer
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 유저 삭제 (관리자)
      tags:
      - Users
  /api/users/{id}/role:
    patch:
      consumes:
      - application/json
      description: 유저의 역할을 admin 또는 user로 변경합니다
      parameters:
      - description: 유저 ID
        in: path
        name: id
        required: true
        type: integer
      - description: 변경할 역할
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/docs.UpdateRoleRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/docs.MessageResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/docs.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 유저 권한 변경 (관리자)
      tags:
      - Users
securityDefinitions:
  ApiKeyAuth:
    description: 내부 API 키 (게임 서버 ↔ API 서버 통신용)
    in: header
    name: X-API-Key
    type: apiKey
  BearerAuth:
    description: 'JWT Bearer 토큰 (예: Bearer eyJhbGci...)'
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"