hyapp-server/docs/幸运礼物实现文档.md

幸运礼物实现文档

本文档描述当前代码里的幸运礼物服务端实现。旧的产品方案、重构分步文档和早期 activity-service 开发文档已经下线；服务端实现以后续本文档为准，Flutter App 对接以 幸运礼物 Flutter 对接 为准。

当前实现不兼容旧玩法假设。幸运礼物以 pool_id 为规则维度，以 activity-service 为规则、抽奖、奖池、RTP 窗口、风控、抽奖事实和 outbox owner；扣费和返奖入账属于 wallet-service；房间状态、热度、礼物榜和房间 outbox 属于 room-service。

一、核心原则

功能点	当前规则	代码函数实现	验收
服务边界	activity-service 只做幸运礼物规则和开奖结果，不改 Room Cell，不直接改钱包表；返奖必须通过 wallet-service gRPC	services/activity-service/internal/service/luckygift.Service.Draw、services/activity-service/internal/service/luckygift.Service.processDrawOutbox、services/room-service/internal/room/service.Service.SendGift	已验收：抽奖在扣费后执行，正常返奖走同步 wallet gRPC 快路径，outbox 只做补偿和表现
规则维度	线上规则按 pool_id 读取最新版本，不按真实 gift_id 读取旧规则	Repository.GetLuckyGiftRuleConfig、Repository.getLuckyGiftRuleConfig、luckyPoolID	已验收：代码读取 lucky_gift_rule_versions 和 lucky_gift_stage_tiers
返奖率控制	后台发布时校验阶段期望 RTP 落在 target_rtp_ppm ± control_band_ppm，运行时不按 RTP 缺口改概率	validateRuleConfig、validateRuleStageExpectedRTP、selectLuckyCandidate	已验收：发布校验函数存在，候选随机只过滤不可支付档
用户体验	用户阶段按累计金币流水折算等价抽数，避免不同价格礼物用真实抽数误判阶段	luckyEquivalentDraws、luckyExperiencePool、getLuckyUserStateForUpdate	已验收：状态表维护 cumulative_wager_coins、equivalent_draws、loss_streak
批量抽奖	gift_count=N 表示抽 N 次；每一抽按单份金币计算奖励，响应返回总中奖倍数和总奖励	executeLuckyGiftDrawBatch、luckyDrawUnitSpend、stageLuckyBatchDraw、luckyAggregateDrawResults	已验收：单测覆盖 10 抽返回总倍数 11x 的聚合逻辑
聚合发放	批量抽奖可以有 N 条抽奖明细，但正常路径只同步给钱包加币 1 次；outbox 保留 1 条聚合事件用于补偿和表现	insertLuckyAggregateDrawOutbox、creditLuckyGiftRewardFastPath、decodeDrawOutboxPayload、MarkLuckyGiftDrawsGranted	已验收：批量只按聚合 draw 发放，worker 遇到已 granted 会跳过钱包

二、配置模型

2.1 Proto 契约

功能点	字段或 RPC	代码函数实现	验收
App/房间抽奖元信息	LuckyGiftMeta，包含 command_id、pool_id、gift_count、coin_spent、paid_at_ms、visible_region_id	api/proto/activity/v1/activity.proto LuckyGiftMeta、LuckyGiftServer.ExecuteLuckyGiftDraw	已验收：房间送礼只把 wallet 已结算 coin_spent 传给 activity
抽奖结果	LuckyGiftDrawResult，包含 multiplier_ppm、effective_reward_coins、reward_status、wallet_transaction_id、coin_balance_after、RTP 窗口和阶段字段	luckyDrawResultToProto、luckyGiftResultFromProto	已验收：room 返回 LuckyGift 字段给送礼用户，中奖同步成功时可直接刷新余额
后台规则	LuckyGiftRuleConfig、LuckyGiftRuleStage、LuckyGiftRuleTier	luckyRuleConfigFromProto、luckyRuleConfigToProto、configToProto、configFromProto	已验收：后台百分比和倍率在 handler 内转成 ppm
后台审计	ListLuckyGiftDraws、GetLuckyGiftDrawSummary	AdminLuckyGiftServer.ListLuckyGiftDraws、AdminLuckyGiftServer.GetLuckyGiftDrawSummary	已验收：按 pool_id/gift_id/user_id/room_id/status 查询

