邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
76 lines
4.8 KiB
Markdown
76 lines
4.8 KiB
Markdown
## 目标与边界
|
||
- 建立“任务中心”独立域（不改动现有`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/任务中心/`生成对齐/设计/任务分解文档，并开始增量实现新域。 |