HI-VPN/hi-server
4
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

新功能(#3): 抽奖活动 Stage 1 骨架（DB + 规则引擎 + Handler 抽象）

Browse Source 
Closes HIF-3

Stage 1 骨架：7 张表迁移 + 门槛规则引擎 + 加权选奖 + 次数入账/消耗（幂等）+ 发奖 handler 抽象与注册表。

- 单测覆盖 75.5%（未覆盖行 = stub handler ErrNotImplemented，合理）
- CI 全绿（构建/Vet/测试 + golangci-lint）
- 骨架不接入真实业务，vpn_duration/commission handler 在 Dispatch 中返回 ErrNotImplemented；合并后线上零变更

架构师 review 通过，4 项决策已在 issue 上给出：
1. 邀请转化语义 = 首次付款激活
2. 佣金日志类型 = 新增 CommissionTypeLottery=339
3. 家庭组归属 = 穿透到 owner
4. 管理端 IP 白名单 = 不做（推到 nginx/ingress 层）

后续 PR B/C 补真实业务对接 + 用户 API + 后台 CRUD + 集成/并发/概率测试。
This commit is contained in:
shanshanzhong147
2026-07-08 20:05:05 -07:00
committed by GitHub
parent d2710d356f
commit 9933d34bdd
12 changed files with 1495 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
initialize/migrate/database/02156_lottery_stage1.down.sql
+11
View File
@@ -0,0 +1,11 @@
-- 02156 抽奖活动 Stage 1 回滚
-- 反向删除 7 张表。因存在业务耦合数据（用户次数、抽奖记录、快照）在生产回滚前
-- 必须先备份，回滚只删表结构。执行顺序按外键依赖反向：先删依赖别人的，再删被依赖的。
DROP TABLE IF EXISTS `lottery_eligibility_snapshot`;
DROP TABLE IF EXISTS `lottery_prize_snapshot`;
DROP TABLE IF EXISTS `lottery_draw`;
DROP TABLE IF EXISTS `lottery_chance_grant`;
DROP TABLE IF EXISTS `lottery_chance_balance`;
DROP TABLE IF EXISTS `lottery_prize`;
DROP TABLE IF EXISTS `lottery_activity`;
initialize/migrate/database/02156_lottery_stage1.up.sql
+125
View File
@@ -0,0 +1,125 @@
-- 02156 抽奖活动 Stage 1（后端核心闭环）
--
-- 新建 7 张表 + 全部索引 + 幂等约束。
-- 幂等设计：全部 `CREATE TABLE IF NOT EXISTS`；索引通过 INFORMATION_SCHEMA 预检
-- 后再补齐。可重复执行不报错，符合 `doc/development-workflow-zh.md` 迁移规范。
--
-- 关键唯一索引（都是并发/幂等正确性的核心，切勿删）：
-- 1) lottery_prize (activity_id, slot) — 一个活动一个位置只能挂一个奖品
-- 2) lottery_draw (user_id, client_nonce) — 用户端幂等键，重放同一 nonce 返回同一 draw
-- 3) lottery_chance_balance (user_id, activity_id) — 每人每活动一个次数余额行
-- 4) lottery_chance_grant (activity_id, source, source_ref) — 次数入账幂等键（避免同订单发两次机会）
-- 5) lottery_prize_snapshot (draw_id) — 抽奖时刻的奖品快照，1:1
-- 6) lottery_eligibility_snapshot (draw_id) — 抽奖时刻的门槛评估快照，1:1
CREATE TABLE IF NOT EXISTS `lottery_activity` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`title` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '活动标题',
`description` TEXT COMMENT '活动描述（Markdown）',
`start_at` DATETIME NOT NULL COMMENT '开始时间',
`end_at` DATETIME NOT NULL COMMENT '结束时间',
`status` VARCHAR(16) NOT NULL DEFAULT 'draft' COMMENT '状态：draft / running / paused / ended',
`grid_size` TINYINT NOT NULL DEFAULT 9 COMMENT '前端九宫格数量（3/6/8/9/12）',
`eligibility` JSON NOT NULL COMMENT '参与门槛（AND/OR 嵌套规则）',
`chance_sources` JSON NOT NULL COMMENT '次数来源列表（daily_signin / new_subscription / invite_success / manual_grant）',
`unmet_action` VARCHAR(32) NOT NULL DEFAULT 'block' COMMENT '未达门槛策略：block / show_reason',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`deleted_at` DATETIME DEFAULT NULL COMMENT '软删除时间',
PRIMARY KEY (`id`),
KEY `idx_status_time` (`status`, `start_at`, `end_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽奖活动';
CREATE TABLE IF NOT EXISTS `lottery_prize` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`activity_id` BIGINT UNSIGNED NOT NULL COMMENT '所属活动 ID',
`slot` TINYINT NOT NULL COMMENT '九宫格位置（0-based）',
`type` VARCHAR(32) NOT NULL COMMENT '奖品类型：vpn_duration / commission / balance / gift_amount / coupon / points / encrypted / physical / manual_other / none',
`name` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '奖品名称',
`icon_url` VARCHAR(512) NOT NULL DEFAULT '' COMMENT '奖品图标 URL',
`config` JSON NOT NULL COMMENT '类型专属配置（如 {"duration_days":3}）',
`weight` INT NOT NULL DEFAULT 0 COMMENT '加权随机权重（0 表示不参与随机）',
`total_stock` BIGINT COMMENT '总库存（NULL 表示无限）',
`remaining_stock` BIGINT COMMENT '剩余库存（NULL 表示无限，与 total_stock 同 NULL）',
`is_fallback` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否为保底奖（1: 是，抽中限量奖降级到此；weight 被忽略）',
`version` BIGINT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_activity_slot` (`activity_id`, `slot`),
KEY `idx_activity_fallback` (`activity_id`, `is_fallback`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽奖奖品定义';
CREATE TABLE IF NOT EXISTS `lottery_chance_balance` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户 ID',
`activity_id` BIGINT UNSIGNED NOT NULL COMMENT '活动 ID',
`remaining` BIGINT NOT NULL DEFAULT 0 COMMENT '剩余次数（下一次抽奖要读这里并 -1）',
`total_earned` BIGINT NOT NULL DEFAULT 0 COMMENT '累计入账次数（审计用）',
`total_spent` BIGINT NOT NULL DEFAULT 0 COMMENT '累计消耗次数（审计用）',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_user_activity` (`user_id`, `activity_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽奖次数余额';
CREATE TABLE IF NOT EXISTS `lottery_chance_grant` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`user_id` BIGINT UNSIGNED NOT NULL COMMENT '发放对象用户 ID',
`activity_id` BIGINT UNSIGNED NOT NULL COMMENT '活动 ID',
`source` VARCHAR(32) NOT NULL COMMENT '触发源：daily_signin / new_subscription / invite_success / manual_grant',
`source_ref` VARCHAR(128) NOT NULL COMMENT '外部业务幂等键（如 order_no、"signin:{yyyymmdd}"、"manual:{admin_id}:{ts}"）',
`amount` INT NOT NULL DEFAULT 0 COMMENT '本次发放次数',
`expires_at` DATETIME DEFAULT NULL COMMENT '本次入账的到期时间（NULL 表示不过期）',
`granted_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_activity_source_ref` (`activity_id`, `source`, `source_ref`),
KEY `idx_user_activity_expires` (`user_id`, `activity_id`, `expires_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽奖次数入账流水（幂等键 = activity_id+source+source_ref）';
CREATE TABLE IF NOT EXISTS `lottery_draw` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户 ID',
`activity_id` BIGINT UNSIGNED NOT NULL COMMENT '活动 ID',
`client_nonce` VARCHAR(64) NOT NULL COMMENT '前端幂等键（UUID）',
`prize_id` BIGINT UNSIGNED DEFAULT NULL COMMENT '中奖奖品 ID（未中奖为 NULL）',
`is_win` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否中奖（未中奖=谢谢参与，也会写 draw）',
`dispatch_state` VARCHAR(16) NOT NULL DEFAULT 'none' COMMENT '发放状态：none(无需发) / auto_claimed(自动已发) / pending_claim(等待人工领) / paid(人工发完) / expired(超时未领) / failed',
`dispatch_error` TEXT COMMENT '发放失败的错误信息（仅失败时写）',
`dispatched_at` DATETIME DEFAULT NULL COMMENT '发放完成时间（自动类=事务提交时；人工类=运营录入后）',
`drawn_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '抽奖时间',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_user_nonce` (`user_id`, `client_nonce`),
KEY `idx_user_time` (`user_id`, `drawn_at`),
KEY `idx_activity_win_time` (`activity_id`, `is_win`, `drawn_at`),
KEY `idx_activity_prize` (`activity_id`, `prize_id`),
KEY `idx_dispatch_state` (`dispatch_state`, `drawn_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽奖记录';
CREATE TABLE IF NOT EXISTS `lottery_prize_snapshot` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`draw_id` BIGINT UNSIGNED NOT NULL COMMENT '抽奖记录 ID',
`prize_id` BIGINT UNSIGNED NOT NULL COMMENT '奖品 ID（快照当时的 id）',
`slot` TINYINT NOT NULL COMMENT '九宫格位置（快照）',
`type` VARCHAR(32) NOT NULL COMMENT '奖品类型（快照）',
`name` VARCHAR(128) NOT NULL COMMENT '奖品名称（快照）',
`config` JSON NOT NULL COMMENT '类型专属配置（快照）',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_draw_id` (`draw_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽奖时刻的奖品快照（对账/纠纷用）';
CREATE TABLE IF NOT EXISTS `lottery_eligibility_snapshot` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`draw_id` BIGINT UNSIGNED NOT NULL COMMENT '抽奖记录 ID',
`user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户 ID',
`activity_id` BIGINT UNSIGNED NOT NULL COMMENT '活动 ID',
`passed` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否通过门槛（未通过=拒绝抽奖或前端提示）',
`unmet_reasons` JSON COMMENT '未通过项（rule/hint/current/required）',
`evaluated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_draw_id` (`draw_id`),
KEY `idx_user_activity_time` (`user_id`, `activity_id`, `evaluated_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽奖时刻的门槛评估快照（对账/申诉用）';