zfc/bindbox-game
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
bindbox-game/docs/活动大厅任务中心规则梳理.md
win e0db8751f3 任务中心的问题
2026-02-27 16:07:12 +08:00

8.9 KiB
Raw Permalink Blame History

活动大厅（任务中心）规则与计算逻辑梳理

1. 后端数据结构与配置来源

  • 任务、档位、奖励主表：Task、TaskTier、TaskReward、UserTaskProgress 与 TaskEventLog 分别落在 task_center_tasks、task_center_task_tiers、task_center_task_rewards、task_center_user_progress、task_center_event_logs 表中，字段包含任务级/档位级限额、活动绑定、扩展参数 JSON 以及幂等键等核心信息（bindbox_game/internal/repository/mysql/task_center/models.go:10-95）。
  • 限额与扩展字段迁移：
    • migrations/task_level_quota.sql:1-12 在 2026-02-16 引入任务级 quota/claimed_count，同时移除旧的档位限额。
    • migrations/20260206_add_task_tier_quota.sql:1-6 再次为档位恢复独立限额字段，用于任务总限量之外的档位限量。
    • migrations/20251223_add_user_invites_effective_columns.sql:1-4 添加 extra_params、effective_invite_count 以及邀请有效性相关列，为后续“新用户限制”等规则提供数据面支撑。
  • 管理端 CRUD & 配置 API：internal/api/task_center/admin.go 提供任务创建、修改、删除、档位/奖励配置、模拟事件与奖励发放统计接口（admin.go:14-486）。所有接口最终落到 task_center/service.go 的 CreateTask、UpsertTaskTiers、UpsertTaskRewards 等方法（service.go:953-1162），确保配置变更会触发缓存失效。

2. 运行期进度计算流程

  • 时间窗口规范化：normalizeWindow / normalizeWindowStrict 将非法或空窗口统一视为 lifetime（service.go:200-217），computeTimeWindow 根据 daily/weekly/monthly/activity_period 返回具体起止时间，缺省为不限（service.go:500-525）。
  • 订单指标采集：fetchOrderMetricRows 联结订单、期次、活动表，并按活动聚合抽赏次数/票价或订单金额（service.go:223-247）；calculateEffectiveAmount / aggregateOrderMetrics 负责将抽赏次数 × 票价或订单实付换算成有效金额，支持去重订单总量与活动内统计（service.go:249-281）。
  • 邀请指标采集：countInvites、countInvitesForActivities 分别处理单一活动窗口和多活动聚合，只有邀请人邀请的用户在目标活动内完成已支付订单后才计入特定活动任务（service.go:283-346）。
  • 任务列表出参：ListTasks 默认过滤启用且可见的任务（App 端）并预加载档位/奖励，同时根据 task_center_task_rewards 关联优惠券、道具卡、称号名称（service.go:348-498）。
  • 按窗口分组统计进度：GetUserProgress 会先查询任务与其所有档位，根据 (window, activity_id) 组合拉取订单/邀请数据，产出 TierProgressMap（每个档位独立窗口内订单/金额/邀请）与 SubProgress（按活动粒度的订单汇总），同时聚合全局订单/邀请指标以及已领取档位列表（service.go:528-668）。

3. 达成校验与领取路径

  • 前置校验：ClaimTier 首先调用 GetUserProgress 获取窗口化进度，并加载目标档位/任务最新配置（service.go:670-686）。
  • Redis 限流：对于绑定 ActivityID 的档位，会抢占 tc:claim_lock:{user_id}:{activity_id} 避免并发重复领（service.go:688-700）。
  • 指标达成判定：优先读取 TierProgressMap 中窗口内数值，其次使用 SubProgress → 全局进度回退；支持 >=/= 操作符，对 first_order 直接使用布尔值（service.go:702-752）。
  • 跨任务资源占用校验：calculateCrossTaskConsumedThreshold 会收集同活动+同指标的其他任务已领取档位，按任务窗口是否重叠、创建时间先后过滤后累积最大门槛值，若 currentValue < consumed + 自身阈值 则拒绝领取（service.go:754-939）。
  • 限额 & 状态更新：领取前更新任务级别 claimed_count，若已达 quota 返回“奖励已领完”（service.go:788-799）；奖励发放成功后，事务性地在 task_center_user_progress 中追加 tier_id，幂等写入 claimed_tiers JSON（service.go:801-851）。

