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.
This commit is contained in:
Claude
2026-07-29 10:39:24 +00:00
Unverified
parent e62ee93a10
commit 6fe4dc91f3
3 changed files with 193 additions and 0 deletions
+157
View File
@@ -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")
+15
View File
@@ -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) {
+21
View File
@@ -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 {