埋点系统产品需求文档 V2.12.4（人工优惠活动迭代版）#
本版本以【埋点系统 V2.12.0】为唯一功能基线，V2.12.0 未声明变更的功能、口径、权限和非功能要求继续有效。本文件定义财务管理新增的人工优惠与自动优惠能力。
0. 文档信息与变更记录#
| 项目 | 内容 |
|---|---|
| 版本号 | V2.12.4 |
| 基准版本 | 埋点系统 V2.12.0 |
| 发布日期 | 2026-08-27 |
| 产品原型 | https://lg-admin-promo-v2124.pages.dev/?page=finance-manual-promotion |
| 文档状态 | 待评审 |
| 负责人 | 产品 / 财务运营 / 活动运营 |
| 版本 | 日期 | 变更内容 | 影响范围 |
|---|---|---|---|
| V2.12.3 | 2026-08-27 | 财务管理新增【人工优惠活动】、【自动优惠活动】及各自记录页；支持单人、批量、会员分组、三种领取方式、奖励加倍和注册限时未充值模板 | 财务后台、会员前台弹窗、钱包账变、充值结果、活动奖励服务、审计日志 |
| V2.12.4 | 2026-08-27 | 优化稽核布局与领取方式卡片；新增充值加倍模版管理、固定/随机倍数档位编辑及加倍稽核的游戏参与范围 | 人工优惠创建页、自动优惠模板、加倍规则服务、游戏投注流水计算、审计日志 |
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 会员与批量对象#
| 对象 | 定义 | 核心规则 |
|---|---|---|
| 单个会员 | 当前站点下唯一的 member_id | 输入后校验会员存在、站点、币种和账号状态 |
| Excel 名单 | 首列字段名为 member_id 的 .xlsx / .xls 文件 | 导入后去重；显示有效、重复、无效和跨站点数量；仅在用户确认后执行有效会员 |
| 会员分组 | 用户管理中已存在的会员分组 | 提交任务时生成成员快照；任务创建后分组成员变化不追溯 |
黑名单、风控冻结、自我排除、已注销和币种不一致会员默认排除并记录失败原因。批量任务中单个会员失败不得阻塞其他有效会员。
3.2 金额与精度#
- 所有金额使用当前站点币种，原型站点为 PHP。
- 存入金额必须大于 0，最多保留 2 位小数；金额上限由站点和角色权限共同决定。
- 后端使用十进制定点数，不使用浮点数计算奖励。
- 每次钱包入账必须生成唯一账变单号，并使用任务号 + 会员 ID + 奖励阶段作为幂等键。
3.3 稽核流水#
| 类型 | 输入 | 计算规则 | 展示方式 |
|---|---|---|---|
| 倍数 | 稽核流水倍数，允许 0，最多 2 位小数 | 所需流水 = 对应奖励金额 × 稽核倍数 | 显示“奖励金额 × N 倍” |
| 自定义 | 固定稽核流水数值，大于或等于 0，最多 2 位小数 | 所需流水 = 输入的固定数值 | 显示“固定流水 N”，输入框不显示 PHP 单位 |
基础奖励与加倍奖励分别建账、分别记录稽核要求。加倍奖励的稽核倍数只作用于加倍奖励金额。
3.4 奖励加倍口径#
- 奖励加倍仅在开关开启时生效。
- 触发起点为基础奖励已到账或已领取；起点前的充值订单不计入。
- 仅取起点后的第一笔充值成功订单进行加倍计算；失败、取消、冲正订单不计入。
- 固定倍数：额外加倍奖励 = 基础奖励金额 × 配置倍数。
- 按充值金额加倍：根据第一笔充值成功金额命中模板档位，额外加倍奖励 = 基础奖励金额 × 档位倍数，并受档位单次上限约束。
- 同一基础奖励最多产生一笔加倍奖励。加倍入账失败时允许后台按原幂等键重试，不得重复入账。
3.5 加倍模版与游戏参与口径#
- 加倍模版分为【按充值金额固定倍数】和【按充值金额随机倍数】。
- 每个档位的充值金额必须大于 0、按升序排列且不可重复；订单金额命中“小于或等于该金额的最高档位”。
- 固定倍数档位配置充值金额和加倍倍数；随机倍数档位配置充值金额、最小倍数、最大倍数和期望倍数。
- 随机倍数必须满足
最小倍数 ≤ 期望倍数 ≤ 最大倍数；实际结果保留 2 位小数，并保存模版版本、随机结果及可审计的随机摘要。 - 加倍奖励稽核只统计【游戏参与】范围内的有效投注。游戏类型之间为 OR；游戏标签之间为 OR；同时配置类型和标签时两组条件为 AND。
- 全选游戏类型且游戏标签为空等同于全部游戏。模版或人工任务提交时固化游戏范围快照，后续游戏分类或标签变化不追溯。
4. 人工优惠活动#
4.1 页面目标#
通过单个会员 ID、Excel 名单或会员分组创建人工优惠任务，配置奖励、稽核、备注及领取链路，并在提交前预览完整规则。
4.2 页面操作链路#
| 步骤 | 用户操作 | 页面响应 | 异常处理 |
|---|---|---|---|
| 1 | 进入【人工优惠活动】 | 默认选择单个会员、倍数稽核、弹窗领取 | 无创建权限时表单只读 |
| 2 | 选择单个或批量会员 | 展示会员 ID、Excel 导入或会员分组选项 | 对象无效时显示原因并禁止提交 |
| 3 | 输入存入金额并配置稽核 | 稽核类型名称与切换控件同一行左右排列；倍数/数值输入使用高识别度输入区 | 金额或稽核超限时字段报错；自定义数值不显示 PHP 单位 |
| 4 | 输入前台备注和后台备注 | 前台备注展示给会员；后台备注进入审计日志 | 后台备注必填，敏感词按站点规则校验 |
| 5 | 选择领取方式 | 使用紧凑卡片动态展开自动到账、弹窗或充值后领取配置 | 切换方式时清空上一方式未提交的条件 |
| 6 | 弹窗领取开启奖励加倍 | 奖励加倍说明与开关独占一行；展示固定倍数/充值金额加倍及游戏参与 | 关闭开关时隐藏并清空加倍配置 |
| 7 | 按充值金额加倍点击【新增模版】 | 打开【添加加倍模版】列表，可继续进入【新增模版】编辑器 | 无模版权限时仅可选择，不展示新增/编辑/删除操作 |
| 8 | 检查配置预览并点击确认派奖 | 打开二次确认，明确对象、金额和领取方式 | 权限或余额校验失败时不创建任务 |
| 9 | 确认创建 | 生成任务编号，异步处理会员，并跳转或提示查看记录 | 部分失败在会员明细中单独展示 |
4.3 字段与筛选条件#
| 字段 | 是否必填 | 控件 | 规则 |
|---|---|---|---|
| 赠送对象模式 | 是 | 单选分段 | 单个会员 / 批量会员，互斥 |
| 会员 ID | 单个时是 | 输入框 | 精确匹配当前站点会员 ID |
| 批量来源 | 批量时是 | 单选分段 | Excel 导入 / 会员分组，互斥 |
| Excel 文件 | Excel 时是 | 文件导入 | .xlsx / .xls；首列 member_id；解析后显示校验汇总 |
| 会员分组 | 分组时是 | 下拉选择 | 显示分组当前人数；提交时固化快照 |
| 存入金额 | 是 | 金额输入框 | 大于 0，2 位小数，受角色额度限制 |
| 稽核流水类型 | 是 | 单选分段 | 倍数 / 自定义；标题在左、选择控件在右，同一行展示 |
| 稽核流水倍数 | 倍数时是 | 强调型数字输入 | 大于或等于 0，最多 2 位小数；显示“倍”后缀 |
| 稽核流水数值 | 自定义时是 | 强调型数字输入 | 大于或等于 0，最多 2 位小数；不显示 PHP 或其他币种单位 |
| 前台备注 | 否 | 多行输入 | 最多 100 字，展示给会员 |
| 后台备注 | 是 | 多行输入 | 最多 200 字，仅后台可见 |
| 领取方式 | 是 | 卡片单选 | 自动领取 / 弹窗领取 / 充值后领取 |
4.4 功能明细#
| 功能 | 功能作用 | 核心规则 | 输出结果 |
|---|---|---|---|
| 单个会员校验 | 确认奖励对象可处理 | 校验站点、币种、账号状态、黑名单和角色可见范围 | 通过后显示会员基础摘要；失败时禁止提交 |
| Excel 导入 | 批量获取会员 ID | 去重并按行返回有效、重复、无效、跨站点和受限会员 | 可下载失败明细；提交只处理有效会员 |
| 会员分组 | 对指定分组批量赠送 | 创建时生成不可变成员快照；同一会员只处理一次 | 记录分组 ID、分组名、快照时间和人数 |
| 配置预览 | 降低错误派奖风险 | 实时显示对象、金额、稽核、领取方式和加倍方式 | 提交前保持与后端请求一致 |
| 加倍模版管理 | 复用充值档位规则 | 列表展示创建时间、模版名称、加倍类型、操作人；系统默认模版不可删除 | 可选择、创建、编辑或删除有权限的模版 |
| 新增模版 | 配置固定或随机倍数档位 | 动态增删档位；保存前校验金额递增、倍数范围和模版名称唯一性 | 生成不可变模版版本并回填当前选择 |
| 游戏参与 | 限定加倍奖励稽核流水来源 | 支持游戏类型全选/多选、游戏标签选择和游戏预览 | 任务保存游戏范围快照，结算仅累计命中范围的有效投注 |
| 保存草稿 | 暂存未完成配置 | 草稿不占用额度、不触发会员校验和入账 | 草稿可编辑、删除或再次提交 |
| 确认派奖 | 创建不可变任务 | 二次确认后再次做权限、额度、对象和幂等校验 | 返回任务编号和受理数量 |
| 批量处理 | 独立执行每位会员 | 单个失败不回滚其他会员；任务汇总实时更新 | 成功、失败、跳过和处理中数量 |
| 钱包入账 | 存入基础或加倍奖励 | 每个阶段使用独立幂等键；账变记录关联任务号 | 成功返回账变单号，失败可重试 |
4.5 领取方式#
4.5.1 自动领取#
任务通过校验后直接写入会员钱包。成功状态为【派发完成】；钱包失败状态为【派发失败】，允许有权限人员重试。该方式不需要奖励过期时间，也不支持前台手动领取。
4.5.2 弹窗领取#
| 字段 | 是否必填 | 规则 |
|---|---|---|
| 奖励过期时间 | 是 | 必须晚于当前站点时间；到期未领取自动变为【已过期】 |
| 奖励加倍开关 | 否 | 默认关闭；开启后显示加倍方式 |
| 加倍方式 | 开启时是 | 固定倍数 / 按充值金额加倍 |
| 固定倍数 | 固定倍数时是 | 大于 0，最多 2 位小数 |
| 加倍奖励稽核倍数 | 开启时是 | 大于或等于 0，最多 2 位小数 |
| 充值加倍模版 | 按充值金额时是 | 选择已启用且币种一致的阶梯模版；旁边展示【新增模版】按钮 |
| 模版加倍类型 | 新建模版时是 | 按充值金额固定倍数 / 按充值金额随机倍数 |
| 游戏类型 | 加倍开启时是 | 全选或多选电子游戏、棋牌、捕鱼、小游戏、视讯、体育、彩票、斗鸡 |
| 游戏标签 | 否 | 选择一个或多个游戏标签；为空表示不限标签 |
会员前台只展示当前有效、未领取奖励。领取接口必须防重复提交；领取成功后基础奖励立即入账。奖励加倍开启时，从基础奖励入账成功时间开始等待第一笔充值成功订单。
4.5.3 充值后领取#
| 类型 | 判定规则 | 未达标处理 | 达标处理 |
|---|---|---|---|
| 单笔充值 | 取派奖成功后、有效期内最先充值成功的订单金额 | 第一笔成功订单金额低于目标时奖励立即作废；后续订单不补判 | 达到目标时基础奖励自动入账 |
| 累计充值 | 累计派奖成功后、有效期内所有充值成功订单金额 | 到期累计仍不足时奖励作废 | 累计首次达到目标时基础奖励自动入账 |
充值失败、取消、超时和支付中订单不参与判定。冲正或退款发生在奖励入账前时，从累计金额中扣除；奖励已入账后的资金追回走现有风控和账变流程，本版本不自动扣回。
5. 人工优惠活动记录#
5.1 页面操作链路#
| 步骤 | 用户操作 | 页面响应 | 后续操作 |
|---|---|---|---|
| 1 | 进入记录页 | 默认查询最近 7 天任务，按创建时间倒序 | 查看汇总指标与任务列表 |
| 2 | 输入任务编号、会员 ID、领取方式、状态或时间 | 仅修改待查询条件 | 点击查询 |
| 3 | 点击查询 | 按已提交条件刷新列表并回到第 1 页 | 查看任务或导出 |
| 4 | 点击查看详情 | 打开任务配置快照和处理时间线 | 批量任务继续查看会员明细 |
| 5 | 点击导出 | 创建当前筛选条件下的异步导出任务 | 完成后通过下载中心获取 |
5.2 筛选条件#
| 条件 | 匹配方式 | 默认值 | 规则 |
|---|---|---|---|
| 任务编号 | 精确 | 空 | 支持完整任务编号 |
| 会员 ID | 精确 | 空 | 批量任务按会员处理明细反查任务 |
| 领取方式 | 枚举 | 全部 | 自动领取、弹窗领取、单笔充值、累计充值 |
| 任务状态 | 枚举 | 全部 | 草稿、处理中、待领取、等待充值、派发完成、部分失败、奖励作废、已取消 |
| 创建时间 | 时间范围 | 最近 7 天 | 按站点时间查询，最大跨度 90 天 |
5.3 功能明细#
| 功能 | 功能作用 | 核心规则 | 输出结果 |
|---|---|---|---|
| 汇总指标 | 查看当日任务、人数、金额和完成率 | 指标使用同一筛选快照；失败不显示为 0 | 今日任务、覆盖会员、奖励金额、领取/到账率 |
| 任务列表 | 查看任务级状态 | 默认创建时间倒序；分页服务端处理 | 展示对象、金额、领取方式、状态和创建时间 |
| 任务详情 | 复核不可变配置 | 展示创建时对象快照、稽核、备注、领取和加倍规则 | 配置快照与处理时间线 |
| 会员明细 | 定位批量任务单人结果 | 每位会员独立状态、失败原因、账变单号和时间 | 支持按会员 ID 查询与导出 |
| 导出 | 审计和对账 | 导出当前筛选下全部结果，不受当前页限制 | 异步文件，保留 7 天 |
6. 自动优惠活动#
6.1 用户定义：注册限时未充值#
同时满足以下条件的会员进入候选集：
- 当前站点存在注册成功结果，注册时间以服务器成功时间为准。
- 从注册成功到模板配置的限定时长结束，仍不存在充值成功订单。
- 会员处于正常状态，不在黑名单、风控冻结和自我排除范围。
- 同一会员从未命中过同一模板；模板停用期间不补发历史漏扫用户，除非重新启用时明确选择补扫。
6.2 页面操作链路#
| 步骤 | 用户操作 | 页面响应 | 异常处理 |
|---|---|---|---|
| 1 | 进入【自动优惠活动】 | 展示模板汇总、筛选和模板列表 | 无配置权限时按钮隐藏 |
| 2 | 点击新增自动优惠模板 | 打开模板配置抽屉，触发人群固定为注册限时未充值 | 必填项未完成不得启用 |
| 3 | 配置未充值时长、扫描频率、分组和有效期 | 实时显示用户定义和执行范围 | 有效期或频率无效时字段报错 |
| 4 | 配置基础奖励、领取方式、稽核和备注 | 展示自动到账或弹窗领取相关字段 | 币种和角色额度不匹配时禁止保存 |
| 5 | 开启奖励加倍并配置方式 | 展开固定倍数或充值阶梯模版，同时配置游戏参与范围 | 加倍模版停用、币种不一致或游戏范围为空时禁止启用 |
| 6 | 保存并启用 | 生成模板编号，从下一扫描周期开始执行 | 保存失败不改变原模板状态 |
| 7 | 暂停或编辑模板 | 新扫描停止或新版本在下一周期生效 | 已命中会员继续按命中时的配置快照执行 |
6.3 筛选条件#
| 条件 | 用途 | 默认值 | 规则 |
|---|---|---|---|
| 模板名称 / 编号 | 定位模板 | 空 | 名称模糊，编号精确 |
| 模板状态 | 查看运行状态 | 全部 | 草稿、运行中、已暂停、已结束 |
| 触发人群 | 查看人群类型 | 注册限时未充值 | 本版本只有该类型 |
| 创建时间 | 限定模板创建日期 | 空 | 按站点时间查询 |
6.4 功能明细#
| 功能 | 功能作用 | 核心规则 | 输出结果 |
|---|---|---|---|
| 模板基础信息 | 定义可维护模板 | 名称同站点不可重复；触发类型创建后不可变 | 模板编号、名称、状态、版本号 |
| 未充值时长 | 定义候选窗口 | 从注册成功时间起算，单位小时，大于 0 | 计算候选会员的判定时间 |
| 扫描频率 | 控制后台扫描 | 支持 5、10、30、60 分钟；同一会员命中需幂等 | 记录每次执行开始、结束和游标 |
| 适用会员分组 | 缩小候选集 | 命中时读取当前分组；命中后固化快照 | 记录分组 ID 和命中时会员属性 |
| 基础奖励领取方式 | 控制奖励到账 | 自动到账或弹窗领取；弹窗必须配置领取期限 | 生成钱包入账或可领取奖励 |
| 奖励加倍 | 提升后续充值转化 | 基础奖励到账/领取后，第一笔充值成功触发 | 生成一笔额外加倍奖励 |
| 加倍模版 | 复用固定/随机充值档位 | 自动模板与人工优惠共用站点级模版库，命中时固化模版版本 | 保存模版 ID、版本和档位快照 |
| 游戏参与 | 限定加倍稽核有效投注 | 使用游戏类型和标签交集计算，命中范围外投注不累计 | 保存游戏范围快照和累计有效投注 |
| 单日发放上限 | 控制预算 | 达到上限后剩余候选顺延到下一扫描周期，并保留候选顺序 | 记录受预算限制人数 |
| 模板版本 | 保证历史可追溯 | 修改运行中模板生成新版本；已命中会员使用旧快照 | 记录版本号、生效时间和操作人 |
| 启停控制 | 暂停新命中 | 暂停不影响已命中会员的领取或加倍链路 | 状态与操作日志 |
7. 自动优惠活动记录#
7.1 页面操作链路#
| 步骤 | 用户操作 | 页面响应 | 后续操作 |
|---|---|---|---|
| 1 | 进入记录页 | 默认展示今天命中记录和汇总指标 | 查看基础领取和加倍状态 |
| 2 | 按会员 ID、模板、状态和命中时间查询 | 刷新会员级记录并回到第 1 页 | 查看链路或导出 |
| 3 | 点击查看链路 | 展示注册、扫描命中、奖励生成、领取/到账、充值和加倍时间线 | 定位未发放原因 |
| 4 | 点击导出 | 导出当前条件下全部会员级记录 | 下载中心获取文件 |
7.2 筛选条件#
| 条件 | 匹配方式 | 默认值 | 规则 |
|---|---|---|---|
| 会员 ID | 精确 | 空 | 仅当前站点 |
| 模板 | 枚举 | 全部 | 仅展示用户有权限查看的模板 |
| 奖励状态 | 枚举 | 全部 | 待领取、已到账、已领取、已过期、派发失败 |
| 加倍状态 | 枚举 | 全部 | 未开启、待基础奖励、等待充值、已触发、触发失败、已失效 |
| 命中时间 | 时间范围 | 今天 | 最大跨度 90 天，按站点时间 |
7.3 功能明细#
| 功能 | 功能作用 | 核心规则 | 输出结果 |
|---|---|---|---|
| 扫描汇总 | 查看自动任务健康度 | 扫描人数、命中人数、排除人数和异常人数必须可对账 | 每次执行记录和当日汇总 |
| 会员命中记录 | 追踪单个会员 | 同模板同会员唯一；保存命中时配置快照 | 命中编号、会员、模板、奖励和状态 |
| 奖励链路 | 解释当前状态 | 串联注册、无充值判定、奖励、领取、充值和加倍阶段 | 时间线与各阶段业务单号 |
| 失败重试 | 处理技术失败 | 仅钱包或消息技术失败可按原幂等键重试；业务不满足不可重试 | 重试次数、结果和最后错误码 |
| 导出 | 支持财务对账 | 导出当前筛选全部记录，金额字段保留币种和精度 | 异步文件与下载审计 |
8. 状态机与异常规则#
8.1 人工任务状态#
| 状态 | 进入条件 | 可执行操作 | 终态 |
|---|---|---|---|
| 草稿 | 保存但未提交 | 编辑、删除、提交 | 否 |
| 处理中 | 任务已创建，会员正在校验或入账 | 查看进度 | 否 |
| 待领取 | 弹窗奖励已生成 | 会员领取、后台取消未触达奖励 | 否 |
| 等待充值 | 充值后领取或加倍等待充值 | 查看充值判定 | 否 |
| 派发完成 | 奖励已成功入账 | 查看、导出 | 是 |
| 部分失败 | 批量任务部分会员失败 | 导出失败、重试技术失败 | 是 |
| 奖励作废 | 过期或单笔充值未达标 | 查看原因 | 是 |
| 已取消 | 未开始任务被有权限人员取消 | 查看 | 是 |
8.2 关键异常#
| 场景 | 系统处理 | 用户提示 / 记录 |
|---|---|---|
| 重复提交 | 根据请求幂等键返回原任务 | “任务已创建，请勿重复提交” |
| 会员跨站点 | 不处理该会员 | 失败原因为“会员不属于当前站点” |
| 批量处理中角色额度被调低 | 已受理任务继续按创建时权限快照执行 | 审计日志保留权限快照 |
| 钱包服务超时 | 状态保持处理中，按原幂等键重试 | 超过重试阈值变为派发失败 |
| 领取与过期同时发生 | 以服务器原子状态转换为准 | 只能有一个成功结果 |
| 充值回调重复 | 按充值订单号去重 | 不重复累计、不重复派发 |
| 模板扫描任务重跑 | 使用模板 + 会员 + 模板版本唯一键 | 不重复命中 |
9. 数据、接口与审计#
9.1 核心数据对象#
| 对象 | 关键字段 | 说明 |
|---|---|---|
| 人工优惠任务 | task_id、site_id、target_type、reward_amount、audit_rule、claim_mode、creator_id、status | 任务级不可变配置 |
| 任务会员明细 | task_id、member_id、target_snapshot、reward_status、failure_code、ledger_id | 批量任务会员级结果 |
| 可领取奖励 | reward_id、member_id、expire_at、claimed_at、claim_status | 弹窗领取状态 |
| 充值触发条件 | reward_id、deposit_mode、target_amount、valid_until、first_order_id、cumulative_amount | 单笔或累计充值判定 |
| 加倍奖励 | reward_id、bonus_mode、bonus_value、template_version、trigger_order_id、bonus_ledger_id | 额外奖励计算与入账 |
| 自动优惠模板 | template_id、version、no_deposit_hours、scan_interval、reward_config、status | 自动扫描和奖励配置 |
| 自动命中记录 | hit_id、template_id、template_version、member_id、registered_at、hit_at、status | 会员命中与链路追踪 |
9.2 接口要求#
- 创建接口必须接收客户端幂等键并返回稳定的任务编号。
- 批量导入采用“上传解析—确认有效名单—创建任务”三阶段，不允许上传后直接入账。
- 充值判定消费充值成功结果事件，以订单号幂等；模板扫描读取注册成功与充值成功的业务事实。
- 列表使用服务端分页；导出使用已提交筛选快照，不读取页面未提交输入。
- 所有时间存 UTC，页面按站点时区展示；有效期比较也使用站点时区转换后的明确 UTC 时间。
9.3 审计日志#
必须记录创建、编辑草稿、提交、取消、模板启停、模板版本变更、技术重试和导出。日志至少包含操作人、角色、站点、操作时间、对象编号、变更前后配置、权限快照、请求来源 IP 和结果。
10. 非功能要求#
| 类别 | 要求 |
|---|---|
| 性能 | 单任务列表查询 P95 ≤ 2 秒；单个会员创建受理 P95 ≤ 1 秒；批量任务 5 万会员内 5 分钟完成受理与分片 |
| 可用性 | 创建和钱包入账链路月可用性 ≥ 99.9%；模板扫描支持断点续跑 |
| 一致性 | 任务、奖励、钱包账变和记录页可按业务单号对账；不得出现状态完成但无账变单号 |
| 安全 | 金额和批量操作受角色额度控制；导出文件带水印并记录下载审计 |
| 可观测性 | 监控创建成功率、入账成功率、领取率、充值触发率、扫描延迟、重复拦截数和失败码分布 |
| 兼容性 | 后台适配 1280px 及以上桌面；关键表格支持横向滚动；表单支持键盘操作和明确标签 |
11. 验收标准#
11.1 人工优惠#
- 财务管理可进入【人工优惠活动】，顶部可切换到【人工优惠活动记录】。
- 单个会员可通过会员 ID 创建奖励；批量可通过 Excel 或会员分组创建。
- 稽核选择倍数时只显示倍数输入；选择自定义时只显示固定数值输入。
- 稽核类型标题与切换选择同一行左右布局；稽核倍数/数值输入区具有明显边框和字号，自定义数值不带 PHP 单位。
- 三个领取方式选择卡片采用紧凑尺寸；弹窗领取的奖励加倍说明和开关独占一行。
- 按充值金额加倍可打开模版列表，并继续新建固定或随机倍数模版；动态增删档位和保存回填正常。
- 游戏参与支持全选/多选游戏类型、选择游戏标签和预览；仅命中范围的有效投注计入加倍稽核。
- 自动领取创建成功后金额自动到账，并生成唯一账变记录。
- 弹窗领取展示过期时间；到期前只能领取一次，到期后不可领取。
- 奖励加倍关闭时不生成加倍条件；开启时固定倍数和按充值金额模版互斥。
- 固定倍数与充值阶梯模版均按第一笔充值成功订单触发一次，并生成独立稽核要求。
- 单笔充值以最先充值成功订单判断，低于目标立即作废；累计充值达到目标时自动派发。
- 批量任务单个会员失败不影响其他会员，记录页可查询和导出失败原因。
11.2 自动优惠#
- 财务管理可进入【自动优惠活动】，顶部可切换到【自动优惠活动记录】。
- 可新增“注册限时未充值”模板并配置未充值时长、扫描频率、会员分组和有效期。
- 可配置自动到账或弹窗领取、基础奖励、稽核、备注、单日上限和排除人群。
- 同一会员同一模板只能命中一次，模板重扫或回调重复不得重复赠送。
- 奖励加倍开启后按固定倍数或充值金额模板计算，并在记录页展示完整链路。
- 暂停模板后不再产生新命中；已命中会员继续按命中时配置执行。
- 模板修改产生新版本，历史记录保留原版本配置快照。
12. 回归范围与已知问题#
12.1 回归重点#
- V2.12.0 原有财务菜单、埋点系统 10 页、用户 360、埋点管理和事件查询不受影响。
- 站点、币种、会员分组和角色额度在单个、Excel、分组和自动模板四类入口保持一致。
- 奖励基础入账和加倍入账分别幂等；重复点击、重复回调和任务重跑不重复加款。
- 页面筛选、分页、导出与详情使用同一已提交条件。
- 所有奖励状态均能关联任务号、会员 ID、充值订单号和钱包账变单号。
- 模版版本、随机倍数结果、游戏类型/标签快照和有效投注累计结果可完整追溯。
12.2 已知问题 / 待产品确认#
- “固定倍数”的业务口径当前定义为“额外奖励 = 基础奖励 × 配置倍数”；如业务期望总奖励为基础奖励的 N 倍，应在开发前统一调整为“额外奖励 = 基础奖励 ×（N-1）”。
- 自动模板弹窗奖励的前台视觉和多奖励并存排序沿用现有活动弹窗规范，本版本原型只覆盖后台配置与记录。
- 批量 Excel 最大 5 万行作为本版实施上限；更大规模名单需拆分任务或后续改为对象存储异步导入。
- 随机倍数的概率分布算法和期望倍数收敛窗口需研发、风控在技术评审时锁定；原型已覆盖字段、校验和审计要求。