From 6fe4dc91f3944cd1a1120b429db3beeed87a2063 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Jul 2026 10:39:24 +0000 Subject: [PATCH] feat: add admin endpoint to grant an existing star gift to a user New POST /v1/accounts/grant-star-gift admin API endpoint. Recipient is resolved by user_id, username, or phone (in that priority order) via new AdminUserByUsername/AdminUserByPhone lookups that bypass privacy projection (appropriate for admin/back-office actions). Delivery is funded internally from the official system account (777000) and routed through the existing purchase-form + Purchase flow, so availability counters, per-user limits, and idempotent delivery are enforced by already-tested code rather than a new parallel free-grant path. price_label is optional and purely informational (recorded in the command's audit details only) -- it is never charged against the recipient. NOTE: could not run 'go build'/'go test' in the authoring sandbox (go.mod requires go 1.25, sandbox toolchain is 1.22 with no network access to download the newer toolchain). Verified with gofmt only. Build and test locally before deploying. --- internal/admin/service.go | 157 ++++++++++++++++++++++++++++++++++ internal/adminapi/server.go | 15 ++++ internal/app/users/service.go | 21 +++++ 3 files changed, 193 insertions(+) diff --git a/internal/admin/service.go b/internal/admin/service.go index 386f1591..dfb5b574 100644 --- a/internal/admin/service.go +++ b/internal/admin/service.go @@ -22,6 +22,7 @@ const ( ActionSetAccountFrozen = "account.set_frozen" ActionGrantPremium = "account.grant_premium" ActionGrantStars = "account.grant_stars" + ActionGrantStarGift = "account.grant_star_gift" ActionSetVerified = "account.set_verified" ActionSetChannelVerified = "channel.set_verified" ActionRevokeSessions = "account.revoke_sessions" @@ -64,6 +65,8 @@ type AuthKeyRevoker interface { type UsersService interface { AdminUser(ctx context.Context, userID int64) (domain.User, bool, error) + AdminUserByUsername(ctx context.Context, username string) (domain.User, bool, error) + AdminUserByPhone(ctx context.Context, phone string) (domain.User, bool, error) GrantPremium(ctx context.Context, userID int64, months int) (domain.User, error) SetVerified(ctx context.Context, userID int64, verified bool) (domain.User, error) } @@ -97,6 +100,9 @@ type MessagesService interface { } type GiftsService interface { + GiftByID(ctx context.Context, id int64) (domain.StarGift, bool, error) + IssuePurchaseForm(ctx context.Context, form domain.StarGiftPurchaseForm) (domain.StarGiftPurchaseForm, error) + Purchase(ctx context.Context, req domain.StarGiftPurchaseRequest) (domain.StarGiftPurchaseResult, error) PrepareAnimation(fileName string, data []byte) (domain.StarGiftAnimation, error) PrepareOfficialAnimation(fileName string, data []byte) (domain.StarGiftAnimation, error) CreateCatalogRevision(ctx context.Context, write domain.StarGiftCatalogWrite) (domain.StarGiftCatalogEntry, error) @@ -316,6 +322,23 @@ type GrantStarsRequest struct { Amount int64 `json:"amount"` } +// GrantStarGiftRequest grants an existing catalog gift to a recipient +// identified by UserID, Username, or Phone (checked in that priority order). +// PriceLabel is purely informational (recorded in the command's audit +// details) — it is never charged; delivery is funded internally from the +// official system account so it goes through the same tested purchase path +// as a normal paid gift. +type GrantStarGiftRequest struct { + CommandMeta + UserID int64 `json:"user_id,omitempty"` + Username string `json:"username,omitempty"` + Phone string `json:"phone,omitempty"` + GiftID int64 `json:"gift_id"` + PriceLabel string `json:"price_label,omitempty"` + Message string `json:"message,omitempty"` + HideName bool `json:"hide_name,omitempty"` +} + type SetVerifiedRequest struct { CommandMeta UserID int64 `json:"user_id"` @@ -562,6 +585,140 @@ func (s *Service) GrantStars(ctx context.Context, req GrantStarsRequest) (Comman }) } +// resolveAdminRecipient looks up a target user for an admin action by +// UserID, Username, or Phone, in that priority order. Exactly one of the +// three should normally be set. +func (s *Service) resolveAdminRecipient(ctx context.Context, userID int64, username, phone string) (domain.User, error) { + if s == nil || s.users == nil { + return domain.User{}, fmt.Errorf("admin user dependency is not configured") + } + switch { + case userID > 0: + u, found, err := s.users.AdminUser(ctx, userID) + if err != nil { + return domain.User{}, err + } + if !found { + return domain.User{}, domain.ErrUserNotFound + } + return u, nil + case strings.TrimSpace(username) != "": + u, found, err := s.users.AdminUserByUsername(ctx, username) + if err != nil { + return domain.User{}, err + } + if !found { + return domain.User{}, domain.ErrUserNotFound + } + return u, nil + case strings.TrimSpace(phone) != "": + u, found, err := s.users.AdminUserByPhone(ctx, phone) + if err != nil { + return domain.User{}, err + } + if !found { + return domain.User{}, domain.ErrUserNotFound + } + return u, nil + default: + return domain.User{}, fmt.Errorf("one of user_id, username, or phone is required") + } +} + +// GrantStarGift delivers an existing catalog gift to a recipient for free. +// It does not invent a parallel "free gift" code path: it funds the official +// system account for exactly the gift's catalog price and sends it through +// the same purchase-form + Purchase flow used for a real paid gift, so all +// the usual invariants (availability counters, per-user limits, idempotent +// delivery) are enforced by already-tested code. PriceLabel is never charged +// against the recipient — it's recorded in the command's audit details only, +// for the admin's own bookkeeping (e.g. an internal marketplace price tag). +func (s *Service) GrantStarGift(ctx context.Context, req GrantStarGiftRequest) (CommandResult, error) { + if req.GiftID <= 0 { + return CommandResult{}, fmt.Errorf("gift_id is required") + } + if s == nil || s.users == nil || s.gifts == nil || s.stars == nil { + return CommandResult{}, fmt.Errorf("admin gift dependencies are not configured") + } + recipient, err := s.resolveAdminRecipient(ctx, req.UserID, req.Username, req.Phone) + if err != nil { + return CommandResult{}, err + } + if recipient.Bot { + return CommandResult{}, fmt.Errorf("cannot grant a gift to a bot account") + } + return s.runCommand(ctx, req.CommandMeta, ActionGrantStarGift, recipient.ID, domain.Peer{}, req, func() (CommandResult, error) { + gift, found, err := s.gifts.GiftByID(ctx, req.GiftID) + if err != nil { + return CommandResult{}, err + } + if !found { + return CommandResult{}, domain.ErrStarGiftInvalid + } + details := map[string]any{ + "recipient_user_id": recipient.ID, + "recipient_username": recipient.Username, + "recipient_phone": recipient.Phone, + "gift_id": gift.ID, + "gift_title": gift.Title, + "gift_stars": gift.Stars, + "price_label": req.PriceLabel, + } + if req.DryRun { + return CommandResult{Message: "dry-run completed", Details: details}, nil + } + now := s.now() + // Fund the house/system account for exactly this gift's price. This + // keeps the transfer inside the existing, tested purchase ledger + // instead of writing a new free-grant path that could drift out of + // sync with availability/per-user-limit bookkeeping. + if _, err := s.stars.Credit(ctx, domain.OfficialSystemUserID, gift.Stars, domain.StarsReasonAdjust, + domain.Peer{}, "Admin gift grant funding", req.Reason); err != nil { + return CommandResult{}, err + } + form := domain.StarGiftPurchaseForm{ + BuyerUserID: domain.OfficialSystemUserID, + To: domain.Peer{Type: domain.PeerTypeUser, ID: recipient.ID}, + GiftID: gift.ID, + RevisionID: gift.RevisionID, + HideName: req.HideName, + Message: req.Message, + ChargeStars: gift.Stars, + IssuedAt: now.Unix(), + ExpiresAt: now.Unix() + 600, + } + issued, err := s.gifts.IssuePurchaseForm(ctx, form) + if err != nil { + return CommandResult{}, err + } + commandKey := strings.TrimSpace(req.CommandMeta.CommandID) + if commandKey == "" { + commandKey = fmt.Sprintf("admin-gift-grant:%d:%d", recipient.ID, issued.FormID) + } + purchaseReq := domain.StarGiftPurchaseRequest{ + BuyerUserID: domain.OfficialSystemUserID, + To: issued.To, + GiftID: issued.GiftID, + RevisionID: issued.RevisionID, + HideName: issued.HideName, + Message: issued.Message, + ChargeStars: issued.ChargeStars, + FormID: issued.FormID, + CommandKey: commandKey, + Date: int(now.Unix()), + } + result, err := s.gifts.Purchase(ctx, purchaseReq) + if err != nil { + return CommandResult{}, err + } + details["saved_gift_id"] = result.Saved.ID + if err := s.notifyUserChanged(ctx, recipient); err != nil { + details["notify_error"] = err.Error() + } + return CommandResult{Message: "gift granted", Details: details}, nil + }) +} + func (s *Service) SetVerified(ctx context.Context, req SetVerifiedRequest) (CommandResult, error) { if req.UserID <= 0 { return CommandResult{}, fmt.Errorf("user_id is required") diff --git a/internal/adminapi/server.go b/internal/adminapi/server.go index e7f07f14..a42d2287 100644 --- a/internal/adminapi/server.go +++ b/internal/adminapi/server.go @@ -28,6 +28,7 @@ type Service interface { SetAccountFrozen(ctx context.Context, req admin.SetAccountFrozenRequest) (admin.CommandResult, error) GrantPremium(ctx context.Context, req admin.GrantPremiumRequest) (admin.CommandResult, error) GrantStars(ctx context.Context, req admin.GrantStarsRequest) (admin.CommandResult, error) + GrantStarGift(ctx context.Context, req admin.GrantStarGiftRequest) (admin.CommandResult, error) SetVerified(ctx context.Context, req admin.SetVerifiedRequest) (admin.CommandResult, error) SetChannelVerified(ctx context.Context, req admin.SetChannelVerifiedRequest) (admin.CommandResult, error) RevokeSessions(ctx context.Context, req admin.RevokeSessionsRequest) (admin.CommandResult, error) @@ -94,6 +95,7 @@ func (s *Server) routes() http.Handler { mux.HandleFunc("POST /v1/accounts/set-frozen", s.authenticated(s.handleSetAccountFrozen)) mux.HandleFunc("POST /v1/accounts/grant-premium", s.authenticated(s.handleGrantPremium)) mux.HandleFunc("POST /v1/accounts/grant-stars", s.authenticated(s.handleGrantStars)) + mux.HandleFunc("POST /v1/accounts/grant-star-gift", s.authenticated(s.handleGrantStarGift)) mux.HandleFunc("POST /v1/accounts/set-verified", s.authenticated(s.handleSetVerified)) mux.HandleFunc("POST /v1/accounts/revoke-sessions", s.authenticated(s.handleRevokeSessions)) mux.HandleFunc("POST /v1/channels/set-verified", s.authenticated(s.handleSetChannelVerified)) @@ -150,6 +152,19 @@ func (s *Server) handleGrantStars(w http.ResponseWriter, r *http.Request) { writeCommandResult(w, result, err) } +// handleGrantStarGift grants an existing catalog gift (identified by +// gift_id) to a recipient identified by user_id, username, or phone. +// price_label is optional and purely informational (e.g. an internal +// marketplace price tag like "1000 YUT") — it is never charged. +func (s *Server) handleGrantStarGift(w http.ResponseWriter, r *http.Request) { + var req admin.GrantStarGiftRequest + if !decodeJSON(w, r, &req) { + return + } + result, err := s.svc.GrantStarGift(r.Context(), req) + writeCommandResult(w, result, err) +} + func (s *Server) handleSetVerified(w http.ResponseWriter, r *http.Request) { var req admin.SetVerifiedRequest if !decodeJSON(w, r, &req) { diff --git a/internal/app/users/service.go b/internal/app/users/service.go index fa7bed43..3f5d86fb 100644 --- a/internal/app/users/service.go +++ b/internal/app/users/service.go @@ -132,6 +132,27 @@ func (s *Service) AdminUser(ctx context.Context, userID int64) (domain.User, boo return s.loadBaseUserByID(ctx, userID) } +// AdminUserByUsername resolves a username to a user for admin/back-office use. +// Unlike ResolveUsername, this bypasses privacy projection: admin actions act +// on the raw account, not on what a given viewer is allowed to see. +func (s *Service) AdminUserByUsername(ctx context.Context, username string) (domain.User, bool, error) { + username = normalizeUsername(username) + if !validUsername(username) { + return domain.User{}, false, domain.ErrUsernameInvalid + } + return s.users.ByUsername(ctx, username) +} + +// AdminUserByPhone resolves a phone number to a user for admin/back-office +// use. Bypasses privacy projection for the same reason as AdminUserByUsername. +func (s *Service) AdminUserByPhone(ctx context.Context, phone string) (domain.User, bool, error) { + phone = normalizePhone(phone) + if phone == "" { + return domain.User{}, false, domain.ErrPhoneNotOccupied + } + return s.users.ByPhone(ctx, phone) +} + // ByIDs 批量返回指定用户。调用方必须已登录;缺失用户不会出现在结果中。 func (s *Service) ByIDs(ctx context.Context, currentUserID int64, userIDs []int64) ([]domain.User, error) { if currentUserID == 0 {