埋点系统产品需求文档 V2.12.5（人工优惠活动视觉重构版）#

本版本以【埋点系统 V2.12.0】为唯一功能基线，V2.12.0 未声明变更的功能、口径、权限和非功能要求继续有效。本文件定义财务管理新增的人工优惠与自动优惠能力。

0. 文档信息与变更记录#

1. 背景与目标#

1.1 业务背景#

客服补偿、VIP 关怀、新客召回和临时运营奖励目前缺少统一的配置、批量处理、领取条件、充值触发和审计记录。运营需要通过会员 ID 或会员分组快速赠送金额，也需要把“注册后限定时间仍未充值”的会员转化为可持续运行的自动奖励人群。

1.2 产品目标#

• 为单个会员、Excel 名单或会员分组创建人工优惠任务。
• 统一配置奖励金额、稽核流水、前后台备注及领取方式。
• 支持自动到账、弹窗领取、充值后领取三条互斥的奖励链路。
• 在弹窗领取和自动优惠模板中支持固定倍数或按充值金额阶梯计算的奖励加倍。
• 支持在人工优惠页面直接管理充值加倍模版，并配置固定倍数或随机倍数档位。
• 允许为加倍奖励稽核选择参与计算的游戏类型与游戏标签。
• 统一人工优惠页面与埋点系统既有后台样式，减少装饰性容器，以输入效率、字段识别和长表单可读性为优先。
• 统一居中弹窗及右侧抽屉的尺寸、标题区、内容滚动区和底部操作区，消除错位、拉伸和内容叠层。
• 通过自动模板识别“注册限时未充值”会员，自动创建奖励。
• 对任务、会员处理结果、充值判定、领取、加倍和失败原因形成完整记录。

1.3 非目标#

• 本版本不新增现金提款审核规则。
• 本版本不支持优惠模板之间自动叠加、互斥优先级编排或 A/B 实验。
• 本版本不允许修改已经创建或已经命中会员的奖励金额和领取条件。
• 本版本不改变 V2.12.0 原有埋点系统 10 个页面和 104+16 事件基线。

2. 信息架构与权限#

2.1 菜单结构#

2.2 权限矩阵#

金额权限继续继承后台角色的单笔金额、单日累计金额和会员分组范围。超出权限时禁止提交，不允许通过拆分批次规避限制。

3. 公共业务定义#

3.1 会员与批量对象#

黑名单、风控冻结、自我排除、已注销和币种不一致会员默认排除并记录失败原因。批量任务中单个会员失败不得阻塞其他有效会员。

3.2 金额与精度#

• 所有金额使用当前站点币种，原型站点为 PHP。
• 存入金额必须大于 0，最多保留 2 位小数；金额上限由站点和角色权限共同决定。
• 后端使用十进制定点数，不使用浮点数计算奖励。
• 每次钱包入账必须生成唯一账变单号，并使用任务号 + 会员 ID + 奖励阶段作为幂等键。

3.3 稽核流水#

基础奖励与加倍奖励分别建账、分别记录稽核要求。加倍奖励的稽核倍数只作用于加倍奖励金额。

3.4 奖励加倍口径#

• 奖励加倍仅在开关开启时生效。
• 触发起点为基础奖励已到账或已领取；起点前的充值订单不计入。
• 仅取起点后的第一笔充值成功订单进行加倍计算；失败、取消、冲正订单不计入。
• 固定倍数：额外加倍奖励 = 基础奖励金额 × 配置倍数。
• 按充值金额加倍：根据第一笔充值成功金额命中模板档位，额外加倍奖励 = 基础奖励金额 × 档位倍数，并受档位单次上限约束。
• 同一基础奖励最多产生一笔加倍奖励。加倍入账失败时允许后台按原幂等键重试，不得重复入账。

3.5 加倍模版与游戏参与口径#

