hyapp-server/docs/通用抽奖引擎技术文档.md

通用抽奖引擎技术文档

本文档描述当前服务端通用抽奖能力的代码结构、运行口径和转盘落地方式。抽奖通用能力目前由 activity-service 持有，钱包入账由 wallet-service 持有。幸运礼物已经复用通用权重选择；转盘新增独立配置、抽奖记录、RTP 统计、钱包 reason 和后台查询入口。

一、边界和结论

模块	Owner	当前职责	不做什么	代码位置
通用抽奖引擎	activity-service	候选归一化、权重随机、奖品类型归一化、RTP 计值归一化	不读取数据库、不判断资格、不改奖池、不发奖	services/activity-service/internal/domain/lotteryengine/engine.go
幸运礼物	activity-service	继续拥有幸运礼物规则、奖池、RTP 窗口、风控、记录和 outbox；候选随机改为调用通用引擎	不改变原有幸运礼物 RTP 观察和不可支付过滤逻辑	services/activity-service/internal/storage/mysql/lucky_gift_repository.go
转盘	activity-service	独立规则版本、奖档、奖池、RTP 窗口、抽奖记录、后台统计、金币快路径发奖	不复用幸运礼物表；不把道具/装扮价值计入 RTP	services/activity-service/internal/domain/wheel、internal/service/wheel、internal/storage/mysql/wheel_repository.go
钱包 reason	wallet-service	新增 wheel_reward 入账 reason、交易、分录、钱包 outbox	不判断转盘中奖资格，不计算 RTP	services/wallet-service/internal/service/wallet/service.go、internal/storage/mysql/repository.go
Proto/gRPC	api/proto + transport	暴露转盘抽奖和后台配置/记录/统计 RPC	当前未新增 gateway HTTP 包装	api/proto/activity/v1/activity.proto、services/activity-service/internal/transport/grpc/wheel_server.go

核心原则：

1. 通用引擎只负责“从已过滤候选里按权重选中一个奖档”。
2. 业务模块必须在调用引擎前完成资格、价格、奖池、风控和预算过滤。
3. RTP 只使用 rtp_value_coins 作为分子；转盘道具和装扮无论配置价值多少，运行态都强制为 0。
4. 金币发放必须走钱包独立 reason wheel_reward，不能混用 lucky_gift_reward。
5. 转盘配置、记录和统计使用 wheel_* 表，不能写入幸运礼物表。

二、代码索引

2.1 通用抽奖引擎

文件	关键符号	说明
services/activity-service/internal/domain/lotteryengine/engine.go	Candidate	引擎唯一输入视图：ID、Weight、PrizeKind、RTPValueCoins
同上	NormalizeCandidates	复制并清洗候选；负权重拒绝；全部权重为 0 时退化为等权随机
同上	SelectWeighted	使用 crypto/rand 生成随机下标，按权重选择候选
同上	NormalizePrizeKind	把 coin/gift/prop/dress 及同义值归一化
同上	NormalizeRTPValueCoins	金币/礼物保留非负 RTP 价值；prop/dress 强制归零
services/activity-service/internal/domain/lotteryengine/engine_test.go	单测	覆盖权重选择、全 0 权重兜底、道具/装扮 RTP 归零

2.2 转盘代码

文件	关键符号	说明
services/activity-service/internal/domain/wheel/wheel.go	RuleConfig、Tier、DrawCommand、DrawResult、DrawSummary	转盘领域模型
services/activity-service/internal/service/wheel/config.go	NormalizeRuleConfig、ValidateRuleConfig	后台配置发布前归一化和硬边界校验
services/activity-service/internal/service/wheel/service.go	Service.Draw、UpsertConfig、GetConfig、ListDraws、GetDrawSummary	转盘用例入口
同上	creditCoinRewardFastPath	金币奖品同步调用钱包 CreditWheelReward，成功后回写 draw、统计和 outbox
services/activity-service/internal/storage/mysql/wheel_repository.go	PublishWheelRuleConfig	发布不可变规则版本和奖档
同上	ExecuteWheelDraw	转盘抽奖主事务：幂等、规则锁定、价格校验、RTP 窗口、奖池、记录、统计、outbox
同上	executeSingleWheelDraw	单次命中奖档、更新 RTP 窗口、写 draw record 和 outbox
同上	wheelPayableCandidates	按奖池容量和单次 RTP 上限过滤候选；道具/装扮 RTP 价值归零
同上	ListWheelDraws、GetWheelDrawSummary	后台抽奖明细和汇总统计读取
同上	MarkWheelDrawsGranted	金币发放成功后回写记录、统计和 activity_outbox
services/activity-service/internal/storage/mysql/wheel_schema.go	ensureWheelTables	运行时兜底创建 wheel_* 表
services/activity-service/deploy/mysql/initdb/001_activity_service.sql	wheel_* DDL	新环境初始化表结构
services/activity-service/internal/transport/grpc/wheel_server.go	WheelServer、AdminWheelServer	转盘 App 抽奖和后台配置/统计 gRPC
services/activity-service/internal/app/services.go	wheelservice.New	activity-service 装配转盘 service
services/activity-service/internal/app/grpc_registration.go	RegisterWheelServiceServer、RegisterAdminWheelServiceServer	注册转盘 gRPC 服务

