# 兑换码管理 API 文档

本文档描述了兑换码管理相关的接口规范。

## 1. 兑换码列表

*   **URL**: `/v2/redemption/code/list`
*   **Method**: `GET`
*   **描述**: 分页查询兑换码列表，支持按兑换码关键字和状态筛选。

### 请求参数

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `page` | integer | 否 | 页码，默认 1 |
| `size` | integer | 否 | 每页大小，默认 10 |
| `keyword` | string | 否 | 搜索关键字（模糊匹配兑换码） |
| `status` | integer | 否 | 状态 0:禁用 1:启用 |

### 响应参数 (`data` 字段)

返回 Mybatis-Plus `Page` 对象，包含 `records` (记录列表), `total` (总数), `size` (页大小), `current` (当前页) 等。

`records` 中的对象 (`RedemptionCodeVO`) 结构如下：

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `id` | long | 主键ID |
| `code` | string | 兑换码 |
| `points` | long | 积分 |
| `maxUsage` | long | 最大使用次数 |
| `usedCount` | long | 已使用次数 |
| `expireTime` | string | 失效日期 |
| `status` | integer | 状态 0:禁用 1:启用 |
| `createTime` | string | 创建时间 |

### 示例请求

查询全部兑换码：

```http
GET /v2/redemption/code/list?page=1&size=10
```

按关键字搜索：

```http
GET /v2/redemption/code/list?page=1&size=10&keyword=ABC
```

按状态筛选：

```http
GET /v2/redemption/code/list?page=1&size=10&status=1
```

### 示例响应

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "code": "ABC12345",
        "points": 100,
        "maxUsage": 10,
        "usedCount": 3,
        "expireTime": "2026-12-31 23:59:59",
        "status": 1,
        "createTime": "2026-01-01 00:00:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "timestamp": 1698372000000
}
```

---

## 2. 新增兑换码

*   **URL**: `/v2/redemption/code/add`
*   **Method**: `POST`
*   **描述**: 新增一个兑换码。

### 请求参数 (JSON Body)

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `code` | string | 是 | 兑换码（唯一） |
| `points` | long | 否 | 积分 |
| `maxUsage` | long | 否 | 最大使用次数 |
| `expireTime` | string | 否 | 失效日期 (yyyy-MM-dd HH:mm:ss) |
| `status` | integer | 否 | 状态 0:禁用 1:启用，默认 1 |

### 示例请求

```http
POST /v2/redemption/code/add
Content-Type: application/json

{
  "code": "NEWYEAR2026",
  "points": 500,
  "maxUsage": 100,
  "expireTime": "2026-12-31 23:59:59",
  "status": 1
}
```

### 示例响应

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": true,
  "timestamp": 1698372000000
}
```

---

## 3. 批量新增兑换码

*   **URL**: `/v2/redemption/code/addBatch`
*   **Method**: `POST`
*   **描述**: 批量新增兑换码。

### 请求参数 (JSON Body)

传入 `TRedemptionCode` 对象数组，每个对象字段同"新增兑换码"接口：

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `code` | string | 是 | 兑换码（唯一） |
| `points` | long | 否 | 积分 |
| `maxUsage` | long | 否 | 最大使用次数 |
| `expireTime` | string | 否 | 失效日期 (yyyy-MM-dd HH:mm:ss) |
| `status` | integer | 否 | 状态 0:禁用 1:启用，默认 1 |

### 示例请求

```http
POST /v2/redemption/code/addBatch
Content-Type: application/json

[
  {
    "code": "BATCH001",
    "points": 100,
    "maxUsage": 50,
    "expireTime": "2026-12-31 23:59:59",
    "status": 1
  },
  {
    "code": "BATCH002",
    "points": 200,
    "maxUsage": 30,
    "expireTime": "2026-06-30 23:59:59",
    "status": 1
  }
]
```

### 示例响应

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": true,
  "timestamp": 1698372000000
}
```

---

## 4. 更新兑换码

*   **URL**: `/v2/redemption/code/update`
*   **Method**: `PUT`
*   **描述**: 根据 ID 更新兑换码信息。

### 请求参数 (JSON Body)

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `id` | long | 是 | 主键ID |
| `code` | string | 否 | 兑换码 |
| `points` | long | 否 | 积分 |
| `maxUsage` | long | 否 | 最大使用次数 |
| `expireTime` | string | 否 | 失效日期 (yyyy-MM-dd HH:mm:ss) |
| `status` | integer | 否 | 状态 0:禁用 1:启用 |

### 示例请求

```http
PUT /v2/redemption/code/update
Content-Type: application/json

{
  "id": 1,
  "points": 1000,
  "status": 0
}
```

### 示例响应

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": true,
  "timestamp": 1698372000000
}
```

---

## 5. 删除兑换码

*   **URL**: `/v2/redemption/code/delete`
*   **Method**: `DELETE`
*   **描述**: 根据 ID 批量删除兑换码。

### 请求参数 (JSON Body)

传入 ID 数组：

```json
[1, 2, 3]
```

### 示例请求

```http
DELETE /v2/redemption/code/delete
Content-Type: application/json

[1, 2, 3]
```

### 示例响应

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": true,
  "timestamp": 1698372000000
}
```