• 加倍模版分为【按充值金额固定倍数】和【按充值金额随机倍数】。
• 每个档位的充值金额必须大于 0、按升序排列且不可重复；订单金额命中“小于或等于该金额的最高档位”。
• 固定倍数档位配置充值金额和加倍倍数；随机倍数档位配置充值金额、最小倍数、最大倍数和期望倍数。
• 随机倍数必须满足 最小倍数 ≤ 期望倍数 ≤ 最大倍数；实际结果保留 2 位小数，并保存模版版本、随机结果及可审计的随机摘要。
• 加倍奖励稽核只统计【游戏参与】范围内的有效投注。游戏类型之间为 OR；游戏标签之间为 OR；同时配置类型和标签时两组条件为 AND。
• 全选游戏类型且游戏标签为空等同于全部游戏。模版或人工任务提交时固化游戏范围快照，后续游戏分类或标签变化不追溯。

3.6 V2.12.5 视觉与布局规范#

4. 人工优惠活动#

4.1 页面目标#

通过单个会员 ID、Excel 名单或会员分组创建人工优惠任务，配置奖励、稽核、备注及领取链路，并在提交前预览完整规则。

4.2 页面操作链路#

4.3 字段与筛选条件#

4.4 功能明细#

4.5 领取方式#

4.5.1 自动领取#

任务通过校验后直接写入会员钱包。成功状态为【派发完成】；钱包失败状态为【派发失败】，允许有权限人员重试。该方式不需要奖励过期时间，也不支持前台手动领取。

4.5.2 弹窗领取#

会员前台只展示当前有效、未领取奖励。领取接口必须防重复提交；领取成功后基础奖励立即入账。奖励加倍开启时，从基础奖励入账成功时间开始等待第一笔充值成功订单。

4.5.3 充值后领取#

充值失败、取消、超时和支付中订单不参与判定。冲正或退款发生在奖励入账前时，从累计金额中扣除；奖励已入账后的资金追回走现有风控和账变流程，本版本不自动扣回。

5. 人工优惠活动记录#

5.1 页面操作链路#

5.2 筛选条件#

5.3 功能明细#

6. 自动优惠活动#

6.1 用户定义：注册限时未充值#

同时满足以下条件的会员进入候选集：

1. 当前站点存在注册成功结果，注册时间以服务器成功时间为准。
2. 从注册成功到模板配置的限定时长结束，仍不存在充值成功订单。
3. 会员处于正常状态，不在黑名单、风控冻结和自我排除范围。
4. 同一会员从未命中过同一模板；模板停用期间不补发历史漏扫用户，除非重新启用时明确选择补扫。

6.2 页面操作链路#

6.3 筛选条件#

6.4 功能明细#

7. 自动优惠活动记录#

7.1 页面操作链路#

7.2 筛选条件#

7.3 功能明细#

8. 状态机与异常规则#

8.1 人工任务状态#

8.2 关键异常#

9. 数据、接口与审计#

9.1 核心数据对象#

9.2 接口要求#

• 创建接口必须接收客户端幂等键并返回稳定的任务编号。
• 批量导入采用“上传解析—确认有效名单—创建任务”三阶段，不允许上传后直接入账。
• 充值判定消费充值成功结果事件，以订单号幂等；模板扫描读取注册成功与充值成功的业务事实。
• 列表使用服务端分页；导出使用已提交筛选快照，不读取页面未提交输入。
• 所有时间存 UTC，页面按站点时区展示；有效期比较也使用站点时区转换后的明确 UTC 时间。

9.3 审计日志#

必须记录创建、编辑草稿、提交、取消、模板启停、模板版本变更、技术重试和导出。日志至少包含操作人、角色、站点、操作时间、对象编号、变更前后配置、权限快照、请求来源 IP 和结果。

10. 非功能要求#

11. 验收标准#

11.1 人工优惠#

