zhongyouweb/docs/api/modules/11-exchange-config.md

兑换安全配置

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

快速索引

接口名称	方法	路径	用途
获取当前启用的兑换配置	GET	/gd_dataserver/business/points/exchange/config/active	无请求参数。返回 data 为 ExchangeConfig 对象（数据库无记录时返回默认配置）。字段：pointsRatio-积分比例(N积分=1元)、singleMaxPoints-单笔最大积分、singleMinPoints-单笔最小积分、dailyLimitPerUser-每人每日兑换上限、monthlyLimitPerUser-每月上限、yearlyLimitPerUser-每年上限、dailyOrderCountLimit-每日兑换次数上限、rapidExchangeThreshold-短时间兑换次数阈值、rapidExchangeWindowMinutes-快速兑换检测窗口(分钟)、largeAmountThreshold-大额预警阈值、largeAmountNeedApproval-大额是否需审批(1是/0否)、antiFarmEnabled-隐患上报防刷检测开关(1启用/0禁用)。当安全开关关闭(enabled=0)时返回 null。
新增	POST	/gd_dataserver/business/points/exchange/config/add	新增单条记录，请求体为实体类对象（字段说明见对应实体模型）。成功返回 data 为 null。
批量新增	POST	/gd_dataserver/business/points/exchange/config/addBatch	批量新增多条记录，请求体为实体类数组。成功返回 data 为 null。
新增并返回保存的数据	POST	/gd_dataserver/business/points/exchange/config/addReturn	新增单条记录并返回保存后的数据（含自增ID），请求体为实体类对象。成功返回 data 为保存的实体对象。
根据属性删除	GET	/gd_dataserver/business/points/exchange/config/delete	根据实体属性条件删除记录，请求体为实体类对象。成功返回 data 为 null。
主键删除	GET	/gd_dataserver/business/points/exchange/config/deleteById	根据主键ID删除单条记录，成功返回 data 为 null。
批量删除	GET	/gd_dataserver/business/points/exchange/config/deleteByIds	根据ID列表批量删除记录，成功返回 data 为 null。
查询所有	GET	/gd_dataserver/business/points/exchange/config/getAll	查询所有记录（无分页、无条件）。成功返回 data 为实体类数组。
分页查询	GET	/gd_dataserver/business/points/exchange/config/getListByPage	分页查询记录列表，查询条件为实体类字段。成功返回 data 为 PageInfo 分页对象，其中 list 为实体类数组。
详情	GET	/gd_dataserver/business/points/exchange/config/info	根据主键ID查询单条记录详情。成功返回 data 为实体类对象，包含该实体所有字段。
条件查询	GET	/gd_dataserver/business/points/exchange/config/list	根据实体属性条件查询记录列表。成功返回 data 为实体类数组。
逻辑删除	GET	/gd_dataserver/business/points/exchange/config/removeById	根据主键ID逻辑删除单条记录，成功返回 data 为 null。
查询兑换安全开关状态	GET	/gd_dataserver/business/points/exchange/config/switch/status	无请求参数。返回 data 为 boolean，true-启用安全校验，false-已关闭。判断逻辑：数据库无配置记录时默认启用；有记录时根据 enabled 字段(1启用/0禁用)决定。
切换兑换安全开关（管理端）	POST	/gd_dataserver/business/points/exchange/config/switch/toggle	请求参数：enabled-true启用/false禁用(Boolean，必填)。返回 data 为 boolean，true-切换成功，false-切换失败。若数据库无配置记录且传入true，会自动创建默认配置。
修改	POST	/gd_dataserver/business/points/exchange/config/updateById	根据主键ID修改记录，请求体为实体类对象（需包含id字段）。成功返回 data 为 null。
校验兑换请求（APP端）	POST	/gd_dataserver/business/points/exchange/config/validate	在下单前调用，校验是否满足安全规则。请求参数：totalPoints-兑换总积分(int，必填)。返回 data 为对象，包含：passed-是否通过(boolean)、errors-错误信息数组(如'单笔兑换不能超过5000积分')、warnings-警告信息数组、securityEnabled-安全开关是否启用(boolean)、config-当前启用的兑换配置对象(开关关闭时为null)。前端根据 passed 判断能否兑换，errors 为空表示校验通过。当安全开关关闭时，passed=true、securityEnabled=false。