2.3 钱包代码

文件	关键符号	说明
api/proto/wallet/v1/wallet.proto	CreditWheelRewardRequest、CreditWheelReward	钱包转盘金币奖品入账 RPC
services/wallet-service/internal/domain/ledger/ledger.go	WheelRewardCommand、WheelRewardReceipt	钱包 service/repository 间领域命令
services/wallet-service/internal/service/wallet/service.go	CreditWheelReward	校验转盘金币奖品入账命令，固定钱包职责边界
services/wallet-service/internal/storage/mysql/repository.go	bizTypeWheelReward、CreditWheelReward	交易、账户余额、分录和钱包 outbox 同事务提交
同上	wheelRewardRequestHash	保证同一转盘 draw 幂等入账
services/wallet-service/internal/transport/grpc/server.go	CreditWheelReward	gRPC 请求转换为钱包领域命令

2.4 Proto 契约

文件	RPC/Message	说明
api/proto/activity/v1/activity.proto	WheelService.ExecuteWheelDraw	扣费后执行转盘抽奖
同上	AdminWheelService.GetWheelConfig	后台读取当前转盘配置
同上	AdminWheelService.UpsertWheelConfig	后台发布新规则版本
同上	AdminWheelService.ListWheelDraws	后台查看抽奖明细
同上	AdminWheelService.GetWheelDrawSummary	后台查看转盘统计汇总
同上	WheelRuleConfig、WheelPrizeTier	转盘规则和奖档配置
同上	WheelDrawMeta、WheelDrawResult、WheelDrawSummary	抽奖入参、结果和统计
api/proto/wallet/v1/wallet.proto	CreditWheelRewardRequest、CreditWheelRewardResponse	转盘金币发放钱包契约

三、通用引擎模型

3.1 Candidate

lotteryengine.Candidate 是通用引擎唯一关心的数据：

字段	含义	规则
ID	业务奖档 ID	引擎只原样返回，业务侧负责保证唯一
Weight	权重	负数拒绝；正数参与随机；全部为 0 时每个候选权重按 1 处理
PrizeKind	奖品类型	归一化为 coin/gift/prop/dress 等标准值
RTPValueCoins	计入 RTP 的金币价值	负数按 0；prop/dress 强制为 0

引擎不直接使用 RewardCoins、RewardID、库存、奖池余额、用户信息。这些都属于业务模块。

3.2 权重选择

流程：

1. 调用方传入已过滤候选。
2. NormalizeCandidates 清洗权重、奖品类型和 RTP 价值。
3. SelectWeighted 汇总权重。
4. 用 crypto/rand.Int 生成 [0,totalWeight) 的随机数。
5. 按权重区间返回命中的 Candidate。

设计原因：

设计	原因
使用 crypto/rand	高价值奖品不能被时间种子或进程启动顺序预测
全 0 权重兜底为等权	兼容旧配置或临时配置错误，避免整个活动不可抽
负权重直接失败	负权重没有业务语义，继续运行会让概率不可解释
不在引擎内做 RTP 修正	RTP 修正依赖奖池、预算、用户风险和活动策略，必须留在业务层

四、转盘配置模型

4.1 RuleConfig

domain/wheel.RuleConfig 是一个不可变版本快照：

