definitions:
  data.User:
    properties:
      allow_public:
        type: boolean
      avatar:
        type: string
      bio:
        type: string
      email:
        type: string
      id:
        type: integer
      nickname:
        type: string
      permission_level:
        type: integer
      subtitle:
        type: string
      user_id:
        type: string
      username:
        type: string
      uuid:
        type: string
    type: object
  data.UserSearchDoc:
    properties:
      avatar:
        type: string
      email:
        type: string
      nickname:
        type: string
      subtitle:
        type: string
      type:
        type: string
      user_id:
        type: string
      username:
        type: string
    type: object
  exception.Builder:
    properties:
      endpoint:
        type: string
      error: {}
      errorCode:
        type: string
      original:
        type: string
      service:
        type: string
      status:
        type: string
      type:
        type: string
    type: object
  service_auth.ExchangeData:
    properties:
      client_id:
        type: string
      redirect_uri:
        type: string
      state:
        type: string
    type: object
  service_auth.ExchangeResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data:
        properties:
          redirect_uri:
            type: string
        type: object
    type: object
  service_auth.MagicData:
    properties:
      client_id:
        type: string
      client_ip:
        type: string
      email:
        type: string
      redirect_uri:
        type: string
      state:
        type: string
      turnstile_token:
        type: string
    type: object
  service_auth.MagicResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data: {}
    type: object
  service_auth.RefreshData:
    properties:
      refresh_token:
        type: string
    type: object
  service_auth.RefreshResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data:
        $ref: '#/definitions/service_auth.TokenResponse'
    type: object
  service_auth.TokenData:
    properties:
      code:
        type: string
    type: object
  service_auth.TokenResponse:
    properties:
      access_token:
        type: string
      refresh_token:
        type: string
    type: object
  service_auth.TokenResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data:
        $ref: '#/definitions/service_auth.TokenResponse'
    type: object
  service_event.CheckinQueryResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data:
        properties:
          checkin_at:
            type: string
        type: object
    type: object
  service_event.CheckinResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data:
        properties:
          checkin_code:
            type: string
        type: object
    type: object
  service_event.CheckinSubmitData:
    properties:
      checkin_code:
        type: string
    type: object
  service_event.CheckinSubmitResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
    type: object
  service_event.InfoResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data:
        properties:
          end_time:
            type: string
          name:
            type: string
          start_time:
            type: string
        type: object
    type: object
  service_user.UserInfoData:
    properties:
      allow_public:
        type: boolean
      avatar:
        type: string
      bio:
        type: string
      email:
        type: string
      nickname:
        type: string
      permission_level:
        type: integer
      subtitle:
        type: string
      user_id:
        type: string
      username:
        type: string
    type: object
  service_user.UserInfoResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      data:
        $ref: '#/definitions/service_user.UserInfoData'
    type: object
  service_user.UserListResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      user_list:
        items:
          $ref: '#/definitions/data.UserSearchDoc'
        type: array
    type: object
  service_user.UserTableResult:
    properties:
      common:
        $ref: '#/definitions/shared.CommonResult'
      user_table:
        items:
          $ref: '#/definitions/data.User'
        type: array
    type: object
  shared.CommonResult:
    properties:
      exception:
        $ref: '#/definitions/exception.Builder'
      httpCode:
        type: integer
    type: object
info:
  contact: {}
