# 兑换物品管理



本模块共 14 个接口。源文件：`api.json`。



## 快速索引



| 接口名称 | 方法 | 路径 | 用途 |
| --- | --- | --- | --- |
| 新增 | POST | `/gd_dataserver/gd_dataserver/business/exchange/item/add` | 新增单条记录，请求体为实体类对象（字段说明见对应实体模型）。成功返回 data 为 null。 |
| 批量新增 | POST | `/gd_dataserver/gd_dataserver/business/exchange/item/addBatch` | 批量新增多条记录，请求体为实体类数组。成功返回 data 为 null。 |
| 新增并返回保存的数据 | POST | `/gd_dataserver/gd_dataserver/business/exchange/item/addReturn` | 新增单条记录并返回保存后的数据（含自增ID），请求体为实体类对象。成功返回 data 为保存的实体对象。 |
| 根据属性删除 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/delete` | 根据实体属性条件删除记录，请求体为实体类对象。成功返回 data 为 null。 |
| 主键删除 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/deleteById` | 根据主键ID删除单条记录，成功返回 data 为 null。 |
| 批量删除 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/deleteByIds` | 根据ID列表批量删除记录，成功返回 data 为 null。 |
| 查询所有 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/getAll` | 查询所有记录（无分页、无条件）。成功返回 data 为实体类数组。 |
| 分页查询 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/getListByPage` | 分页查询记录列表，查询条件为实体类字段。成功返回 data 为 PageInfo 分页对象，其中 list 为实体类数组。 |
| 详情 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/info` | 根据主键ID查询单条记录详情。成功返回 data 为实体类对象，包含该实体所有字段。 |
| 条件查询 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/list` | 根据实体属性条件查询记录列表。成功返回 data 为实体类数组。 |
| 查询上架物品列表 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/listOnShelf` | 前端展示用，返回 status=1 的物品，按 sortOrder 降序。返回 data 为 ExchangeItem 数组，每个元素包含：id、itemName-物品名称、itemPrice-所需积分、itemImage-物品图片URL、description-描述、stock-库存。 |
| 逻辑删除 | GET | `/gd_dataserver/gd_dataserver/business/exchange/item/removeById` | 根据主键ID逻辑删除单条记录，成功返回 data 为 null。 |
| 修改 | POST | `/gd_dataserver/gd_dataserver/business/exchange/item/updateById` | 根据主键ID修改记录，请求体为实体类对象（需包含id字段）。成功返回 data 为 null。 |
| 上下架操作 | POST | `/gd_dataserver/gd_dataserver/business/exchange/item/updateStatus` | status=0 下架，status=1 上架。返回 data 为 boolean。 |


## 接口详情



### 新增

- **用途：** 新增单条记录，请求体为实体类对象（字段说明见对应实体模型）。成功返回 data 为 null。
- **请求：** `POST /gd_dataserver/gd_dataserver/business/exchange/item/add`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `addOneUsingPOST_4`

参数：

_无_

请求体：

- Content-Type：`application/json`
- 模型：`兑换物品`
- 必填：文档未标记

| 字段 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| createTime | 否 | string / date-time | 创建时间 | - |
| dailyLimitPerUser | 否 | integer / int32 | 每人每日兑换上限（0表示无限制） | - |
| description | 否 | string | 物品描述 | - |
| externalLink | 否 | string | 第三方兑换链接 | - |
| id | 否 | integer / int64 | 主键ID | - |
| itemCode | 否 | string | 物品编码 | - |
| itemName | 否 | string | 物品名称 | - |
| pointsRequired | 否 | integer / int32 | 所需积分 | - |
| sortOrder | 否 | integer / int32 | 排序权重 | - |
| status | 否 | integer / int32 | 状态：0-下架 1-上架 | - |
| stock | 否 | integer / int32 | 库存数量（0表示无限） | - |
| thirdPartyCode | 否 | string | 第三方平台物品编码 | - |
| updateTime | 否 | string / date-time | 更新时间 | - |


响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 批量新增

- **用途：** 批量新增多条记录，请求体为实体类数组。成功返回 data 为 null。
- **请求：** `POST /gd_dataserver/gd_dataserver/business/exchange/item/addBatch`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `addBatchUsingPOST_4`

