{ "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": { "Announcement": { "type": "object", "required": [ "title", "content", "type", "priority" ], "properties": { "id": { "type": "integer", "description": "公告ID", "example": 1 }, "title": { "type": "string", "description": "公告标题", "example": "系统维护通知" }, "content": { "type": "string", "description": "公告内容", "example": "系统将于今晚进行维护，预计维护时间2小时，期间可能影响部分功能使用。" }, "type": { "type": "string", "description": "公告类型", "enum": [ "system", "maintenance", "promotion", "warning" ], "example": "maintenance" }, "priority": { "type": "string", "description": "优先级", "enum": [ "low", "medium", "high", "urgent" ], "example": "high" }, "status": { "type": "string", "description": "状态", "enum": [ "draft", "published", "archived" ], "example": "published" }, "isTop": { "type": "boolean", "description": "是否置顶", "example": false }, "publishTime": { "type": "string", "format": "date-time", "description": "发布时间", "example": "2024-01-15T10:00:00Z" }, "expireTime": { "type": "string", "format": "date-time", "description": "过期时间", "example": "2024-01-20T10:00:00Z" }, "createdBy": { "type": "integer", "description": "创建者用户ID", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "description": "创建时间", "example": "2024-01-15T09:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "更新时间", "example": "2024-01-15T09:30:00Z" }, "creator": { "type": "object", "description": "创建者信息", "properties": { "id": { "type": "integer", "example": 1 }, "username": { "type": "string", "example": "admin" }, "email": { "type": "string", "example": "admin@example.com" } } }, "is_pinned": { "type": "boolean", "description": "是否置顶" }, "publish_time": { "type": "string", "format": "date-time", "description": "发布时间" }, "expire_time": { "type": "string", "format": "date-time", "description": "过期时间" }, "created_by": { "type": "integer", "description": "创建者ID" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } }, "AnnouncementCreate": { "type": "object", "required": [ "title", "content", "type", "priority" ], "properties": { "title": { "type": "string", "description": "公告标题", "example": "系统维护通知" }, "content": { "type": "string", "description": "公告内容", "example": "系统将于今晚进行维护，预计维护时间2小时。" }, "type": { "type": "string", "description": "公告类型", "enum": [ "system", "activity", "maintenance", "urgent" ], "example": "maintenance" }, "priority": { "type": "string", "description": "优先级", "enum": [ "high", "medium", "low" ], "example": "high" }, "status": { "type": "string", "description": "公告状态", "enum": [ "draft", "published" ], "default": "draft", "example": "draft" }, "isTop": { "type": "boolean", "description": "是否置顶", "default": false, "example": false }, "publishTime": { "type": "string", "format": "date-time", "description": "发布时间", "example": "2024-01-15T10:00:00Z" }, "expireTime": { "type": "string", "format": "date-time", "description": "过期时间", "example": "2024-01-20T10:00:00Z" } } }, "AnnouncementUpdate": { "type": "object", "properties": { "title": { "type": "string", "description": "公告标题", "example": "系统维护通知（更新）" }, "content": { "type": "string", "description": "公告内容", "example": "系统维护时间调整为明晚进行。" }, "type": { "type": "string", "description": "公告类型", "enum": [ "system", "activity", "maintenance", "urgent" ], "example": "maintenance" }, "priority": { "type": "string", "description": "优先级", "enum": [ "high", "medium", "low" ], "example": "medium" }, "status": { "type": "string", "description": "公告状态", "enum": [ "draft", "published", "expired" ], "example": "published" }, "isTop": { "type": "boolean", "description": "是否置顶", "example": true }, "publishTime": { "type": "string", "format": "date-time", "description": "发布时间", "example": "2024-01-16T10:00:00Z" }, "expireTime": { "type": "string", "format": "date-time", "description": "过期时间", "example": "2024-01-21T10:00:00Z" } } }, "AnnouncementList": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "announcements": { "type": "array", "items": { "$ref": "#/components/schemas/Announcement" } }, "total": { "type": "integer", "description": "总记录数", "example": 50 }, "page": { "type": "integer", "description": "当前页码", "example": 1 }, "limit": { "type": "integer", "description": "每页数量", "example": 10 }, "totalPages": { "type": "integer", "description": "总页数", "example": 5 } } } } }, "AnnouncementResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "操作成功" }, "data": { "$ref": "#/components/schemas/Announcement" } } }, "AnnouncementError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "操作失败" }, "error": { "type": "string", "example": "公告不存在" } } }, "CartItem": { "type": "object", "required": [ "user_id", "product_id", "quantity" ], "properties": { "id": { "type": "integer", "description": "购物车项ID" }, "user_id": { "type": "integer", "description": "用户ID" }, "product_id": { "type": "integer", "description": "商品ID" }, "quantity": { "type": "integer", "description": "商品数量" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" }, "spec_combination_id": { "type": "integer", "description": "商品规格组合ID" }, "product": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "price": { "type": "integer" }, "points_price": { "type": "integer" }, "rongdou_price": { "type": "integer" }, "image_url": { "type": "string" }, "stock": { "type": "integer" }, "status": { "type": "string" } } } } }, "CartItemWithProduct": { "type": "object", "properties": { "id": { "type": "integer", "description": "购物车商品ID" }, "product_id": { "type": "integer", "description": "商品ID" }, "product_name": { "type": "string", "description": "商品名称" }, "quantity": { "type": "integer", "description": "商品数量" }, "points_price": { "type": "integer", "description": "积分价格" }, "rongdou_price": { "type": "number", "description": "融豆价格" }, "image_url": { "type": "string", "description": "商品图片URL" }, "stock": { "type": "integer", "description": "库存数量" }, "payment_methods": { "type": "array", "items": { "type": "string" }, "description": "支付方式列表" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" } } }, "AddToCartRequest": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "integer", "description": "商品ID" }, "quantity": { "type": "integer", "minimum": 1, "description": "商品数量" } } }, "UpdateCartRequest": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "description": "商品数量" } } }, "Order": { "type": "object", "required": [ "user_id", "total_amount", "status" ], "properties": { "id": { "type": "integer", "description": "订单ID" }, "order_number": { "type": "string", "description": "订单号" }, "user_id": { "type": "integer", "description": "用户ID" }, "total_amount": { "type": "number", "description": "订单总金额" }, "total_points": { "type": "integer", "description": "订单总积分" }, "total_rongdou": { "type": "number", "description": "订单总融豆" }, "status": { "type": "string", "description": "订单状态", "enum": [ "pending", "confirmed", "shipped", "delivered", "cancelled" ] }, "payment_status": { "type": "string", "description": "支付状态", "enum": [ "pending", "paid", "failed", "refunded" ] }, "shipping_address": { "type": "string", "description": "收货地址" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } }, "OrderItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "订单商品ID" }, "order_id": { "type": "integer", "description": "订单ID" }, "product_id": { "type": "integer", "description": "商品ID" }, "quantity": { "type": "integer", "description": "商品数量" }, "price": { "type": "number", "description": "商品价格" }, "points_price": { "type": "integer", "description": "积分价格" }, "rongdou_price": { "type": "number", "description": "融豆价格" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" } } }, "PreOrder": { "type": "object", "properties": { "preOrderId": { "type": "integer", "description": "预订单ID" }, "orderNumber": { "type": "string", "description": "订单号" }, "totalAmount": { "type": "number", "description": "总金额" }, "totalPoints": { "type": "integer", "description": "所需积分总数" }, "totalRongdou": { "type": "number", "description": "所需融豆总数" }, "paymentMethods": { "type": "array", "items": { "type": "string" }, "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": "积分价格" }, "rongdou_price": { "type": "number", "description": "融豆价格" }, "stock": { "type": "integer", "description": "库存数量" }, "image_url": { "type": "string", "description": "商品图片URL" }, "description": { "type": "string", "description": "商品描述" }, "status": { "type": "string", "description": "商品状态", "enum": [ "active", "inactive" ] }, "payment_methods": { "type": "array", "items": { "type": "string" }, "description": "支付方式列表" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } } }, "User": { "type": "object", "required": [ "username", "password", "real_name", "id_card" ], "properties": { "id": { "type": "integer", "description": "用户ID" }, "username": { "type": "string", "description": "用户名" }, "email": { "type": "string", "format": "email", "description": "邮箱地址" }, "phone": { "type": "string", "description": "手机号" }, "points": { "type": "integer", "description": "用户积分" }, "rongdou": { "type": "number", "description": "融豆余额" }, "avatar": { "type": "string", "description": "用户头像URL" }, "status": { "type": "string", "description": "用户状态", "enum": [ "active", "inactive", "banned" ] }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" }, "role": { "type": "string", "description": "用户角色", "enum": [ "user", "admin", "merchant" ] }, "real_name": { "type": "string", "description": "真实姓名" }, "id_card": { "type": "string", "description": "身份证号" }, "is_system_account": { "type": "boolean", "description": "是否为系统账户" }, "is_distribute": { "type": "boolean", "description": "是否为分发账户" } } }, "UserProfile": { "type": "object", "properties": { "id": { "type": "integer", "description": "用户ID" }, "username": { "type": "string", "description": "用户名" }, "email": { "type": "string", "description": "邮箱地址" }, "phone": { "type": "string", "description": "手机号码" }, "points": { "type": "integer", "description": "积分余额" }, "rongdou": { "type": "number", "description": "融豆余额" }, "avatar": { "type": "string", "description": "头像URL" } } }, "LoginRequest": { "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": "用户名" }, "email": { "type": "string", "format": "email", "description": "邮箱地址" }, "password": { "type": "string", "description": "密码" }, "phone": { "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" } } }, "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": "密码" } } }, "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": "发送方用户余额" } } }, "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": "创建时间" } } }, "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": "验证码" } } }, "SpecName": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "规格名称（如：颜色、尺寸）" }, "display_name": { "type": "string", "description": "显示名称" }, "sort_order": { "type": "integer", "description": "排序" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } }, "SpecValue": { "type": "object", "properties": { "id": { "type": "integer" }, "spec_name_id": { "type": "integer" }, "value": { "type": "string", "description": "规格值（如：红色、XL）" }, "display_value": { "type": "string" }, "color_code": { "type": "string", "description": "颜色代码" }, "image_url": { "type": "string" }, "sort_order": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } }, "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": "总页数" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/announcements/{id}": { "get": { "summary": "获取单个公告详情", "tags": [ "Announcements" ], "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/Announcement" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "公告不存在" }, "500": { "description": "服务器错误" } } }, "put": { "summary": "更新通知公告", "tags": [ "Announcements" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "公告ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "公告标题" }, "content": { "type": "string", "description": "公告内容" }, "type": { "type": "string", "enum": [ "system", "activity", "maintenance", "urgent" ], "description": "公告类型" }, "priority": { "type": "string", "enum": [ "high", "medium", "low", "urgent" ], "description": "优先级" }, "status": { "type": "string", "enum": [ "draft", "published", "expired" ], "description": "状态" }, "is_pinned": { "type": "boolean" }, "publish_time": { "type": "string", "format": "date-time" }, "expire_time": { "type": "string", "format": "date-time" }, "isTop": { "type": "boolean", "description": "是否置顶" }, "publishTime": { "type": "string", "format": "date-time", "description": "发布时间" }, "expireTime": { "type": "string", "format": "date-time", "description": "过期时间" } } } } } }, "responses": { "200": { "description": "公告更新成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "公告更新成功" }, "data": { "$ref": "#/components/schemas/Announcement" } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "404": { "description": "公告不存在" }, "500": { "description": "服务器错误" } } }, "delete": { "summary": "删除通知公告", "tags": [ "Announcements" ], "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": "服务器错误" } } } }, "/api/announcements/{id}/read": { "post": { "summary": "标记公告为已读", "tags": [ "Announcements" ], "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": "服务器错误" } } } }, "/api/announcements/unread/count": { "get": { "summary": "获取用户未读公告数量", "tags": [ "Announcements" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "获取未读数量成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "unread_count": { "type": "integer", "example": 5, "description": "未读公告数量" } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/announcements/batch/read": { "post": { "summary": "批量标记公告为已读", "tags": [ "Announcements" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "announcement_ids" ], "properties": { "announcement_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ], "description": "公告ID列表" } } } } } }, "responses": { "200": { "description": "批量标记已读成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "批量标记已读成功" } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/announcements": { "post": { "summary": "创建新的通知公告", "tags": [ "Announcements" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "content", "type", "priority" ], "properties": { "title": { "type": "string", "description": "公告标题", "example": "系统维护通知" }, "content": { "type": "string", "description": "公告内容", "example": "系统将于今晚进行维护，预计维护时间2小时" }, "type": { "type": "string", "enum": [ "system", "activity", "maintenance", "urgent" ], "default": "system", "description": "公告类型", "example": "maintenance" }, "priority": { "type": "string", "enum": [ "high", "medium", "low", "urgent" ], "default": "medium", "description": "优先级", "example": "high" }, "status": { "type": "string", "enum": [ "draft", "published" ], "default": "draft", "description": "状态" }, "is_pinned": { "type": "boolean", "default": false }, "publish_time": { "type": "string", "format": "date-time" }, "expire_time": { "type": "string", "format": "date-time" }, "isTop": { "type": "boolean", "default": false, "description": "是否置顶" }, "publishTime": { "type": "string", "format": "date-time", "description": "发布时间" }, "expireTime": { "type": "string", "format": "date-time", "description": "过期时间" } } } } } }, "responses": { "201": { "description": "公告创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "公告创建成功" }, "data": { "type": "object", "properties": { "id": { "type": "integer" } }, "$ref": "#/components/schemas/Announcement" } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } }, "get": { "summary": "获取通知公告列表", "tags": [ "Announcements" ], "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": "type", "schema": { "type": "string", "enum": [ "system", "activity", "maintenance", "urgent" ] }, "description": "公告类型" }, { "in": "query", "name": "priority", "schema": { "type": "string", "enum": [ "high", "medium", "low" ] }, "description": "优先级" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "draft", "published", "expired" ] }, "description": "状态" }, { "in": "query", "name": "isTop", "schema": { "type": "boolean" }, "description": "是否置顶" }, { "in": "query", "name": "sortBy", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "publish_time", "priority" ], "default": "created_at" }, "description": "排序字段" }, { "in": "query", "name": "sortOrder", "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": { "announcements": { "type": "array", "items": { "$ref": "#/components/schemas/Announcement" } }, "total": { "type": "integer", "example": 50 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 10 }, "totalPages": { "type": "integer", "example": 5 } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/announcements/public/list": { "get": { "summary": "获取公开发布的公告列表（无需认证）", "tags": [ "Announcements" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 5 }, "description": "获取数量" } ], "responses": { "200": { "description": "成功获取公开公告列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Announcement" } } } } } } }, "500": { "description": "服务器错误" } } } }, "/api/announcements/{id}/toggle-top": { "put": { "summary": "切换公告置顶状态", "tags": [ "Announcements" ], "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": "置顶状态更新成功" }, "data": { "type": "object", "properties": { "isTop": { "type": "boolean", "example": true } } } } } } } }, "401": { "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" }, "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": "服务器错误" } } } }, "/api/orders/confirm": { "post": { "summary": "确认下单", "tags": [ "Orders" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pre_order_id", "address" ], "properties": { "pre_order_id": { "type": "integer", "description": "预订单ID" }, "address": { "type": "object", "properties": { "recipient_name": { "type": "string", "description": "收货人姓名" }, "phone": { "type": "string", "description": "收货人电话" }, "province": { "type": "string", "description": "省份" }, "city": { "type": "string", "description": "城市" }, "district": { "type": "string", "description": "区县" }, "detail_address": { "type": "string", "description": "详细地址" } } } } } } } }, "responses": { "200": { "description": "确认下单成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "order_id": { "type": "integer" }, "order_no": { "type": "string" } } } } } } } }, "400": { "description": "请求参数错误" }, "401": { "description": "未授权" }, "404": { "description": "预订单不存在" }, "500": { "description": "服务器错误" } } } }, "/api/orders/pre-order/{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": { "id": { "type": "integer" }, "order_no": { "type": "string" }, "total_amount": { "type": "integer" }, "total_points": { "type": "integer" }, "total_rongdou": { "type": "integer" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "integer" }, "points_price": { "type": "integer" }, "rongdou_price": { "type": "integer" }, "spec_info": { "type": "object" } } } } } } } } } } }, "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": "服务器错误" } } } }, "/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": "array", "items": { "type": "string" } } } } } } } } } }, "/products/hot": { "get": { "summary": "获取热门商品", "tags": [ "Products" ], "parameters": [ { "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": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } } } } } } }, "/products/{id}": { "get": { "summary": "获取单个商品详情（包含增强规格信息）", "tags": [ "Products" ], "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/Product", "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string" }, "price": { "type": "number" }, "points_price": { "type": "number" }, "rongdou_price": { "type": "number" }, "stock": { "type": "integer" }, "specifications": { "type": "array", "description": "商品规格组合列表（笛卡尔积规格系统）", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "规格组合ID" }, "combination_key": { "type": "string", "description": "规格组合键（如：1-3-5）" }, "spec_display": { "type": "string", "description": "规格显示文本（如：颜色:红色 | 尺寸:XL）" }, "spec_details": { "type": "array", "description": "规格详细信息", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "spec_name": { "type": "string", "description": "规格名称" }, "spec_display_name": { "type": "string", "description": "规格显示名称" }, "value": { "type": "string", "description": "规格值" }, "display_value": { "type": "string", "description": "规格显示值" }, "color_code": { "type": "string", "description": "颜色代码" }, "image_url": { "type": "string", "description": "规格图片" } } } }, "price_adjustment": { "type": "number", "description": "价格调整" }, "points_adjustment": { "type": "number", "description": "积分调整" }, "rongdou_adjustment": { "type": "number", "description": "融豆调整" }, "stock": { "type": "integer", "description": "规格库存" }, "sku_code": { "type": "string", "description": "SKU编码" }, "barcode": { "type": "string", "description": "条形码" }, "weight": { "type": "number", "description": "重量" }, "volume": { "type": "number", "description": "体积" }, "actual_price": { "type": "number", "description": "实际价格（基础价格+调整）" }, "actual_points_price": { "type": "number", "description": "实际积分价格" }, "actual_rongdou_price": { "type": "number", "description": "实际融豆价格" }, "is_available": { "type": "boolean", "description": "是否有库存" } } } }, "specification_count": { "type": "integer", "description": "规格总数" }, "available_specifications": { "type": "integer", "description": "有库存的规格数量" }, "attributes": { "type": "array", "description": "商品属性" }, "isFavorited": { "type": "boolean", "description": "是否已收藏" } } } } } } } } } }, "404": { "description": "商品不存在" } } } }, "/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/cart": { "get": { "summary": "获取购物车列表", "tags": [ "Cart" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "获取购物车成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "total_count": { "type": "integer", "description": "购物车商品总数量" }, "total_amount": { "type": "integer", "description": "购物车总金额" }, "total_points": { "type": "integer", "description": "购物车总积分" }, "total_rongdou": { "type": "integer", "description": "购物车总融豆" } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } }, "post": { "summary": "添加商品到购物车", "tags": [ "Cart" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "商品ID" }, "quantity": { "type": "integer", "description": "商品数量", "minimum": 1 }, "spec_combination_id": { "type": "integer", "description": "商品规格组合ID（可选）" } }, "required": [ "product_id", "quantity" ] } } } }, "responses": { "201": { "description": "添加到购物车成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "cart_item_id": { "type": "integer" } } } } } } } }, "400": { "description": "参数错误或库存不足" }, "401": { "description": "未授权" }, "404": { "description": "商品不存在或已下架" }, "500": { "description": "服务器错误" } } } }, "/api/cart/{id}": { "put": { "summary": "更新购物车商品数量", "tags": [ "Cart" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "购物车项ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "新的商品数量", "minimum": 1 } }, "required": [ "quantity" ] } } } }, "responses": { "200": { "description": "更新购物车成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "参数错误或库存不足" }, "401": { "description": "未授权" }, "404": { "description": "购物车项不存在" }, "500": { "description": "服务器错误" } } }, "delete": { "summary": "删除购物车商品", "tags": [ "Cart" ], "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" } } } } } }, "401": { "description": "未授权" }, "404": { "description": "购物车项不存在" }, "500": { "description": "服务器错误" } } } }, "/api/cart/batch": { "delete": { "summary": "批量删除购物车商品", "tags": [ "Cart" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cart_item_ids": { "type": "array", "items": { "type": "integer" }, "description": "购物车项ID数组" } }, "required": [ "cart_item_ids" ] } } } }, "responses": { "200": { "description": "批量删除购物车商品成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "deleted_count": { "type": "integer", "description": "删除的商品数量" } } } } } } } }, "400": { "description": "参数错误" }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/cart/clear": { "delete": { "summary": "清空购物车", "tags": [ "Cart" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "清空购物车成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/cart/count": { "get": { "summary": "获取购物车商品数量", "tags": [ "Cart" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "获取购物车商品数量成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "count": { "type": "integer", "description": "购物车商品总数量" } } } } } } } }, "401": { "description": "未授权" }, "500": { "description": "服务器错误" } } } }, "/api/cart/checkout": { "post": { "summary": "购物车结账", "tags": [ "Cart" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cart_item_ids": { "type": "array", "items": { "type": "integer" }, "description": "要结账的购物车项ID数组" }, "shipping_address": { "type": "string", "description": "收货地址" } }, "required": [ "cart_item_ids", "shipping_address" ] } } } }, "responses": { "201": { "description": "结账成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "order_id": { "type": "integer" }, "order_no": { "type": "string" }, "total_amount": { "type": "integer" }, "total_points": { "type": "integer" }, "total_rongdou": { "type": "integer" } } } } } } } }, "400": { "description": "参数错误或库存不足" }, "401": { "description": "未授权" }, "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/{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/pending-payment/{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": { "id": { "type": "integer" }, "order_no": { "type": "string" }, "total_amount": { "type": "integer" }, "total_points": { "type": "integer" }, "total_rongdou": { "type": "integer" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "integer" }, "points_price": { "type": "integer" }, "rongdou_price": { "type": "integer" }, "spec_info": { "type": "object" } } } } } } } } } } }, "401": { "description": "未授权" }, "404": { "description": "预订单不存在" }, "500": { "description": "服务器错误" } } } }, "/api/orders/confirm-payment": { "post": { "summary": "确认支付订单", "description": "根据商品支付方式确认订单支付：\n- 仅积分支付：按10000积分=1融豆的比例扣除积分\n- 仅融豆支付：直接扣除融豆\n- 组合支付：优先扣除积分（按10000:1转换），不足部分扣除融豆\n", "tags": [ "Orders" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order_id", "address_id" ], "properties": { "order_id": { "type": "integer", "description": "订单ID", "example": 123 }, "address_id": { "type": "integer", "description": "收货地址ID", "example": 456 } } } } } }, "responses": { "200": { "description": "确认支付成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "订单支付成功" }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 123 }, "order_no": { "type": "string", "example": "ORD20240101123456" } } } } } } } }, "400": { "description": "请求参数错误或余额不足", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "enum": [ "订单ID和收货地址ID为必填项", "积分不足", "融豆不足", "积分和融豆余额不足", "商品支付方式配置错误" ] } } } } } }, "401": { "description": "未授权" }, "404": { "description": "订单或地址不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "enum": [ "订单不存在或已处理", "收货地址不存在", "用户不存在" ] } } } } } }, "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/flash-sale": { "get": { "summary": "获取秒杀商品", "tags": [ "Products" ], "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" } } } } } } } } } } } }, "/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": "服务器错误" } } } }, "/specifications/names": { "get": { "summary": "获取所有规格名称", "tags": [ "Specifications" ], "parameters": [ { "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": "array", "items": { "$ref": "#/components/schemas/SpecName" } } } } } } } } }, "post": { "summary": "创建规格名称", "tags": [ "Specifications" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "display_name" ], "properties": { "name": { "type": "string", "description": "规格名称" }, "display_name": { "type": "string", "description": "显示名称" }, "sort_order": { "type": "integer", "default": 0 } } } } } }, "responses": { "201": { "description": "规格名称创建成功" } } } }, "/specifications/names/{id}": { "delete": { "summary": "删除规格名称", "tags": [ "Specifications" ], "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", "example": "规格名称删除成功" } } } } } }, "400": { "description": "该规格名称下还有规格值，无法删除" }, "404": { "description": "规格名称不存在" }, "500": { "description": "服务器错误" } } } }, "/specifications/values": { "get": { "summary": "获取规格值列表", "tags": [ "Specifications" ], "parameters": [ { "in": "query", "name": "spec_name_id", "schema": { "type": "integer" }, "description": "规格名称ID" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "description": "状态筛选" } ], "responses": { "200": { "description": "成功获取规格值列表" } } }, "post": { "summary": "创建规格值", "tags": [ "Specifications" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "spec_name_id", "value", "display_value" ], "properties": { "spec_name_id": { "type": "integer" }, "value": { "type": "string" }, "display_value": { "type": "string" }, "color_code": { "type": "string" }, "image_url": { "type": "string" }, "sort_order": { "type": "integer", "default": 0 } } } } } }, "responses": { "201": { "description": "规格值创建成功" } } } }, "/specifications/combinations/{productId}": { "get": { "summary": "获取商品的规格组合", "tags": [ "Specifications" ], "parameters": [ { "in": "path", "name": "productId", "required": true, "schema": { "type": "integer" }, "description": "商品ID" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "description": "状态筛选" } ], "responses": { "200": { "description": "成功获取规格组合" } } } }, "/specifications/combinations/{id}": { "get": { "summary": "获取单个规格组合详情", "tags": [ "Specifications" ], "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": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "combination_key": { "type": "string" }, "spec_values": { "type": "array", "items": { "type": "integer" } }, "price_adjustment": { "type": "integer" }, "points_adjustment": { "type": "integer" }, "rongdou_adjustment": { "type": "integer" }, "stock": { "type": "integer" }, "sku_code": { "type": "string" }, "barcode": { "type": "string" }, "weight": { "type": "number" }, "volume": { "type": "number" }, "status": { "type": "string" }, "spec_details": { "type": "array", "items": { "type": "object" } }, "actual_price": { "type": "number" }, "actual_points_price": { "type": "number" }, "actual_rongdou_price": { "type": "number" }, "is_available": { "type": "boolean" } } } } } } } }, "404": { "description": "规格组合不存在" }, "500": { "description": "服务器错误" } } }, "delete": { "summary": "删除规格组合", "tags": [ "Specifications" ], "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", "example": "规格组合删除成功" } } } } } }, "404": { "description": "规格组合不存在" }, "500": { "description": "服务器错误" } } }, "put": { "summary": "更新规格组合", "tags": [ "Specifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "规格组合ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price_adjustment": { "type": "integer" }, "points_adjustment": { "type": "integer" }, "rongdou_adjustment": { "type": "integer" }, "stock": { "type": "integer" }, "sku_code": { "type": "string" }, "barcode": { "type": "string" }, "weight": { "type": "number" }, "volume": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } } } } }, "responses": { "200": { "description": "规格组合更新成功" }, "404": { "description": "规格组合不存在" } } } }, "/specifications/combinations": { "post": { "summary": "创建商品规格组合", "tags": [ "Specifications" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id", "spec_values" ], "properties": { "product_id": { "type": "integer" }, "spec_values": { "type": "array", "items": { "type": "integer" }, "description": "规格值ID数组" }, "price_adjustment": { "type": "integer", "default": 0 }, "points_adjustment": { "type": "integer", "default": 0 }, "rongdou_adjustment": { "type": "integer", "default": 0 }, "stock": { "type": "integer", "default": 0 }, "sku_code": { "type": "string" }, "barcode": { "type": "string" }, "weight": { "type": "number" }, "volume": { "type": "number" } } } } } }, "responses": { "201": { "description": "规格组合创建成功" } } } }, "/specifications/generate-combinations": { "post": { "summary": "为商品生成笛卡尔积规格组合", "tags": [ "Specifications" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id", "spec_name_ids" ], "properties": { "product_id": { "type": "integer" }, "spec_name_ids": { "type": "array", "items": { "type": "integer" }, "description": "规格名称ID数组" }, "default_stock": { "type": "integer", "default": 0, "description": "默认库存" } } } } } }, "responses": { "201": { "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": "服务器错误" } } } }, "/api/users/{id}/distribute": { "put": { "summary": "设置用户分发状态", "description": "更新指定用户的分发状态", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "用户ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_distribute" ], "properties": { "is_distribute": { "type": "boolean", "description": "分发状态，true为启用分发，false为禁用分发", "example": true } } } } } }, "responses": { "200": { "description": "分发状态更新成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "分发状态更新成功" }, "is_distribute": { "type": "boolean", "description": "更新后的分发状态", "example": true } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "分发状态无效" } } } } } }, "404": { "description": "用户不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "用户不存在" } } } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "服务器内部错误" } } } } } } } } } }, "tags": [ { "name": "Announcements", "description": "通知公告管理API" }, { "name": "Orders", "description": "订单管理API" }, { "name": "Products", "description": "商品管理API" }, { "name": "Authentication", "description": "用户认证API" }, { "name": "Captcha", "description": "验证码API" }, { "name": "Cart", "description": "购物车管理相关接口" }, { "name": "Matching", "description": "匹配订单相关接口" }, { "name": "MatchingAdmin", "description": "匹配订单管理员相关接口" }, { "name": "Points", "description": "积分管理相关接口" }, { "name": "Regions", "description": "地区数据API" }, { "name": "RiskManagement", "description": "风险管理API" }, { "name": "SMS", "description": "短信验证码相关接口" }, { "name": "Upload", "description": "文件上传API" }, { "name": "Users", "description": "用户管理API" } ] }