2.2 配置字段语义

字段	业务含义	代码函数实现	验收
target_rtp_ppm	基础返奖目标，例如 950000 表示 95%	validateRuleConfig、luckyRuntimeConfigFromRuleConfig	已验收：发布入口限制 10% 到 99%
pool_rate_ppm	每笔扣费进入基础奖池的比例，必须不低于目标 RTP	validateRuleConfig、luckyBasePoolIn、creditLuckyBasePools	已验收：低于目标 RTP 会拒绝发布
settlement_window_wager	RTP 结算窗口金币流水，运行时按参考价格折算窗口抽数	luckyRuntimeConfigFromRuleConfig、luckyCeilDiv	已验收：窗口抽数由 settlement_window_wager / gift_price_reference 得到
control_band_ppm	发布时允许阶段期望 RTP 波动带	validateRuleStageExpectedRTP	已验收：阶段期望 RTP 不在区间内会返回 InvalidArgument
gift_price_reference	阶段阈值和奖档金额的配置参考价格	luckyRuntimeConfigFromRuleConfig、luckyRuntimeConfig	已验收：真实抽奖按单抽 coin_spent 等比缩放奖档金额
novice_max_equivalent_draws	新手阶段最大等价抽数	luckyExperiencePool、DefaultRuleConfig	已验收：小额和高价礼物统一按累计流水折算阶段
normal_max_equivalent_draws	正常阶段最大等价抽数，超过后进入高级阶段	luckyExperiencePool、DefaultRuleConfig	已验收：正常阈值必须大于等于新手阈值
风控上限字段	单次、用户小时、用户日、设备日、房间小时、主播日返奖上限	validateRuleConfig、luckyRiskCapacity、updateLuckyRiskCounters	已验收：所有上限必须为正数，候选过滤时统一参与
stages[].tiers[]	三个阶段的基础候选概率和倍率	validateRuleStage、validateRuleStageExpectedRTP、luckyRuntimeTiersFromRuleStages	已验收：每阶段启用概率和必须为 1000000，且必须有 0x 档和基础 RTP 档

2.3 默认草稿和发布

功能点	行为	代码函数实现	验收
默认草稿	后台读取未配置奖池时返回 disabled 草稿，不会自动生效	Service.GetConfig、DefaultRuleConfig	已验收：未找到配置时返回草稿，运行抽奖仍要求已发布启用规则
参数归一化	补齐 stage、reward_source、broadcast_level，清理空格	normalizeRuleConfig	已验收：后台提交的空 reward_source 默认 base_rtp
发布校验	校验 RTP、入池比例、窗口、阶段、概率、风控和高倍水位	validateRuleConfig、validateRuleStage、validRuleStage、validRewardSource、validBroadcastLevel	已验收：service 层发布前执行完整校验
不可变版本	每次发布新增 rule_version，不覆盖历史版本	Repository.PublishLuckyGiftRuleConfig	已验收：事务里锁最新版本并写入 lucky_gift_rule_versions 和 lucky_gift_stage_tiers
最新版本读取	后台和运行时都读取指定 pool_id 的最新版本	Repository.GetLuckyGiftRuleConfig、Repository.ListLuckyGiftRuleConfigs、Repository.getLuckyGiftRuleStages	已验收：列表按每个 pool 的最大 rule_version 返回

三、送礼链路

3.1 送礼前检查

功能点	行为	代码函数实现	验收
App 检查接口	POST /api/v1/activities/lucky-gifts/check 只做资格检查，不扣费、不抽奖；App 路径不随内部 v2 规则实现变化	activityapi.Handler.checkLuckyGift	已验收：接口要求 room_id/gift_id/pool_id 必填
gRPC 检查	gateway 或 room-service 通过 gRPC 查奖池是否启用	LuckyGiftServer.CheckLuckyGift、Service.Check	已验收：入参缺失返回 InvalidArgument
规则读取	按 pool_id 查 v2 最新规则，未配置返回 disabled	Repository.CheckLuckyGift、Repository.getLuckyGiftRuleConfig	已验收：不再从旧 lucky_gift_rules 作为运行规则来源
阶段展示	检查响应返回当前用户所在体验池	getLuckyUserState、luckyExperiencePool	已验收：响应包含 experience_pool

