basePath: /api/v1
definitions:
  activity.PurchaseItemRequest:
    properties:
      activity_id:
        type: integer
      item_type:
        type: string
      quantity:
        type: integer
      star_id:
        type: integer
      user_id:
        description: 当前用户ID
        type: integer
    type: object
  common.BaseResponse:
    properties:
      code:
        allOf:
        - $ref: '#/definitions/common.StatusCode'
        description: 状态码
      message:
        description: 错误信息（成功时为空）
        type: string
      timestamp:
        description: 响应时间戳（Unix时间戳毫秒）
        type: integer
    type: object
  common.StatusCode:
    enum:
    - 0
    - 200
    - 400
    - 401
    - 403
    - 404
    - 429
    - 500
    format: int32
    type: integer
    x-enum-varnames:
    - StatusCode_STATUS_UNSPECIFIED
    - StatusCode_STATUS_OK
    - StatusCode_STATUS_BAD_REQUEST
    - StatusCode_STATUS_UNAUTHORIZED
    - StatusCode_STATUS_FORBIDDEN
    - StatusCode_STATUS_NOT_FOUND
    - StatusCode_STATUS_TOO_MANY_REQUESTS
    - StatusCode_STATUS_INTERNAL_ERROR
  dto.AddIdentityResponseDTO:
    properties:
      bound:
        type: boolean
      identity_id:
        type: string
    type: object
  dto.AssetDTO:
    properties:
      asset_id:
        description: 资产ID
        type: integer
      block_number:
        description: 区块号（可选）
        type: integer
      cover_url:
        description: 封面图URL
        type: string
      cover_url_signed:
        description: 封面图预签名URL（自动生成）
        type: string
      created_at:
        description: 创建时间（毫秒时间戳）
        type: integer
      description:
        description: 藏品描述（可选）
        type: string
      is_liked:
        description: 当前用户是否已点赞
        type: boolean
      like_count:
        description: 点赞数
        type: integer
      material_url:
        description: 用户上传的素材URL
        type: string
      material_url_signed:
        description: 素材图预签名URL（自动生成）
        type: string
      minted_at:
        description: 上链成功时间（毫秒时间戳，可选）
        type: integer
      name:
        description: 藏品名称
        type: string
      owner:
        allOf:
        - $ref: '#/definitions/dto.OwnerInfoDTO'
        description: 持有者信息（可选，保留用于兼容性）
      owner_nickname:
        description: 持有者昵称（在该star下的昵称）
        type: string
      owner_uid:
        description: 当前持有者
        type: integer
      rarity:
        description: 稀有度（可选）
        type: integer
      star_id:
        description: 所属星球
        type: integer
      status:
        description: 状态：0=Pending, 1=Active
        type: integer
      tags:
        description: 标签数组（可选）
        items:
          type: string
        type: array
      tx_hash:
        description: 交易哈希（可选）
        type: string
      updated_at:
        description: 更新时间（毫秒时间戳）
        type: integer
      visibility:
        description: 可见性：private, friends, public
        type: string
    type: object
  dto.AssetInfoDTO:
    properties:
      asset_id:
        description: 资产ID
        type: integer
      cover_url:
        description: 封面图URL
        type: string
      like_count:
        description: 点赞数
        type: integer
      name:
        description: 资产名称
        type: string
      remain_time:
        description: 剩余时间（秒）
        type: integer
    type: object
  dto.CreateMintOrderRequestDTO:
    properties:
      description:
        description: 藏品描述（可选）
        type: string
      event:
        description: 藏品事件（可选）
        type: string
      material_type:
        description: 素材类型（可选）
        type: string
      material_url:
        description: 用户上传的素材URL（必填，前端已上传到OSS）
        type: string
      name:
        description: 藏品名称（必填）
        type: string
      order_id:
        description: 阶段一生成的订单ID（必填）
        type: string
      rarity:
        description: 稀有度（可选）
        type: integer
      tags:
        description: 标签列表（可选）
        items:
          type: string
        type: array
    required:
    - material_url
    - name
    - order_id
    type: object
  dto.CurrentIdentityDTO:
    properties:
      crystal_balance:
        type: integer
      identity_id:
        description: '"wyb"'
        type: string
      identity_name:
        description: '"王一博"'
        type: string
      level:
        type: integer
      star_id:
        description: 明星ID
        type: integer
      tag:
        description: '"小摩托"'
        type: string
    type: object
  dto.FanIdentityDTO:
    properties:
      identity_id:
        description: stars.identity_id（如"wyb"）
        type: string
      name:
        description: stars.name（原始名称，如"王一博"）
        type: string
      star_id:
        description: 明星ID
        type: integer
      tag:
        description: stars.tag（昵称标签，如"小摩托"）
        type: string
    type: object
  dto.FanIdentityListItemDTO:
    properties:
      identity_id:
        description: '"wyb"'
        type: string
      name:
        description: '"王一博"'
        type: string
      pic_url:
        type: string
      star_id:
        description: 88（star 的主键 ID，用于切换身份）
        type: integer
      tag:
        description: '"小摩托"'
        type: string
    type: object
  dto.FanIdentityListResponseDTO:
    properties:
      items:
        items:
          $ref: '#/definitions/dto.FanIdentityListItemDTO'
        type: array
      total:
        type: integer
    type: object
  dto.GetMeResponseDTO:
    properties:
      avatar_url:
        type: string
      chain_address:
        type: string
      current_identity:
        $ref: '#/definitions/dto.CurrentIdentityDTO'
      nickname:
        type: string
      uid:
        type: integer
    type: object
  dto.GetMintOrderResponseDTO:
    properties:
      asset:
        allOf:
        - $ref: '#/definitions/dto.AssetDTO'
        description: 关联的资产信息（如果存在）
      order:
        allOf:
        - $ref: '#/definitions/dto.MintOrderDTO'
        description: 订单信息
    type: object
  dto.GetMyGalleryResponseDTO:
    properties:
      gallery_owner_id:
        description: 展馆所有者ID
        type: integer
      nickname:
        description: 展馆所有者昵称
        type: string
      slot_total:
        description: 展位总数
        type: integer
      slots:
        description: 展位列表
        items:
          $ref: '#/definitions/dto.SlotInfoDTO'
        type: array
    type: object
  dto.GetUserGalleryResponseDTO:
    properties:
      gallery_owner_id:
        description: 展馆所有者ID
        type: integer
      nickname:
        description: 展馆所有者昵称
        type: string
      slot_total:
        description: 展位总数
        type: integer
      slots:
        description: 展位列表
        items:
          $ref: '#/definitions/dto.SlotInfoDTO'
        type: array
    type: object
  dto.LoginResponseDTO:
    properties:
      access_token:
        type: string
      expires_in:
        type: integer
      refresh_token:
        type: string
      user:
        $ref: '#/definitions/dto.UserWithIdentityDTO'
    type: object
  dto.MintOrderDTO:
    properties:
      asset_id:
        description: 关联资产ID
        type: integer
      cost_crystal:
        description: 消耗的水晶数量
        type: integer
      cover_url:
        description: 订单查询响应中的扩展字段
        type: string
      cover_url_signed:
        description: 封面图预签名URL（成功时）
        type: string
      created_at:
        description: 创建时间（毫秒时间戳）
        type: integer
      description:
        description: 阶段一保存的描述（可选）
        type: string
      error_message:
        description: 错误信息（可选）
        type: string
      event:
        description: 藏品事件（可选）
        type: string
      material_type:
        description: 素材类型（可选）
        type: string
      material_url:
        description: 阶段一保存的素材URL（可选）
        type: string
      minted_at:
        description: 上链成功时间（毫秒时间戳，可选）
        type: integer
      name:
        description: 阶段一保存的名称（可选）
        type: string
      order_id:
        description: 订单ID（UUID）
        type: string
      retry_count:
        description: 重试次数
        type: integer
      star_id:
        description: 明星ID
        type: integer
      status:
        description: 状态：PENDING, PROCESSING, SUCCESS, FAILED
        type: string
      tx_hash:
        description: 交易哈希（成功时）
        type: string
      updated_at:
        description: 更新时间（毫秒时间戳）
        type: integer
      user_id:
        description: 用户ID
        type: integer
    type: object
  dto.MyFanIdentitiesResponseDTO:
    properties:
      current_star_id:
        description: 当前激活的明星ID
        type: integer
      items:
        items:
          $ref: '#/definitions/dto.MyFanIdentityItemDTO'
        type: array
      total:
        type: integer
    type: object
  dto.MyFanIdentityItemDTO:
    properties:
      crystal_balance:
        description: 水晶余额
        type: integer
      experience:
        description: 经验值
        type: integer
      identity_id:
        description: 身份ID（如 "xz"）
        type: string
      is_active:
        description: 是否激活（当前使用）
        type: boolean
      level:
        description: 等级
        type: integer
      nickname:
        description: 用户昵称
        type: string
      star_id:
        description: 明星ID
        type: integer
      star_name:
        description: 明星名称
        type: string
      star_tag:
        description: 明星标签
        type: string
    type: object
  dto.OwnerInfoDTO:
    properties:
      avatar:
        description: 头像URL
        type: string
      nickname:
        description: 昵称
        type: string
      user_id:
        description: 用户ID
        type: integer
    type: object
  dto.PlaceAssetRequestDTO:
    properties:
      asset_id:
        description: 资产ID（必填）
        type: integer
      gallery_owner_id:
        description: 展馆所有者ID（必填）
        type: integer
      slot_id:
        description: 展位ID（必填）
        type: integer
    required:
    - asset_id
    - gallery_owner_id
    - slot_id
    type: object
  dto.PreCreateMintOrderRequestDTO:
    properties:
      description:
        description: 描述（可选）
        type: string
      event:
        description: 藏品事件（可选）
        type: string
      material_type:
        description: 素材类型（可选）
        type: string
      material_url:
        description: 素材URL（必填）
        type: string
      name:
        description: 藏品名称（可选）
        type: string
    required:
    - material_url
    type: object
  dto.ProfileResponseDTO:
    properties:
      assets_num:
        type: integer
      chain_address:
        type: string
      crystal_balance:
        type: integer
      fan_identity:
        $ref: '#/definitions/dto.FanIdentityDTO'
      fan_level:
        type: integer
      nickname:
        type: string
      slot_limit:
        type: integer
      starbook_limit:
        type: integer
      uid:
        type: integer
    type: object
  dto.RegisterResponseDTO:
    properties:
      access_token:
        type: string
      expires_in:
        type: integer
      user:
        $ref: '#/definitions/dto.UserWithIdentityDTO'
    type: object
  dto.SlotInfoDTO:
    properties:
      asset:
        allOf:
        - $ref: '#/definitions/dto.AssetInfoDTO'
        description: 展品信息（仅当status为OCCUPIED时存在）
      can_operate:
        description: 当前用户是否可以操作此展位
        type: boolean
      expire_at:
        description: 占用过期时间（毫秒时间戳，仅当status为OCCUPIED时存在）
        type: integer
      is_enabled:
        description: 是否已解锁
        type: boolean
      occupied_at:
        description: 占用开始时间（毫秒时间戳，仅当status为OCCUPIED时存在）
        type: integer
      occupier_uid:
        description: 占位者用户ID（仅当status为OCCUPIED时存在）
        type: integer
      operation:
        description: '操作类型: "place" | "remove" | "none"'
        type: string
      slot_id:
        description: 展位ID
        type: integer
      slot_index:
        description: 展位序号
        type: integer
      status:
        description: 状态：EMPTY, OCCUPIED, LOCKED
        type: string
      unlock_condition:
        allOf:
        - $ref: '#/definitions/dto.UnlockConditionDTO'
        description: 解锁条件（仅当status为LOCKED时存在）
      visibility:
        description: public / private
        type: string
    type: object
  dto.SwitchIdentityResponseDTO:
    properties:
      access_token:
        type: string
      current_identity:
        $ref: '#/definitions/dto.CurrentIdentityDTO'
      expires_in:
        type: integer
    type: object
  dto.UnlockConditionDTO:
    properties:
      type:
        description: 解锁类型：level（等级）, crystal（水晶）
        type: string
      value:
        description: 解锁条件值（等级或水晶数量）
        type: integer
    type: object
  dto.UpdateNicknameResponseDTO:
    properties:
      nickname:
        type: string
    type: object
  dto.UserWithIdentityDTO:
    properties:
      assets_num:
        description: assets_count
        type: integer
      avatar_url:
        type: string
      chain_address:
        type: string
      crystal_balance:
        type: integer
      fan_identity:
        $ref: '#/definitions/dto.FanIdentityDTO'
      fan_level:
        type: integer
      nickname:
        type: string
      slot_limit:
        type: integer
      starbook_limit:
        type: integer
      uid:
        description: 使用 uid，值为数据库ID
        type: integer
    type: object
  response.Response:
    properties:
      code:
        type: integer
      data: {}
      message:
        type: string
    type: object
  user.AddIdentityRequest:
    properties:
      nickname:
        description: 粉丝身份昵称
        type: string
      star_id:
        description: 选择的明星ID
        type: integer
    type: object
  user.CheckNicknameRequest:
    properties:
      nickname:
        description: 要检查的昵称
        type: string
    type: object
  user.CheckNicknameResponse:
    properties:
      base:
        $ref: '#/definitions/common.BaseResponse'
      exists:
        description: 昵称是否已存在
        type: boolean
    type: object
  user.LoginRequest:
    properties:
      mobile:
        description: 手机号
        type: string
      password:
        description: 密码
        type: string
      star_id:
        description: 可选：指定登录的明星ID，不指定则使用最早创建的粉丝档案
        type: integer
    type: object
  user.RegisterRequest:
    properties:
      mobile:
        description: 手机号
        type: string
      nickname:
        description: 第一个粉丝身份的昵称
        type: string
      password:
        description: 密码
        type: string
      star_id:
        description: 选择第一个粉丝身份的明星ID
        type: integer
    type: object
  user.SwitchIdentityRequest:
    properties:
      new_star_id:
        description: 切换到的新明星ID
        type: integer
    type: object
  user.UpdateAvatarRequest:
    properties:
      avatar_url:
        description: 头像URL（必填）
        type: string
    type: object
  user.UpdateNicknameRequest:
    properties:
      nickname:
        description: 新昵称
        type: string
    type: object
  user.UpdatePasswordRequest:
    properties:
      new_password:
        description: 新密码
        type: string
      old_password:
        description: 旧密码
        type: string
    type: object
  user.ValidateTokenRequest:
    properties:
      access_token:
        type: string
    type: object
