cpzs-backend/VIP兑换记录查询API使用说明.md

# VIP兑换记录查询API使用说明

## 接口概述

本文档描述了VIP兑换记录查询相关的API接口，主要用于查询用户的VIP兑换记录信息。

## 接口列表

### 1. 获取用户所有兑换记录

**接口地址：** `GET /vip-exchange-record/user/{userId}`

**接口描述：** 根据用户ID获取该用户的所有VIP兑换记录

**请求参数：**
- `userId` (必填): 用户ID，路径参数，必须大于0

**请求示例：**
```http
GET /vip-exchange-record/user/123
```

**响应示例：**
```json
{
    "code": 0,
    "message": "success",
    "data": [
        {
            "id": 1,
            "userId": 123,
            "type": "月度会员",
            "exchangeMode": 1,
            "orderNo": 1234567890123456,
            "orderAmount": 0,
            "isUse": 1,
            "exchangeTime": "2024-01-15T10:30:00",
            "updateTime": "2024-01-15T10:30:00"
        },
        {
            "id": 2,
            "userId": 123,
            "type": "年度会员",
            "exchangeMode": 1,
            "orderNo": 1234567890123457,
            "orderAmount": 0,
            "isUse": 1,
            "exchangeTime": "2024-02-15T14:20:00",
            "updateTime": "2024-02-15T14:20:00"
        }
    ]
}
```

### 2. 分页获取用户兑换记录

**接口地址：** `GET /vip-exchange-record/user/{userId}/page`

**接口描述：** 根据用户ID分页获取该用户的VIP兑换记录

**请求参数：**
- `userId` (必填): 用户ID，路径参数，必须大于0
- `page` (可选): 页码，从1开始，默认为1
- `size` (可选): 每页大小，默认为10，最大100

**请求示例：**
```http
GET /vip-exchange-record/user/123/page?page=1&size=5
```

**响应示例：**
```json
{
    "code": 0,
    "message": "success",
    "data": [
        {
            "id": 1,
            "userId": 123,
            "type": "月度会员",
            "exchangeMode": 1,
            "orderNo": 1234567890123456,
            "orderAmount": 0,
            "isUse": 1,
            "exchangeTime": "2024-01-15T10:30:00",
            "updateTime": "2024-01-15T10:30:00"
        }
    ]
}
```

### 3. 获取兑换记录详情

**接口地址：** `GET /vip-exchange-record/{recordId}`

**接口描述：** 根据兑换记录ID获取详细信息

**请求参数：**
- `recordId` (必填): 兑换记录ID，路径参数，必须大于0

**请求示例：**
```http
GET /vip-exchange-record/1
```

**响应示例：**
```json
{
    "code": 0,
    "message": "success",
    "data": {
        "id": 1,
        "userId": 123,
        "type": "月度会员",
        "exchangeMode": 1,
        "orderNo": 1234567890123456,
        "orderAmount": 0,
        "isUse": 1,
        "exchangeTime": "2024-01-15T10:30:00",
        "updateTime": "2024-01-15T10:30:00"
    }
}
```

## 数据字段说明

### VipExchangeRecord 字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 兑换记录唯一标识符 |
| userId | Long | 用户ID |
| type | String | 会员类型（月度会员/年度会员） |
| exchangeMode | Integer | 兑换方式（1-VIP码兑换） |
| orderNo | Long | 订单编号（16位随机数字） |
| orderAmount | Integer | 订单金额（单位：分） |
| isUse | Integer | 是否已兑换（0-未兑换，1-已兑换） |
| exchangeTime | Date | 兑换时间 |
| updateTime | Date | 更新时间 |

## 响应状态码

| 状态码 | 说明 |
|--------|------|
| 0 | 成功 |
| 40000 | 请求参数错误 |
| 40400 | 请求数据不存在 |
| 50000 | 系统内部异常 |

## 错误响应示例

```json
{
    "code": 40000,
    "message": "用户ID不能为空且必须大于0",
    "data": null
}
```

## 使用说明

1. **数据排序**: 所有查询结果都按照兑换时间倒序排列（最新的记录在前）

2. **分页查询**: 
   - 页码从1开始
   - 每页大小限制在1-100之间
   - 超出范围会使用默认值

3. **参数校验**: 
   - 用户ID和记录ID必须为正整数
   - 参数错误会返回40000状态码

4. **异常处理**: 
   - 系统异常会返回50000状态码
   - 详细错误信息会在message字段中说明

## 注意事项

1. 接口支持Swagger文档，可通过 `/swagger-ui/index.html` 查看详细文档
2. 所有接口都有完整的日志记录，便于问题排查
3. 建议在生产环境中添加认证和权限控制
4. 分页查询采用内存分页，大数据量时建议使用数据库分页优化