邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
4.8 KiB
4.8 KiB
目标与边界
- 建立“任务中心”独立域（不改动现有
Activities抽奖域）。 - 支持任务类型：首日下单、订单里程碑（完成N单阶梯）、邀请有效好友人数N。
- 奖励类型：积分、优惠券、道具卡、称号；统一走发奖服务，库存安全与幂等。
域与架构
- 新域：
TaskCenter（目录建议：internal/api/task_center、internal/service/task_center、internal/repository/mysql/task_center）。 - 模式：事件驱动 + 调度补偿；与抽奖域并行、互不侵入。
- 统一发奖：复用
internal/service/user/reward_grant.go；任务域自有进度与日志。
核心数据模型（新表）
Tasks：任务基础信息（id/name/description/status/start_time/end_time/visibility）。TaskTiers：任务档位（task_id/tier_id/threshold/operator(metric: first_order|order_count|invite_count)/repeatable/priority）。TaskRewards：档位奖励映射（task_id/tier_id/reward_type(points|coupon|item_card|title)/reward_payload/quantity）。UserTaskProgress：用户进度（user_id/task_id/metrics{order_count,invite_count,first_order}、claimed_tiers[]）。TaskEventLogs：事件与发放日志（event_id/source(order_id|invite_id)/user_id/task_id/tier_id/status/result/enforced_idempotency_key）。UserTitles（如无现表）：用户称号（user_id/title_id/source(task_id/tier_id)）。若已有虚拟Inventory可用则复用。
任务规则与判定
- 首日下单：事件
OrderPaid且为用户首次有效订单；档位一次性发放（repeatable=false）。 - 订单里程碑：累计
order_count>=[1,3,5,10]，每档一次（repeatable=true_once_per_tier）。 - 邀请有效好友：
InviteSuccess（有效：注册+首单），累计invite_count>=[1,5,10]。 - 规则DSL：存于
Tasks.conditions_schema或按TaskTiers结构硬编码字段，支持窗口（活动期/注册日起）。
事件处理流程
- 实时：
- 订阅
OrderPaid、InviteSuccess→更新UserTaskProgress→匹配达标档位→查TaskEventLogs幂等→user.GrantReward(...)→记日志与claimed_tiers。
- 订阅
- 幂等：
idempotency_key=user_id + task_id + tier_id + event_id。 - 逆向事件：
OrderRefunded/Cancelled→回滚进度（不回收已发奖励，策略可配置，默认不回收）。
奖励发放映射
- 积分：安全增加余额；入账日志。
- 优惠券：派发券码（有效期/叠加规则从券系统读取）。
- 道具卡：发卡入用户
Inventory；与抽奖加成逻辑无耦合，仅作为奖励资产。 - 称号：新建
Titles/UserTitles或复用Inventory虚拟类型；展示端读取用户当前称号。
管理端接口（新路由前缀/api/admin/task-center）
POST /tasks创建任务PUT /tasks/:id修改、DELETE /tasks/:id删除POST /tasks/:id/tiers批量配置档位与奖励GET /tasks/:id/progress任务进度与发放统计- 复用券/卡管理：
/api/admin/system_coupons、/api/admin/system_item_cards
APP端接口（新路由前缀/api/app/task-center）
GET /tasks任务列表与规则说明GET /tasks/:id/progress我的进度与已领奖档位POST /tasks/:id/claim（可选手动领取，默认自动发放）GET /rewards统一查看已获奖励（或复用现有奖励中心）
调度与补偿
- 新增任务域调度器：周期对账
UserTaskProgress与事件流，补漏发奖，生成统计报表。 - 指标快照：每日汇总订单/邀请指标与发奖结果，便于风控与运营复盘。
风控与限制
- 邀请有效性：设备指纹、手机号/实名校验、首单达成才计数。
- 刷单检测：黑名单、频次限制、风控评分；达到阈值的用户不触发发奖。
- 限制：每日发奖上限、IP/设备限流、防重入保护。
集成与兼容
- 与抽奖域零耦合：不读写
Activities/ActivityRewardSettings/DrawLogs。 - 统一发奖：仅调用
internal/service/user/reward_grant.go；券/卡系统复用现有接口。 - 路由与权限：参考
internal/router/router.go风格新增task-center分组。
验收标准
- 三类任务均可正确识别达标并一次性/阶梯发奖；幂等无重复。
- 奖励入账正确，库存扣减准确；日志完备可追溯。
- 调度能补漏；风控能拦截异常；性能P95<200ms。
实施里程碑
- M1 新域目录/数据模型/管理端CRUD（不影响现有抽奖）。
- M2 接入
OrderPaid、实现订单里程碑任务与APP进度查询。 - M3 首日下单与邀请N任务、称号奖励落地。
- M4 调度补偿/对账与统一奖励查看页面。
- M5 风控与监控报警完善、压测与性能优化。
确认后，我将按6A工作流在docs/任务中心/生成对齐/设计/任务分解文档，并开始增量实现新域。