埋点系统产品需求文档 V2.13.0（人工优惠活动系统通知版）#

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

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

1. 背景与目标#

1.1 业务背景#

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

1.2 产品目标#

• 为单个会员、Excel 名单或会员分组创建人工优惠任务。
• 统一配置奖励金额、稽核流水、前后台备注及领取方式。
• 支持自动到账、弹窗领取、充值后领取三条互斥的奖励链路。
• 在弹窗领取和自动优惠模板中支持固定倍数或按充值金额阶梯计算的奖励加倍。
• 支持在人工优惠页面直接管理充值加倍模版，并配置固定倍数或随机倍数档位。
• 允许为加倍奖励稽核选择参与计算的游戏类型与游戏标签。
• 统一人工优惠页面与埋点系统既有后台样式，减少装饰性容器，以输入效率、字段识别和长表单可读性为优先。
• 移除人工优惠创建页顶部重复的“人工优惠派奖”展示模块，让页签后直接进入任务配置步骤。
• 参考用户提供的打码量样式，将稽核流水类型改为圆形单选；标题与选项同一行，对应输入框在下一行铺满并贴合现有后台视觉。
• 将稽核倍数/数值输入框收窄到与存入金额输入框相同的第一列宽度，使两个字段左右边缘对齐；820px 以下恢复整宽。
• 为批量会员 Excel 导入提供可直接下载的标准模版，并明确仅接收 xls、xlsx 且文件不超过 15MB。
• 将弹窗领取和充值后领取的期限字段统一为【奖励过期时间】，按天输入、支持小数，并从奖励获得时间开始计算自动作废时点。
• 在人工优惠创建链路新增步骤 04【配置系统通知】，提供人工优惠专用通知模版，允许编辑标题、正文并通过开关决定本次任务是否发送。
• 配置预览覆盖赠送对象、金额、稽核、备注、领取、过期、加倍、游戏参与及系统通知等当前有效配置，并随输入实时更新。
• 移除创建页【草稿】状态提示与【保存草稿】按钮，人工优惠任务只允许确认后正式创建。
• 统一居中弹窗及右侧抽屉的尺寸、标题区、内容滚动区和底部操作区，消除错位、拉伸和内容叠层。
• 通过自动模板识别“注册限时未充值”会员，自动创建奖励。
• 对任务、会员处理结果、充值判定、领取、加倍和失败原因形成完整记录。

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 系统通知口径#

默认标题为“🎁 您已获得人工优惠奖励”。默认正文使用人工优惠活动语义，包含会员名称、奖励金额、领取方式和奖励过期时间，不沿用注册成功模版的注册、首充或账号信息文案。

3.7 V2.13.0 视觉与布局规范#

4. 人工优惠活动#

4.1 页面目标#

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

4.2 页面操作链路#

4.3 字段与筛选条件#

4.4 功能明细#

4.5 领取方式#

4.5.1 自动领取#

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

4.5.2 弹窗领取#

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

4.5.3 充值后领取#

充值后领取不再配置【充值有效期】，改为配置与弹窗领取一致的【奖励过期时间】。该字段为必填天数，必须大于 0、支持小数；从奖励获得时间开始按 天数 × 24 小时 计算。到期前仍未触发奖励派发的会员记录自动作废。

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

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 接口要求#

• 创建接口必须接收客户端幂等键并返回稳定的任务编号。
• 批量导入采用“上传解析—确认有效名单—创建任务”三阶段，不允许上传后直接入账。
• 充值判定消费充值成功结果事件，以订单号幂等；模板扫描读取注册成功与充值成功的业务事实。
• 人工优惠创建接口在通知开启时必须接收完整 notification_config；服务端重新校验字符长度、模版变量白名单和信件类型，不信任客户端校验结果。
• 通知发送使用任务 ID + 会员 ID + 信件类型作为幂等键；通知失败不得回滚已完成的钱包入账，也不得触发重复派奖。
• 列表使用服务端分页；导出使用已提交筛选快照，不读取页面未提交输入。
• 所有时间存 UTC，页面按站点时区展示；有效期比较也使用站点时区转换后的明确 UTC 时间。

9.3 审计日志#

必须记录创建、提交、取消、通知启停与模版内容快照、通知发送结果、自动模板启停、模板版本变更、技术重试和导出。日志至少包含操作人、角色、站点、操作时间、对象编号、变更前后配置、权限快照、请求来源 IP 和结果。通知正文涉及会员变量时，审计查询按权限展示，导出遵循现有敏感信息脱敏规则。

10. 非功能要求#

11. 验收标准#

11.1 人工优惠#

