{ "openapi": "3.0.0", "info": { "title": "炬融圈代理后台", "version": "1.0.0", "description": "炬融圈代理后台API文档", "contact": { "name": "技术支持", "email": "support@example.com" } }, "servers": [ { "url": "/api", "description": "API服务器" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT认证，请在请求头中添加 Authorization: Bearer " } }, "schemas": { "Agent": { "type": "object", "required": [ "id", "phone", "name" ], "properties": { "id": { "type": "integer", "description": "代理ID" }, "phone": { "type": "string", "description": "代理手机号" }, "name": { "type": "string", "description": "代理名称" }, "status": { "type": "integer", "description": "代理状态 (1-正常, 0-禁用)" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } }, "Commission": { "type": "object", "required": [ "id", "agent_id", "user_id", "amount", "commission_type", "status" ], "properties": { "id": { "type": "integer", "description": "佣金记录ID" }, "agent_id": { "type": "integer", "description": "代理ID" }, "user_id": { "type": "integer", "description": "用户ID" }, "amount": { "type": "number", "format": "decimal", "description": "佣金金额" }, "commission_type": { "type": "string", "description": "佣金类型" }, "status": { "type": "string", "enum": [ "pending", "paid", "cancelled" ], "description": "佣金状态" }, "description": { "type": "string", "description": "佣金描述" }, "order_id": { "type": "string", "description": "关联订单ID" }, "payment_method": { "type": "string", "description": "支付方式" }, "payment_time": { "type": "string", "format": "date-time", "description": "支付时间" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" }, "user": { "$ref": "#/components/schemas/User", "description": "关联用户信息" } } }, "Transfer": { "type": "object", "required": [ "id", "user_id", "amount", "type", "status" ], "properties": { "id": { "type": "integer", "description": "转账记录ID" }, "user_id": { "type": "integer", "description": "用户ID" }, "amount": { "type": "number", "format": "decimal", "description": "转账金额" }, "type": { "type": "string", "enum": [ "deposit", "withdraw", "transfer" ], "description": "转账类型" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "cancelled" ], "description": "转账状态" }, "transaction_id": { "type": "string", "description": "交易单号" }, "payment_method": { "type": "string", "description": "支付方式" }, "bank_info": { "type": "object", "properties": { "bank_name": { "type": "string", "description": "银行名称" }, "account_number": { "type": "string", "description": "账户号码" }, "account_name": { "type": "string", "description": "账户名称" } }, "description": "银行信息" }, "description": { "type": "string", "description": "转账描述" }, "fee": { "type": "number", "format": "decimal", "description": "手续费" }, "actual_amount": { "type": "number", "format": "decimal", "description": "实际到账金额" }, "processed_at": { "type": "string", "format": "date-time", "description": "处理时间" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" }, "user": { "$ref": "#/components/schemas/User", "description": "关联用户信息" } } }, "User": { "type": "object", "required": [ "id", "phone", "username" ], "properties": { "id": { "type": "integer", "description": "用户ID" }, "phone": { "type": "string", "description": "用户手机号" }, "username": { "type": "string", "description": "用户名" }, "email": { "type": "string", "format": "email", "description": "用户邮箱" }, "avatar": { "type": "string", "description": "用户头像URL" }, "role": { "type": "string", "description": "用户角色" }, "status": { "type": "integer", "description": "用户状态 (1-正常, 0-禁用)" }, "city": { "type": "string", "description": "所在城市" }, "area": { "type": "string", "description": "所在区域" }, "agent_id": { "type": "integer", "description": "所属代理ID" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/agent/stats": { "get": { "summary": "获取代理统计数据", "tags": [ "代理统计" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "totalUsers": { "type": "integer", "description": "总用户数" }, "totalCommissions": { "type": "number", "format": "decimal", "description": "总佣金金额" }, "pendingCommissions": { "type": "number", "format": "decimal", "description": "待发放佣金" }, "thisMonthUsers": { "type": "integer", "description": "本月新增用户数" }, "thisMonthCommissions": { "type": "number", "format": "decimal", "description": "本月佣金收入" } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/agent/user-growth-trend": { "get": { "summary": "获取用户增长趋势", "tags": [ "代理统计" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "days", "schema": { "type": "integer", "default": 30 }, "description": "查询天数" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "日期" }, "count": { "type": "integer", "description": "新增用户数" } } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/agent/commission-trend": { "get": { "summary": "获取佣金收入趋势", "tags": [ "代理统计" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "days", "schema": { "type": "integer", "default": 30 }, "description": "查询天数" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "日期" }, "amount": { "type": "number", "format": "decimal", "description": "佣金金额" } } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/agent/commission-distribution": { "get": { "summary": "获取佣金类型分布", "tags": [ "代理统计" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "佣金类型" }, "amount": { "type": "number", "format": "decimal", "description": "佣金金额" }, "count": { "type": "integer", "description": "记录数量" } } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/agent/recent-users": { "get": { "summary": "获取最新下级用户", "tags": [ "代理统计" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "返回数量限制" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/agent/recent-commissions": { "get": { "summary": "获取最新佣金记录", "tags": [ "代理统计" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "返回数量限制" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Commission" } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/auth/login": { "post": { "summary": "代理登录", "tags": [ "认证" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "password" ], "properties": { "phone": { "type": "string", "description": "代理手机号" }, "password": { "type": "string", "description": "登录密码" }, "captchaId": { "type": "string", "description": "验证码ID" }, "captchaText": { "type": "string", "description": "验证码文本" } } } } } }, "responses": { "200": { "description": "登录成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "JWT令牌" }, "agent": { "$ref": "#/components/schemas/Agent" } } } } } } } }, "400": { "description": "参数错误" }, "401": { "description": "登录失败" } } } }, "/auth/me": { "get": { "summary": "获取当前代理信息", "tags": [ "认证" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "401": { "description": "未授权或令牌无效" }, "500": { "description": "服务器错误" } } } }, "/auth/logout": { "post": { "summary": "代理登出", "tags": [ "认证" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "登出成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "登出成功" } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/captcha/generate": { "get": { "summary": "生成图形验证码", "tags": [ "验证码" ], "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "captchaId": { "type": "string", "description": "验证码唯一标识" }, "captchaImage": { "type": "string", "description": "SVG格式的验证码图片" } } } } } } } }, "500": { "description": "服务器错误" } } } }, "/captcha/verify": { "post": { "summary": "验证图形验证码", "tags": [ "验证码" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "captchaId", "captchaText" ], "properties": { "captchaId": { "type": "string", "description": "验证码唯一标识" }, "captchaText": { "type": "string", "description": "用户输入的验证码文本" } } } } } }, "responses": { "200": { "description": "验证成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "验证码验证成功" } } } } } }, "400": { "description": "验证失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "examples": { "invalid_params": { "value": "验证码ID和文本不能为空" }, "not_found": { "value": "验证码不存在或已过期" }, "incorrect": { "value": "验证码错误" } } } } } } } }, "500": { "description": "服务器错误" } } } }, "/commissions": { "get": { "summary": "获取佣金记录列表", "tags": [ "佣金管理" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "搜索关键词（用户名、手机号）" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "paid", "cancelled" ] }, "description": "佣金状态" }, { "in": "query", "name": "commission_type", "schema": { "type": "string" }, "description": "佣金类型" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "description": "开始日期" }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "description": "结束日期" }, { "in": "query", "name": "min_amount", "schema": { "type": "number" }, "description": "最小金额" }, { "in": "query", "name": "max_amount", "schema": { "type": "number" }, "description": "最大金额" }, { "in": "query", "name": "sort_by", "schema": { "type": "string", "default": "created_at" }, "description": "排序字段" }, { "in": "query", "name": "sort_order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "排序方向" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "commissions": { "type": "array", "items": { "$ref": "#/components/schemas/Commission" } }, "total": { "type": "integer", "description": "总记录数" }, "page": { "type": "integer", "description": "当前页码" }, "limit": { "type": "integer", "description": "每页数量" }, "totalPages": { "type": "integer", "description": "总页数" }, "stats": { "type": "object", "properties": { "totalAmount": { "type": "number", "format": "decimal", "description": "总佣金金额" }, "pendingAmount": { "type": "number", "format": "decimal", "description": "待发放金额" }, "paidAmount": { "type": "number", "format": "decimal", "description": "已发放金额" } } } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/commissions/{id}": { "get": { "summary": "获取单个佣金记录详情", "tags": [ "佣金管理" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "佣金记录ID" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Commission" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "佣金记录不存在" }, "500": { "description": "服务器错误" } } } }, "/commissions/{id}/request-payment": { "post": { "summary": "申请单个佣金发放", "tags": [ "佣金管理" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "佣金记录ID" } ], "responses": { "200": { "description": "申请成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "佣金发放申请已提交" } } } } } }, "400": { "description": "申请失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "该佣金记录不可申请发放" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "佣金记录不存在" }, "500": { "description": "服务器错误" } } } }, "/commissions/batch-request-payment": { "post": { "summary": "批量申请佣金发放", "tags": [ "佣金管理" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "commission_ids" ], "properties": { "commission_ids": { "type": "array", "items": { "type": "integer" }, "description": "佣金记录ID数组" } } } } } }, "responses": { "200": { "description": "批量申请成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "successCount": { "type": "integer", "description": "成功申请数量" }, "failedCount": { "type": "integer", "description": "失败申请数量" }, "failedIds": { "type": "array", "items": { "type": "integer" }, "description": "失败的佣金记录ID" } } }, "message": { "type": "string", "example": "批量申请完成" } } } } } }, "400": { "description": "参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/transfers": { "get": { "summary": "获取代理下级用户转账记录列表", "tags": [ "转账管理" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "搜索关键词（用户名、手机号、转账单号）" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "success", "failed", "cancelled" ] }, "description": "转账状态" }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "deposit", "withdraw", "transfer" ] }, "description": "转账类型" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "description": "开始日期" }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "description": "结束日期" }, { "in": "query", "name": "min_amount", "schema": { "type": "number" }, "description": "最小金额" }, { "in": "query", "name": "max_amount", "schema": { "type": "number" }, "description": "最大金额" }, { "in": "query", "name": "sort_by", "schema": { "type": "string", "default": "created_at" }, "description": "排序字段" }, { "in": "query", "name": "sort_order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "排序方向" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } }, "total": { "type": "integer", "description": "总记录数" }, "page": { "type": "integer", "description": "当前页码" }, "limit": { "type": "integer", "description": "每页数量" }, "totalPages": { "type": "integer", "description": "总页数" }, "stats": { "type": "object", "properties": { "totalAmount": { "type": "number", "format": "decimal", "description": "总转账金额" }, "successAmount": { "type": "number", "format": "decimal", "description": "成功转账金额" }, "pendingAmount": { "type": "number", "format": "decimal", "description": "待处理转账金额" }, "failedAmount": { "type": "number", "format": "decimal", "description": "失败转账金额" } } } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/upload/single": { "post": { "summary": "单文件上传", "tags": [ "文件上传" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "上传的文件" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "filename": { "type": "string", "description": "文件名" }, "originalname": { "type": "string", "description": "原始文件名" }, "path": { "type": "string", "description": "文件路径" }, "size": { "type": "integer", "description": "文件大小（字节）" }, "mimetype": { "type": "string", "description": "文件MIME类型" }, "url": { "type": "string", "description": "文件访问URL" } } } } } } } }, "400": { "description": "上传失败" }, "401": { "description": "未授权" }, "413": { "description": "文件过大" }, "500": { "description": "服务器错误" } } } }, "/upload/multiple": { "post": { "summary": "多文件上传", "tags": [ "文件上传" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "上传的文件数组" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "文件名" }, "originalname": { "type": "string", "description": "原始文件名" }, "path": { "type": "string", "description": "文件路径" }, "size": { "type": "integer", "description": "文件大小（字节）" }, "mimetype": { "type": "string", "description": "文件MIME类型" }, "url": { "type": "string", "description": "文件访问URL" } } } } } } } } }, "400": { "description": "上传失败" }, "401": { "description": "未授权" }, "413": { "description": "文件过大" }, "500": { "description": "服务器错误" } } } }, "/upload/avatar": { "post": { "summary": "头像上传", "tags": [ "文件上传" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "avatar": { "type": "string", "format": "binary", "description": "头像文件（支持jpg, jpeg, png, gif格式，最大2MB）" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "filename": { "type": "string", "description": "文件名" }, "url": { "type": "string", "description": "头像访问URL" } } } } } } } }, "400": { "description": "文件格式不支持或文件过大" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/upload/qrcode": { "post": { "summary": "二维码上传", "tags": [ "文件上传" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "qrcode": { "type": "string", "format": "binary", "description": "二维码文件（支持jpg, jpeg, png格式，最大5MB）" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "filename": { "type": "string", "description": "文件名" }, "url": { "type": "string", "description": "二维码访问URL" } } } } } } } }, "400": { "description": "文件格式不支持或文件过大" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/upload/idcard": { "post": { "summary": "身份证上传", "tags": [ "文件上传" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "idcard": { "type": "string", "format": "binary", "description": "身份证文件（支持jpg, jpeg, png格式，最大10MB）" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "filename": { "type": "string", "description": "文件名" }, "url": { "type": "string", "description": "身份证访问URL" } } } } } } } }, "400": { "description": "文件格式不支持或文件过大" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/upload/license": { "post": { "summary": "营业执照上传", "tags": [ "文件上传" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "license": { "type": "string", "format": "binary", "description": "营业执照文件（支持jpg, jpeg, png, pdf格式，最大10MB）" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "filename": { "type": "string", "description": "文件名" }, "url": { "type": "string", "description": "营业执照访问URL" } } } } } } } }, "400": { "description": "文件格式不支持或文件过大" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/upload/file": { "delete": { "summary": "删除文件", "tags": [ "文件上传" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filename" ], "properties": { "filename": { "type": "string", "description": "要删除的文件名" } } } } } }, "responses": { "200": { "description": "删除成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "文件删除成功" } } } } } }, "400": { "description": "参数错误" }, "401": { "description": "未授权" }, "404": { "description": "文件不存在" }, "500": { "description": "服务器错误" } } } }, "/users": { "get": { "summary": "获取代理下级用户列表", "tags": [ "用户管理" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "搜索关键词（用户名、手机号、邮箱）" }, { "in": "query", "name": "role", "schema": { "type": "string" }, "description": "用户角色筛选" }, { "in": "query", "name": "city", "schema": { "type": "string" }, "description": "城市筛选" }, { "in": "query", "name": "area", "schema": { "type": "string" }, "description": "区域筛选" }, { "in": "query", "name": "sort_by", "schema": { "type": "string", "default": "created_at" }, "description": "排序字段" }, { "in": "query", "name": "sort_order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "排序方向" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "total": { "type": "integer", "description": "总记录数" }, "page": { "type": "integer", "description": "当前页码" }, "limit": { "type": "integer", "description": "每页数量" }, "totalPages": { "type": "integer", "description": "总页数" } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/users/{id}": { "get": { "summary": "获取用户详情", "tags": [ "用户管理" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "用户ID" } ], "responses": { "200": { "description": "获取成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/User" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "用户不存在" }, "500": { "description": "服务器错误" } } } }, "/users/export/data": { "get": { "summary": "导出用户数据", "tags": [ "用户管理" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "excel", "csv" ], "default": "excel" }, "description": "导出格式" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "搜索关键词（用户名、手机号、邮箱）" }, { "in": "query", "name": "role", "schema": { "type": "string" }, "description": "用户角色筛选" }, { "in": "query", "name": "city", "schema": { "type": "string" }, "description": "城市筛选" }, { "in": "query", "name": "area", "schema": { "type": "string" }, "description": "区域筛选" } ], "responses": { "200": { "description": "导出成功", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } } }, "tags": [ { "name": "代理统计", "description": "代理统计数据相关接口" }, { "name": "认证", "description": "代理认证相关接口" }, { "name": "验证码", "description": "验证码生成和验证相关接口" }, { "name": "佣金管理", "description": "佣金记录管理相关接口" }, { "name": "转账管理", "description": "转账记录管理相关接口" }, { "name": "文件上传", "description": "文件上传管理相关接口" }, { "name": "用户管理", "description": "用户管理相关接口" } ] }