字段	含义
WheelID	转盘 ID，空值归一为 default
RuleVersion	不可变规则版本，每次发布 +1
Enabled	是否启用
DrawPriceCoins	单抽价格
TargetRTPPPM	RTP 目标，ppm
PoolRatePPM	每笔消耗进入转盘奖池比例，ppm
SettlementWindowDraws	RTP 观察窗口抽数
InitialPoolCoins	初始奖池水位
PoolReserveCoins	奖池保底水位
MaxSingleRTPPayout	单次可支付的 RTP 价值上限
Tiers	奖档列表

4.2 Tier

字段	含义	特殊规则
TierID	奖档 ID	同一规则版本内必须唯一
DisplayName	展示名称快照	只用于后台和前端展示
RewardType	coin/gift/prop/dress	会调用通用引擎归一化
RewardID	礼物、道具、装扮资源 ID	非金币奖品必填
RewardCount	奖励数量	小于等于 0 时归一为 1
RewardCoins	金币奖励金额	coin 使用
RTPValueCoins	计入 RTP 的价值	prop/dress 强制为 0
WeightPPM	随机权重	当前作为权重值使用，不要求总和等于 1000000
Enabled	是否启用	至少需要一个启用奖档
MetadataJSON	展示和发放扩展快照	空值或非法 JSON 归一为 {}

4.3 配置校验

入口：services/activity-service/internal/service/wheel/config.go

规则：

1. draw_price_coins 必须大于 0。
2. target_rtp_ppm、pool_rate_ppm 不能为负。
3. settlement_window_draws 必须大于 0。
4. 奖档不能为空。
5. tier_id 必须唯一。
6. weight_ppm 不能为负。
7. coin 奖档的 reward_coins 不能为负。
8. gift/prop/dress 必须有 reward_id。
9. prop/dress 的 rtp_value_coins 在归一化后必须为 0。
10. 至少一个奖档启用。

五、转盘抽奖链路

5.1 调用前提

转盘抽奖 RPC 是扣费后的服务端事实入口：

阶段	Owner	说明
扣费	调用方 + wallet-service	先扣用户金币，拿到真实 coin_spent 和 paid_at_ms
抽奖	activity-service	使用 ExecuteWheelDraw 固化中奖结果和 RTP
金币发放	wallet-service	coin 奖品通过 CreditWheelReward 入账
礼物/道具/装扮发放	对应资产 owner	当前只固化 pending 记录和 outbox 事实，后续接资产发放接口

转盘 repository 会校验：

coin_spent == draw_price_coins * draw_count

这样避免客户端或调用方伪造 RTP 分母。

5.2 主事务

入口：Repository.ExecuteWheelDraw

事务内顺序：

1. 归一化 wheel_id 和 draw_count。
2. 按 command_id 收集已有 draw，完整存在则幂等返回。
3. 如果只存在部分子抽，返回冲突，避免重复发奖。
4. 锁定当前启用的转盘规则版本。
5. 校验 coin_spent 与当前单价一致。
6. 获取或创建 RTP 窗口。
7. 获取或创建转盘奖池。
8. 按 draw_count 拆分每次消耗。
9. 每一抽调用 executeSingleWheelDraw。
10. 汇总写回奖池净变化。
11. 更新后台统计。
12. 提交事务。

5.3 单抽

入口：executeSingleWheelDraw

单抽顺序：

1. wheelPayableCandidates 过滤可支付候选。
2. 组装 lotteryengine.Candidate。
3. 调用 lotteryengine.SelectWeighted 命中奖档。
4. 用命中奖档的 RTPValueCoins 更新奖池和 RTP 窗口。
5. 写入 wheel_draw_records。
6. 如果奖品需要发放，写入 activity_outbox，事件类型为 WheelRewardSettlement。
7. 返回 DrawResult。

候选过滤口径：

过滤项	说明
tier.Enabled	未启用奖档不参与
RTPValueCoins	prop/dress 强制为 0
奖池容量	pool.balance - reserve_floor
单次上限	max_single_rtp_payout 大于 0 时限制容量

注意：道具/装扮 RTPValueCoins=0，所以不会因为展示价值占用奖池，也不会提高 RTP 分子。

5.4 批量抽奖

当前转盘支持 draw_count：