host: localhost:8080
info:
  contact: {}
  description: TopFans 后端 API 文档 - 微服务架构 Gateway 层
  title: TopFans API
  version: "1.0"
paths:
  /api/v1/account/password:
    post:
      consumes:
      - application/json
      description: 更新当前用户的登录密码
      parameters:
      - description: 更新密码请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.UpdatePasswordRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 更新用户密码
      tags:
      - users
  /api/v1/activities:
    get:
      consumes:
      - application/json
      description: 获取活动列表，支持按star_id筛选
      parameters:
      - description: 粉丝身份ID
        format: int64
        in: query
        name: star_id
        required: true
        type: integer
      - description: '活动状态: pending/active/completed/expired'
        in: query
        name: status
        type: string
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认10
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取活动列表
      tags:
      - activities
  /api/v1/activities/{activity_id}:
    get:
      consumes:
      - application/json
      description: 获取活动详情
      parameters:
      - description: 活动ID
        format: int64
        in: path
        name: activity_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取活动详情
      tags:
      - activities
  /api/v1/activities/{activity_id}/items:
    get:
      consumes:
      - application/json
      description: 获取活动道具列表
      parameters:
      - description: 活动ID
        format: int64
        in: path
        name: activity_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取活动道具列表
      tags:
      - activities
  /api/v1/activities/{activity_id}/progress:
    get:
      consumes:
      - application/json
      description: 获取活动进度
      parameters:
      - description: 活动ID
        format: int64
        in: path
        name: activity_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取活动进度
      tags:
      - activities
  /api/v1/activities/{activity_id}/purchase:
    post:
      consumes:
      - application/json
      description: 购买活动道具
      parameters:
      - description: 活动ID
        format: int64
        in: path
        name: activity_id
        required: true
        type: integer
      - description: 购买请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/activity.PurchaseItemRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 购买道具
      tags:
      - activities
  /api/v1/activities/{activity_id}/ranking:
    get:
      consumes:
      - application/json
      description: 获取活动贡献点排名
      parameters:
      - description: 活动ID
        format: int64
        in: path
        name: activity_id
        required: true
        type: integer
      - description: 粉丝身份ID
        format: int64
        in: query
        name: star_id
        type: integer
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认10
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取贡献点排名
      tags:
      - activities
  /api/v1/assets/{asset_id}:
    get:
      consumes:
      - application/json
      description: 获取指定资产的详细信息
      parameters:
      - description: 资产ID
        in: path
        name: asset_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取资产详情
      tags:
      - assets
  /api/v1/assets/{asset_id}/status:
    get:
      consumes:
      - application/json
      description: 查询指定资产的上链状态
      parameters:
      - description: 资产ID
        in: path
        name: asset_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 查询上链状态
      tags:
      - assets
  /api/v1/assets/me/items:
    get:
      consumes:
      - application/json
      description: 获取当前用户的数字藏品列表
      parameters:
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认20
        in: query
        name: page_size
        type: integer
      - description: 藏品状态
        in: query
        name: status
        type: string
      - description: 搜索关键词
        in: query
        name: keyword
        type: string
      - description: 排序方式，默认created_at_desc
        in: query
        name: sort
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取我的藏品
      tags:
      - assets
  /api/v1/assets/mints:
    post:
      consumes:
      - application/json
      description: 创建一个新的数字藏品铸造订单
      parameters:
      - description: 铸造订单请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/dto.CreateMintOrderRequestDTO'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 创建铸造订单
      tags:
      - assets
  /api/v1/assets/mints/{order_id}:
    delete:
      consumes:
      - application/json
      description: 取消指定铸造订单
      parameters:
      - description: 订单ID
        in: path
        name: order_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 取消铸造订单
      tags:
      - assets
    get:
      consumes:
      - application/json
      description: 查询指定铸造订单的状态和详细信息。订单状态包括：PROCESSING（处理中）、SUCCESS（成功）、FAILED（失败）。成功时会返回关联的资产信息，包括
        cover_url_signed（预签名URL）和 tx_hash（交易哈希）。
      parameters:
      - description: 订单ID（UUID格式）
        in: path
        name: order_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回订单和资产信息
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.GetMintOrderResponseDTO'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Response'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/response.Response'
        "404":
          description: 订单不存在
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 查询铸造订单状态
      tags:
      - assets
  /api/v1/assets/mints/precreate:
    post:
      consumes:
      - application/json
      description: 上传素材后先创建 PENDING 订单，返回 order_id，前端决定是否继续铸造或取消
      parameters:
      - description: 预创建铸造订单请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/dto.PreCreateMintOrderRequestDTO'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 预创建铸造订单（阶段一）
      tags:
      - assets
  /api/v1/assets/oss/batch-presigned-urls:
    get:
      consumes:
      - application/json
      description: 批量获取OSS预签名URL用于下载多个文件
      parameters:
      - description: '类型: avatar/asset'
        in: query
        name: type
        required: true
        type: string
      - description: 过期时间(秒)，默认3600
        in: query
        name: expires
        type: integer
      - description: 最大返回数量，默认100
        in: query
        name: max_keys
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 批量获取OSS预签名URL
      tags:
      - assets
  /api/v1/assets/oss/presigned-url:
    get:
      consumes:
      - application/json
      description: 获取OSS预签名URL用于下载文件。file_name 支持三种形式：1）纯文件名（自动拼接当前用户的路径）；2）完整 OSS
        key（例如 asset/7/88/materials/x.png）；3）完整 OSS URL（例如 https://bucket.oss-xx.aliyuncs.com/asset/...）。
      parameters:
      - description: '类型: avatar/asset'
        in: query
        name: type
        required: true
        type: string
      - description: 文件名或完整OSS key/URL
        in: query
        name: file_name
        required: true
        type: string
      - description: 过期时间(秒)，默认3600，最大86400
        in: query
        name: expires
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取OSS预签名URL
      tags:
      - assets
  /api/v1/assets/oss/signature:
    get:
      consumes:
      - application/json
      description: 获取阿里云OSS上传签名和策略（阶段一：素材准备）。前端调用此接口获取上传签名后，可以直接上传图片到 OSS，获得 material_url。
      parameters:
      - description: '上传类型: avatar/asset，默认asset'
        in: query
        name: type
        type: string
      - description: 订单ID（可选）。不传则后端生成，并在响应中返回，用于后续铸造全流程唯一标识
        in: query
        name: order_id
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回上传签名信息
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  properties:
                    dir:
                      type: string
                    expire_time:
                      type: integer
                    host:
                      type: string
                    order_id:
                      type: string
                    policy:
                      type: string
                    security_token:
                      type: string
                    signature:
                      type: string
                    x_oss_credential:
                      type: string
                    x_oss_date:
                      type: string
                    x_oss_signature_version:
                      type: string
                  type: object
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Response'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/response.Response'
        "500":
          description: OSS配置错误或生成签名失败
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取OSS上传签名
      tags:
      - assets
  /api/v1/assets/oss/upload-signature:
    get:
      consumes:
      - application/json
      description: 获取阿里云OSS上传签名和策略（阶段一：素材准备）。前端调用此接口获取上传签名后，可以直接上传图片到 OSS，获得 material_url。
      parameters:
      - description: '上传类型: avatar/asset，默认asset'
        in: query
        name: type
        type: string
      - description: 订单ID（可选）。不传则后端生成，并在响应中返回，用于后续铸造全流程唯一标识
        in: query
        name: order_id
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回上传签名信息
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  properties:
                    dir:
                      type: string
                    expire_time:
                      type: integer
                    host:
                      type: string
                    order_id:
                      type: string
                    policy:
                      type: string
                    security_token:
                      type: string
                    signature:
                      type: string
                    x_oss_credential:
                      type: string
                    x_oss_date:
                      type: string
                    x_oss_signature_version:
                      type: string
                  type: object
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Response'
        "401":
          description: 未授权
          schema:
            $ref: '#/definitions/response.Response'
        "500":
          description: OSS配置错误或生成签名失败
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取OSS上传签名
      tags:
      - assets
  /api/v1/assets/upload:
    post:
      consumes:
      - application/json
      description: 上传图片到系统（提供图片URL）
      parameters:
      - description: '图片URL和类型: cover/material'
        in: body
        name: request
        required: true
        schema:
          properties:
            image_url:
              type: string
            type:
              type: string
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 上传图片
      tags:
      - assets
  /api/v1/auth/check-nickname:
    post:
      consumes:
      - application/json
      description: 检查指定昵称是否已被他人使用
      parameters:
      - description: 检查昵称请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.CheckNicknameRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/user.CheckNicknameResponse'
              type: object
      summary: 检查昵称是否被注册
      tags:
      - auth
  /api/v1/auth/login:
    post:
      consumes:
      - application/json
      description: 用户登录接口，需要提供手机号和密码
      parameters:
      - description: 登录请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.LoginResponseDTO'
              type: object
      summary: 用户登录
      tags:
      - auth
  /api/v1/auth/logout:
    post:
      consumes:
      - application/json
      description: 使用户访问令牌失效
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 用户登出
      tags:
      - auth
  /api/v1/auth/me:
    get:
      consumes:
      - application/json
      description: 获取当前登录用户的完整信息
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.GetMeResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 获取当前用户信息
      tags:
      - users
  /api/v1/auth/refresh:
    post:
      consumes:
      - application/json
      description: 使用当前访问令牌刷新获取新的访问令牌
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 刷新访问令牌
      tags:
      - auth
  /api/v1/auth/register:
    post:
      consumes:
      - application/json
      description: 用户注册接口，需要提供手机号、密码、选择明星身份
      parameters:
      - description: 注册请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.RegisterRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.RegisterResponseDTO'
              type: object
      summary: 用户注册
      tags:
      - auth
  /api/v1/auth/validate:
    post:
      consumes:
      - application/json
      description: 验证访问令牌的有效性
      parameters:
      - description: 验证请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.ValidateTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      summary: 验证访问令牌
      tags:
      - auth
  /api/v1/fan-identities:
    get:
      consumes:
      - application/json
      description: 获取所有可选的明星粉丝身份列表
      parameters:
      - description: 搜索关键词
        in: query
        name: keyword
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.FanIdentityListResponseDTO'
              type: object
      summary: 获取可选粉丝身份列表
      tags:
      - users
  /api/v1/fan-profiles:
    get:
      consumes:
      - application/json
      description: 根据用户ID和明星ID获取粉丝档案信息
      parameters:
      - description: 用户ID
        in: query
        name: user_id
        required: true
        type: integer
      - description: 明星ID
        in: query
        name: star_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      summary: 获取粉丝档案
      tags:
      - users
  /api/v1/galleries/{target_uid}:
    get:
      consumes:
      - application/json
      description: 获取指定用户的展馆信息
      parameters:
      - description: 用户ID
        in: path
        name: target_uid
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.GetUserGalleryResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 获取他人展馆
      tags:
      - galleries
  /api/v1/galleries/me:
    get:
      consumes:
      - application/json
      description: 获取当前用户的展馆信息
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.GetMyGalleryResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 获取我的展馆
      tags:
      - galleries
  /api/v1/galleries/place:
    post:
      consumes:
      - application/json
      description: 在指定展位放置数字藏品进行展示
      parameters:
      - description: 展位ID和资产ID
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/dto.PlaceAssetRequestDTO'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 放置藏品
      tags:
      - galleries
  /api/v1/galleries/random:
    get:
      consumes:
      - application/json
      description: 随机返回一个玩家的展馆信息，格式与 GET /api/v1/galleries/:target_uid 一致
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.GetUserGalleryResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 获取随机展馆
      tags:
      - galleries
  /api/v1/galleries/slots/{slot_id}/asset:
    delete:
      consumes:
      - application/json
      description: 从指定展位移除展示的藏品
      parameters:
      - description: 展位ID
        in: path
        name: slot_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 移除藏品
      tags:
      - galleries
  /api/v1/galleries/slots_unlock:
    post:
      consumes:
      - application/json
      description: 解锁或购买新的展位
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 解锁展位
      tags:
      - galleries
  /api/v1/me/avatar:
    put:
      consumes:
      - application/json
      description: 更新当前用户的头像URL
      parameters:
      - description: 更新头像请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.UpdateAvatarRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 更新用户头像
      tags:
      - users
  /api/v1/me/nickname:
    put:
      consumes:
      - application/json
      description: 更新当前用户的粉丝昵称
      parameters:
      - description: 更新昵称请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.UpdateNicknameRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.UpdateNicknameResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 更新用户昵称
      tags:
      - users
  /api/v1/me/profile:
    get:
      consumes:
      - application/json
      description: 获取当前登录用户的粉丝档案信息
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.ProfileResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 获取当前用户粉丝档案
      tags:
      - users
  /api/v1/my/fan-identities:
    get:
      consumes:
      - application/json
      description: 获取当前用户拥有的所有粉丝身份列表
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.MyFanIdentitiesResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 获取我的粉丝身份列表
      tags:
      - users
    post:
      consumes:
      - application/json
      description: 为当前用户添加一个新的明星粉丝身份
      parameters:
      - description: 添加身份请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.AddIdentityRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.AddIdentityResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 添加粉丝身份
      tags:
      - users
  /api/v1/my/fan-identities/switch:
    post:
      consumes:
      - application/json
      description: 切换到指定的粉丝身份，返回新的访问令牌
      parameters:
      - description: 切换身份请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/user.SwitchIdentityRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Response'
            - properties:
                data:
                  $ref: '#/definitions/dto.SwitchIdentityResponseDTO'
              type: object
      security:
      - BearerAuth: []
      summary: 切换粉丝身份
      tags:
      - users
  /api/v1/rankings/hot:
    get:
      consumes:
      - application/json
      description: 获取热度排行榜，支持按维度筛选(displaying:展示中, month:本月, total:全部)
      parameters:
      - description: '统计维度: displaying(展示中), month(本月), total(全部)，默认total'
        in: query
        name: dimension
        type: string
      - description: 粉丝身份ID，不传则使用当前身份
        format: int64
        in: query
        name: star_id
        type: integer
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认10
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取热度排行榜
      tags:
      - rankings
  /api/v1/rankings/original:
    get:
      consumes:
      - application/json
      description: 获取自制藏品排行榜，支持按维度筛选(displaying:展示中, month:本月, total:全部)
      parameters:
      - description: '统计维度: displaying(展示中), month(本月), total(全部)，默认total'
        in: query
        name: dimension
        type: string
      - description: 粉丝身份ID，不传则使用当前身份
        format: int64
        in: query
        name: star_id
        type: integer
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认10
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取自制排行榜
      tags:
      - rankings
  /api/v1/social/assets/{asset_id}/like:
    delete:
      consumes:
      - application/json
      description: 取消对指定资产的点赞
      parameters:
      - description: 资产ID
        in: path
        name: asset_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 取消点赞
      tags:
      - social
    post:
      consumes:
      - application/json
      description: 对指定资产进行点赞
      parameters:
      - description: 资产ID
        in: path
        name: asset_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 点赞资产
      tags:
      - social
  /api/v1/social/friend-requests:
    get:
      consumes:
      - application/json
      description: 获取当前用户的好友请求列表
      parameters:
      - description: '请求类型: received/sent'
        in: query
        name: type
        type: string
      - description: 请求状态
        in: query
        name: status
        type: string
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认20
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取好友请求列表
      tags:
      - social
    post:
      consumes:
      - application/json
      description: 向指定用户发送好友请求
      parameters:
      - description: 好友请求参数
        in: body
        name: request
        required: true
        schema:
          properties:
            friend_user_id:
              type: integer
            message:
              type: string
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 发送好友请求
      tags:
      - social
  /api/v1/social/friend-requests/handle:
    post:
      consumes:
      - application/json
      description: 接受或拒绝好友请求
      parameters:
      - description: '处理请求参数: action=accept/reject'
        in: body
        name: request
        required: true
        schema:
          properties:
            action:
              type: string
            request_id:
              type: integer
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 处理好友请求
      tags:
      - social
  /api/v1/social/friends:
    delete:
      consumes:
      - application/json
      description: 删除指定好友
      parameters:
      - description: 好友用户ID
        in: body
        name: request
        required: true
        schema:
          properties:
            friend_user_id:
              type: integer
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 删除好友
      tags:
      - social
    get:
      consumes:
      - application/json
      description: 获取当前用户的好友列表
      parameters:
      - description: 搜索关键词
        in: query
        name: keyword
        type: string
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认20
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取好友列表
      tags:
      - social
  /api/v1/social/friends/count:
    get:
      consumes:
      - application/json
      description: 获取当前用户的好友数量
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取好友数量
      tags:
      - social
  /api/v1/social/friends/remark:
    put:
      consumes:
      - application/json
      description: 设置指定好友的备注名称
      parameters:
      - description: 好友ID和备注
        in: body
        name: request
        required: true
        schema:
          properties:
            friend_user_id:
              type: integer
            remark:
              type: string
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 设置好友备注
      tags:
      - social
  /api/v1/social/friendship/check:
    get:
      consumes:
      - application/json
      description: 检查当前用户与指定用户是否为好友关系
      parameters:
      - description: 好友用户ID
        in: query
        name: friend_user_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 检查好友关系
      tags:
      - social
  /api/v1/social/random-users:
    get:
      consumes:
      - application/json
      description: 获取同一明星身份下的随机推荐用户
      parameters:
      - description: 获取数量，默认1，最大100
        in: query
        name: count
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取随机用户
      tags:
      - social
  /api/v1/social/search-user:
    get:
      consumes:
      - application/json
      description: 根据用户ID查找用户信息，用于添加好友
      parameters:
      - description: 粉丝档案ID
        in: query
        name: friend_fan_profile_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 查找用户
      tags:
      - social
  /api/v1/social/users:
    get:
      consumes:
      - application/json
      description: 获取同一明星身份下的分页用户列表，包含用户ID、展馆所有者ID、昵称、等级
      parameters:
      - description: 页码，默认1
        in: query
        name: page
        type: integer
      - description: 每页数量，默认20，最大100
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      security:
      - BearerAuth: []
      summary: 获取分页用户列表
      tags:
      - social
  /api/v1/users/{user_id}:
    get:
      consumes:
      - application/json
      description: 根据用户ID获取用户公开信息
      parameters:
      - description: 用户ID
        in: path
        name: user_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Response'
      summary: 获取指定用户信息
      tags:
      - users
securityDefinitions:
  BearerAuth:
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"