接口详情

获取当前启用的兑换配置

• 用途： 无请求参数。返回 data 为 ExchangeConfig 对象（数据库无记录时返回默认配置）。字段：pointsRatio-积分比例(N积分=1元)、singleMaxPoints-单笔最大积分、singleMinPoints-单笔最小积分、dailyLimitPerUser-每人每日兑换上限、monthlyLimitPerUser-每月上限、yearlyLimitPerUser-每年上限、dailyOrderCountLimit-每日兑换次数上限、rapidExchangeThreshold-短时间兑换次数阈值、rapidExchangeWindowMinutes-快速兑换检测窗口(分钟)、largeAmountThreshold-大额预警阈值、largeAmountNeedApproval-大额是否需审批(1是/0否)、antiFarmEnabled-隐患上报防刷检测开关(1启用/0禁用)。当安全开关关闭(enabled=0)时返回 null。
• 请求： GET /gd_dataserver/business/points/exchange/config/active
• 鉴权： X-Access-Token（以接口定义为准）
• operationId： getActiveConfigUsingGET_1

参数：

无

响应：

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

新增

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

参数：

无

请求体：

• Content-Type：application/json
• 模型：兑换安全配置
• 必填：文档未标记

字段	必填	类型	说明	示例
antiFarmEnabled	否	integer / int32	隐患上报防刷检测是否启用：1-启用 0-禁用	-
configName	否	string	配置名称	-
createTime	否	string / date-time	创建时间	-
dailyLimitPerUser	否	integer / int32	每人每日兑换上限（积分）	-
dailyOrderCountLimit	否	integer / int32	每人每日兑换次数上限	-
enabled	否	integer / int32	是否启用：1-启用 0-禁用	-
id	否	integer / int64	主键ID	-
largeAmountNeedApproval	否	integer / int32	大额兑换是否需审批：1-是 0-否	-
largeAmountThreshold	否	integer / int32	大额兑换预警阈值（积分）	-
monthlyLimitPerUser	否	integer / int32	每人每月上限（积分）	-
pointsRatio	否	integer / int32	积分比例（N积分=1元）	-
rapidExchangeThreshold	否	integer / int32	短时间内兑换次数阈值（触发预警）	-
rapidExchangeWindowMinutes	否	integer / int32	快速兑换检测时间窗口（分钟）	-
remark	否	string	备注	-
singleMaxPoints	否	integer / int32	单笔最大积分	-
singleMinPoints	否	integer / int32	单笔最小积分	-
updateTime	否	string / date-time	更新时间	-
yearlyLimitPerUser	否	integer / int32	每人每年上限（积分）	-

响应：

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

批量新增

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

参数：

无

请求体：

• Content-Type：application/json
• 模型：array<兑换安全配置>
• 必填：文档未标记

响应：

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

新增并返回保存的数据

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

参数：

无

请求体：

• Content-Type：application/json
• 模型：兑换安全配置
• 必填：文档未标记

字段	必填	类型	说明	示例
antiFarmEnabled	否	integer / int32	隐患上报防刷检测是否启用：1-启用 0-禁用	-
configName	否	string	配置名称	-
createTime	否	string / date-time	创建时间	-
dailyLimitPerUser	否	integer / int32	每人每日兑换上限（积分）	-
dailyOrderCountLimit	否	integer / int32	每人每日兑换次数上限	-
enabled	否	integer / int32	是否启用：1-启用 0-禁用	-
id	否	integer / int64	主键ID	-
largeAmountNeedApproval	否	integer / int32	大额兑换是否需审批：1-是 0-否	-
largeAmountThreshold	否	integer / int32	大额兑换预警阈值（积分）	-
monthlyLimitPerUser	否	integer / int32	每人每月上限（积分）	-
pointsRatio	否	integer / int32	积分比例（N积分=1元）	-
rapidExchangeThreshold	否	integer / int32	短时间内兑换次数阈值（触发预警）	-
rapidExchangeWindowMinutes	否	integer / int32	快速兑换检测时间窗口（分钟）	-
remark	否	string	备注	-
singleMaxPoints	否	integer / int32	单笔最大积分	-
singleMinPoints	否	integer / int32	单笔最小积分	-
updateTime	否	string / date-time	更新时间	-
yearlyLimitPerUser	否	integer / int32	每人每年上限（积分）	-