1. 财务管理可进入【人工优惠活动】，顶部可切换到【人工优惠活动记录】。
2. 顶部页签下方直接显示步骤 01【选择赠送对象】，不得出现“人工优惠派奖”、MANUAL REWARD、必填项数量、领取方式数量或 T+0 概览模块。
3. 单个会员可通过会员 ID 创建奖励；批量可通过 Excel 或会员分组创建。Excel 上传区下方必须展示【下载模版】，点击后下载可正常打开的 .xlsx 文件，首列字段名为 member_id。
4. 稽核区域第一行展示【稽核流水类型】和圆形单选【倍数 / 自定义流水】，不得继续使用左右分栏或分段按钮卡片；选中态必须包含主色外圈与圆点。
5. 稽核选择倍数时，下一行输入显示“倍”后缀；选择自定义流水时原位切换为固定数值输入且不显示 PHP 或其他币种单位，帮助文案必须为“填写固定有效投注流水数值”；桌面端稽核输入框必须与存入金额输入框等宽且左右边缘对齐，820px 以下两者均占满容器。
6. 三个领取方式选择卡片采用紧凑尺寸；弹窗领取的奖励加倍说明和开关独占一行。
7. 按充值金额加倍可打开模版列表，并继续新建固定或随机倍数模版；动态增删档位和保存回填正常。
8. 游戏参与支持全选/多选游戏类型、选择游戏标签和预览；仅命中范围的有效投注计入加倍稽核。
9. 自动领取创建成功后金额自动到账，并生成唯一账变记录。
10. Excel 文件提示文案必须为“仅支持xls、xlsx格式的文件（大小：<=15MB）”；非 xls/xlsx 或超过 15MB 的文件不得进入导入解析。
11. 前台备注帮助文案必须为“展示给会员，最多 100字符”，输入长度上限为 100 字符。
12. 弹窗领取的【奖励过期时间】为带“天”后缀的数字输入，允许正小数；从奖励获得开始计算，到期前只能领取一次，到期后不可领取。
13. 充值后领取不得出现【充值有效期】或日期时间控件，必须使用与弹窗领取相同的【奖励过期时间】天数输入；奖励过期仍未触发时自动作废。
14. 奖励加倍关闭时不生成加倍条件；开启时固定倍数和按充值金额模版互斥。
15. 固定倍数与充值阶梯模版均按第一笔充值成功订单触发一次，并生成独立稽核要求。
16. 单笔充值以奖励过期前最先充值成功订单判断，低于目标立即作废；累计充值在奖励过期前达到目标时自动派发。
17. 批量任务单个会员失败不影响其他会员，记录页可查询和导出失败原因。
18. 所有主要输入控件高度统一为 40px；标签、输入值、帮助文字具有明确字号层级，桌面端两列表单边缘对齐。
19. 加倍模版列表、固定倍数编辑、随机倍数编辑和人工派奖确认弹窗均垂直居中，正文超高时只滚动内容区。
20. 固定倍数档位必须保持正常文档流，不得与档位校验提示、表头或弹窗底部操作区重叠。
21. 人工任务详情和自动优惠模板使用右侧抽屉；标题与底部按钮固定，滚动正文时底部操作始终可见。
22. 创建页必须在领取方式之后展示步骤 04【配置系统通知】；默认开启，切换关闭后收起信件类型、标题、正文和站内通知选项，并在配置预览显示“系统通知：关闭”。
23. 通知开启时可在【站内信 / 平台公告】之间切换；标题和正文可编辑，分别限制 100、1000 字符并显示实时计数；默认内容必须为人工优惠活动模版，不得包含注册成功或首充解锁语义。
24. 通知正文支持 {userName}、{rewardAmount}、{claimMethod}、{expiryDays}；创建任务后保存模版快照，批量任务按会员独立渲染且发送幂等。
25. 【是否发送站内通知】可选择否或是，默认是；该选择与信件类型、通知开关一起进入任务详情和审计日志。
26. 右侧配置预览必须完整展示当前有效的赠送对象、金额、稽核、前后台备注、领取方式、过期时间、奖励加倍、加倍配置、游戏参与及系统通知摘要；编辑金额、通知类型或标题后实时更新。
27. 创建页和配置预览不得出现【草稿】标签、【保存草稿】按钮或其他草稿操作入口。

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. 随机倍数的概率分布算法和期望倍数收敛窗口需研发、风控在技术评审时锁定；原型已覆盖字段、校验和审计要求。
5. 平台公告的会员可见范围、展示入口和前台排序沿用现有消息中心能力；若现网平台公告仅支持全站广播，研发前需确认是否支持按人工优惠任务会员集合定向投放。