3.2 扣费后抽奖

功能点	行为	代码函数实现	验收
幸运礼物识别	显式传 pool_id 或钱包礼物类型为 lucky/super_lucky 时触发抽奖	Service.shouldDrawLuckyGift	已验收：旧客户端可由礼物类型触发，新客户端应传明确 pool_id
先扣费	房间链路先调用 wallet 扣费，成功后才调用 activity 抽奖	Service.SendGift、wallet.DebitGift 调用段	已验收：抽奖使用 billing.GetCoinSpent()，不信任客户端价格
抽奖命令	使用房间命令 ID 作为幂等根 ID	Service.SendGift、LuckyGiftServer.ExecuteLuckyGiftDraw、Service.Draw	已验收：重复命令由抽奖记录幂等返回
设备和主播 scope	设备优先取 session_id，主播优先取房主 ID	luckyGiftDeviceID、luckyGiftAnchorID	已验收：scope 不为空，风控计数可落表
同步响应	当前送礼用户立即拿到抽奖结果；中奖快路径成功时同时拿到返奖交易 ID 和账后余额	creditLuckyGiftRewardFastPath、luckyGiftResultFromProto、roomv1.SendGiftResponse.LuckyGift	已验收：room response 带 lucky_gift.wallet_transaction_id 和 lucky_gift.coin_balance_after
房间事实	送礼本身仍写 Room Cell、热度、榜单和 room outbox	Service.SendGift、outbox.Build	已验收：幸运礼物不替代普通送礼事实

四、抽奖事务

4.1 入口和幂等

功能点	行为	代码函数实现	验收
service 入参校验	command、用户、设备、房间、主播、礼物、金额、数量必须有效	Service.Draw	已验收：gift_count <= 0 会被拒绝
MySQL 事务	抽奖事实、奖池、窗口、风控、用户状态和 outbox 在一个事务内提交	Repository.ExecuteLuckyGiftDraw	已验收：事务提交前不调用外部 RPC
单抽幂等	单抽按原始 command_id 查已有 draw	executeSingleLuckyGiftDraw、getLuckyDrawByCommand	已验收：已存在时直接返回已有结果
批量幂等	批量按 command_id#序号 查子抽；部分存在时报冲突	executeLuckyGiftDrawBatch、collectLuckyBatchDrawsByCommand、luckyDrawSubCommandID	已验收：避免重试补写导致重复返奖

4.2 单抽路径

功能点	行为	代码函数实现	验收
规则锁定	抽奖时锁定当前 pool_id 最新规则版本	executeSingleLuckyGiftDraw、getLuckyGiftRuleConfig(... forUpdate=true)	已验收：规则未启用返回 RuleNotActive
运行配置转换	v2 阶段奖档转换为运行候选，窗口流水转等价抽数	luckyRuntimeConfigFromRuleConfig、luckyRuntimeTiersFromRuleStages、luckyRuntimePoolFromRuleStage	已验收：只读取 SourceBaseRTP 作为基础候选
实际金额缩放	同一奖池可服务不同价格礼物，奖励按本次 coin_spent 缩放	luckyRuntimeConfig、luckyScaleReward	已验收：风险上限保持绝对金币，不随小额礼物缩小
阶段推进	累计流水折算等价抽数并选择阶段	luckyEquivalentDraws、luckyExperiencePool、luckyStageFeedback	已验收：阶段反馈只是表现，不强制发币
RTP 窗口	记录 wager、target payout、actual base payout 和 carry	getOpenLuckyRTPWindow、luckyRTPWindow.withCurrentWager、createLuckyRTPWindow	已验收：RTP 只观察结算，不直接改随机概率
三层基础奖池	平台、房间、礼物三层共同承担基础返奖，任一层不足都会过滤奖档	getOrCreateLuckyPool、creditLuckyBasePools、debitLuckyPool、luckyWeightedPoolCapacity	已验收：候选过滤前先入池，容量按责任权重反推
房间气氛池	额外体验预算独立于基础 RTP	getOrCreateLuckyAtmosphere、creditLuckyAtmosphere	已验收：气氛奖励不写入基础 RTP payout
活动预算	活动补贴预算按 UTC 日切分	getLuckyActivityRemaining、getOrCreateLuckyActivityTotalRemaining	已验收：预算不足时不会产生活动补贴候选
风控计数	单次、用户、设备、房间、主播上限统一过滤可支付候选	getLuckyRiskCounters、luckyRiskCapacity、updateLuckyRiskCounters	已验收：并发抽奖通过 FOR UPDATE 锁计数行
候选随机	只使用后台阶段概率，过滤不可支付档，不注入 RTP 修正档	selectLuckyCandidate、luckyConfiguredWeightCandidates、luckySecureIndex	已验收：候选为空时落 no_payable_tier 0 倍，不透支
事实落库	写入 draw 明细和必要 outbox	applyLuckyDraw、luckyInitialRewardStatus、luckyDrawNeedsOutbox	已验收：无奖励且无反馈时直接 granted