4. 奖励发放与事件机制

  • 奖励发放器：grantTierRewards 会根据 task_id + tier_id 查询奖励列表、构造 idempotency_key 并写入 task_center_event_logs，支持积分、优惠券、道具卡、称号、游戏票、实物商品等类型，并对 quantity 与 payload 内数量做“优先取 r.Quantity”策略修复（service.go:1400-1558）。
  • 异步事件：
    • OnOrderPaid / OnInviteSuccess 先尝试投递到 Redis 队列，否则直接同步处理；processOrderPaid 只在订单状态为已支付时并发写入邀请人累计金额，同时加 Redis 幂等锁防止 24 小时内重复处理（service.go:1165-1243）。
    • StartWorker 在 Redis 队列可用时启动 5 个 goroutine 消费 order_paid 与 invite_success 事件，最终调用 processOrderPaid / processInviteSuccess（worker.go:12-80）。
  • 触发入口（上游链路）：
    • 微信支付回调完成后，后台会异步执行 _ = h.task.OnOrderPaid(...)，确保真实支付订单刷新任务进度（internal/api/pay/wechat_notify.go:294-305）。
    • 0 元抽奖订单、虚拟玩法等也会在服务器端模拟支付后触发 OnOrderPaid（internal/api/activity/lottery_app.go:458-464、internal/api/activity/matching_game_app.go:203-206）。
    • 新用户带邀请码登录成功后，若存在邀请人则调用 OnInviteSuccess 记入邀请进度（internal/api/user/login_app.go:78-83）。
    • 管理端提供 /admin/task_center/simulate/order_paid 与 /simulate/invite_success 便于调试触发（internal/api/task_center/admin.go:315-369）。

5. 小程序端消费链路

  • API 封装：getTasks / getTaskProgress / claimTaskReward 直接映射到 App 端任务中心列表、进度、领取接口（bindbox-mini/api/appUser.js:262-271）。
  • 入口触达：个人中心“常用功能”列表包含「任务中心」入口，点击跳转至 pages-user/tasks/index.vue 页面（bindbox-mini/pages/mine/index.vue:140-184）。
  • UI 与状态处理：
    • 页面顶部展示订单数、邀请数、首单状态等汇总统计，同时支持空态、骨架加载（pages-user/tasks/index.vue:1-56）。
    • 任务卡片内根据 task.quota/claimed_count、tier.remaining、userProgress.claimedTiers 和 tier_activity_id 决定显示“已领完”“可领取”“进行中”等状态（pages-user/tasks/index.vue:57-150、220-379）。
    • taskProgress 为每个任务缓存独立进度，normalizeSubProgress + getSubProgress* 系列方法根据 sub_progress（活动维度进度）渲染子进度条，确保与后端 TierProgressMap 字段语义一致（pages-user/tasks/index.vue:222-479、590-666）。
    • fetchData 并行拉取任务与进度，首个任务默认展开，领取成功后本地更新 claimedTiers 并 toast 提示（pages-user/tasks/index.vue:515-589、481-505）。
  • 交互约束：未登录/未缓存用户信息会弹出“请先登录”提示并跳转登录页，确保任务接口只在持有 token 的情况下访问（pages-user/tasks/index.vue:187-209）。

6. 测试覆盖与验证建议

  • 单元/集成测试：
    • TestListTasks_FilterByStatusAndVisibility 验证 App 列表只返回启用且可见的任务（internal/service/task_center/list_tasks_filter_test.go:11-95）。
    • service_test.go 中的场景覆盖活动有效期窗口统计与跨任务占用判断，确保 TierProgressMap 与 calculateCrossTaskConsumedThreshold 行为正确（internal/service/task_center/service_test.go:350-514）。
    • TestInviteLogicSymmetry 通过 SQLite 集成测试验证全局/特定活动邀请数统计与订单联动逻辑（internal/service/task_center/invite_logic_test.go:10-80）。
  • 建议的手工校验：
    1. 使用管理端创建带活动绑定与不同窗口的任务→调用 /api/app/task-center/tasks 与 /progress/{user} 核对 sub_progress、tier_progress_map 是否如预期。
    2. 在沙箱环境支付一笔订单或通过模拟接口触发 OnOrderPaid，确认 Redis 幂等锁与任务限额的日志输出，并在 task_center_event_logs 中观察发放记录。
    3. 在小程序端登陆真实账号，完成任务条件后点击“领取”，应同步看到 task.quota / tier.remaining 与“已领取”状态更新，且后台奖励统计接口 /admin/task_center/tasks/{id}/reward-stats 的计数随之增加。
  • 假设与范围：本文将“活动大厅”视为任务中心在小程序端的 UI 展示，不涉及其他独立模块；仅梳理现有逻辑，不包含代码改动。
  • 交付复核：若需要进一步变更规则，可从本文档列出的结构/流程入手定位受影响的函数与 API。