功能	代码	说明
子命令 ID	wheelSubCommandID	单抽使用原 command，多抽追加 #000001 这类后缀
金额拆分	复用 luckyDrawUnitSpend	总金额按次数拆分，余数给前几抽
幂等聚合	collectWheelDrawsByCommand、aggregateWheelDrawResults	完整存在则聚合返回
发放限制	creditCoinRewardFastPath	当前只对单抽金币做同步快路径，多抽保留 pending/outbox

六、RTP 口径

6.1 分子和分母

项	字段	来源
RTP 分母	coin_spent / wager_coins	用户实际扣费金币
RTP 分子	rtp_value_coins / actual_rtp_value_coins	命中奖档计入 RTP 的价值
目标值	target_rtp_ppm	后台规则配置
当前值	actual_rtp_ppm	actual_rtp_value_coins * 1000000 / wager_coins

6.2 奖品类型口径

奖品类型	是否可配置	是否发放	是否计入 RTP
coin	是	钱包 wheel_reward	是，使用 rtp_value_coins
gift	是	待接礼物/资源 owner	是，使用 rtp_value_coins
prop	是	待接道具 owner	否，强制 0
dress	是	待接装扮 owner	否，强制 0

强制归零的位置：

层	代码
通用引擎	lotteryengine.NormalizeRTPValueCoins
转盘配置	wheel.NormalizeRuleConfig
转盘仓储	normalizeWheelTiers、wheelPayableCandidates
转盘测试	services/activity-service/internal/service/wheel/config_test.go、domain/lotteryengine/engine_test.go

七、发奖和 outbox

7.1 金币奖品

金币奖品路径：

1. ExecuteWheelDraw 写入 wheel_draw_records，初始状态为 pending。
2. Service.Draw 在事务提交后进入 creditCoinRewardFastPath。
3. 调用 wallet-service CreditWheelReward。
4. wallet-service 以 biz_type=wheel_reward 写交易、账户、分录和 wallet outbox。
5. activity-service 调用 MarkWheelDrawsGranted。
6. MarkWheelDrawsGranted 同事务更新：
   • wheel_draw_records.reward_status = granted
   • wheel_draw_records.reward_transaction_id
   • wheel_draw_stats.pending_draws/granted_draws
   • activity_outbox.status = delivered

钱包 reason：

项	值
wallet biz type	wheel_reward
RPC reason	wheel_reward
command ID	wheel_reward:<draw_id>
钱包事件	WalletWheelRewardCredited

7.2 礼物/道具/装扮奖品

当前状态：

1. 抽奖结果会落 wheel_draw_records。
2. reward_status 为 pending。
3. activity_outbox 会写 WheelRewardSettlement。
4. 具体发放 worker 和资产 owner RPC 还没有接入。

后续接入时必须遵守：

1. 不允许在 activity-service 直接改钱包或资产表。
2. 发放成功后调用转盘仓储状态回写方法，保持 draw record、统计和 outbox 一致。
3. 道具/装扮发放成功也不能把展示价值写入 RTP。
4. 礼物如果要计入 RTP，必须使用抽奖时固化的 rtp_value_coins，不能按发放时礼物价格重新估值。

八、后台记录和统计

8.1 明细

入口：AdminWheelService.ListWheelDraws

仓储：Repository.ListWheelDraws

支持筛选：

字段	说明
wheel_id	转盘 ID
user_id	用户 ID
status	pending/granted/failed
page/page_size	分页，page_size 最大 100

返回字段包括：

draw_id、command_id、wheel_id、rule_version、selected_tier_id、reward_type、reward_id、reward_count、reward_coins、rtp_value_coins、reward_status、wallet_transaction_id、rtp_window_index、metadata_json。

8.2 汇总

入口：AdminWheelService.GetWheelDrawSummary

仓储：Repository.GetWheelDrawSummary

统计字段：

字段	说明
total_draws	抽奖次数
unique_users	去重用户数
total_spent_coins	总消耗金币
total_rtp_value_coins	计入 RTP 的返奖价值
actual_rtp_ppm	实际 RTP
pending_draws	待发放
granted_draws	已发放
failed_draws	失败

当只按 wheel_id 汇总时，优先读 wheel_draw_stats；带 user_id/status 过滤时直接聚合 wheel_draw_records。

九、数据表

