[V4.26] 代金券/礼包等多项优化

需求来源：飞书 Wiki《[V4.26] 代金券/礼包等多项优化》
飞书链接：https://bcnwdpujw6rb.feishu.cn/wiki/LxbGwNFDMiJyltk4aH9cqSuan7Y
文档负责人：韩辉
飞书最近修改时间：2026-08-05 18:14
本地整理时间：2026-08-11

1、代金券功能调整（三端）

1.1 增加代金券可领取时间

需求内容：

代金券需要新增“可领取时间”配置，只有在指定时间范围内，SDK 用户才可以领取。
如果当前时间已经超过可领取时间，代金券状态自动变更为“下架”。
“下架”在 SDK 客户端表现为不再展示该代金券。
现有“代金券有效期”只负责限制代金券是否过期，不再承担“是否允许领取”的判断。

需要确认：

可领取时间是否按“开始时间 + 结束时间”配置。
下架是只影响 SDK 展示，还是后台列表也标记为已下架。
已经领取但未使用的代金券，在超过可领取时间后是否仍可正常使用；按当前描述，应不受领取时间影响，只受券有效期影响。

1.2 新增可拆分代金券

需求内容：

新增一种代金券类型：可拆分代金券。
用户持有一张可拆分代金券后，可以根据订单金额分多次抵扣。
每次使用只扣除本次订单实际抵扣金额，剩余金额保留在券内。
当代金券余额全部用完后，该券才变更为已使用/不可用。

业务示例：

用户有一张 100 元可拆分代金券。
第一笔订单充值 30 元，抵扣 30 元，券剩余 70 元。
第二笔订单充值 50 元，抵扣 50 元，券剩余 20 元。
第三笔订单充值 80 元，最多只能再抵扣 20 元，券剩余 0 元并视为用完。

当前系统差异：

现有代金券是“一张券一次用完”的模式。
当前 cy_coupon_member 主要通过 is_use 标记“未使用 / 使用中 / 已使用”，没有剩余金额字段。
当前订单表只记录 coupon_member_id 和 coupon_amount，能知道本单用了哪张券、抵了多少钱，但不能完整追踪券余额变化过程。

需要改造：

代金券模板表需要区分普通券和可拆分券。
用户券表需要记录券总额和剩余金额。
需要新增券抵扣流水，记录每次订单抵扣金额、抵扣前余额、抵扣后余额、状态。
下单、支付成功、取消订单、退款或回调重复通知时，都要能准确扣减或回退券余额。
SDK 客户端需要展示可拆分券剩余金额，并在支付时按余额抵扣。

2、游戏管理筛选调整

需求背景：

SDK 接入的游戏数量较多。
已下架游戏不需要在默认视图中继续干扰运营操作。

需求内容：

游戏管理页面的“对接状态”筛选默认值调整为勾选：
- 对接中
- 上线
- 白名单限制
“下架”状态默认不勾选。

需要确认：

只是修改默认筛选条件，还是同时保存用户上次选择的筛选条件。
已下架游戏是否仍允许通过手动勾选查询出来；按需求描述，应保留手动查询能力。

3、充值记录管理 - 订单手动换绑页面增加备注

需求内容：

订单手动换绑页面新增备注字段。
备注为选填。
换绑操作提交后，备注需要随换绑记录保存。
换绑列表需要展示该备注，方便后续追溯换绑原因。

需要改造：

换绑表单增加备注输入框。
换绑提交接口接收并保存备注。
换绑记录列表增加备注展示。
如果已有换绑日志表，需要确认是在原表加备注字段，还是另存操作日志。

4、充值记录管理 - 用户充值列表增加绑定手机号

需求内容：

用户充值列表增加“账号绑定手机号”字段。
列表支持按手机号搜索。
导出的充值数据同步增加：
- 手机号
- 游戏名

需要改造：

充值记录查询需要关联账号手机号。
列表页新增手机号列和手机号搜索条件。
导出逻辑同步补充手机号、游戏名字段。

需要确认：

搜索的是账号当前绑定手机号，还是订单发生时的历史手机号。
导出中的手机号是否需要脱敏。

5、数据页面支持实付金额排序

需求内容：

数据页面新增“新增玩家”“实付金额”的排序能力。
排序状态包括：
- 默认状态
- 金额倒序
- 金额正序

涉及页面：

数据统计：
- 数据汇总
- 游戏留存
- 区服数据
- 区服留存
推广管理：
- 推广员数据
聚合统计管理：
- 游戏数据汇总
- 渠道数据汇总
- 游戏单日报表
- 游戏留存报表
- 游戏区服数据

需要确认：

“实付金额”的排序口径是只按现金支付金额，还是按扣除代金券后的金额。
新增玩家排序和实付金额排序是否互斥。
排序是否需要支持导出后的文件顺序保持一致。

6、数据表增加自定义字段显示

需求背景：

部分数据需要给 CP 提供后台截图。
某些字段不适合直接展示给 CP，需要能隐藏。

需求内容：

数据表新增自定义字段显示功能。
用户可以根据需要选择显示或隐藏部分字段。

涉及页面：

数据统计
充值记录管理

需要确认：

字段隐藏只影响页面展示，还是导出也要同步隐藏。
字段配置是否按用户保存，还是每次进入页面都使用默认字段。
是否需要按角色或权限控制可配置字段范围。

7、礼包调整（三端）

需求背景：

增加礼包发放类型，满足业务部门运营需求。

需求内容：

SDK 后台礼包功能需要调整。
SDK 客户端礼包页面需要同步调整。

需要确认：

新增哪些礼包发放类型。
后台配置项、客户端展示样式、领取规则和发放记录如何变化。
是否需要兼容已有礼包类型和历史数据。

8、SDK 与巨量包独立配置登录开关

需求背景：

SDK 包存在提前上架、预下载但限制登录的情况。
当前如果限制登录，会同时影响巨量包。
巨量包无法登录会影响巨量审核。

需求内容：

游戏管理中的“封禁登录”选项调整为支持四种状态：
- 关
- 全部封禁
- 封禁 SDK
- 封禁巨量

实现方向：

兼容现有 is_login 字段。
现有 0 可继续表示“关”。
现有 1 可继续表示“全部封禁”。
新增枚举值表示“封禁 SDK”“封禁巨量”。
登录接口需要能识别当前请求来自 SDK 包还是巨量包，再按配置判断是否允许登录。

需要确认：

客户端请求是否会稳定传入区分 SDK/巨量的字段。
如果不能稳定传入，需要通过包配置、appid/appkey 或服务端配置判断来源。
白名单逻辑是否对“封禁 SDK”和“封禁巨量”同时生效。

9、【玩家角色信息】调整

需求内容：

玩家角色信息列表增加字段：
- 最后活跃时间
- 登录设备
为直播平台提供接口。

需要确认：

最后活跃时间取自最近一次登录、最近一次角色在线，还是最近一次支付/行为日志。
登录设备展示设备类型、设备型号，还是设备唯一标识。
直播平台接口需要返回哪些字段，以及是否只读。

当前优先级建议

建议优先梳理和评审以下三项：

可拆分代金券：涉及券余额、订单、支付回调、退款和客户端展示，改动最大。
SDK 与巨量包独立登录开关：涉及线上登录兼容性，需要先确认包来源识别方式。
自定义字段显示：需要明确是否影响导出和权限，否则后续容易返工。