参数：

_无_

请求体：

- Content-Type：`application/json`
- 模型：`array<兑换物品>`
- 必填：文档未标记

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 新增并返回保存的数据

- **用途：** 新增单条记录并返回保存后的数据（含自增ID），请求体为实体类对象。成功返回 data 为保存的实体对象。
- **请求：** `POST /gd_dataserver/gd_dataserver/business/exchange/item/addReturn`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `addReturnUsingPOST_4`

参数：

_无_

请求体：

- Content-Type：`application/json`
- 模型：`兑换物品`
- 必填：文档未标记

| 字段 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| createTime | 否 | string / date-time | 创建时间 | - |
| dailyLimitPerUser | 否 | integer / int32 | 每人每日兑换上限（0表示无限制） | - |
| description | 否 | string | 物品描述 | - |
| externalLink | 否 | string | 第三方兑换链接 | - |
| id | 否 | integer / int64 | 主键ID | - |
| itemCode | 否 | string | 物品编码 | - |
| itemName | 否 | string | 物品名称 | - |
| pointsRequired | 否 | integer / int32 | 所需积分 | - |
| sortOrder | 否 | integer / int32 | 排序权重 | - |
| status | 否 | integer / int32 | 状态：0-下架 1-上架 | - |
| stock | 否 | integer / int32 | 库存数量（0表示无限） | - |
| thirdPartyCode | 否 | string | 第三方平台物品编码 | - |
| updateTime | 否 | string / date-time | 更新时间 | - |


响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 根据属性删除

- **用途：** 根据实体属性条件删除记录，请求体为实体类对象。成功返回 data 为 null。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/delete`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `deleteUsingGET_4`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| createTime | query | 否 | string / date-time | 创建时间 | - |
| dailyLimitPerUser | query | 否 | integer / int32 | 每人每日兑换上限（0表示无限制） | - |
| description | query | 否 | string | 物品描述 | - |
| externalLink | query | 否 | string | 第三方兑换链接 | - |
| id | query | 否 | integer / int64 | 主键ID | - |
| itemCode | query | 否 | string | 物品编码 | - |
| itemName | query | 否 | string | 物品名称 | - |
| pointsRequired | query | 否 | integer / int32 | 所需积分 | - |
| sortOrder | query | 否 | integer / int32 | 排序权重 | - |
| status | query | 否 | integer / int32 | 状态：0-下架 1-上架 | - |
| stock | query | 否 | integer / int32 | 库存数量（0表示无限） | - |
| thirdPartyCode | query | 否 | string | 第三方平台物品编码 | - |
| updateTime | query | 否 | string / date-time | 更新时间 | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 主键删除

- **用途：** 根据主键ID删除单条记录，成功返回 data 为 null。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/deleteById`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `deleteOneUsingGET_4`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| id | query | 是 | string | 主键ID | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 批量删除

- **用途：** 根据ID列表批量删除记录，成功返回 data 为 null。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/deleteByIds`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `deleteListUsingGET_9`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| ids | query | 是 | string | ID列表(逗号分隔) | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 查询所有

- **用途：** 查询所有记录（无分页、无条件）。成功返回 data 为实体类数组。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/getAll`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `getAllUsingGET_4`

参数：

_无_

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 分页查询

- **用途：** 分页查询记录列表，查询条件为实体类字段。成功返回 data 为 PageInfo 分页对象，其中 list 为实体类数组。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/getListByPage`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `getListByPageUsingGET_4`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| createTime | query | 否 | string / date-time | 创建时间 | - |
| dailyLimitPerUser | query | 否 | integer / int32 | 每人每日兑换上限（0表示无限制） | - |
| description | query | 否 | string | 物品描述 | - |
| externalLink | query | 否 | string | 第三方兑换链接 | - |
| id | query | 否 | integer / int64 | 主键ID | - |
| itemCode | query | 否 | string | 物品编码 | - |
| itemName | query | 否 | string | 物品名称 | - |
| pageNum | query | 是 | integer / int32 | 页码 | - |
| pointsRequired | query | 否 | integer / int32 | 所需积分 | - |
| sortOrder | query | 否 | integer / int32 | 排序权重 | - |
| status | query | 否 | integer / int32 | 状态：0-下架 1-上架 | - |
| stock | query | 否 | integer / int32 | 库存数量（0表示无限） | - |
| thirdPartyCode | query | 否 | string | 第三方平台物品编码 | - |
| updateTime | query | 否 | string / date-time | 更新时间 | - |
| pageSize | query | 是 | integer / int32 | 每页条数 | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 详情

- **用途：** 根据主键ID查询单条记录详情。成功返回 data 为实体类对象，包含该实体所有字段。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/info`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `infoUsingGET_4`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| id | query | 是 | string | 主键ID | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 条件查询

