{ "swagger": "2.0", "info": { "description": "TopFans 后端 API 文档 - 微服务架构 Gateway 层", "title": "TopFans API", "contact": {}, "version": "1.0" }, "host": "localhost:8080", "basePath": "/api/v1", "paths": { "/api/tasks/daily": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取每日任务列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "获取每日任务列表", "parameters": [ { "type": "integer", "format": "int64", "description": "粉丝身份ID", "name": "star_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/daily/claim": { "post": { "security": [ { "BearerAuth": [] } ], "description": "领取单个每日任务奖励", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "领取每日任务奖励", "parameters": [ { "description": "领取请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.ClaimDailyTaskRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/daily/claim-all": { "post": { "security": [ { "BearerAuth": [] } ], "description": "一键领取所有可领取的每日任务奖励", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "一键领取所有每日任务", "parameters": [ { "type": "integer", "format": "int64", "description": "粉丝身份ID", "name": "star_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/exhibition-revenue": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取展馆收益记录", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "获取展示收益", "parameters": [ { "type": "integer", "format": "int64", "description": "粉丝身份ID", "name": "star_id", "in": "query", "required": true }, { "type": "string", "description": "状态筛选：claimable/claimed", "name": "status", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认10", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/exhibition-revenue/claim": { "post": { "security": [ { "BearerAuth": [] } ], "description": "领取单条展馆收益记录", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "领取单条展示收益", "parameters": [ { "description": "领取请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.ClaimExhibitionRevenueRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/exhibition-revenue/claim-all": { "post": { "security": [ { "BearerAuth": [] } ], "description": "一键领取所有可领取的展馆收益", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "一键领取所有展示收益", "parameters": [ { "type": "integer", "format": "int64", "description": "粉丝身份ID", "name": "star_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/guide/complete": { "post": { "security": [ { "BearerAuth": [] } ], "description": "完成引导任务步骤", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "完成引导任务", "parameters": [ { "description": "引导完成请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.CompleteGuideRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/onboarding/advance-stage": { "post": { "security": [ { "BearerAuth": [] } ], "description": "进入新手引导的下一阶段", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "进入下一引导阶段", "parameters": [ { "description": "阶段推进请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.AdvanceStageRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/onboarding/claim-reward": { "post": { "security": [ { "BearerAuth": [] } ], "description": "领取新手引导阶段奖励", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "领取引导阶段奖励", "parameters": [ { "description": "领取奖励请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.ClaimOnboardingRewardRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/onboarding/status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取新手引导状态", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "获取引导状态", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/tasks/report-event": { "post": { "security": [ { "BearerAuth": [] } ], "description": "上报任务事件，如 daily_login, daily_browse_asset", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "上报任务事件", "parameters": [ { "description": "事件上报请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.ReportEventRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/account/password": { "post": { "security": [ { "BearerAuth": [] } ], "description": "更新当前用户的登录密码", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "更新用户密码", "parameters": [ { "description": "更新密码请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.UpdatePasswordRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取活动列表，支持按star_id筛选", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "获取活动列表", "parameters": [ { "type": "integer", "format": "int64", "description": "粉丝身份ID", "name": "star_id", "in": "query", "required": true }, { "type": "string", "description": "活动状态: pending/active/completed/expired", "name": "status", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认10", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities/{activity_id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取活动详情", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "获取活动详情", "parameters": [ { "type": "integer", "format": "int64", "description": "活动ID", "name": "activity_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities/{activity_id}/batch-purchase": { "post": { "security": [ { "BearerAuth": [] } ], "description": "批量购买活动道具", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "批量购买道具", "parameters": [ { "type": "integer", "format": "int64", "description": "活动ID", "name": "activity_id", "in": "path", "required": true }, { "description": "批量购买请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/activity.BatchPurchaseItemRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities/{activity_id}/contributions/latest": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取活动最新贡献记录，用于实时显示", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "获取最新贡献记录", "parameters": [ { "type": "integer", "format": "int64", "description": "活动ID", "name": "activity_id", "in": "path", "required": true }, { "type": "integer", "format": "int64", "description": "时间戳筛选，返回此时间之后的新记录", "name": "since_timestamp", "in": "query" }, { "type": "integer", "format": "int64", "description": "ID筛选，配合since_timestamp使用", "name": "since_id", "in": "query" }, { "type": "integer", "description": "返回数量，默认5，最大20", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities/{activity_id}/items": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取活动道具列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "获取活动道具列表", "parameters": [ { "type": "integer", "format": "int64", "description": "活动ID", "name": "activity_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities/{activity_id}/progress": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取活动进度", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "获取活动进度", "parameters": [ { "type": "integer", "format": "int64", "description": "活动ID", "name": "activity_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities/{activity_id}/purchase": { "post": { "security": [ { "BearerAuth": [] } ], "description": "购买活动道具", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "购买道具", "parameters": [ { "type": "integer", "format": "int64", "description": "活动ID", "name": "activity_id", "in": "path", "required": true }, { "description": "购买请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/activity.PurchaseItemRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/activities/{activity_id}/ranking": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取活动贡献点排名", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "activities" ], "summary": "获取贡献点排名", "parameters": [ { "type": "integer", "format": "int64", "description": "活动ID", "name": "activity_id", "in": "path", "required": true }, { "type": "integer", "format": "int64", "description": "粉丝身份ID", "name": "star_id", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认10", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/ai-chat/history/{sessionId}": { "get": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai-chat" ], "summary": "获取对话历史", "parameters": [ { "type": "string", "description": "会话ID", "name": "sessionId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/ai-chat/personas": { "get": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai-chat" ], "summary": "获取用户的所有人设", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/me/earnings-summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户的收益汇总（总每小时收益、总展出收益、水晶余额）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "获取收益汇总", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/me/items": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户的数字藏品列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "获取我的藏品", "parameters": [ { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20", "name": "page_size", "in": "query" }, { "type": "string", "description": "藏品状态", "name": "status", "in": "query" }, { "type": "string", "description": "搜索关键词", "name": "keyword", "in": "query" }, { "type": "string", "description": "排序方式，默认created_at_desc", "name": "sort", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/mints": { "post": { "security": [ { "BearerAuth": [] } ], "description": "创建一个新的数字藏品铸造订单", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "创建铸造订单", "parameters": [ { "description": "铸造订单请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreateMintOrderRequestDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/mints/cost-estimate": { "post": { "security": [ { "BearerAuth": [] } ], "description": "在用户确认铸造前，显示本次铸造消耗水晶数和当前余额", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "估算铸造费用", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/mints/image/generation": { "post": { "security": [ { "BearerAuth": [] } ], "description": "调用 MiniMax 图生图 API", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "图生图", "parameters": [ { "description": "图生图请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.ImageGenerationRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/mints/precreate": { "post": { "security": [ { "BearerAuth": [] } ], "description": "上传素材后先创建 PENDING 订单，返回 order_id，前端决定是否继续铸造或取消", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "预创建铸造订单（阶段一）", "parameters": [ { "description": "预创建铸造订单请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.PreCreateMintOrderRequestDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/mints/{order_id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "查询指定铸造订单的状态和详细信息。订单状态包括：PROCESSING（处理中）、SUCCESS（成功）、FAILED（失败）。成功时会返回关联的资产信息，包括 cover_url_signed（预签名URL）和 tx_hash（交易哈希）。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "查询铸造订单状态", "parameters": [ { "type": "string", "description": "订单ID（UUID格式）", "name": "order_id", "in": "path", "required": true } ], "responses": { "200": { "description": "成功返回订单和资产信息", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetMintOrderResponseDTO" } } } ] } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/response.Response" } }, "401": { "description": "未授权", "schema": { "$ref": "#/definitions/response.Response" } }, "404": { "description": "订单不存在", "schema": { "$ref": "#/definitions/response.Response" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "取消指定铸造订单", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "取消铸造订单", "parameters": [ { "type": "string", "description": "订单ID", "name": "order_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/oss/batch-presigned-urls": { "get": { "security": [ { "BearerAuth": [] } ], "description": "批量获取OSS预签名URL用于下载多个文件", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "批量获取OSS预签名URL", "parameters": [ { "type": "string", "description": "类型: avatar/asset", "name": "type", "in": "query", "required": true }, { "type": "integer", "description": "过期时间(秒)，默认3600", "name": "expires", "in": "query" }, { "type": "integer", "description": "最大返回数量，默认100", "name": "max_keys", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/oss/presigned-url": { "get": { "security": [ { "BearerAuth": [] } ], "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/...）。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "获取OSS预签名URL", "parameters": [ { "type": "string", "description": "类型: avatar/asset", "name": "type", "in": "query", "required": true }, { "type": "string", "description": "文件名或完整OSS key/URL", "name": "file_name", "in": "query", "required": true }, { "type": "integer", "description": "过期时间(秒)，默认3600，最大86400", "name": "expires", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/oss/signature": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取阿里云OSS上传签名和策略（阶段一：素材准备）。前端调用此接口获取上传签名后，可以直接上传图片到 OSS，获得 material_url。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "获取OSS上传签名", "parameters": [ { "type": "string", "description": "上传类型: avatar/asset，默认asset", "name": "type", "in": "query" }, { "type": "string", "description": "订单ID（可选）。不传则后端生成，并在响应中返回，用于后续铸造全流程唯一标识", "name": "order_id", "in": "query" } ], "responses": { "200": { "description": "成功返回上传签名信息", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "type": "object", "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" } } } } } ] } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/response.Response" } }, "401": { "description": "未授权", "schema": { "$ref": "#/definitions/response.Response" } }, "500": { "description": "OSS配置错误或生成签名失败", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/oss/upload-signature": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取阿里云OSS上传签名和策略（阶段一：素材准备）。前端调用此接口获取上传签名后，可以直接上传图片到 OSS，获得 material_url。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "获取OSS上传签名", "parameters": [ { "type": "string", "description": "上传类型: avatar/asset，默认asset", "name": "type", "in": "query" }, { "type": "string", "description": "订单ID（可选）。不传则后端生成，并在响应中返回，用于后续铸造全流程唯一标识", "name": "order_id", "in": "query" } ], "responses": { "200": { "description": "成功返回上传签名信息", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "type": "object", "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" } } } } } ] } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/response.Response" } }, "401": { "description": "未授权", "schema": { "$ref": "#/definitions/response.Response" } }, "500": { "description": "OSS配置错误或生成签名失败", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/upload": { "post": { "security": [ { "BearerAuth": [] } ], "description": "上传图片到系统（提供图片URL）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "上传图片", "parameters": [ { "description": "图片URL和类型: cover/material", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "image_url": { "type": "string" }, "type": { "type": "string" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/{asset_id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取指定资产的详细信息", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "获取资产详情", "parameters": [ { "type": "integer", "description": "资产ID", "name": "asset_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/assets/{asset_id}/status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "查询指定资产的上链状态", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "查询上链状态", "parameters": [ { "type": "integer", "description": "资产ID", "name": "asset_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/auth/check-mobile": { "post": { "description": "检查指定手机号是否已被他人使用", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "检查手机号是否被注册", "parameters": [ { "description": "检查手机号请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.CheckMobileRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/user.CheckMobileResponse" } } } ] } } } } }, "/api/v1/auth/check-nickname": { "post": { "description": "检查指定昵称是否已被他人使用", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "检查昵称是否被注册", "parameters": [ { "description": "检查昵称请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.CheckNicknameRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/user.CheckNicknameResponse" } } } ] } } } } }, "/api/v1/auth/login": { "post": { "description": "用户登录接口，需要提供手机号和密码", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "用户登录", "parameters": [ { "description": "登录请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.LoginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.LoginResponseDTO" } } } ] } } } } }, "/api/v1/auth/logout": { "post": { "security": [ { "BearerAuth": [] } ], "description": "使用户访问令牌失效", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "用户登出", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/auth/me": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前登录用户的完整信息", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "获取当前用户信息", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetMeResponseDTO" } } } ] } } } } }, "/api/v1/auth/refresh": { "post": { "security": [ { "BearerAuth": [] } ], "description": "使用当前访问令牌刷新获取新的访问令牌", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "刷新访问令牌", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/auth/register": { "post": { "description": "用户注册接口，需要提供手机号、密码、选择明星身份", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "用户注册", "parameters": [ { "description": "注册请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.RegisterRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.RegisterResponseDTO" } } } ] } } } } }, "/api/v1/auth/send-code": { "post": { "description": "发送手机验证码，用于注册或重置密码", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "发送验证码", "parameters": [ { "description": "发送验证码请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SendCodeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.SendCodeResponse" } } } ] } } } } }, "/api/v1/auth/validate": { "post": { "description": "验证访问令牌的有效性", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "验证访问令牌", "parameters": [ { "description": "验证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.ValidateTokenRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/auth/verify-code": { "post": { "description": "验证手机验证码，验证成功后返回 verify_token", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "验证验证码", "parameters": [ { "description": "验证验证码请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.VerifyCodeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.VerifyCodeResponse" } } } ] } } } } }, "/api/v1/castlove/config": { "get": { "security": [ { "BearerAuth": [] } ], "description": "强制鉴权;返回全量分类(星卡/吧唧/海报 等)及其下卡片(含 route_path / route_params)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "castlove" ], "summary": "获取铸爱工艺配置", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/fan-identities": { "get": { "description": "获取所有可选的明星粉丝身份列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "获取可选粉丝身份列表", "parameters": [ { "type": "string", "description": "搜索关键词", "name": "keyword", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.FanIdentityListResponseDTO" } } } ] } } } } }, "/api/v1/fan-profiles": { "get": { "description": "根据用户ID和明星ID获取粉丝档案信息", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "获取粉丝档案", "parameters": [ { "type": "integer", "description": "用户ID", "name": "user_id", "in": "query", "required": true }, { "type": "integer", "description": "明星ID", "name": "star_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/galleries/me": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户的展馆信息", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "获取我的展馆", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetMyGalleryResponseDTO" } } } ] } } } } }, "/api/v1/galleries/place": { "post": { "security": [ { "BearerAuth": [] } ], "description": "在指定展位放置数字藏品进行展示", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "放置藏品", "parameters": [ { "description": "展位ID和资产ID", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.PlaceAssetRequestDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/galleries/random": { "get": { "security": [ { "BearerAuth": [] } ], "description": "随机返回一个玩家的展馆信息，格式与 GET /api/v1/galleries/:target_uid 一致", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "获取随机展馆", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetUserGalleryResponseDTO" } } } ] } } } } }, "/api/v1/galleries/slots/{slot_id}/asset": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "从指定展位移除展示的藏品", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "移除藏品", "parameters": [ { "type": "integer", "description": "展位ID", "name": "slot_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/galleries/slots_unlock": { "post": { "security": [ { "BearerAuth": [] } ], "description": "解锁或购买新的展位", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "解锁展位", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/galleries/{target_uid}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取指定用户的展馆信息", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "获取他人展馆", "parameters": [ { "type": "integer", "description": "用户ID", "name": "target_uid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetUserGalleryResponseDTO" } } } ] } } } } }, "/api/v1/inspiration-flow": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取灵感瀑布藏品列表，支持随机展示和双向滚动", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "获取灵感瀑布藏品列表", "parameters": [ { "type": "string", "description": "游标", "name": "cursor", "in": "query" }, { "type": "string", "default": "right", "description": "滚动方向：right（加载新数据）/ left（加载历史）", "name": "direction", "in": "query" }, { "type": "integer", "default": 10, "description": "每页数量", "name": "limit", "in": "query" }, { "type": "string", "default": "all", "description": "过滤类型：badge/poster/original/all", "name": "type", "in": "query" }, { "type": "string", "description": "会话ID", "name": "session_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetInspirationFlowResponseDTO" } } } ] } } } } }, "/api/v1/me/avatar": { "put": { "security": [ { "BearerAuth": [] } ], "description": "更新当前用户的头像URL。提交前会校验 OSS 对象真实存在，避免 user 表指向不存在的对象。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "更新用户头像", "parameters": [ { "description": "更新头像请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.UpdateAvatarRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } }, "400": { "description": "头像URL无效或对象不存在", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/me/exhibited-assets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户正在展出的作品列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "获取我展出的作品列表", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetMyExhibitedAssetsResponseDTO" } } } ] } } } } }, "/api/v1/me/liked-assets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户点赞过的作品列表（只返回展出中且未过期的）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取我点赞的作品列表", "parameters": [ { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20，最大100", "name": "page_size", "in": "query" }, { "type": "string", "description": "排序字段：liked_at(默认), like_count(按点赞数)", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/me/nickname": { "put": { "security": [ { "BearerAuth": [] } ], "description": "更新当前用户的粉丝昵称", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "更新用户昵称", "parameters": [ { "description": "更新昵称请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.UpdateNicknameRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.UpdateNicknameResponseDTO" } } } ] } } } } }, "/api/v1/me/profile": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前登录用户的粉丝档案信息", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "获取当前用户粉丝档案", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.ProfileResponseDTO" } } } ] } } } } }, "/api/v1/me/today-liked-assets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户今日点赞过的作品列表（只返回展出中且未过期的）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取我今日点赞的作品列表", "parameters": [ { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20，最大100", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/me/week-liked-assets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户本周点赞过的作品列表（只返回展出中且未过期的）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取我本周点赞的作品列表", "parameters": [ { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20，最大100", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/minting-activities": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取铸造活动列表，用于运营banner展示", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "minting-activities" ], "summary": "获取铸造活动列表", "parameters": [ { "type": "integer", "format": "int64", "description": "粉丝身份ID，不传则返回所有", "name": "star_id", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认10", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/my/fan-identities": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户拥有的所有粉丝身份列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "获取我的粉丝身份列表", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.MyFanIdentitiesResponseDTO" } } } ] } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "为当前用户添加一个新的明星粉丝身份", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "添加粉丝身份", "parameters": [ { "description": "添加身份请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.AddIdentityRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.AddIdentityResponseDTO" } } } ] } } } } }, "/api/v1/my/fan-identities/switch": { "post": { "security": [ { "BearerAuth": [] } ], "description": "切换到指定的粉丝身份，返回新的访问令牌", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "切换粉丝身份", "parameters": [ { "description": "切换身份请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.SwitchIdentityRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.SwitchIdentityResponseDTO" } } } ] } } } } }, "/api/v1/public/oss/upload-signature": { "get": { "description": "用于注册等未登录场景下上传头像，无需鉴权。\n后端生成唯一完整 key，policy 锁到该 key，前端只能写到指定路径；key 形如 avatar/register-pending/{key}/avatar_\u003cuuid\u003e.png。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "assets" ], "summary": "获取公开 OSS 上传签名（注册流程用）", "parameters": [ { "type": "string", "description": "场景，目前固定为 register", "name": "scene", "in": "query", "required": true }, { "type": "string", "description": "前端传入的命名空间（注册时传 mobile），仅允许 [a-zA-Z0-9_-]，最长 32 字符", "name": "key", "in": "query", "required": true } ], "responses": { "200": { "description": "成功返回上传签名信息", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "type": "object", "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" } } } } } ] } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/response.Response" } }, "500": { "description": "OSS配置错误或生成签名失败", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/rankings/hot": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取热度排行榜，支持按维度筛选(displaying:展示中, month:本月, total:全部)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rankings" ], "summary": "获取热度排行榜", "parameters": [ { "type": "string", "description": "统计维度: displaying(展示中), month(本月), total(全部)，默认total", "name": "dimension", "in": "query" }, { "type": "integer", "format": "int64", "description": "粉丝身份ID，不传则使用当前身份", "name": "star_id", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认10", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/rankings/original": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取自制藏品排行榜，支持按维度筛选(displaying:展示中, month:本月, total:全部)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rankings" ], "summary": "获取自制排行榜", "parameters": [ { "type": "string", "description": "统计维度: displaying(展示中), month(本月), total(全部)，默认total", "name": "dimension", "in": "query" }, { "type": "integer", "format": "int64", "description": "粉丝身份ID，不传则使用当前身份", "name": "star_id", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认10", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/assets/{asset_id}/like": { "post": { "security": [ { "BearerAuth": [] } ], "description": "对指定资产进行点赞", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "点赞资产", "parameters": [ { "type": "integer", "description": "资产ID", "name": "asset_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "取消对指定资产的点赞", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "取消点赞", "parameters": [ { "type": "integer", "description": "资产ID", "name": "asset_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/assets/{asset_id}/likers": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取指定藏品的点赞用户列表（带游标分页）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取资产点赞用户列表", "parameters": [ { "type": "integer", "description": "资产ID", "name": "asset_id", "in": "path", "required": true }, { "type": "integer", "description": "每页数量，默认20，最大100", "name": "page_size", "in": "query" }, { "type": "integer", "description": "游标（上一页最后一条的 created_at，首次请求传0）", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/friend-requests": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户的好友请求列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取好友请求列表", "parameters": [ { "type": "string", "description": "请求类型: received/sent", "name": "type", "in": "query" }, { "type": "string", "description": "请求状态", "name": "status", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "向指定用户发送好友请求，或按昵称搜索匹配用户", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "发送好友请求", "parameters": [ { "description": "好友请求参数", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "friend_user_id": { "type": "integer" }, "message": { "type": "string" }, "nickname": { "type": "string" }, "search_mode": { "type": "boolean" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/friend-requests/handle": { "post": { "security": [ { "BearerAuth": [] } ], "description": "接受或拒绝好友请求", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "处理好友请求", "parameters": [ { "description": "处理请求参数: action=accept/reject", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "action": { "type": "string" }, "request_id": { "type": "integer" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/friends": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户的好友列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取好友列表", "parameters": [ { "type": "string", "description": "搜索关键词", "name": "keyword", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "删除指定好友", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "删除好友", "parameters": [ { "description": "好友用户ID", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "friend_user_id": { "type": "integer" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/friends/count": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户的好友数量", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取好友数量", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/friends/remark": { "put": { "security": [ { "BearerAuth": [] } ], "description": "设置指定好友的备注名称", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "设置好友备注", "parameters": [ { "description": "好友ID和备注", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "friend_user_id": { "type": "integer" }, "remark": { "type": "string" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/friendship/check": { "get": { "security": [ { "BearerAuth": [] } ], "description": "检查当前用户与指定用户是否为好友关系", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "检查好友关系", "parameters": [ { "type": "integer", "description": "好友用户ID", "name": "friend_user_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/random-users": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取同一明星身份下的随机推荐用户", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取随机用户", "parameters": [ { "type": "integer", "description": "获取数量，默认1，最大100", "name": "count", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/search-user": { "get": { "security": [ { "BearerAuth": [] } ], "description": "根据用户ID查找用户信息，用于添加好友", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "查找用户", "parameters": [ { "type": "integer", "description": "粉丝档案ID", "name": "friend_fan_profile_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/social/users": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取同一明星身份下的分页用户列表，包含用户ID、展馆所有者ID、昵称、等级", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取分页用户列表", "parameters": [ { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20，最大100", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/starbook/home": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取当前用户的星册首页数据，按类型和分组展示", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "starbook" ], "summary": "获取星册首页", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/starbook/items": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取指定分组的藏品列表，支持分页", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "starbook" ], "summary": "获取星册藏品列表", "parameters": [ { "type": "string", "description": "资产类型: regular/collection/activity", "name": "type", "in": "query", "required": true }, { "type": "string", "description": "子分类，regular 时固定为 castlove", "name": "category", "in": "query" }, { "type": "integer", "description": "等级，仅 regular 类型有效", "name": "grade", "in": "query" }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/users/{user_id}": { "get": { "description": "根据用户ID获取用户公开信息", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "获取指定用户信息", "parameters": [ { "type": "integer", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } }, "/api/v1/users/{user_id}/exhibited-assets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取指定用户正在展出的作品列表", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "galleries" ], "summary": "获取他人展出的作品列表", "parameters": [ { "type": "integer", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dto.GetMyExhibitedAssetsResponseDTO" } } } ] } } } } }, "/api/v1/users/{user_id}/liked-assets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "获取指定用户点赞过的作品列表（只返回展出中且未过期的）", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "social" ], "summary": "获取他人点赞的作品列表", "parameters": [ { "type": "integer", "description": "用户ID", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "description": "页码，默认1", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量，默认20，最大100", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Response" } } } } } }, "definitions": { "activity.BatchPurchaseItemRequest": { "type": "object", "properties": { "activity_id": { "type": "integer" }, "items": { "description": "购买项列表", "type": "array", "items": { "$ref": "#/definitions/activity.PurchaseItem" } }, "star_id": { "type": "integer" }, "user_id": { "description": "当前用户ID", "type": "integer" } } }, "activity.PurchaseItem": { "type": "object", "properties": { "item_type": { "type": "string" }, "quantity": { "type": "integer" } } }, "activity.PurchaseItemRequest": { "type": "object", "properties": { "activity_id": { "type": "integer" }, "item_type": { "type": "string" }, "quantity": { "type": "integer" }, "star_id": { "type": "integer" }, "user_id": { "description": "当前用户ID", "type": "integer" } } }, "common.BaseResponse": { "type": "object", "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" } } }, "dto.AddIdentityResponseDTO": { "type": "object", "properties": { "bound": { "type": "boolean" }, "identity_id": { "type": "string" } } }, "dto.AssetDTO": { "type": "object", "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": { "description": "持有者信息（可选，保留用于兼容性）", "allOf": [ { "$ref": "#/definitions/dto.OwnerInfoDTO" } ] }, "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": "标签数组（可选）", "type": "array", "items": { "type": "string" } }, "tx_hash": { "description": "交易哈希（可选）", "type": "string" }, "updated_at": { "description": "更新时间（毫秒时间戳）", "type": "integer" }, "visibility": { "description": "可见性：private, friends, public", "type": "string" } } }, "dto.AssetInfoDTO": { "type": "object", "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" } } }, "dto.CreateMintOrderRequestDTO": { "type": "object", "required": [ "info", "material_url", "order_id" ], "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": "标签列表（可选）", "type": "array", "items": { "type": "string" } } } }, "dto.CurrentIdentityDTO": { "type": "object", "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" } } }, "dto.ExhibitedAssetItemDTO": { "type": "object", "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" } } }, "dto.FanIdentityDTO": { "type": "object", "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" } } }, "dto.FanIdentityListItemDTO": { "type": "object", "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" } } }, "dto.FanIdentityListResponseDTO": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/dto.FanIdentityListItemDTO" } }, "total": { "type": "integer" } } }, "dto.GetInspirationFlowResponseDTO": { "type": "object", "properties": { "cursor": { "description": "下次请求的游标", "type": "string" }, "has_more": { "description": "是否有更多", "type": "boolean" }, "items": { "description": "藏品列表", "type": "array", "items": { "$ref": "#/definitions/dto.InspirationFlowItemDTO" } }, "session_id": { "description": "会话ID", "type": "string" } } }, "dto.GetMeResponseDTO": { "type": "object", "properties": { "avatar_url": { "type": "string" }, "chain_address": { "type": "string" }, "current_identity": { "$ref": "#/definitions/dto.CurrentIdentityDTO" }, "nickname": { "type": "string" }, "uid": { "type": "integer" } } }, "dto.GetMintOrderResponseDTO": { "type": "object", "properties": { "asset": { "description": "关联的资产信息（如果存在）", "allOf": [ { "$ref": "#/definitions/dto.AssetDTO" } ] }, "order": { "description": "订单信息", "allOf": [ { "$ref": "#/definitions/dto.MintOrderDTO" } ] } } }, "dto.GetMyExhibitedAssetsResponseDTO": { "type": "object", "properties": { "has_more": { "description": "是否有更多", "type": "boolean" }, "items": { "description": "作品列表", "type": "array", "items": { "$ref": "#/definitions/dto.ExhibitedAssetItemDTO" } }, "page": { "description": "当前页码", "type": "integer" }, "page_size": { "description": "每页数量", "type": "integer" }, "total": { "description": "总数量", "type": "integer" } } }, "dto.GetMyGalleryResponseDTO": { "type": "object", "properties": { "gallery_owner_id": { "description": "展馆所有者ID", "type": "integer" }, "nickname": { "description": "展馆所有者昵称", "type": "string" }, "slot_total": { "description": "展位总数", "type": "integer" }, "slots": { "description": "展位列表", "type": "array", "items": { "$ref": "#/definitions/dto.SlotInfoDTO" } } } }, "dto.GetUserGalleryResponseDTO": { "type": "object", "properties": { "gallery_owner_id": { "description": "展馆所有者ID", "type": "integer" }, "nickname": { "description": "展馆所有者昵称", "type": "string" }, "slot_total": { "description": "展位总数", "type": "integer" }, "slots": { "description": "展位列表", "type": "array", "items": { "$ref": "#/definitions/dto.SlotInfoDTO" } } } }, "dto.ImageGenerationRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "aspect_ratio": { "type": "string" }, "model": { "type": "string" }, "n": { "description": "1-4", "type": "integer" }, "prompt": { "type": "string" }, "subject_reference": { "type": "array", "items": { "$ref": "#/definitions/dto.SubjectReference" } } } }, "dto.InspirationFlowItemDTO": { "type": "object", "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" } } }, "dto.LoginResponseDTO": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "user": { "$ref": "#/definitions/dto.UserWithIdentityDTO" } } }, "dto.MintOrderDTO": { "type": "object", "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" } } }, "dto.MyFanIdentitiesResponseDTO": { "type": "object", "properties": { "current_star_id": { "description": "当前激活的明星ID", "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/definitions/dto.MyFanIdentityItemDTO" } }, "total": { "type": "integer" } } }, "dto.MyFanIdentityItemDTO": { "type": "object", "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" } } }, "dto.OwnerInfoDTO": { "type": "object", "properties": { "avatar": { "description": "头像URL", "type": "string" }, "nickname": { "description": "昵称", "type": "string" }, "user_id": { "description": "用户ID", "type": "integer" } } }, "dto.PlaceAssetRequestDTO": { "type": "object", "required": [ "asset_id", "gallery_owner_id", "slot_id" ], "properties": { "asset_id": { "description": "资产ID（必填）", "type": "integer" }, "gallery_owner_id": { "description": "展馆所有者ID（必填）", "type": "integer" }, "slot_id": { "description": "展位ID（必填）", "type": "integer" } } }, "dto.PreCreateMintOrderRequestDTO": { "type": "object", "required": [ "material_url" ], "properties": { "description": { "description": "描述（可选）", "type": "string" }, "event": { "description": "藏品事件（可选）", "type": "string" }, "material_type": { "description": "素材类型（可选）", "type": "string" }, "material_url": { "description": "素材URL（必填）", "type": "string" }, "name": { "description": "藏品名称（可选）", "type": "string" } } }, "dto.ProfileResponseDTO": { "type": "object", "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" } } }, "dto.RegisterResponseDTO": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "user": { "$ref": "#/definitions/dto.UserWithIdentityDTO" } } }, "dto.SendCodeRequest": { "type": "object", "required": [ "mobile", "scene" ], "properties": { "mobile": { "type": "string" }, "scene": { "description": "register, password", "type": "string" } } }, "dto.SendCodeResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "expires_in": { "description": "多少秒后可以重发", "type": "integer" }, "message": { "type": "string" } } }, "dto.SlotInfoDTO": { "type": "object", "properties": { "asset": { "description": "展品信息（仅当status为OCCUPIED时存在）", "allOf": [ { "$ref": "#/definitions/dto.AssetInfoDTO" } ] }, "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": { "description": "解锁条件（仅当status为LOCKED时存在）", "allOf": [ { "$ref": "#/definitions/dto.UnlockConditionDTO" } ] }, "visibility": { "description": "public / private", "type": "string" } } }, "dto.SubjectReference": { "type": "object", "properties": { "image_file": { "type": "string" }, "type": { "type": "string" } } }, "dto.SwitchIdentityResponseDTO": { "type": "object", "properties": { "access_token": { "type": "string" }, "current_identity": { "$ref": "#/definitions/dto.CurrentIdentityDTO" }, "expires_in": { "type": "integer" } } }, "dto.UnlockConditionDTO": { "type": "object", "properties": { "type": { "description": "解锁类型：level（等级）, crystal（水晶）", "type": "string" }, "value": { "description": "解锁条件值（等级或水晶数量）", "type": "integer" } } }, "dto.UpdateNicknameResponseDTO": { "type": "object", "properties": { "nickname": { "type": "string" } } }, "dto.UserWithIdentityDTO": { "type": "object", "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" } } }, "dto.VerifyCodeRequest": { "type": "object", "required": [ "code", "mobile", "scene" ], "properties": { "code": { "type": "string" }, "mobile": { "type": "string" }, "scene": { "type": "string" } } }, "dto.VerifyCodeResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "expires_in": { "description": "token有效期（秒）", "type": "integer" }, "message": { "type": "string" }, "verified": { "type": "boolean" }, "verify_token": { "type": "string" } } }, "response.Response": { "type": "object", "properties": { "code": { "type": "integer" }, "data": {}, "message": { "type": "string" } } }, "task.AdvanceStageRequest": { "type": "object", "properties": { "target_stage": { "type": "integer" } } }, "task.ClaimDailyTaskRequest": { "type": "object", "properties": { "star_id": { "type": "integer" }, "task_key": { "type": "string" } } }, "task.ClaimExhibitionRevenueRequest": { "type": "object", "properties": { "revenue_id": { "type": "integer" }, "star_id": { "type": "integer" } } }, "task.ClaimOnboardingRewardRequest": { "type": "object", "properties": { "stage": { "type": "integer" } } }, "task.CompleteGuideRequest": { "type": "object", "properties": { "stages": { "description": "前端传入的阶段配置，首次调用时存储", "type": "array", "items": { "$ref": "#/definitions/task.OnboardingStage" } }, "task_key": { "type": "string" } } }, "task.OnboardingStage": { "type": "object", "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": { "type": "array", "items": { "type": "string" } }, "stage": { "type": "integer" }, "status": { "description": "pending/completed/in_progress", "type": "string" } } }, "task.ReportEventRequest": { "type": "object", "properties": { "event_type": { "description": "如 \"daily_browse_asset\", \"daily_login\"", "type": "string" }, "star_id": { "type": "integer" } } }, "user.AddIdentityRequest": { "type": "object", "properties": { "nickname": { "description": "粉丝身份昵称", "type": "string" }, "star_id": { "description": "选择的明星ID", "type": "integer" } } }, "user.CheckMobileRequest": { "type": "object", "properties": { "mobile": { "description": "要检查的手机号", "type": "string" } } }, "user.CheckMobileResponse": { "type": "object", "properties": { "base": { "$ref": "#/definitions/common.BaseResponse" }, "exists": { "description": "手机号是否已存在", "type": "boolean" } } }, "user.CheckNicknameRequest": { "type": "object", "properties": { "nickname": { "description": "要检查的昵称", "type": "string" } } }, "user.CheckNicknameResponse": { "type": "object", "properties": { "base": { "$ref": "#/definitions/common.BaseResponse" }, "exists": { "description": "昵称是否已存在", "type": "boolean" } } }, "user.LoginRequest": { "type": "object", "properties": { "mobile": { "description": "手机号", "type": "string" }, "password": { "description": "密码", "type": "string" }, "star_id": { "description": "可选：指定登录的明星ID，不指定则使用最早创建的粉丝档案", "type": "integer" } } }, "user.RegisterRequest": { "type": "object", "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" } } }, "user.SwitchIdentityRequest": { "type": "object", "properties": { "new_star_id": { "description": "切换到的新明星ID", "type": "integer" } } }, "user.UpdateAvatarRequest": { "type": "object", "properties": { "avatar_url": { "description": "头像URL（必填）", "type": "string" } } }, "user.UpdateNicknameRequest": { "type": "object", "properties": { "nickname": { "description": "新昵称", "type": "string" } } }, "user.UpdatePasswordRequest": { "type": "object", "properties": { "new_password": { "description": "新密码", "type": "string" }, "old_password": { "description": "旧密码", "type": "string" }, "verify_token": { "description": "短信验证 token（scene=password 下发的一次性 token）", "type": "string" } } }, "user.ValidateTokenRequest": { "type": "object", "properties": { "access_token": { "type": "string" } } } }, "securityDefinitions": { "BearerAuth": { "type": "apiKey", "name": "Authorization", "in": "header" } } }