4.3 批量路径

功能点	行为	代码函数实现	验收
单份金额拆分	coin_spent 按 gift_count 拆成 N 份，余数分配给前几抽	luckyDrawUnitSpend	已验收：单测覆盖 1001 金币拆成 101 + 9 个 100
循环外锁共享状态	规则、用户状态、RTP 窗口、奖池、气氛池、活动预算、风控计数只读取和锁定一次	executeOptimizedLuckyGiftDrawBatch	已验收：批量入口不再循环调用完整 executeSingleLuckyGiftDraw
循环内只做业务推进	每一抽在内存里推进阶段、窗口、入池、候选、出池、风控和 draw 明细	stageLuckyBatchDraw、creditLuckyPoolInMemory、debitLuckyPoolInMemory、incrementLuckyRiskCountersInMemory	已验收：避免 777 抽产生 777 轮 SQL 状态写入
批量落库	窗口、奖池、气氛池、风控、用户状态按本批净变化写一次	persistLuckyBatchDraw、updateLuckyPoolNet、updateLuckyAtmosphereNet	已验收：写入顺序保证 outbox 指向已存在 draw records
明细保留	每一抽仍保留一条 lucky_draw_records，用于审计和统计抽奖次数	insertLuckyDrawRecords、luckyDrawRecordArgs、luckyDrawRecordSnapshots	已验收：批量 INSERT，每 200 条一批
聚合响应	批量响应把金额、倍数、阶段反馈和高倍标记聚合	luckyAggregateDrawResults、luckyAggregateBudgetSourcesJSON	已验收：总倍数为各命中倍数相加，不是平均倍率
聚合发放	整批只写一条 outbox，payload 里有聚合 draw_id 和全部 draw_ids	insertLuckyAggregateDrawOutbox	已验收：待发放队列按送礼命令增长，不按中奖子抽增长

五、返奖快路径和房间表现

功能点	行为	代码函数实现	验收
同步返奖快路径	抽奖事务提交后，如果 effective_reward_coins > 0，立即调用 wallet-service CreditLuckyGiftReward；成功后把 draw 标记为 granted 并把交易 ID、账后余额写回响应	Service.Draw、creditLuckyGiftRewardFastPath、creditLuckyGiftReward、MarkLuckyGiftDrawsGranted	已验收：不在 activity MySQL 事务里调用 wallet，成功响应可直接给 App 刷余额
worker 循环	持续 claim LuckyGiftDrawn outbox，但它现在是补偿和表现投递路径，不是正常发币主路径	Service.RunWorker、Service.ProcessPendingDrawOutbox、Repository.ClaimPendingLuckyGiftOutbox	已验收：claim 使用 delivering 锁和 lock TTL
payload 兼容	新 payload 支持 draw_ids，老 payload 只有单个 draw_id 时回填	decodeDrawOutboxPayload	已验收：单抽旧 payload 仍能发放
钱包补偿	worker 先检查 draw 是否已 granted；已发奖则跳过 wallet，未发奖才用聚合 draw_id 生成幂等 command 补发一次	Service.processDrawOutbox、GetLuckyGiftDrawRewardState、walletv1.CreditLuckyGiftReward 调用	已验收：wallet 成功但 activity 标记失败时，worker 可用同一 command 补标；已 granted 不重复加币
房间开奖结果 IM	worker 投递 lucky_gift_drawn 房间群消息	publishLuckyGiftDrawn	已验收：发布失败时 outbox 可重试；已返奖的 draw 不会因为 IM 失败被标 failed
区域播报	符合条件的中奖写区域播报 outbox	shouldPublishLuckyGiftRegionBroadcast、publishLuckyGiftRegionBroadcast、luckyGiftRegionBroadcastPayload	已验收：当前阈值为有区域、有效奖励、聚合倍数不低于 1x
成功收敛	钱包成功后 draw records 先收敛为 granted；区域播报和房间 IM 成功后 outbox 标记 delivered	MarkLuckyGiftDrawsGranted、markLuckyGiftDraws、MarkLuckyGiftOutboxDelivered	已验收：批量更新按 500 个 draw_id 分片
失败收敛	未返奖且达到最大重试时，批量标记 pending draw failed	markOutboxFailed、MarkLuckyGiftDrawsFailed	已验收：已返奖但 IM 失败不会覆盖账务事实
重试退避	outbox 失败按指数退避重试	luckyGiftBackoff、MarkLuckyGiftOutboxRetryable	已验收：错误保存在 activity_outbox.last_error

