basePath: /api/v1 definitions: activity.BatchPurchaseItemRequest: properties: activity_id: type: integer items: description: 购买项列表 items: $ref: '#/definitions/activity.PurchaseItem' type: array star_id: type: integer user_id: description: 当前用户ID type: integer type: object activity.PurchaseItem: properties: item_type: type: string quantity: type: integer type: object 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: description: google.rpc.Code 数字(0=OK, 3=INVALID_ARGUMENT, 5=NOT_FOUND, 7=PERMISSION_DENIED, 8=RESOURCE_EXHAUSTED, 13=INTERNAL, 16=UNAUTHENTICATED) type: integer message: description: 错误信息（成功时为空） type: string timestamp: description: 响应时间戳（Unix时间戳毫秒） type: integer type: object 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 display_status: description: 展示状态：0=待展示, 1=已展示 type: integer earnings: description: 当前展出收益（实时计算，仅展出中时有值） type: integer exhibition_expire_at: description: 展出过期时间（毫秒时间戳，仅展出中时有值，0=未展出） type: integer grade: description: 星册等级（可选） type: integer hourly_earnings: description: 每小时收益（实时计算，仅展出中时有值） type: number info: 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 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 grade: description: 星册等级（可选） type: integer info: description: 藏品信息（必填） type: string instance_no: 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 tags: description: 标签列表（可选） items: type: string type: array required: - info - material_url - 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.ExhibitedAssetItemDTO: properties: asset_id: description: 资产ID type: integer cover_url: description: 封面图URL type: string earnings: description: 当前可领取收益 type: integer exhibited_at: description: 展出开始时间（毫秒时间戳） type: integer expire_at: description: 展出过期时间（毫秒时间戳） type: integer hourly_earnings: description: 每小时收益 type: number is_lenticular: description: 是否为光栅卡 type: boolean like_count: description: 实时点赞数 type: integer name: description: 藏品名称 type: string slot_index: description: 展位序号 type: integer 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.GetInspirationFlowResponseDTO: properties: cursor: description: 下次请求的游标 type: string has_more: description: 是否有更多 type: boolean items: description: 藏品列表 items: $ref: '#/definitions/dto.InspirationFlowItemDTO' type: array session_id: description: 会话ID type: string 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.GetMyExhibitedAssetsResponseDTO: properties: has_more: description: 是否有更多 type: boolean items: description: 作品列表 items: $ref: '#/definitions/dto.ExhibitedAssetItemDTO' type: array page: description: 当前页码 type: integer page_size: description: 每页数量 type: integer total: description: 总数量 type: integer 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.ImageGenerationRequest: properties: aspect_ratio: type: string model: type: string "n": description: 1-4 type: integer prompt: type: string subject_reference: items: $ref: '#/definitions/dto.SubjectReference' type: array required: - model - prompt type: object dto.InspirationFlowItemDTO: properties: asset_id: description: 资产ID type: integer cover_url: description: 封面图URL type: string exhibition_id: description: 当前展出记录ID（未展出时为0） type: integer is_liked: description: 当前用户是否已点赞 type: boolean like_count: description: 点赞数 type: integer material_type: description: '素材类型: hot(人气王者), potential(潜力之星), new(新鲜上架)' type: string name: description: 藏品名称 type: string owner_avatar: description: 展出者头像 type: string owner_nickname: description: 展出者昵称 type: string span: description: '卡片大小: 0-30→1, 31-100→2, 101-200→3, 200+→4' type: integer 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 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.SendCodeRequest: properties: mobile: type: string scene: description: register, password type: string required: - mobile - scene type: object dto.SendCodeResponse: properties: code: type: integer expires_in: description: 多少秒后可以重发 type: integer message: type: string 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.SubjectReference: properties: image_file: type: string type: 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 mobile_masked: description: 脱敏手机号，如 139****0001 type: string nickname: type: string slot_limit: type: integer starbook_limit: type: integer uid: description: 使用 uid，值为数据库ID type: integer type: object dto.VerifyCodeRequest: properties: code: type: string mobile: type: string scene: type: string required: - code - mobile - scene type: object dto.VerifyCodeResponse: properties: code: type: integer expires_in: description: token有效期（秒） type: integer message: type: string verified: type: boolean verify_token: type: string type: object response.Response: properties: code: type: integer data: {} message: type: string type: object task.AdvanceStageRequest: properties: target_stage: type: integer type: object task.ClaimDailyTaskRequest: properties: star_id: type: integer task_key: type: string type: object task.ClaimExhibitionRevenueRequest: properties: revenue_id: type: integer star_id: type: integer type: object task.ClaimOnboardingRewardRequest: properties: stage: type: integer type: object task.CompleteGuideRequest: properties: stages: description: 前端传入的阶段配置，首次调用时存储 items: $ref: '#/definitions/task.OnboardingStage' type: array task_key: type: string type: object task.OnboardingStage: properties: all_tasks_completed: description: 该阶段所有任务是否完成 type: boolean crystal_reward: type: integer is_current: type: boolean is_reward_claimed: description: 该阶段奖励是否已领取 type: boolean name: type: string required_task_keys: items: type: string type: array stage: type: integer status: description: pending/completed/in_progress type: string type: object task.ReportEventRequest: properties: event_type: description: 如 "daily_browse_asset", "daily_login" type: string star_id: type: integer type: object user.AddIdentityRequest: properties: nickname: description: 粉丝身份昵称 type: string star_id: description: 选择的明星ID type: integer type: object user.CheckMobileRequest: properties: mobile: description: 要检查的手机号 type: string type: object user.CheckMobileResponse: properties: base: $ref: '#/definitions/common.BaseResponse' exists: description: 手机号是否已存在 type: boolean 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: avatar_url: description: 头像URL（可选；为空则后端使用默认头像） type: string mobile: description: 手机号 type: string nickname: description: 第一个粉丝身份的昵称 type: string password: description: 密码 type: string star_id: description: 选择第一个粉丝身份的明星ID type: integer verify_token: description: 短信验证token（注册前必须先通过短信验证） type: string 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 verify_token: description: 短信验证 token（scene=password 下发的一次性 token） 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/tasks/daily: get: consumes: - application/json description: 获取每日任务列表 parameters: - description: 粉丝身份ID format: int64 in: query name: star_id required: true type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 获取每日任务列表 tags: - tasks /api/tasks/daily/claim: post: consumes: - application/json description: 领取单个每日任务奖励 parameters: - description: 领取请求 in: body name: request required: true schema: $ref: '#/definitions/task.ClaimDailyTaskRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 领取每日任务奖励 tags: - tasks /api/tasks/daily/claim-all: post: consumes: - application/json description: 一键领取所有可领取的每日任务奖励 parameters: - description: 粉丝身份ID format: int64 in: query name: star_id required: true type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 一键领取所有每日任务 tags: - tasks /api/tasks/exhibition-revenue: get: consumes: - application/json description: 获取展馆收益记录 parameters: - description: 粉丝身份ID format: int64 in: query name: star_id required: true type: integer - description: 状态筛选：claimable/claimed 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: - tasks /api/tasks/exhibition-revenue/claim: post: consumes: - application/json description: 领取单条展馆收益记录 parameters: - description: 领取请求 in: body name: request required: true schema: $ref: '#/definitions/task.ClaimExhibitionRevenueRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 领取单条展示收益 tags: - tasks /api/tasks/exhibition-revenue/claim-all: post: consumes: - application/json description: 一键领取所有可领取的展馆收益 parameters: - description: 粉丝身份ID format: int64 in: query name: star_id required: true type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 一键领取所有展示收益 tags: - tasks /api/tasks/guide/complete: post: consumes: - application/json description: 完成引导任务步骤 parameters: - description: 引导完成请求 in: body name: request required: true schema: $ref: '#/definitions/task.CompleteGuideRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 完成引导任务 tags: - tasks /api/tasks/onboarding/advance-stage: post: consumes: - application/json description: 进入新手引导的下一阶段 parameters: - description: 阶段推进请求 in: body name: request required: true schema: $ref: '#/definitions/task.AdvanceStageRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 进入下一引导阶段 tags: - tasks /api/tasks/onboarding/claim-reward: post: consumes: - application/json description: 领取新手引导阶段奖励 parameters: - description: 领取奖励请求 in: body name: request required: true schema: $ref: '#/definitions/task.ClaimOnboardingRewardRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 领取引导阶段奖励 tags: - tasks /api/tasks/onboarding/status: get: consumes: - application/json description: 获取新手引导状态 produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 获取引导状态 tags: - tasks /api/tasks/report-event: post: consumes: - application/json description: 上报任务事件，如 daily_login, daily_browse_asset parameters: - description: 事件上报请求 in: body name: request required: true schema: $ref: '#/definitions/task.ReportEventRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 上报任务事件 tags: - tasks /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}/batch-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.BatchPurchaseItemRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 批量购买道具 tags: - activities /api/v1/activities/{activity_id}/contributions/latest: get: consumes: - application/json description: 获取活动最新贡献记录，用于实时显示 parameters: - description: 活动ID format: int64 in: path name: activity_id required: true type: integer - description: 时间戳筛选，返回此时间之后的新记录 format: int64 in: query name: since_timestamp type: integer - description: ID筛选，配合since_timestamp使用 format: int64 in: query name: since_id type: integer - description: 返回数量，默认5，最大20 in: query name: limit 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/ai-chat/history/{sessionId}: get: consumes: - application/json parameters: - description: 会话ID in: path name: sessionId required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 获取对话历史 tags: - ai-chat /api/v1/ai-chat/personas: get: consumes: - application/json produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 获取用户的所有人设 tags: - ai-chat /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/earnings-summary: get: consumes: - application/json description: 获取当前用户的收益汇总（总每小时收益、总展出收益、水晶余额） 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/cost-estimate: post: consumes: - application/json description: 在用户确认铸造前，显示本次铸造消耗水晶数和当前余额 produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 估算铸造费用 tags: - assets /api/v1/assets/mints/image/generation: post: consumes: - application/json description: 调用 MiniMax 图生图 API parameters: - description: 图生图请求 in: body name: request required: true schema: $ref: '#/definitions/dto.ImageGenerationRequest' produces: - application/json responses: "200": description: OK 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 key: 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 key: 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-mobile: post: consumes: - application/json description: 检查指定手机号是否已被他人使用 parameters: - description: 检查手机号请求 in: body name: request required: true schema: $ref: '#/definitions/user.CheckMobileRequest' produces: - application/json responses: "200": description: OK schema: allOf: - $ref: '#/definitions/response.Response' - properties: data: $ref: '#/definitions/user.CheckMobileResponse' type: object summary: 检查手机号是否被注册 tags: - auth /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/send-code: post: consumes: - application/json description: 发送手机验证码，用于注册或重置密码 parameters: - description: 发送验证码请求 in: body name: request required: true schema: $ref: '#/definitions/dto.SendCodeRequest' produces: - application/json responses: "200": description: OK schema: allOf: - $ref: '#/definitions/response.Response' - properties: data: $ref: '#/definitions/dto.SendCodeResponse' 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/auth/verify-code: post: consumes: - application/json description: 验证手机验证码，验证成功后返回 verify_token parameters: - description: 验证验证码请求 in: body name: request required: true schema: $ref: '#/definitions/dto.VerifyCodeRequest' produces: - application/json responses: "200": description: OK schema: allOf: - $ref: '#/definitions/response.Response' - properties: data: $ref: '#/definitions/dto.VerifyCodeResponse' type: object summary: 验证验证码 tags: - auth /api/v1/castlove/config: get: consumes: - application/json description: 强制鉴权;返回全量分类(星卡/吧唧/海报 等)及其下卡片(含 route_path / route_params) produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 获取铸爱工艺配置 tags: - castlove /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/inspiration-flow: get: consumes: - application/json description: 获取灵感瀑布藏品列表，支持随机展示和双向滚动 parameters: - description: 游标 in: query name: cursor type: string - default: right description: 滚动方向：right（加载新数据）/ left（加载历史） in: query name: direction type: string - default: 10 description: 每页数量 in: query name: limit type: integer - default: all description: 过滤类型：badge/poster/original/all in: query name: type type: string - description: 会话ID in: query name: session_id type: string produces: - application/json responses: "200": description: OK schema: allOf: - $ref: '#/definitions/response.Response' - properties: data: $ref: '#/definitions/dto.GetInspirationFlowResponseDTO' type: object security: - BearerAuth: [] summary: 获取灵感瀑布藏品列表 tags: - galleries /api/v1/me/avatar: put: consumes: - application/json description: 更新当前用户的头像URL。提交前会校验 OSS 对象真实存在，避免 user 表指向不存在的对象。 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' "400": description: 头像URL无效或对象不存在 schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 更新用户头像 tags: - users /api/v1/me/exhibited-assets: 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: OK schema: allOf: - $ref: '#/definitions/response.Response' - properties: data: $ref: '#/definitions/dto.GetMyExhibitedAssetsResponseDTO' type: object security: - BearerAuth: [] summary: 获取我展出的作品列表 tags: - galleries /api/v1/me/liked-assets: get: consumes: - application/json description: 获取当前用户点赞过的作品列表（只返回展出中且未过期的） parameters: - description: 页码，默认1 in: query name: page type: integer - description: 每页数量，默认20，最大100 in: query name: page_size type: integer - description: 排序字段：liked_at(默认), like_count(按点赞数) in: query name: order_by type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 获取我点赞的作品列表 tags: - social /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/me/today-liked-assets: get: consumes: - application/json description: 获取当前用户今日点赞过的作品列表（只返回展出中且未过期的） 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/me/week-liked-assets: get: consumes: - application/json description: 获取当前用户本周点赞过的作品列表（只返回展出中且未过期的） 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/minting-activities: get: consumes: - application/json description: 获取铸造活动列表，用于运营banner展示 parameters: - 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: - minting-activities /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/public/oss/upload-signature: get: consumes: - application/json description: |- 用于注册等未登录场景下上传头像，无需鉴权。 后端生成唯一完整 key，policy 锁到该 key，前端只能写到指定路径；key 形如 avatar/register-pending/{key}/avatar_.png。 parameters: - description: 场景，目前固定为 register in: query name: scene required: true type: string - description: 前端传入的命名空间（注册时传 mobile），仅允许 [a-zA-Z0-9_-]，最长 32 字符 in: query name: key required: true 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 key: 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' "500": description: OSS配置错误或生成签名失败 schema: $ref: '#/definitions/response.Response' summary: 获取公开 OSS 上传签名（注册流程用） tags: - assets /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/assets/{asset_id}/likers: get: consumes: - application/json description: 获取指定藏品的点赞用户列表（带游标分页） parameters: - description: 资产ID in: path name: asset_id required: true type: integer - description: 每页数量，默认20，最大100 in: query name: page_size type: integer - description: 游标（上一页最后一条的 created_at，首次请求传0） in: query name: cursor 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 nickname: type: string search_mode: type: boolean 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/starbook/home: get: consumes: - application/json description: 获取当前用户的星册首页数据，按类型和分组展示 produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/response.Response' security: - BearerAuth: [] summary: 获取星册首页 tags: - starbook /api/v1/starbook/items: get: consumes: - application/json description: 获取指定分组的藏品列表，支持分页 parameters: - description: '资产类型: regular/collection/activity' in: query name: type required: true type: string - description: 子分类，regular 时固定为 castlove in: query name: category type: string - description: 等级，仅 regular 类型有效 in: query name: grade type: integer - 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: - starbook /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 /api/v1/users/{user_id}/exhibited-assets: get: consumes: - application/json description: 获取指定用户正在展出的作品列表 parameters: - description: 用户ID in: path name: user_id required: true type: integer - 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: OK schema: allOf: - $ref: '#/definitions/response.Response' - properties: data: $ref: '#/definitions/dto.GetMyExhibitedAssetsResponseDTO' type: object security: - BearerAuth: [] summary: 获取他人展出的作品列表 tags: - galleries /api/v1/users/{user_id}/liked-assets: get: consumes: - application/json description: 获取指定用户点赞过的作品列表（只返回展出中且未过期的） parameters: - description: 用户ID in: path name: user_id required: true type: integer - 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 securityDefinitions: BearerAuth: in: header name: Authorization type: apiKey swagger: "2.0"