aitori-bi-v2/doc/REDEMPTION_CODE_API.md

兑换码管理 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	创建时间

示例请求

查询全部兑换码：

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

按关键字搜索：

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

按状态筛选：

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

示例响应

{
  "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

示例请求

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

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

示例响应

{
  "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

示例请求

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
  }
]

示例响应

{
  "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:启用

示例请求

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

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

示例响应

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

---

5. 删除兑换码

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

请求参数 (JSON Body)

传入 ID 数组：

[1, 2, 3]

示例请求

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

[1, 2, 3]

示例响应

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