响应：

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

根据属性删除

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

参数：

字段	位置	必填	类型	说明	示例
antiFarmEnabled	query	否	integer / int32	隐患上报防刷检测是否启用：1-启用 0-禁用	-
configName	query	否	string	配置名称	-
createTime	query	否	string / date-time	创建时间	-
dailyLimitPerUser	query	否	integer / int32	每人每日兑换上限（积分）	-
dailyOrderCountLimit	query	否	integer / int32	每人每日兑换次数上限	-
enabled	query	否	integer / int32	是否启用：1-启用 0-禁用	-
id	query	否	integer / int64	主键ID	-
largeAmountNeedApproval	query	否	integer / int32	大额兑换是否需审批：1-是 0-否	-
largeAmountThreshold	query	否	integer / int32	大额兑换预警阈值（积分）	-
monthlyLimitPerUser	query	否	integer / int32	每人每月上限（积分）	-
pointsRatio	query	否	integer / int32	积分比例（N积分=1元）	-
rapidExchangeThreshold	query	否	integer / int32	短时间内兑换次数阈值（触发预警）	-
rapidExchangeWindowMinutes	query	否	integer / int32	快速兑换检测时间窗口（分钟）	-
remark	query	否	string	备注	-
singleMaxPoints	query	否	integer / int32	单笔最大积分	-
singleMinPoints	query	否	integer / int32	单笔最小积分	-
updateTime	query	否	string / date-time	更新时间	-
yearlyLimitPerUser	query	否	integer / int32	每人每年上限（积分）	-

响应：

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

主键删除

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

参数：

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

响应：

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

批量删除

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

参数：

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

响应：

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

查询所有

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

参数：

无

响应：

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

分页查询

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

参数：

字段	位置	必填	类型	说明	示例
antiFarmEnabled	query	否	integer / int32	隐患上报防刷检测是否启用：1-启用 0-禁用	-
configName	query	否	string	配置名称	-
createTime	query	否	string / date-time	创建时间	-
dailyLimitPerUser	query	否	integer / int32	每人每日兑换上限（积分）	-
dailyOrderCountLimit	query	否	integer / int32	每人每日兑换次数上限	-
enabled	query	否	integer / int32	是否启用：1-启用 0-禁用	-
id	query	否	integer / int64	主键ID	-
largeAmountNeedApproval	query	否	integer / int32	大额兑换是否需审批：1-是 0-否	-
largeAmountThreshold	query	否	integer / int32	大额兑换预警阈值（积分）	-
monthlyLimitPerUser	query	否	integer / int32	每人每月上限（积分）	-
pageNum	query	是	integer / int32	页码	-
pointsRatio	query	否	integer / int32	积分比例（N积分=1元）	-
rapidExchangeThreshold	query	否	integer / int32	短时间内兑换次数阈值（触发预警）	-
rapidExchangeWindowMinutes	query	否	integer / int32	快速兑换检测时间窗口（分钟）	-
remark	query	否	string	备注	-
singleMaxPoints	query	否	integer / int32	单笔最大积分	-
singleMinPoints	query	否	integer / int32	单笔最小积分	-
updateTime	query	否	string / date-time	更新时间	-
yearlyLimitPerUser	query	否	integer / int32	每人每年上限（积分）	-
pageSize	query	是	integer / int32	每页条数	-

响应：

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

详情

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

参数：

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

响应：

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

条件查询

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

参数：

字段	位置	必填	类型	说明	示例
antiFarmEnabled	query	否	integer / int32	隐患上报防刷检测是否启用：1-启用 0-禁用	-
configName	query	否	string	配置名称	-
createTime	query	否	string / date-time	创建时间	-
dailyLimitPerUser	query	否	integer / int32	每人每日兑换上限（积分）	-
dailyOrderCountLimit	query	否	integer / int32	每人每日兑换次数上限	-
enabled	query	否	integer / int32	是否启用：1-启用 0-禁用	-
id	query	否	integer / int64	主键ID	-
largeAmountNeedApproval	query	否	integer / int32	大额兑换是否需审批：1-是 0-否	-
largeAmountThreshold	query	否	integer / int32	大额兑换预警阈值（积分）	-
monthlyLimitPerUser	query	否	integer / int32	每人每月上限（积分）	-
pointsRatio	query	否	integer / int32	积分比例（N积分=1元）	-
rapidExchangeThreshold	query	否	integer / int32	短时间内兑换次数阈值（触发预警）	-
rapidExchangeWindowMinutes	query	否	integer / int32	快速兑换检测时间窗口（分钟）	-
remark	query	否	string	备注	-
singleMaxPoints	query	否	integer / int32	单笔最大积分	-
singleMinPoints	query	否	integer / int32	单笔最小积分	-
updateTime	query	否	string / date-time	更新时间	-
yearlyLimitPerUser	query	否	integer / int32	每人每年上限（积分）	-

