backend/docs/swagger.yaml

definitions:
  carrotskin_internal_model.ErrorResponse:
    properties:
      code:
        type: integer
      error:
        description: 详细错误信息（仅开发环境）
        type: string
      message:
        type: string
    type: object
  carrotskin_internal_model.PaginationResponse:
    properties:
      code:
        type: integer
      data: {}
      message:
        type: string
      page:
        description: 当前页码
        type: integer
      per_page:
        description: 每页数量
        type: integer
      total:
        description: 总记录数
        type: integer
    type: object
  carrotskin_internal_model.Response:
    properties:
      code:
        description: 业务状态码
        type: integer
      data:
        description: 响应数据
      message:
        description: 响应消息
        type: string
    type: object
  carrotskin_internal_types.ChangeEmailRequest:
    properties:
      new_email:
        example: newemail@example.com
        type: string
      verification_code:
        example: "123456"
        type: string
    required:
    - new_email
    - verification_code
    type: object
  carrotskin_internal_types.CreateProfileRequest:
    properties:
      name:
        example: PlayerName
        maxLength: 16
        minLength: 1
        type: string
    required:
    - name
    type: object
  carrotskin_internal_types.CreateTextureRequest:
    properties:
      description:
        example: A very cool skin
        maxLength: 500
        type: string
      hash:
        example: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
        type: string
      is_public:
        example: true
        type: boolean
      is_slim:
        description: Alex模型(细臂)为true，Steve模型(粗臂)为false
        example: false
        type: boolean
      name:
        example: My Cool Skin
        maxLength: 100
        minLength: 1
        type: string
      size:
        example: 2048
        minimum: 1
        type: integer
      type:
        allOf:
        - $ref: '#/definitions/carrotskin_internal_types.TextureType'
        enum:
        - SKIN
        - CAPE
        example: SKIN
      url:
        example: https://rustfs.example.com/textures/user_1/skin/xxx.png
        type: string
    required:
    - hash
    - name
    - size
    - type
    - url
    type: object
  carrotskin_internal_types.GenerateAvatarUploadURLRequest:
    properties:
      file_name:
        example: avatar.png
        type: string
    required:
    - file_name
    type: object
  carrotskin_internal_types.GenerateTextureUploadURLRequest:
    properties:
      file_name:
        example: skin.png
        type: string
      texture_type:
        allOf:
        - $ref: '#/definitions/carrotskin_internal_types.TextureType'
        enum:
        - SKIN
        - CAPE
        example: SKIN
    required:
    - file_name
    - texture_type
    type: object
  carrotskin_internal_types.LoginRequest:
    properties:
      password:
        example: password123
        maxLength: 128
        minLength: 6
        type: string
      username:
        description: 支持用户名或邮箱
        example: testuser
        type: string
    required:
    - password
    - username
    type: object
  carrotskin_internal_types.LoginResponse:
    properties:
      token:
        type: string
      user_info:
        $ref: '#/definitions/carrotskin_internal_types.UserInfo'
    type: object
  carrotskin_internal_types.ProfileInfo:
    properties:
      cape_id:
        example: 2
        type: integer
      created_at:
        example: "2025-10-01T10:00:00Z"
        type: string
      is_active:
        example: true
        type: boolean
      last_used_at:
        example: "2025-10-01T12:00:00Z"
        type: string
      name:
        example: PlayerName
        type: string
      skin_id:
        example: 1
        type: integer
      updated_at:
        example: "2025-10-01T10:00:00Z"
        type: string
      user_id:
        example: 1
        type: integer
      uuid:
        example: 550e8400-e29b-41d4-a716-446655440000
        type: string
    type: object
  carrotskin_internal_types.RegisterRequest:
    properties:
      avatar:
        description: 可选，用户自定义头像
        example: https://rustfs.example.com/avatars/user_1/avatar.png
        type: string
      email:
        example: user@example.com
        type: string
      password:
        example: password123
        maxLength: 128
        minLength: 6
        type: string
      username:
        example: newuser
        maxLength: 50
        minLength: 3
        type: string
      verification_code:
        description: 邮箱验证码
        example: "123456"
        type: string
    required:
    - email
    - password
    - username
    - verification_code
    type: object
  carrotskin_internal_types.ResetPasswordRequest:
    properties:
      email:
        example: user@example.com
        type: string
      new_password:
        example: newpassword123
        maxLength: 128
        minLength: 6
        type: string
      verification_code:
        example: "123456"
        type: string
    required:
    - email
    - new_password
    - verification_code
    type: object
  carrotskin_internal_types.SendVerificationCodeRequest:
    properties:
      email:
        example: user@example.com
        type: string
      type:
        description: '类型: register/reset_password/change_email'
        enum:
        - register
        - reset_password
        - change_email
        example: register
        type: string
    required:
    - email
    - type
    type: object
  carrotskin_internal_types.TextureType:
    enum:
    - SKIN
    - CAPE
    type: string
    x-enum-varnames:
    - TextureTypeSkin
    - TextureTypeCape
  carrotskin_internal_types.UpdateProfileRequest:
    properties:
      cape_id:
        example: 2
        type: integer
      name:
        example: NewPlayerName
        maxLength: 16
        minLength: 1
        type: string
      skin_id:
        example: 1
        type: integer
    type: object
  carrotskin_internal_types.UpdateTextureRequest:
    properties:
      description:
        example: A cool skin
        maxLength: 500
        type: string
      is_public:
        example: true
        type: boolean
      name:
        example: My Skin
        maxLength: 100
        minLength: 1
        type: string
    type: object
  carrotskin_internal_types.UpdateUserRequest:
    properties:
      avatar:
        example: https://example.com/new-avatar.png
        type: string
      new_password:
        description: 新密码
        example: newpassword123
        maxLength: 128
        minLength: 6
        type: string
      old_password:
        description: 修改密码时必需
        example: oldpassword123
        maxLength: 128
        minLength: 6
        type: string
    type: object
  carrotskin_internal_types.UserInfo:
    properties:
      avatar:
        example: https://example.com/avatar.png
        type: string
      created_at:
        example: "2025-10-01T10:00:00Z"
        type: string
      email:
        example: test@example.com
        type: string
      id:
        example: 1
        type: integer
      last_login_at:
        example: "2025-10-01T12:00:00Z"
        type: string
      points:
        example: 100
        type: integer
      role:
        example: user
        type: string
      status:
        example: 1
        type: integer
      updated_at:
        example: "2025-10-01T10:00:00Z"
        type: string
      username:
        example: testuser
        type: string
    type: object