六、后台配置和审计

功能点	HTTP 入口	代码函数实现	验收
获取单个奖池配置	GET /admin/activity/lucky-gifts/v2/config?pool_id=	Handler.GetLuckyGiftConfig、AdminLuckyGiftServer.GetLuckyGiftConfig、Service.GetConfig	已验收：未配置返回 disabled 草稿
发布配置	PUT /admin/activity/lucky-gifts/v2/config	Handler.UpsertLuckyGiftConfig、configToProto、Service.UpsertConfig、Repository.PublishLuckyGiftRuleConfig	已验收：百分比/倍率转换为 ppm 后发布
配置列表	GET /admin/activity/lucky-gifts/v2/configs	Handler.ListLuckyGiftConfigs、Service.ListConfigs、Repository.ListLuckyGiftRuleConfigs	已验收：每个奖池只返回最新版本
抽奖明细	GET /admin/activity/lucky-gifts/v2/draws	Handler.ListLuckyGiftDraws、Service.ListDraws、Repository.ListLuckyGiftDraws、luckyDrawWhereClause	已验收：分页上限由 service 控制，支持状态筛选
抽奖汇总	GET /admin/activity/lucky-gifts/v2/draw-summary	Handler.GetLuckyGiftDrawSummary、Service.GetDrawSummary、Repository.GetLuckyGiftDrawSummary	已验收：统计总抽数、参与用户、消耗、返奖、pending/granted/failed
后台路由权限	所有后台入口需要 lucky-gift:view 或 lucky-gift:update	RegisterRoutes	已验收：路由注册在后台模块内

七、数据表

表	用途	代码函数实现	验收
lucky_gift_rule_versions	v2 不可变规则版本	PublishLuckyGiftRuleConfig、getLuckyGiftRuleConfig	已验收：schema 在 001_activity_service.sql 和迁移兜底中存在
lucky_gift_stage_tiers	每个规则版本的阶段奖档概率	PublishLuckyGiftRuleConfig、getLuckyGiftRuleStages	已验收：按 stage 和倍率顺序读取
lucky_rtp_windows	RTP 观察窗口	getOpenLuckyRTPWindow、createLuckyRTPWindow、persistLuckyBatchDraw、applyLuckyDraw	已验收：窗口关闭后创建新窗口
lucky_pools	平台、房间、礼物三层基础奖池	getOrCreateLuckyPool、updateLuckyPoolNet、creditLuckyPool、debitLuckyPool	已验收：容量过滤使用 reserve floor
lucky_room_atmosphere_pools	房间气氛池	getOrCreateLuckyAtmosphere、updateLuckyAtmosphereNet、creditLuckyAtmosphere	已验收：独立于 Room Cell
lucky_activity_budgets	活动补贴预算	ensureLuckyActivityBudget、getLuckyActivityRemaining	已验收：总预算和 UTC 日预算都支持
lucky_user_states	用户阶段、累计流水、等价抽数和连亏	getLuckyUserState、getLuckyUserStateForUpdate、persistLuckyBatchDraw、applyLuckyDraw	已验收：包含 cumulative_wager_coins、equivalent_draws、loss_streak
lucky_risk_counters	风控窗口累计返奖	getLuckyRiskCounters、getOrCreateLuckyRiskCounter、updateLuckyRiskCounters	已验收：用户小时、用户日、设备日、房间小时、主播日五类 scope
lucky_draw_records	单抽审计事实	insertLuckyDrawRecords、applyLuckyDraw、ListLuckyGiftDraws	已验收：批量送礼仍保留单抽粒度
activity_outbox	幸运礼物钱包补偿和表现副作用，不再承载正常发币主路径	insertLuckyAggregateDrawOutbox、ClaimPendingLuckyGiftOutbox、MarkLuckyGiftOutboxDelivered	已验收：批量送礼只写一条 LuckyGiftDrawn outbox，已 granted 时 worker 跳过 wallet