1. 财务管理可进入【人工优惠活动】，顶部可切换到【人工优惠活动记录】。
2. 单个会员可通过会员 ID 创建奖励；批量可通过 Excel 或会员分组创建。
3. 稽核选择倍数时只显示倍数输入；选择自定义时只显示固定数值输入。
4. 稽核类型标题与切换选择同一行左右布局；稽核倍数/数值输入区具有明显边框和字号，自定义数值不带 PHP 单位。
5. 三个领取方式选择卡片采用紧凑尺寸；弹窗领取的奖励加倍说明和开关独占一行。
6. 按充值金额加倍可打开模版列表，并继续新建固定或随机倍数模版；动态增删档位和保存回填正常。
7. 游戏参与支持全选/多选游戏类型、选择游戏标签和预览；仅命中范围的有效投注计入加倍稽核。
8. 自动领取创建成功后金额自动到账，并生成唯一账变记录。
9. 弹窗领取展示过期时间；到期前只能领取一次，到期后不可领取。
10. 奖励加倍关闭时不生成加倍条件；开启时固定倍数和按充值金额模版互斥。
11. 固定倍数与充值阶梯模版均按第一笔充值成功订单触发一次，并生成独立稽核要求。
12. 单笔充值以最先充值成功订单判断，低于目标立即作废；累计充值达到目标时自动派发。
13. 批量任务单个会员失败不影响其他会员，记录页可查询和导出失败原因。
14. 所有主要输入控件高度统一为 40px；标签、输入值、帮助文字具有明确字号层级，桌面端两列表单边缘对齐。
15. 加倍模版列表、固定倍数编辑、随机倍数编辑和人工派奖确认弹窗均垂直居中，正文超高时只滚动内容区。
16. 固定倍数档位必须保持正常文档流，不得与档位校验提示、表头或弹窗底部操作区重叠。
17. 人工任务详情和自动优惠模板使用右侧抽屉；标题与底部按钮固定，滚动正文时底部操作始终可见。

11.2 自动优惠#

1. 财务管理可进入【自动优惠活动】，顶部可切换到【自动优惠活动记录】。
2. 可新增“注册限时未充值”模板并配置未充值时长、扫描频率、会员分组和有效期。
3. 可配置自动到账或弹窗领取、基础奖励、稽核、备注、单日上限和排除人群。
4. 同一会员同一模板只能命中一次，模板重扫或回调重复不得重复赠送。
5. 奖励加倍开启后按固定倍数或充值金额模板计算，并在记录页展示完整链路。
6. 暂停模板后不再产生新命中；已命中会员继续按命中时配置执行。
7. 模板修改产生新版本，历史记录保留原版本配置快照。
8. 自动优惠模板抽屉宽度为 640px，基础信息和奖励配置采用两列 40px 输入框，游戏参与和生效风控在同一滚动内容区顺序展示。

12. 回归范围与已知问题#

12.1 回归重点#

• V2.12.0 原有财务菜单、埋点系统 10 页、用户 360、埋点管理和事件查询不受影响。
• 站点、币种、会员分组和角色额度在单个、Excel、分组和自动模板四类入口保持一致。
• 奖励基础入账和加倍入账分别幂等；重复点击、重复回调和任务重跑不重复加款。
• 页面筛选、分页、导出与详情使用同一已提交条件。
• 所有奖励状态均能关联任务号、会员 ID、充值订单号和钱包账变单号。
• 模版版本、随机倍数结果、游戏类型/标签快照和有效投注累计结果可完整追溯。

12.2 已知问题 / 待产品确认#

1. “固定倍数”的业务口径当前定义为“额外奖励 = 基础奖励 × 配置倍数”；如业务期望总奖励为基础奖励的 N 倍，应在开发前统一调整为“额外奖励 = 基础奖励 ×（N-1）”。
2. 自动模板弹窗奖励的前台视觉和多奖励并存排序沿用现有活动弹窗规范，本版本原型只覆盖后台配置与记录。
3. 批量 Excel 最大 5 万行作为本版实施上限；更大规模名单需拆分任务或后续改为对象存储异步导入。
4. 随机倍数的概率分布算法和期望倍数收敛窗口需研发、风控在技术评审时锁定；原型已覆盖字段、校验和审计要求。