{ "openapi": "3.0.0", "info": { "title": "融豆商城 API", "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" } }, "schemas": { "Address": { "type": "object", "properties": { "id": { "type": "integer", "description": "地址ID" }, "user_id": { "type": "integer", "description": "用户ID" }, "recipient_name": { "type": "string", "description": "收件人姓名" }, "phone": { "type": "string", "description": "联系电话" }, "province_code": { "type": "string", "description": "省份编码" }, "province_name": { "type": "string", "description": "省份名称" }, "city_code": { "type": "string", "description": "城市编码" }, "city_name": { "type": "string", "description": "城市名称" }, "district_code": { "type": "string", "description": "区县编码" }, "district_name": { "type": "string", "description": "区县名称" }, "detailed_address": { "type": "string", "description": "详细地址" }, "postal_code": { "type": "string", "description": "邮政编码" }, "label_id": { "type": "integer", "description": "地址标签ID" }, "is_default": { "type": "boolean", "description": "是否为默认地址" }, "label_name": { "type": "string", "description": "标签名称" }, "label_color": { "type": "string", "description": "标签颜色" } }, "required": [ "recipient_name", "phone", "province_code", "province_name", "city_code", "city_name", "district_code", "district_name", "detailed_address" ] }, "LoginCredentials": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "description": "用户名或手机号" }, "password": { "type": "string", "description": "密码" } } }, "RegisterRequest": { "type": "object", "required": [ "username", "phone", "password", "registrationCode", "city", "district_id", "captchaId", "captchaText", "smsCode" ], "properties": { "username": { "type": "string", "description": "用户名" }, "phone": { "type": "string", "description": "手机号" }, "password": { "type": "string", "description": "密码" }, "registrationCode": { "type": "string", "description": "注册激活码" }, "city": { "type": "string", "description": "城市" }, "district_id": { "type": "string", "description": "区域ID" }, "captchaId": { "type": "string", "description": "图形验证码ID" }, "captchaText": { "type": "string", "description": "图形验证码文本" }, "smsCode": { "type": "string", "description": "短信验证码" }, "role": { "type": "string", "description": "用户角色", "default": "user" } } }, "MatchingOrder": { "type": "object", "properties": { "id": { "type": "integer", "description": "匹配订单ID" }, "initiator_id": { "type": "integer", "description": "发起人ID" }, "matching_type": { "type": "string", "enum": [ "small", "large" ], "description": "匹配类型（小额或大额）" }, "amount": { "type": "number", "description": "匹配总金额" }, "status": { "type": "string", "enum": [ "pending", "matching", "completed", "failed" ], "description": "订单状态" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" } } }, "Allocation": { "type": "object", "properties": { "id": { "type": "integer", "description": "分配ID" }, "from_user_id": { "type": "integer", "description": "发送方用户ID" }, "to_user_id": { "type": "integer", "description": "接收方用户ID" }, "amount": { "type": "number", "description": "分配金额" }, "cycle_number": { "type": "integer", "description": "轮次编号" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "rejected", "cancelled" ], "description": "分配状态" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" } } }, "UnreasonableMatch": { "type": "object", "properties": { "allocation_id": { "type": "integer", "description": "分配ID" }, "from_user_id": { "type": "integer", "description": "发送方用户ID" }, "to_user_id": { "type": "integer", "description": "接收方用户ID" }, "amount": { "type": "number", "description": "分配金额" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "rejected", "cancelled" ], "description": "分配状态" }, "to_username": { "type": "string", "description": "接收方用户名" }, "to_user_balance": { "type": "number", "description": "接收方用户余额" }, "from_username": { "type": "string", "description": "发送方用户名" }, "from_user_balance": { "type": "number", "description": "发送方用户余额" } } }, "Order": { "type": "object", "properties": { "id": { "type": "integer", "description": "订单ID" }, "order_no": { "type": "string", "description": "订单编号" }, "user_id": { "type": "integer", "description": "用户ID" }, "total_amount": { "type": "number", "description": "订单总金额" }, "total_points": { "type": "number", "description": "订单总积分" }, "status": { "type": "string", "enum": [ "pending", "shipped", "completed", "cancelled" ], "description": "订单状态" }, "address": { "type": "string", "description": "收货地址" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" }, "username": { "type": "string", "description": "用户名" } } }, "PointsHistory": { "type": "object", "properties": { "id": { "type": "integer", "description": "积分历史记录ID" }, "points_change": { "type": "integer", "description": "积分变动数量" }, "type": { "type": "string", "description": "积分变动类型(earn-获得, spend-消费, admin_adjust-管理员调整)" }, "description": { "type": "string", "description": "积分变动描述" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" } } }, "Product": { "type": "object", "required": [ "name", "points_price", "stock" ], "properties": { "id": { "type": "integer", "description": "商品ID" }, "name": { "type": "string", "description": "商品名称" }, "category": { "type": "string", "description": "商品分类" }, "points_price": { "type": "integer", "description": "积分价格" }, "stock": { "type": "integer", "description": "库存数量" }, "image_url": { "type": "string", "description": "商品图片URL" }, "description": { "type": "string", "description": "商品描述" }, "status": { "type": "string", "description": "商品状态", "enum": [ "active", "inactive" ] }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } }, "Region": { "type": "object", "properties": { "code": { "type": "string", "description": "地区编码" }, "name": { "type": "string", "description": "地区名称" } } }, "ZhejiangRegion": { "type": "object", "properties": { "id": { "type": "integer", "description": "地区ID" }, "city_name": { "type": "string", "description": "城市名称" }, "district_name": { "type": "string", "description": "区县名称" }, "region_code": { "type": "string", "description": "地区编码" }, "is_available": { "type": "integer", "description": "是否可用(1:可用 0:不可用)" } } }, "SMSVerification": { "type": "object", "properties": { "phone": { "type": "string", "description": "手机号码" }, "code": { "type": "string", "description": "验证码" } } }, "Transfer": { "type": "object", "properties": { "id": { "type": "integer", "description": "转账记录ID" }, "user_id": { "type": "integer", "description": "用户ID" }, "recipient_id": { "type": "integer", "description": "接收方用户ID" }, "amount": { "type": "number", "format": "float", "description": "转账金额" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "cancelled" ], "description": "转账状态" }, "transfer_type": { "type": "string", "enum": [ "user_to_user", "user_to_system", "system_to_user" ], "description": "转账类型" }, "voucher_image": { "type": "string", "description": "转账凭证图片路径" }, "remark": { "type": "string", "description": "转账备注" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "总记录数" }, "page": { "type": "integer", "description": "当前页码" }, "limit": { "type": "integer", "description": "每页记录数" }, "total_pages": { "type": "integer", "description": "总页数" } } }, "User": { "type": "object", "required": [ "username", "password", "real_name", "id_card" ], "properties": { "id": { "type": "integer", "description": "用户ID" }, "username": { "type": "string", "description": "用户名" }, "role": { "type": "string", "description": "用户角色", "enum": [ "user", "admin", "merchant" ] }, "avatar": { "type": "string", "description": "用户头像URL" }, "points": { "type": "integer", "description": "用户积分" }, "real_name": { "type": "string", "description": "真实姓名" }, "id_card": { "type": "string", "description": "身份证号" }, "phone": { "type": "string", "description": "手机号" }, "is_system_account": { "type": "boolean", "description": "是否为系统账户" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/addresses": { "get": { "summary": "获取用户收货地址列表", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取地址列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } }, "post": { "summary": "创建收货地址", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_name": { "type": "string", "description": "收件人姓名" }, "phone": { "type": "string", "description": "联系电话" }, "province_code": { "type": "string", "description": "省份编码" }, "province_name": { "type": "string", "description": "省份名称" }, "city_code": { "type": "string", "description": "城市编码" }, "city_name": { "type": "string", "description": "城市名称" }, "district_code": { "type": "string", "description": "区县编码" }, "district_name": { "type": "string", "description": "区县名称" }, "detailed_address": { "type": "string", "description": "详细地址" }, "postal_code": { "type": "string", "description": "邮政编码" }, "label_id": { "type": "integer", "description": "地址标签ID" }, "is_default": { "type": "boolean", "description": "是否为默认地址" } }, "required": [ "recipient_name", "phone", "province_code", "province_name", "city_code", "city_name", "district_code", "district_name", "detailed_address" ] } } } }, "responses": { "201": { "description": "地址创建成功" }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/addresses/{id}": { "get": { "summary": "获取单个收货地址详情", "tags": [ "Addresses" ], "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" }, "data": { "$ref": "#/components/schemas/Address" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "地址不存在" }, "500": { "description": "服务器错误" } } }, "put": { "summary": "更新收货地址", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "地址ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_name": { "type": "string", "description": "收件人姓名" }, "phone": { "type": "string", "description": "联系电话" }, "province_code": { "type": "string", "description": "省份编码" }, "province_name": { "type": "string", "description": "省份名称" }, "city_code": { "type": "string", "description": "城市编码" }, "city_name": { "type": "string", "description": "城市名称" }, "district_code": { "type": "string", "description": "区县编码" }, "district_name": { "type": "string", "description": "区县名称" }, "detailed_address": { "type": "string", "description": "详细地址" }, "postal_code": { "type": "string", "description": "邮政编码" }, "label_id": { "type": "integer", "description": "地址标签ID" }, "is_default": { "type": "boolean", "description": "是否为默认地址" } } } } } }, "responses": { "200": { "description": "地址更新成功" }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "404": { "description": "地址不存在" }, "500": { "description": "服务器错误" } } }, "delete": { "summary": "删除收货地址（软删除）", "tags": [ "Addresses" ], "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": "收货地址删除成功" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "地址不存在" }, "500": { "description": "服务器错误" } } } }, "/addresses/{id}/default": { "put": { "summary": "设置默认地址", "tags": [ "Addresses" ], "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": "默认地址设置成功" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "地址不存在" }, "500": { "description": "服务器错误" } } } }, "/auth/register": { "post": { "summary": "用户注册", "description": "需要提供有效的激活码才能注册", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "用户注册成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "token": { "type": "string", "description": "JWT认证令牌" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "role": { "type": "string" } } } } } } } }, "400": { "description": "请求参数错误" }, "500": { "description": "服务器错误" } } } }, "/auth/login": { "post": { "summary": "用户登录", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginCredentials" } } } }, "responses": { "200": { "description": "登录成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "token": { "type": "string", "description": "JWT认证令牌" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "role": { "type": "string" }, "avatar": { "type": "string" }, "points": { "type": "integer" } } } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "用户名或密码错误" }, "403": { "description": "账户审核未通过" }, "500": { "description": "服务器错误" } } } }, "/captcha/generate": { "get": { "summary": "生成图形验证码", "tags": [ "Captcha" ], "responses": { "200": { "description": "成功生成验证码", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "captchaId": { "type": "string", "description": "验证码唯一ID" }, "image": { "type": "string", "description": "Base64编码的SVG验证码图片" } } } } } } } }, "500": { "description": "服务器错误" } } } }, "/captcha/verify": { "post": { "summary": "验证用户输入的验证码", "tags": [ "Captcha" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "captchaId", "captchaText" ], "properties": { "captchaId": { "type": "string", "description": "验证码唯一ID" }, "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", "example": "验证码错误" } } } } } }, "500": { "description": "服务器错误" } } } }, "/api/matching/create": { "post": { "summary": "创建匹配订单", "tags": [ "Matching" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "matchingType": { "type": "string", "enum": [ "small", "large" ], "default": "small", "description": "匹配类型（小额或大额）" }, "customAmount": { "type": "number", "description": "大额匹配时的自定义金额（5000-50000之间）" } } } } } }, "responses": { "200": { "description": "匹配订单创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "matchingOrderId": { "type": "integer" }, "amounts": { "type": "array", "items": { "type": "number" } }, "matchingType": { "type": "string" }, "totalAmount": { "type": "number" } } } } } } } }, "400": { "description": "参数错误或用户未满足匹配条件" }, "401": { "description": "未授权" }, "404": { "description": "用户不存在" }, "500": { "description": "服务器错误" } } } }, "/api/matching/my-orders": { "get": { "summary": "获取用户的匹配订单列表", "tags": [ "Matching" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" } ], "responses": { "200": { "description": "成功获取匹配订单列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MatchingOrder" } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/matching/pending-allocations": { "get": { "summary": "获取用户待处理的分配", "tags": [ "Matching" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取待处理分配", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Allocation" } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/matching/allocation/{id}": { "get": { "summary": "获取分配详情", "tags": [ "Matching" ], "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" }, "data": { "$ref": "#/components/schemas/Allocation" } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无权限访问" }, "404": { "description": "分配不存在" }, "500": { "description": "服务器错误" } } } }, "/api/matching/confirm-allocation/{allocationId}": { "post": { "summary": "确认分配（创建转账）", "tags": [ "Matching" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "allocationId", "required": true, "schema": { "type": "integer" }, "description": "分配ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transferAmount": { "type": "number", "description": "转账金额" }, "description": { "type": "string", "description": "转账描述" }, "voucher": { "type": "string", "description": "转账凭证（图片URL）" } }, "required": [ "voucher" ] } } } }, "responses": { "200": { "description": "转账凭证提交成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "transferId": { "type": "integer" } } } } } } } }, "400": { "description": "参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/matching/reject-allocation/{allocationId}": { "post": { "summary": "拒绝分配", "tags": [ "Matching" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "allocationId", "required": true, "schema": { "type": "integer" }, "description": "分配ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "拒绝原因" } } } } } }, "responses": { "200": { "description": "拒绝分配成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "分配不存在或无权限" }, "500": { "description": "服务器错误" } } } }, "/api/matching/order/{orderId}": { "get": { "summary": "获取匹配订单详情", "tags": [ "Matching" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "type": "integer" }, "description": "订单ID" } ], "responses": { "200": { "description": "成功获取订单详情", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/MatchingOrder" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/Allocation" } }, "records": { "type": "array", "items": { "type": "object" } } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无权限查看" }, "404": { "description": "订单不存在" }, "500": { "description": "服务器错误" } } } }, "/api/matching/stats": { "get": { "summary": "获取匹配统计信息", "tags": [ "Matching" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取统计信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "userStats": { "type": "object", "properties": { "initiated_orders": { "type": "integer" }, "participated_allocations": { "type": "integer" }, "total_initiated_amount": { "type": "number" }, "total_participated_amount": { "type": "number" } } } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/matching-admin/unreasonable-matches": { "get": { "summary": "获取不合理的匹配记录（正余额用户被匹配的情况）", "tags": [ "MatchingAdmin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 20 }, "description": "每页数量" } ], "responses": { "200": { "description": "成功获取不合理匹配记录", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/UnreasonableMatch" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "500": { "description": "服务器错误" } } } }, "/api/matching-admin/fix-unreasonable-match/{allocationId}": { "post": { "summary": "修复不合理的匹配记录", "tags": [ "MatchingAdmin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "allocationId", "required": true, "schema": { "type": "integer" }, "description": "分配ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancel", "reassign" ], "description": "修复操作类型（取消或重新分配）" } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "修复成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "参数错误或无需修复" }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "404": { "description": "分配记录不存在" }, "500": { "description": "服务器错误" } } } }, "/api/matching-admin/matching-stats": { "get": { "summary": "获取匹配统计信息", "tags": [ "MatchingAdmin" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取匹配统计信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "currentStats": { "type": "object", "properties": { "unreasonable_matches": { "type": "integer" }, "reasonable_matches": { "type": "integer" }, "system_matches": { "type": "integer" }, "unreasonable_amount": { "type": "number" }, "reasonable_amount": { "type": "number" } } }, "yesterdayStats": { "type": "object", "properties": { "total_outbound": { "type": "number" }, "unique_amounts": { "type": "integer" } } } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "500": { "description": "服务器错误" } } } }, "/api/matching-admin/fix-all-unreasonable": { "post": { "summary": "批量修复所有不合理匹配", "tags": [ "MatchingAdmin" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "批量修复完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "fixedCount": { "type": "integer", "description": "成功修复的记录数" }, "errorCount": { "type": "integer", "description": "修复失败的记录数" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "错误信息列表（最多10条）" } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "500": { "description": "服务器错误" } } } }, "/api/matching-admin/confirm-allocation/{allocationId}": { "post": { "summary": "管理员确认分配", "tags": [ "MatchingAdmin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "allocationId", "required": true, "schema": { "type": "integer" }, "description": "分配ID" } ], "responses": { "200": { "description": "分配确认成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "404": { "description": "分配不存在或状态不是待处理" }, "500": { "description": "服务器错误" } } } }, "/api/matching-admin/cancel-allocation/{allocationId}": { "post": { "summary": "管理员取消分配", "tags": [ "MatchingAdmin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "allocationId", "required": true, "schema": { "type": "integer" }, "description": "分配ID" } ], "responses": { "200": { "description": "分配取消成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "404": { "description": "分配不存在或状态不是待处理" }, "500": { "description": "服务器错误" } } } }, "/api/orders": { "get": { "summary": "获取订单列表", "tags": [ "Orders" ], "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": "orderNumber", "schema": { "type": "string" }, "description": "订单号" }, { "in": "query", "name": "username", "schema": { "type": "string" }, "description": "用户名" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "shipped", "completed", "cancelled" ] }, "description": "订单状态" }, { "in": "query", "name": "startDate", "schema": { "type": "string", "format": "date" }, "description": "开始日期" }, { "in": "query", "name": "endDate", "schema": { "type": "string", "format": "date" }, "description": "结束日期" } ], "responses": { "200": { "description": "成功获取订单列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } }, "post": { "summary": "创建订单", "tags": [ "Orders" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "商品ID" }, "quantity": { "type": "integer", "description": "购买数量" }, "shipping_address": { "type": "string", "description": "收货地址" } }, "required": [ "product_id", "quantity", "shipping_address" ] } } } }, "responses": { "201": { "description": "订单创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "orderId": { "type": "integer" }, "orderNumber": { "type": "string" }, "pointsUsed": { "type": "integer" } } } } } } } }, "400": { "description": "参数错误或积分不足" }, "401": { "description": "未授权" }, "404": { "description": "商品不存在或已下架" }, "500": { "description": "服务器错误" } } } }, "/api/orders/{id}": { "get": { "summary": "获取单个订单详情", "tags": [ "Orders" ], "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" }, "data": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } } } } } } } }, "401": { "description": "未授权" }, "404": { "description": "订单不存在" }, "500": { "description": "服务器错误" } } } }, "/api/orders/{id}/cancel": { "put": { "summary": "用户取消订单", "tags": [ "Orders" ], "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" }, "message": { "type": "string" } } } } } }, "400": { "description": "只能取消待处理的订单" }, "401": { "description": "未授权" }, "404": { "description": "订单不存在" }, "500": { "description": "服务器错误" } } } }, "/api/orders/{id}/confirm": { "put": { "summary": "确认收货", "tags": [ "Orders" ], "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" }, "message": { "type": "string" } } } } } }, "400": { "description": "只能确认已发货的订单" }, "401": { "description": "未授权" }, "404": { "description": "订单不存在" }, "500": { "description": "服务器错误" } } } }, "/api/orders/{id}/status": { "put": { "summary": "更新订单状态（管理员）", "tags": [ "Orders" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "订单ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "shipped", "completed", "cancelled" ], "description": "订单状态" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "订单状态更新成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "无效的订单状态" }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "404": { "description": "订单不存在" }, "500": { "description": "服务器错误" } } } }, "/api/orders/stats": { "get": { "summary": "获取订单统计信息（管理员权限）", "tags": [ "Orders" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取订单统计信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "totalOrders": { "type": "integer", "description": "总订单数" }, "pendingOrders": { "type": "integer", "description": "待发货订单数" }, "completedOrders": { "type": "integer", "description": "已完成订单数" }, "monthOrders": { "type": "integer", "description": "本月新增订单数" }, "monthGrowthRate": { "type": "number", "description": "月增长率" }, "totalPointsConsumed": { "type": "number", "description": "总积分消费" } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "无管理员权限" }, "500": { "description": "服务器错误" } } } }, "/api/points/balance": { "get": { "summary": "获取用户当前积分余额", "tags": [ "Points" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取积分余额", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "points": { "type": "integer", "description": "用户当前积分" } } } } } } } }, "401": { "description": "未授权，需要登录" }, "404": { "description": "用户不存在" }, "500": { "description": "服务器错误" } } } }, "/api/points/history": { "get": { "summary": "获取用户积分历史记录", "tags": [ "Points" ], "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": "type", "schema": { "type": "string", "enum": [ "earn", "spend", "admin_adjust" ] }, "description": "积分变动类型" }, { "in": "query", "name": "username", "schema": { "type": "string" }, "description": "用户名(仅管理员可用)" }, { "in": "query", "name": "change", "schema": { "type": "string", "enum": [ "positive", "negative" ] }, "description": "积分变动方向(仅管理员可用)" }, { "in": "query", "name": "startDate", "schema": { "type": "string", "format": "date" }, "description": "开始日期(仅管理员可用)" }, { "in": "query", "name": "endDate", "schema": { "type": "string", "format": "date" }, "description": "结束日期(仅管理员可用)" } ], "responses": { "200": { "description": "成功获取积分历史", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/PointsHistory" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } }, "401": { "description": "未授权，需要登录" }, "500": { "description": "服务器错误" } } } }, "/api/points/adjust": { "post": { "summary": "管理员调整用户积分", "tags": [ "Points" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userId", "points", "reason" ], "properties": { "userId": { "type": "integer", "description": "用户ID" }, "points": { "type": "integer", "description": "调整的积分数量(正数为增加，负数为减少)" }, "reason": { "type": "string", "description": "调整原因" } } } } } }, "responses": { "200": { "description": "积分调整成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "积分调整成功" }, "data": { "type": "object", "properties": { "userId": { "type": "integer" }, "pointsChanged": { "type": "integer" }, "newBalance": { "type": "integer" } } } } } } } }, "400": { "description": "参数错误或积分不足" }, "401": { "description": "未授权，需要管理员权限" }, "404": { "description": "用户不存在" }, "500": { "description": "服务器错误" } } } }, "/api/points/recharge": { "post": { "summary": "管理员给用户充值积分", "tags": [ "Points" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id", "points" ], "properties": { "user_id": { "type": "integer", "description": "用户ID" }, "points": { "type": "integer", "description": "充值的积分数量(必须为正数)" }, "description": { "type": "string", "description": "充值描述", "default": "管理员充值" } } } } } }, "responses": { "200": { "description": "积分充值成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "积分充值成功" }, "data": { "type": "object", "properties": { "userId": { "type": "integer" }, "pointsAdded": { "type": "integer" } } } } } } } }, "400": { "description": "参数错误" }, "401": { "description": "未授权，需要管理员权限" }, "404": { "description": "用户不存在" }, "500": { "description": "服务器错误" } } } }, "/api/points/leaderboard": { "get": { "summary": "获取积分排行榜", "tags": [ "Points" ], "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": "object", "properties": { "leaderboard": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "userId": { "type": "integer" }, "username": { "type": "string" }, "points": { "type": "integer" } } } } } } } } } } }, "401": { "description": "未授权，需要登录" }, "500": { "description": "服务器错误" } } } }, "/api/points/stats": { "get": { "summary": "获取积分统计信息（管理员权限）", "tags": [ "Points" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取积分统计信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "totalPoints": { "type": "integer", "description": "系统中总积分数量" }, "totalEarned": { "type": "integer", "description": "总积分发放量" }, "totalSpent": { "type": "integer", "description": "总积分消费量" }, "activeUsers": { "type": "integer", "description": "活跃用户数" } } } } } } } } } }, "401": { "description": "未授权，需要管理员权限" }, "500": { "description": "服务器错误" } } } }, "/products": { "get": { "summary": "获取商品列表", "tags": [ "Products" ], "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": "category", "schema": { "type": "string" }, "description": "商品分类" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "description": "商品状态" } ], "responses": { "200": { "description": "成功获取商品列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } } } } } } } } } } } }, "/products/categories": { "get": { "summary": "获取商品分类列表", "tags": [ "Products" ], "responses": { "200": { "description": "成功获取商品分类列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/products/{id}": { "get": { "summary": "获取单个商品详情", "tags": [ "Products" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "商品ID" } ], "responses": { "200": { "description": "成功获取商品详情", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "description": "商品不存在" } } } }, "/regions/zhejiang": { "get": { "summary": "获取浙江省所有地区数据", "tags": [ "Regions" ], "responses": { "200": { "description": "成功获取浙江省地区数据", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ZhejiangRegion" } }, "message": { "type": "string", "example": "获取地区数据成功" } } } } } }, "500": { "description": "服务器错误" } } } }, "/regions/provinces": { "get": { "summary": "获取所有省份", "tags": [ "Regions" ], "responses": { "200": { "description": "成功获取省份列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } } } }, "500": { "description": "服务器错误" } } } }, "/regions/cities/{provinceCode}": { "get": { "summary": "根据省份代码获取城市列表", "tags": [ "Regions" ], "parameters": [ { "in": "path", "name": "provinceCode", "required": true, "schema": { "type": "string" }, "description": "省份代码" } ], "responses": { "200": { "description": "成功获取城市列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } } } }, "500": { "description": "服务器错误" } } } }, "/regions/districts/{cityCode}": { "get": { "summary": "根据城市代码获取区县列表", "tags": [ "Regions" ], "parameters": [ { "in": "path", "name": "cityCode", "required": true, "schema": { "type": "string" }, "description": "城市代码" } ], "responses": { "200": { "description": "成功获取区县列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } } } }, "500": { "description": "服务器错误" } } } }, "/regions/path/{regionCode}": { "get": { "summary": "根据区域代码获取完整路径（省-市-区）", "tags": [ "Regions" ], "parameters": [ { "in": "path", "name": "regionCode", "required": true, "schema": { "type": "string" }, "description": "区域代码" } ], "responses": { "200": { "description": "成功获取区域完整路径", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "province": { "$ref": "#/components/schemas/Region" }, "city": { "$ref": "#/components/schemas/Region" }, "district": { "$ref": "#/components/schemas/Region" } } } } } } } }, "404": { "description": "区域不存在" }, "500": { "description": "服务器错误" } } } }, "/risk-management/users": { "get": { "summary": "获取风险用户列表", "tags": [ "RiskManagement" ], "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": "is_blacklisted", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "是否被拉黑" }, { "in": "query", "name": "username", "schema": { "type": "string" }, "description": "用户名" } ], "responses": { "200": { "description": "成功获取风险用户列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "real_name": { "type": "string" }, "is_blacklisted": { "type": "boolean" }, "blacklist_reason": { "type": "string" }, "blacklisted_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "权限不足" }, "500": { "description": "服务器错误" } } } }, "/risk-management/blacklist/{userId}": { "post": { "summary": "拉黑用户", "tags": [ "RiskManagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "userId", "schema": { "type": "integer" }, "required": true, "description": "用户ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "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": "未授权" }, "403": { "description": "权限不足" }, "500": { "description": "服务器错误" } } } }, "/risk-management/unblacklist/{userId}": { "post": { "summary": "解除拉黑", "tags": [ "RiskManagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "userId", "schema": { "type": "integer" }, "required": true, "description": "用户ID" } ], "responses": { "200": { "description": "已解除拉黑", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "已解除拉黑" } } } } } }, "401": { "description": "未授权" }, "403": { "description": "权限不足" }, "500": { "description": "服务器错误" } } } }, "/risk-management/overdue-transfers": { "get": { "summary": "获取超时转账列表", "tags": [ "RiskManagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" } ], "responses": { "200": { "description": "成功获取超时转账列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "recipient_id": { "type": "integer" }, "amount": { "type": "number" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "recipient_name": { "type": "string" }, "overdue_hours": { "type": "number" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "权限不足" }, "500": { "description": "服务器错误" } } } }, "/api/sms/send": { "post": { "summary": "发送短信验证码", "tags": [ "SMS" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "手机号码" } } } } } }, "responses": { "200": { "description": "验证码发送成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "验证码发送成功" } } } } } }, "400": { "description": "参数错误或发送频率限制" }, "500": { "description": "服务器错误" } } } }, "/api/sms/verify": { "post": { "summary": "验证短信验证码", "tags": [ "SMS" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "code" ], "properties": { "phone": { "type": "string", "description": "手机号码" }, "code": { "type": "string", "description": "验证码" } } } } } }, "responses": { "200": { "description": "验证码验证成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "手机号验证成功" }, "data": { "type": "object", "properties": { "phone": { "type": "string" }, "verified": { "type": "boolean" } } } } } } } }, "400": { "description": "参数错误或验证码错误" }, "500": { "description": "服务器错误" } } } }, "/transfers": { "get": { "summary": "获取转账列表", "tags": [ "Transfers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string" }, "description": "转账状态过滤" }, { "in": "query", "name": "transfer_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": "search", "schema": { "type": "string" }, "description": "搜索关键词（用户名或真实姓名）" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" }, { "in": "query", "name": "sort", "schema": { "type": "string" }, "description": "排序字段" }, { "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "排序方向" } ], "responses": { "200": { "description": "成功获取转账列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/transfers/list": { "get": { "summary": "获取转账记录列表", "tags": [ "Transfers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string" }, "description": "转账状态过滤" }, { "in": "query", "name": "transfer_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": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" }, { "in": "query", "name": "sort", "schema": { "type": "string" }, "description": "排序字段" }, { "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "排序方向" } ], "responses": { "200": { "description": "成功获取转账记录列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/transfers/public-account": { "get": { "summary": "获取公户信息", "tags": [ "Transfers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功获取公户信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "公户ID" }, "username": { "type": "string", "description": "公户用户名", "example": "public_account" }, "real_name": { "type": "string", "description": "公户名称" }, "balance": { "type": "number", "format": "float", "description": "公户余额" } } } } } } } }, "401": { "description": "未授权" }, "404": { "description": "公户不存在" }, "500": { "description": "服务器错误" } } } }, "/transfers/create": { "post": { "summary": "创建转账记录", "tags": [ "Transfers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to_user_id", "amount", "transfer_type" ], "properties": { "to_user_id": { "type": "integer", "description": "接收方用户ID" }, "amount": { "type": "number", "format": "float", "description": "转账金额" }, "transfer_type": { "type": "string", "enum": [ "user_to_user", "user_to_system", "system_to_user" ], "description": "转账类型" }, "remark": { "type": "string", "description": "转账备注" } } } } } }, "responses": { "201": { "description": "转账记录创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "转账记录创建成功，等待确认" }, "data": { "type": "object", "properties": { "transfer_id": { "type": "integer", "description": "转账记录ID" } } } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/transfers/admin/create": { "post": { "summary": "管理员创建转账记录", "tags": [ "Transfers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_user_id", "to_user_id", "amount", "transfer_type" ], "properties": { "from_user_id": { "type": "integer", "description": "发送方用户ID" }, "to_user_id": { "type": "integer", "description": "接收方用户ID" }, "amount": { "type": "number", "format": "float", "description": "转账金额" }, "transfer_type": { "type": "string", "enum": [ "user_to_user", "user_to_system", "system_to_user" ], "description": "转账类型" }, "description": { "type": "string", "description": "转账描述" } } } } } }, "responses": { "201": { "description": "转账记录创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "转账记录创建成功" }, "data": { "type": "object", "properties": { "transfer_id": { "type": "integer", "description": "转账记录ID" } } } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "403": { "description": "权限不足" }, "500": { "description": "服务器错误" } } } }, "/upload/image": { "post": { "summary": "上传图片", "tags": [ "Upload" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的图片文件" }, "type": { "type": "string", "enum": [ "avatar", "product", "document" ], "default": "document", "description": "上传文件类型" } } } } } }, "responses": { "200": { "description": "图片上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "url": { "type": "string", "description": "上传后的文件URL" }, "filename": { "type": "string", "description": "上传后的文件名" } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/upload": { "post": { "summary": "多文件上传接口 (支持MediaUpload组件)", "tags": [ "Upload" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "要上传的文件列表" }, "type": { "type": "string", "enum": [ "avatar", "product", "document" ], "default": "document", "description": "上传文件类型" } } } } } }, "responses": { "200": { "description": "文件上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "文件上传成功" }, "data": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "originalname": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer" }, "path": { "type": "string" }, "url": { "type": "string" } } } } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/upload/single": { "post": { "summary": "单文件上传接口（兼容性接口）", "tags": [ "Upload" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件" }, "type": { "type": "string", "enum": [ "avatar", "product", "document" ], "default": "document", "description": "上传文件类型" } } } } } }, "responses": { "200": { "description": "文件上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "文件上传成功" }, "url": { "type": "string", "description": "上传后的文件URL" }, "filename": { "type": "string", "description": "上传后的文件名" }, "originalname": { "type": "string", "description": "原始文件名" }, "size": { "type": "integer", "description": "文件大小" } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/users": { "post": { "summary": "创建用户（管理员权限）", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password", "real_name", "id_card" ], "properties": { "username": { "type": "string" }, "password": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "admin", "merchant" ], "default": "user" }, "is_system_account": { "type": "boolean", "default": false }, "real_name": { "type": "string" }, "id_card": { "type": "string" }, "wechat_qr": { "type": "string" }, "alipay_qr": { "type": "string" }, "bank_card": { "type": "string" }, "unionpay_qr": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "201": { "description": "用户创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "403": { "description": "权限不足" }, "500": { "description": "服务器错误" } } } }, "/users/pending-audit": { "get": { "summary": "获取待审核用户列表（管理员权限）", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" } ], "responses": { "200": { "description": "成功获取待审核用户列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } } } } } } } } }, "401": { "description": "未授权" }, "403": { "description": "权限不足" }, "500": { "description": "服务器错误" } } } } }, "tags": [ { "name": "Authentication", "description": "用户认证API" }, { "name": "Captcha", "description": "验证码API" }, { "name": "Matching", "description": "匹配订单相关接口" }, { "name": "MatchingAdmin", "description": "匹配订单管理员相关接口" }, { "name": "Orders", "description": "订单管理相关接口" }, { "name": "Points", "description": "积分管理相关接口" }, { "name": "Products", "description": "商品管理API" }, { "name": "Regions", "description": "地区数据API" }, { "name": "RiskManagement", "description": "风险管理API" }, { "name": "SMS", "description": "短信验证码相关接口" }, { "name": "Upload", "description": "文件上传API" }, { "name": "Users", "description": "用户管理API" } ] }