八、运行边界

场景	当前处理	代码函数实现	验收
奖池未启用	送礼前检查或扣费后抽奖都会失败，不开奖	CheckLuckyGift、ExecuteLuckyGiftDraw、Service.Check、Service.Draw	已验收：未启用返回 RuleNotActive 或 enabled=false
所有正奖档不可支付	本抽返回 0 倍 no_payable_tier，不透支奖池和风控	selectLuckyCandidate	已验收：单测覆盖全正奖不可支付回退 0 倍
小额礼物	阶段按累计流水折算，单抽奖励按单份金额缩放，风控上限不被缩小	luckyRuntimeConfig、luckyEquivalentDraws、luckyRiskCapacity	已验收：单测覆盖大额后小额仍可中小奖
高倍奖	发布校验要求高倍档 HighWaterOnly，运行时仍受奖池和风控过滤	validateRuleStage、selectLuckyCandidate	已验收：高倍率未标高水位会拒绝发布
批量 777 份	抽 777 次，保留 777 条明细，状态写入和 outbox 聚合	executeOptimizedLuckyGiftDrawBatch、stageLuckyBatchDraw、persistLuckyBatchDraw	已验收：代码结构已移出循环内 SQL 状态写入
worker 重试	钱包补偿用聚合 draw_id 幂等，outbox 失败可重试；已 granted 的 draw 只补 IM/播报，不重复加币	processDrawOutbox、GetLuckyGiftDrawRewardState、MarkLuckyGiftOutboxRetryable	已验收：成功后 delivered，不重复加币
已返奖但 IM 失败	不把 draw 标 failed，只让 outbox failed 并保留告警空间	markOutboxFailed	已验收：alreadyCredited 分支不覆盖 draw 状态

九、代码验收清单

验收项	命令或检查	当前结果
旧专属文档删除	test ! -e docs/幸运礼物Activity服务开发.md 等 9 个旧文档	通过
新文档唯一入口	test -f docs/幸运礼物实现文档.md	通过
函数引用存在	`rg -n "executeOptimizedLuckyGiftDrawBatch	stageLuckyBatchDraw
Activity 幸运礼物服务测试	go test ./services/activity-service/internal/service/luckygift	通过
Activity MySQL 抽奖测试	go test ./services/activity-service/internal/storage/mysql	通过
Room 送礼链路测试	go test ./services/room-service/internal/room/service	通过
Gateway 检查接口测试	go test ./services/gateway-service/internal/transport/http/activityapi	通过
Admin 幸运礼物模块测试	cd server/admin && go test ./internal/modules/luckygift	通过

十、后续维护规则

1. 后续幸运礼物规则、字段、算法或接口变化，先改代码，再同步本文档对应功能点和验收项。
2. 新增后台字段必须同时标明：后台 DTO、proto 字段、domain 字段、发布校验、运行读取、数据库字段。
3. 新增抽奖行为必须写明是否影响：候选概率、奖池水位、RTP 观察、风控计数、draw record、outbox payload、客户端同步响应。
4. 批量抽奖不能重新引入“每抽一条发奖 outbox”。抽奖可以是 N 次，钱包发奖必须按一次送礼命令聚合。
5. 不允许用 RTP 缺口在运行时动态改概率。RTP 只在发布校验和窗口观察中使用；运行时只能过滤不可支付奖档。