表	用途	代码
wheel_rule_versions	转盘不可变规则版本	wheel_schema.go、001_activity_service.sql
wheel_prize_tiers	每个规则版本的奖档快照	同上
wheel_rtp_windows	RTP 观察窗口	getOpenWheelRTPWindow、createWheelRTPWindow
wheel_pools	转盘奖池水位	getOrCreateWheelPool、persistWheelPoolDelta
wheel_draw_records	抽奖事实明细	executeSingleWheelDraw、ListWheelDraws
wheel_draw_stats	后台汇总统计	updateWheelStats、GetWheelDrawSummary
wheel_draw_stat_users	统计去重用户	updateWheelStats
activity_outbox	转盘发奖补偿事实	insertWheelRewardOutbox、MarkWheelDrawsGranted
wallet_transactions	钱包交易	wallet-service/internal/storage/mysql.Repository.CreditWheelReward
wallet_outbox	钱包余额和奖励事实	同上

十、和幸运礼物的关系

幸运礼物不是直接迁移成转盘，也不是把转盘塞进幸运礼物：

项	幸运礼物	转盘
规则维度	pool_id，房间送礼场景	wheel_id，H5/活动转盘场景
奖品	金币返奖	金币、礼物、道具、装扮
RTP 口径	原幸运礼物基础返奖口径	rtp_value_coins，道具/装扮强制 0
记录表	lucky_draw_records	wheel_draw_records
钱包 reason	lucky_gift_reward	wheel_reward
通用引擎使用	候选随机复用 lotteryengine.SelectWeighted	候选随机和 RTP 归一化都复用

幸运礼物保留自己的奖池、风控、用户阶段和 room IM 逻辑。通用引擎只替换了“已过滤候选里的权重随机”这一小段，避免改动原业务行为。

十一、扩展新抽奖活动的步骤

新增一个抽奖活动时，不要复制幸运礼物或转盘整套逻辑。按下面顺序接入：

1. 新建独立 domain，定义自己的 RuleConfig、Tier、DrawCommand、DrawResult。
2. 新建 service，负责入参归一化、配置校验和跨服务调用。
3. 新建 storage，负责规则版本、奖池、RTP 窗口、记录、统计和 outbox。
4. 业务层先过滤资格、预算、库存、奖池和风控。
5. 把过滤后的候选转换成 lotteryengine.Candidate。
6. 调用 lotteryengine.SelectWeighted。
7. 用返回候选固化抽奖结果。
8. 如果有金币奖品，在 wallet-service 增加独立 reason，不复用已有 reason。
9. 如果有非金币奖品，接对应 owner service 的发放接口。
10. 补 proto、gRPC、表结构、initdb 和测试。

必须明确回答的问题：

问题	必须落地的位置
奖品有哪些类型	domain Tier.RewardType 和 proto
哪些奖品计入 RTP	RTPValueCoins 归一化
哪个服务发奖	service 跨服务依赖
钱包 reason 是什么	wallet-service domain/service/storage/proto
如何幂等	command ID、draw ID、钱包 request hash
后台查什么	draw records 和 summary
失败如何补偿	activity outbox 或 owner outbox

十二、验证命令

当前相关验证命令：

PATH=/Users/hy/go/bin:$PATH make proto
go test ./services/activity-service/internal/domain/lotteryengine
go test ./services/activity-service/internal/service/wheel
go test ./services/activity-service/internal/storage/mysql
go test ./services/activity-service/internal/transport/grpc
go test ./services/activity-service/internal/app
go test ./services/wallet-service/internal/service/wallet ./services/wallet-service/internal/storage/mysql ./services/wallet-service/internal/transport/grpc
go test ./services/activity-service/...

已知当前仓库全量 make test 仍会失败在既有 MifaPay 配置测试：

services/wallet-service/internal/config.TestLoadMifaPayMerchantConfig
mifapay merchant identity mismatch in ../../configs/config.docker.yaml

该失败与通用抽奖和转盘改动无关。

十三、当前未完成事项

事项	原因	后续接入位置
礼物奖品真实发放	需要确认礼物/资源 owner 的发放接口和背包表现	activity-service 转盘 outbox worker + 对应 owner RPC
道具/装扮真实发放	需要确认装扮资源 owner、有效期和背包协议	activity-service 转盘 outbox worker + resource/wallet owner
Gateway HTTP/H5 接口	当前只到 activity gRPC；H5 页面还需要 gateway 包装	services/gateway-service/internal/transport/http/activityapi
后台管理页面	当前只有 gRPC 后台能力，未接 admin web 模块	server/admin