paths:
  /auth/exchange:
    post:
      consumes:
      - application/json
      description: Exchanges client credentials and user session for a specific redirect
        authorization code.
      parameters:
      - description: Exchange Request Credentials
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.ExchangeData'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_auth.ExchangeResult'
        "400":
          description: Invalid Input
          schema:
            type: string
        "401":
          description: Unauthorized
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Exchange Auth Code
      tags:
      - Authentication
  /auth/magic:
    post:
      consumes:
      - application/json
      description: Verifies Turnstile token and sends an authentication link via email.
        Returns the URI directly if debug mode is enabled.
      parameters:
      - description: Magic Link Request Data
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.MagicData'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_auth.MagicResult'
        "400":
          description: Invalid Input
          schema:
            type: string
        "403":
          description: Turnstile Verification Failed
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      summary: Request Magic Link
      tags:
      - Authentication
  /auth/redirect:
    get:
      consumes:
      - application/x-www-form-urlencoded
      description: Verifies the temporary email code, ensures the user exists (or
        creates one), validates the client's redirect URI, and finally performs a
        302 redirect with a new authorization code.
      parameters:
      - description: Client Identifier
        in: query
        name: client_id
        required: true
        type: string
      - description: Target Redirect URI
        in: query
        name: redirect_uri
        required: true
        type: string
      - description: Temporary Verification Code
        in: query
        name: code
        required: true
        type: string
      - description: Opaque state used to maintain state between the request and callback
        in: query
        name: state
        type: string
      produces:
      - text/html
      responses:
        "302":
          description: Redirect to the provided RedirectUri with a new code
          schema:
            type: string
        "400":
          description: Invalid Input / Client Not Found / URI Mismatch
          schema:
            type: string
        "403":
          description: Invalid or Expired Verification Code
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      summary: Handle Auth Callback and Redirect
      tags:
      - Authentication
  /auth/refresh:
    post:
      consumes:
      - application/json
      description: Accepts a valid refresh token to issue a new access token and a
        rotated refresh token.
      parameters:
      - description: Refresh Token Body
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.RefreshData'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_auth.RefreshResult'
        "400":
          description: Invalid Input
          schema:
            type: string
        "401":
          description: Invalid Refresh Token
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      summary: Refresh Access Token
      tags:
      - Authentication
  /auth/token:
    post:
      consumes:
      - application/json
      description: Verifies the provided authorization code and issues a pair of JWT
        tokens (Access and Refresh).
      parameters:
      - description: Token Request Body
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.TokenData'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_auth.TokenResult'
        "400":
          description: Invalid Input
          schema:
            type: string
        "403":
          description: Invalid or Expired Code
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      summary: Exchange Code for Token
      tags:
      - Authentication
  /event/checkin:
    get:
      consumes:
      - application/json
      description: Creates a temporary check-in code for the authenticated user and
        event.
      parameters:
      - description: Event UUID
        in: query
        name: event_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_event.CheckinResult'
      summary: Generate Check-in Code
      tags:
      - Event
  /event/checkin/query:
    get:
      consumes:
      - application/json
      description: Returns the timestamp of when the user checked in, or null if not
        yet checked in.
      parameters:
      - description: Event UUID
        in: query
        name: event_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_event.CheckinQueryResult'
      summary: Query Check-in Status
      tags:
      - Event
  /event/checkin/submit:
    post:
      consumes:
      - application/json
      description: Submits the generated code to mark the user as attended.
      parameters:
      - description: Checkin Code Data
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_event.CheckinSubmitData'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_event.CheckinSubmitResult'
      summary: Submit Check-in Code
      tags:
      - Event
  /event/info:
    get:
      consumes:
      - application/json
      description: Fetches the name, start time, and end time of an event using its
        UUID.
      parameters:
      - description: Event UUID
        in: query
        name: event_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_event.InfoResult'
        "400":
          description: Invalid Input
          schema:
            type: string
        "404":
          description: Event Not Found
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      summary: Get Event Information
      tags:
      - Event
  /user/full:
    get:
      consumes:
      - application/json
      description: Fetches all user records without pagination. This is typically
        used for administrative overview or data export.
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_user.UserTableResult'
        "500":
          description: Internal Server Error (Database Error)
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Get Full User Table
      tags:
      - User
  /user/info:
    get:
      consumes:
      - application/json
      description: Fetches the complete profile data for the user associated with
        the provided session/token.
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_user.UserInfoResult'
        "403":
          description: Missing User ID / Unauthorized
          schema:
            type: string
        "404":
          description: User Not Found
          schema:
            type: string
        "500":
          description: Internal Server Error (UUID Parse Failed)
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Get My User Information
      tags:
      - User
  /user/list:
    get:
      consumes:
      - application/json
      description: Fetches a list of users with support for pagination via limit and
        offset.
      parameters:
      - description: Maximum number of users to return (default 0)
        in: query
        name: limit
        type: string
      - description: Number of users to skip
        in: query
        name: offset
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_user.UserListResult'
        "400":
          description: Invalid Input (Format Error)
          schema:
            type: string
        "500":
          description: Internal Server Error (Search Engine or Missing Offset)
          schema:
            type: string
      summary: List Users
      tags:
      - User
  /user/update:
    patch:
      consumes:
      - application/json
      description: |-
        Updates specific profile fields such as username, nickname, subtitle, avatar (URL), and bio (Base64).
        Validation: Username (5-255 chars), Nickname (max 24 chars), Subtitle (max 32 chars).
      parameters:
      - description: Updated User Profile Data
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_user.UserInfoData'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/service_user.UserInfoResult'
        "400":
          description: Invalid Input (Validation Failed)
          schema:
            type: string
        "403":
          description: Missing User ID / Unauthorized
          schema:
            type: string
        "500":
          description: Internal Server Error (Database Error / UUID Parse Failed)
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Update User Information
      tags:
      - User
swagger: "2.0"