info:
  contact: {}
paths:
  /api/v1/auth/login:
    post:
      consumes:
      - application/json
      description: 用户登录获取JWT Token，支持用户名或邮箱登录
      parameters:
      - description: 登录信息（username字段支持用户名或邮箱）
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 登录成功
          schema:
            allOf:
            - $ref: '#/definitions/carrotskin_internal_model.Response'
            - properties:
                data:
                  $ref: '#/definitions/carrotskin_internal_types.LoginResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "401":
          description: 登录失败
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      summary: 用户登录
      tags:
      - auth
  /api/v1/auth/register:
    post:
      consumes:
      - application/json
      description: 注册新用户账号
      parameters:
      - description: 注册信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.RegisterRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 注册成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      summary: 用户注册
      tags:
      - auth
  /api/v1/auth/reset-password:
    post:
      consumes:
      - application/json
      description: 通过邮箱验证码重置密码
      parameters:
      - description: 重置密码请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.ResetPasswordRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 重置成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      summary: 重置密码
      tags:
      - auth
  /api/v1/auth/send-code:
    post:
      consumes:
      - application/json
      description: 发送邮箱验证码（注册/重置密码/更换邮箱）
      parameters:
      - description: 发送验证码请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.SendVerificationCodeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 发送成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      summary: 发送验证码
      tags:
      - auth
  /api/v1/profile:
    get:
      consumes:
      - application/json
      description: 获取当前用户的所有档案
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 获取档案列表
      tags:
      - profile
    post:
      consumes:
      - application/json
      description: 创建新的Minecraft角色档案，UUID由后端自动生成
      parameters:
      - description: 档案信息（仅需提供角色名）
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.CreateProfileRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 创建成功，返回完整档案信息（含自动生成的UUID）
          schema:
            allOf:
            - $ref: '#/definitions/carrotskin_internal_model.Response'
            - properties:
                data:
                  $ref: '#/definitions/carrotskin_internal_types.ProfileInfo'
              type: object
        "400":
          description: 请求参数错误或已达档案数量上限
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 创建Minecraft档案
      tags:
      - profile
  /api/v1/profile/{uuid}:
    delete:
      consumes:
      - application/json
      description: 删除指定的Minecraft档案
      parameters:
      - description: 档案UUID
        in: path
        name: uuid
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "403":
          description: 无权操作
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "404":
          description: 档案不存在
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 删除档案
      tags:
      - profile
    get:
      consumes:
      - application/json
      description: 根据UUID获取档案详细信息
      parameters:
      - description: 档案UUID
        in: path
        name: uuid
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "404":
          description: 档案不存在
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      summary: 获取档案详情
      tags:
      - profile
    put:
      consumes:
      - application/json
      description: 更新档案信息
      parameters:
      - description: 档案UUID
        in: path
        name: uuid
        required: true
        type: string
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.UpdateProfileRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "403":
          description: 无权操作
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "404":
          description: 档案不存在
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 更新档案
      tags:
      - profile
  /api/v1/profile/{uuid}/activate:
    post:
      consumes:
      - application/json
      description: 将指定档案设置为活跃状态
      parameters:
      - description: 档案UUID
        in: path
        name: uuid
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 设置成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "403":
          description: 无权操作
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "404":
          description: 档案不存在
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 设置活跃档案
      tags:
      - profile
  /api/v1/system/config:
    get:
      consumes:
      - application/json
      description: 获取公开的系统配置信息
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
      summary: 获取系统配置
      tags:
      - system
  /api/v1/texture:
    get:
      consumes:
      - application/json
      description: 根据关键词和类型搜索材质
      parameters:
      - description: 关键词
        in: query
        name: keyword
        type: string
      - description: 材质类型(SKIN/CAPE)
        in: query
        name: type
        type: string
      - description: 只看公开材质
        in: query
        name: public_only
        type: boolean
      - default: 1
        description: 页码
        in: query
        name: page
        type: integer
      - default: 20
        description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 搜索成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.PaginationResponse'
      summary: 搜索材质
      tags:
      - texture
    post:
      consumes:
      - application/json
      description: 文件上传完成后，创建材质记录到数据库
      parameters:
      - description: 创建材质请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.CreateTextureRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 创建成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 创建材质记录
      tags:
      - texture
  /api/v1/texture/{id}:
    delete:
      consumes:
      - application/json
      description: 删除材质（软删除，仅上传者可操作）
      parameters:
      - description: 材质ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "403":
          description: 无权操作
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 删除材质
      tags:
      - texture
    get:
      consumes:
      - application/json
      description: 根据ID获取材质详细信息
      parameters:
      - description: 材质ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "404":
          description: 材质不存在
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      summary: 获取材质详情
      tags:
      - texture
    put:
      consumes:
      - application/json
      description: 更新材质信息（仅上传者可操作）
      parameters:
      - description: 材质ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新材质请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.UpdateTextureRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "403":
          description: 无权操作
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 更新材质
      tags:
      - texture
  /api/v1/texture/{id}/favorite:
    post:
      consumes:
      - application/json
      description: 收藏或取消收藏材质
      parameters:
      - description: 材质ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 切换成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
      security:
      - BearerAuth: []
      summary: 切换收藏状态
      tags:
      - texture
  /api/v1/texture/favorites:
    get:
      consumes:
      - application/json
      description: 获取当前用户收藏的所有材质
      parameters:
      - default: 1
        description: 页码
        in: query
        name: page
        type: integer
      - default: 20
        description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.PaginationResponse'
      security:
      - BearerAuth: []
      summary: 获取用户收藏的材质列表
      tags:
      - texture
  /api/v1/texture/my:
    get:
      consumes:
      - application/json
      description: 获取当前用户上传的所有材质
      parameters:
      - default: 1
        description: 页码
        in: query
        name: page
        type: integer
      - default: 20
        description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.PaginationResponse'
      security:
      - BearerAuth: []
      summary: 获取用户上传的材质列表
      tags:
      - texture
  /api/v1/texture/upload-url:
    post:
      consumes:
      - application/json
      description: 生成预签名URL用于上传材质文件
      parameters:
      - description: 上传URL请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.GenerateTextureUploadURLRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 生成成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 生成材质上传URL
      tags:
      - texture
  /api/v1/user/avatar:
    put:
      consumes:
      - application/json
      description: 上传完成后更新用户的头像URL到数据库
      parameters:
      - description: 头像URL
        in: query
        name: avatar_url
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 更新头像URL
      tags:
      - user
  /api/v1/user/avatar/upload-url:
    post:
      consumes:
      - application/json
      description: 生成预签名URL用于上传用户头像
      parameters:
      - description: 文件名
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.GenerateAvatarUploadURLRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 生成成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 生成头像上传URL
      tags:
      - user
  /api/v1/user/change-email:
    post:
      consumes:
      - application/json
      description: 通过验证码更换用户邮箱
      parameters:
      - description: 更换邮箱请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.ChangeEmailRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更换成功
          schema:
            allOf:
            - $ref: '#/definitions/carrotskin_internal_model.Response'
            - properties:
                data:
                  $ref: '#/definitions/carrotskin_internal_types.UserInfo'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 更换邮箱
      tags:
      - user
  /api/v1/user/profile:
    get:
      consumes:
      - application/json
      description: 获取当前登录用户的详细信息
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            $ref: '#/definitions/carrotskin_internal_model.Response'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 获取用户信息
      tags:
      - user
    put:
      consumes:
      - application/json
      description: 更新当前登录用户的头像和密码（修改邮箱请使用 /change-email 接口）
      parameters:
      - description: 更新信息（修改密码时需同时提供old_password和new_password）
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/carrotskin_internal_types.UpdateUserRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/carrotskin_internal_model.Response'
            - properties:
                data:
                  $ref: '#/definitions/carrotskin_internal_types.UserInfo'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/carrotskin_internal_model.ErrorResponse'
      security:
      - BearerAuth: []
      summary: 更新用户信息
      tags:
      - user
  /health:
    get:
      consumes:
      - application/json
      description: 检查服务是否正常运行
      produces:
      - application/json
      responses:
        "200":
          description: 成功
          schema:
            additionalProperties: true
            type: object
      summary: 健康检查
      tags:
      - system
swagger: "2.0"