新功能(#3): 抽奖 Stage 1 收官 — 用户 API + 后台 CRUD + 集成

Closes HIF-3 Stage 1 完整闭环 PR C：用户 API + 后台 CRUD + 抽奖事务服务 + 审计 + QA curl。合并后 Stage 1 可交测试。架构师 review R1（rulecaps depth≤8/nodes≤64/bytes≤8KB）+ R2（InviteHook source_ref 加 order: 前缀）已全部落地。 - 迁移 02158_admin_action_log：后台写操作审计 - xerr 100xxx 段：抽奖错误码（NotEligible/NoChances/ActivityEnded/RateLimited/NotClaimable/InternalError/RuleTooDeep/RuleTooMany/RuleTooLarge） - feature flag config.Lottery.Enable 默认 false，合并后线上零副作用 - draw service：feature flag → rate limit → pre-tx reads → nonce dedupe → Consume → Pick → 乐观扣库存 → 双快照 → Dispatch → finalize - 用户 API 4 个：GET /config、POST /draw、GET /records、POST /claim（Stage 1 返回 100010） - 后台 CRUD：活动 / 奖品 / rules PUT（rulecaps gate）/ chances/grant - audit.WriteAdminAction：与调用方 tx 同生共死，SHA1 body 摘要 - QA 脚本：qa/lottery/stage1_curl.sh 全链路 curl 测试覆盖：model 76.5% / draw 69% / handler 68.3% / hook 91.9% / rulecaps 87.8% / audit 100% 100 并发抢库存 + 10000 次概率分布 e2e 推 QA 环境（sqlmock 无法忠实模拟 InnoDB 行锁） CI 全绿：构建/Vet/测试 + golangci-lint
2026-07-08 22:33:18 -07:00
parent a46fb83054
commit ce3babcc33
27 changed files with 3599 additions and 18 deletions
@@ -0,0 +1,169 @@
+// Package lottery contains gin handlers for the admin-side lottery endpoints.
+package lottery
+
+import (
+	"github.com/gin-gonic/gin"
+	adminlottery "github.com/perfect-panel/server/internal/logic/admin/lottery"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+func CreateLotteryActivityHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.CreateAdminLotteryActivityRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewCreateLotteryActivityLogic(c.Request.Context(), svcCtx)
+		resp, err := l.CreateLotteryActivity(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+func UpdateLotteryActivityHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.UpdateAdminLotteryActivityRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewUpdateLotteryActivityLogic(c.Request.Context(), svcCtx)
+		resp, err := l.UpdateLotteryActivity(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+func ListLotteryActivitiesHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.ListAdminLotteryActivitiesRequest
+		_ = c.ShouldBind(&req)
+		l := adminlottery.NewListLotteryActivitiesLogic(c.Request.Context(), svcCtx)
+		resp, err := l.ListLotteryActivities(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+func GetLotteryActivityHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.AdminActivityIdRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewGetLotteryActivityLogic(c.Request.Context(), svcCtx)
+		resp, err := l.GetLotteryActivity(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+func PublishLotteryActivityHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.AdminActivityIdRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewPublishLotteryActivityLogic(c.Request.Context(), svcCtx)
+		result.HttpResult(c, nil, l.PublishLotteryActivity(&req))
+	}
+}
+
+func PauseLotteryActivityHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.AdminActivityIdRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewPauseLotteryActivityLogic(c.Request.Context(), svcCtx)
+		result.HttpResult(c, nil, l.PauseLotteryActivity(&req))
+	}
+}
+
+func UpdateLotteryRulesHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.UpdateAdminLotteryRulesRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewUpdateLotteryRulesLogic(c.Request.Context(), svcCtx)
+		result.HttpResult(c, nil, l.UpdateLotteryRules(&req))
+	}
+}
+
+func CreateLotteryPrizeHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.CreateAdminLotteryPrizeRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewCreateLotteryPrizeLogic(c.Request.Context(), svcCtx)
+		resp, err := l.CreateLotteryPrize(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+func UpdateLotteryPrizeHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.UpdateAdminLotteryPrizeRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewUpdateLotteryPrizeLogic(c.Request.Context(), svcCtx)
+		resp, err := l.UpdateLotteryPrize(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+func DeleteLotteryPrizeHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.AdminPrizeIdRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewDeleteLotteryPrizeLogic(c.Request.Context(), svcCtx)
+		result.HttpResult(c, nil, l.DeleteLotteryPrize(&req))
+	}
+}
+
+func ListLotteryPrizesHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.ListAdminLotteryPrizesRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewListLotteryPrizesLogic(c.Request.Context(), svcCtx)
+		resp, err := l.ListLotteryPrizes(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+func GrantLotteryChanceHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.GrantAdminLotteryChanceRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := adminlottery.NewGrantLotteryChanceLogic(c.Request.Context(), svcCtx)
+		result.HttpResult(c, nil, l.GrantLotteryChance(&req))
+	}
+}
@@ -0,0 +1,44 @@
+package handler
+
+import (
+	"github.com/gin-gonic/gin"
+	adminLottery "github.com/perfect-panel/server/internal/handler/admin/lottery"
+	publicLottery "github.com/perfect-panel/server/internal/handler/public/lottery"
+	"github.com/perfect-panel/server/internal/middleware"
+	"github.com/perfect-panel/server/internal/svc"
+)
+
+// registerLotteryRoutes wires the Stage 1 lottery endpoints. Kept in its own
+// file to avoid ballooning routes.go and to make the lottery surface easy to
+// audit end-to-end. The path prefix "/v1/lottery" is under the user middleware
+// stack (AuthMiddleware + DeviceMiddleware); "/v1/admin/lottery" uses the
+// admin-detecting AuthMiddleware (path contains "admin" segment).
+func registerLotteryRoutes(router *gin.Engine, serverCtx *svc.ServiceContext) {
+	userGroup := router.Group("/v1/lottery")
+	userGroup.Use(middleware.AuthMiddleware(serverCtx), middleware.DeviceMiddleware(serverCtx))
+	{
+		userGroup.GET("/config", publicLottery.QueryLotteryConfigHandler(serverCtx))
+		userGroup.POST("/draw", publicLottery.DrawLotteryHandler(serverCtx))
+		userGroup.GET("/records", publicLottery.QueryLotteryRecordsHandler(serverCtx))
+		userGroup.POST("/claim", publicLottery.ClaimLotteryPrizeHandler(serverCtx))
+	}
+
+	adminGroup := router.Group("/v1/admin/lottery")
+	adminGroup.Use(middleware.AuthMiddleware(serverCtx))
+	{
+		adminGroup.POST("/activities", adminLottery.CreateLotteryActivityHandler(serverCtx))
+		adminGroup.PUT("/activities", adminLottery.UpdateLotteryActivityHandler(serverCtx))
+		adminGroup.GET("/activities", adminLottery.ListLotteryActivitiesHandler(serverCtx))
+		adminGroup.GET("/activities/detail", adminLottery.GetLotteryActivityHandler(serverCtx))
+		adminGroup.POST("/activities/publish", adminLottery.PublishLotteryActivityHandler(serverCtx))
+		adminGroup.POST("/activities/pause", adminLottery.PauseLotteryActivityHandler(serverCtx))
+		adminGroup.PUT("/activities/rules", adminLottery.UpdateLotteryRulesHandler(serverCtx))
+
+		adminGroup.POST("/prizes", adminLottery.CreateLotteryPrizeHandler(serverCtx))
+		adminGroup.PUT("/prizes", adminLottery.UpdateLotteryPrizeHandler(serverCtx))
+		adminGroup.DELETE("/prizes", adminLottery.DeleteLotteryPrizeHandler(serverCtx))
+		adminGroup.GET("/prizes", adminLottery.ListLotteryPrizesHandler(serverCtx))
+
+		adminGroup.POST("/chances/grant", adminLottery.GrantLotteryChanceHandler(serverCtx))
+	}
+}
@@ -0,0 +1,69 @@
+// Package lottery contains the user-facing lottery HTTP handlers. Each handler
+// binds request params via gin, validates, delegates to the logic package,
+// and renders through pkg/result to keep the API response envelope consistent.
+package lottery
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/public/lottery"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+// QueryLotteryConfigHandler serves GET /api/v1/lottery/config.
+func QueryLotteryConfigHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.GetLotteryConfigRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := lottery.NewQueryLotteryConfigLogic(c.Request.Context(), svcCtx)
+		resp, err := l.QueryLotteryConfig(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+// DrawLotteryHandler serves POST /api/v1/lottery/draw.
+func DrawLotteryHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.DrawLotteryRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := lottery.NewDrawLotteryLogic(c.Request.Context(), svcCtx)
+		resp, err := l.DrawLottery(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+// QueryLotteryRecordsHandler serves GET /api/v1/lottery/records.
+func QueryLotteryRecordsHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.GetLotteryRecordsRequest
+		_ = c.ShouldBind(&req)
+		l := lottery.NewQueryLotteryRecordsLogic(c.Request.Context(), svcCtx)
+		resp, err := l.QueryLotteryRecords(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
+
+// ClaimLotteryPrizeHandler serves POST /api/v1/lottery/claim. Stage 1
+// always returns 4010 not_claimable.
+func ClaimLotteryPrizeHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.ClaimLotteryPrizeRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := lottery.NewClaimLotteryPrizeLogic(c.Request.Context(), svcCtx)
+		resp, err := l.ClaimLotteryPrize(&req)
+		result.HttpResult(c, resp, err)
+	}
+}
@@ -1221,4 +1221,7 @@ func RegisterHandlers(router *gin.Engine, serverCtx *svc.ServiceContext) {
 		// Get Server Protocol Config
 		serverGroupRouterV2.GET("/:server_id", server.QueryServerProtocolConfigHandler(serverCtx))
 	}
+
+	// ---- Lottery (Stage 1) --------------------------------------------------
+	registerLotteryRoutes(router, serverCtx)
 }