- **用途：** 根据实体属性条件查询记录列表。成功返回 data 为实体类数组。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/list`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `getListUsingGET_4`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| createTime | query | 否 | string / date-time | 创建时间 | - |
| dailyLimitPerUser | query | 否 | integer / int32 | 每人每日兑换上限（0表示无限制） | - |
| description | query | 否 | string | 物品描述 | - |
| externalLink | query | 否 | string | 第三方兑换链接 | - |
| id | query | 否 | integer / int64 | 主键ID | - |
| itemCode | query | 否 | string | 物品编码 | - |
| itemName | query | 否 | string | 物品名称 | - |
| pointsRequired | query | 否 | integer / int32 | 所需积分 | - |
| sortOrder | query | 否 | integer / int32 | 排序权重 | - |
| status | query | 否 | integer / int32 | 状态：0-下架 1-上架 | - |
| stock | query | 否 | integer / int32 | 库存数量（0表示无限） | - |
| thirdPartyCode | query | 否 | string | 第三方平台物品编码 | - |
| updateTime | query | 否 | string / date-time | 更新时间 | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 查询上架物品列表

- **用途：** 前端展示用，返回 status=1 的物品，按 sortOrder 降序。返回 data 为 ExchangeItem 数组，每个元素包含：id、itemName-物品名称、itemPrice-所需积分、itemImage-物品图片URL、description-描述、stock-库存。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/listOnShelf`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `listOnShelfUsingGET`

参数：

_无_

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 逻辑删除

- **用途：** 根据主键ID逻辑删除单条记录，成功返回 data 为 null。
- **请求：** `GET /gd_dataserver/gd_dataserver/business/exchange/item/removeById`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `deleteListUsingGET_8`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| id | query | 是 | string | 主键ID | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 修改

- **用途：** 根据主键ID修改记录，请求体为实体类对象（需包含id字段）。成功返回 data 为 null。
- **请求：** `POST /gd_dataserver/gd_dataserver/business/exchange/item/updateById`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `updateByIdUsingPOST_4`

参数：

_无_

请求体：

- Content-Type：`application/json`
- 模型：`兑换物品`
- 必填：文档未标记

| 字段 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| createTime | 否 | string / date-time | 创建时间 | - |
| dailyLimitPerUser | 否 | integer / int32 | 每人每日兑换上限（0表示无限制） | - |
| description | 否 | string | 物品描述 | - |
| externalLink | 否 | string | 第三方兑换链接 | - |
| id | 否 | integer / int64 | 主键ID | - |
| itemCode | 否 | string | 物品编码 | - |
| itemName | 否 | string | 物品名称 | - |
| pointsRequired | 否 | integer / int32 | 所需积分 | - |
| sortOrder | 否 | integer / int32 | 排序权重 | - |
| status | 否 | integer / int32 | 状态：0-下架 1-上架 | - |
| stock | 否 | integer / int32 | 库存数量（0表示无限） | - |
| thirdPartyCode | 否 | string | 第三方平台物品编码 | - |
| updateTime | 否 | string / date-time | 更新时间 | - |


响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 上下架操作

- **用途：** status=0 下架，status=1 上架。返回 data 为 boolean。
- **请求：** `POST /gd_dataserver/gd_dataserver/business/exchange/item/updateStatus`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `updateStatusUsingPOST`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| itemId | query | 是 | integer / int64 | 物品ID | - |
| status | query | 是 | integer / int32 | 状态：0-下架 1-上架 | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: object<string, object> |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |