## 目标与边界 - 建立“任务中心”独立域(不改动现有`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/任务中心/`生成对齐/设计/任务分解文档,并开始增量实现新域。