响应：

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

逻辑删除

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

参数：

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

响应：

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

查询兑换安全开关状态

• 用途： 无请求参数。返回 data 为 boolean，true-启用安全校验，false-已关闭。判断逻辑：数据库无配置记录时默认启用；有记录时根据 enabled 字段(1启用/0禁用)决定。
• 请求： GET /gd_dataserver/business/points/exchange/config/switch/status
• 鉴权： X-Access-Token（以接口定义为准）
• operationId： getSwitchStatusUsingGET

参数：

无

响应：

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

切换兑换安全开关（管理端）

• 用途： 请求参数：enabled-true启用/false禁用(Boolean，必填)。返回 data 为 boolean，true-切换成功，false-切换失败。若数据库无配置记录且传入true，会自动创建默认配置。
• 请求： POST /gd_dataserver/business/points/exchange/config/switch/toggle
• 鉴权： X-Access-Token（以接口定义为准）
• operationId： toggleSwitchUsingPOST

参数：

字段	位置	必填	类型	说明	示例
enabled	query	是	boolean	true-启用安全校验，false-禁用	-

响应：

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

修改

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

参数：

无

请求体：

• Content-Type：application/json
• 模型：兑换安全配置
• 必填：文档未标记

字段	必填	类型	说明	示例
antiFarmEnabled	否	integer / int32	隐患上报防刷检测是否启用：1-启用 0-禁用	-
configName	否	string	配置名称	-
createTime	否	string / date-time	创建时间	-
dailyLimitPerUser	否	integer / int32	每人每日兑换上限（积分）	-
dailyOrderCountLimit	否	integer / int32	每人每日兑换次数上限	-
enabled	否	integer / int32	是否启用：1-启用 0-禁用	-
id	否	integer / int64	主键ID	-
largeAmountNeedApproval	否	integer / int32	大额兑换是否需审批：1-是 0-否	-
largeAmountThreshold	否	integer / int32	大额兑换预警阈值（积分）	-
monthlyLimitPerUser	否	integer / int32	每人每月上限（积分）	-
pointsRatio	否	integer / int32	积分比例（N积分=1元）	-
rapidExchangeThreshold	否	integer / int32	短时间内兑换次数阈值（触发预警）	-
rapidExchangeWindowMinutes	否	integer / int32	快速兑换检测时间窗口（分钟）	-
remark	否	string	备注	-
singleMaxPoints	否	integer / int32	单笔最大积分	-
singleMinPoints	否	integer / int32	单笔最小积分	-
updateTime	否	string / date-time	更新时间	-
yearlyLimitPerUser	否	integer / int32	每人每年上限（积分）	-

响应：

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

校验兑换请求（APP端）

• 用途： 在下单前调用，校验是否满足安全规则。请求参数：totalPoints-兑换总积分(int，必填)。返回 data 为对象，包含：passed-是否通过(boolean)、errors-错误信息数组(如'单笔兑换不能超过5000积分')、warnings-警告信息数组、securityEnabled-安全开关是否启用(boolean)、config-当前启用的兑换配置对象(开关关闭时为null)。前端根据 passed 判断能否兑换，errors 为空表示校验通过。当安全开关关闭时，passed=true、securityEnabled=false。
• 请求： POST /gd_dataserver/business/points/exchange/config/validate
• 鉴权： X-Access-Token（以接口定义为准）
• operationId： validateExchangeUsingPOST

参数：

字段	位置	必填	类型	说明	示例
totalPoints	query	是	integer / int32	兑换总积分	-

响应：

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