《游戏服务端架构·核心系统与契约》10.3 批量领取、补偿与红点

ClaimBatch(ids):
  requested = len(ids)
  for id in sorted(ids):
      outcome = ClaimOne(id)
      granted   -> count, append grants
      already   -> count
      expired   -> count
      missing   -> count
      error     -> failures[]
  return counts + grants + failures

compensation_key = reason + source_id + recipient + grants_digest

// file: internal/mailclaim/claim.go
// tier: L1
// verify: go test ./internal/mailclaim/
package mailclaim

import (
	"errors"
	"sort"
	"time"
)

// Add inserts a mail in the unread, unclaimed state.
func (s *Store) Add(m Mail) error {
	if m.ID == "" || m.Recipient == "" {
		return ErrEmptyID
	}
	if !validGrants(m.Grants) {
		return ErrInvalidGrant
	}
	if _, ok := s.mails[m.ID]; ok {
		return ErrDuplicateID
	}
	cp := m
	cp.Grants = cloneGrants(m.Grants)
	s.mails[cp.ID] = &cp
	s.order = append(s.order, cp.ID)
	s.version++
	return nil
}

// MarkRead clears the unread bit. It is idempotent and does not bump the
// version twice.
func (s *Store) MarkRead(recipient, id string) error {
	m, ok := s.mails[id]
	if !ok {
		return ErrNotFound
	}
	if m.Recipient != recipient {
		return ErrNotOwner
	}
	if !m.Read {
		m.Read = true
		s.version++
	}
	return nil
}

// ClaimOne decides one mail. Expiry is a status, not an error, because a
// batch must continue with the remaining mails.
func (s *Store) ClaimOne(recipient, id string, now time.Time) (ClaimOutcome, error) {
	m, ok := s.mails[id]
	if !ok {
		return ClaimOutcome{MailID: id, Status: ClaimMissing}, ErrNotFound
	}
	if m.Recipient != recipient {
		return ClaimOutcome{MailID: id, Status: ClaimMissing}, ErrNotOwner
	}
	if m.Claimed {
		return ClaimOutcome{MailID: id, Status: ClaimAlready, Grants: cloneGrants(m.Grants)}, nil
	}
	if now.After(m.ExpiresAt) {
		return ClaimOutcome{MailID: id, Status: ClaimExpired}, nil
	}
	m.Claimed = true
	s.version++
	return ClaimOutcome{MailID: id, Status: ClaimGranted, Grants: cloneGrants(m.Grants)}, nil
}

// ClaimBatch claims ids independently. A missing or expired mail is reported
// in the result; an earlier grant stays granted when a later mail fails.
func (s *Store) ClaimBatch(recipient string, ids []string, now time.Time) BatchResult {
	result := BatchResult{Requested: len(ids)}
	for _, id := range ids {
		outcome, err := s.ClaimOne(recipient, id, now)
		if err != nil {
			if errors.Is(err, ErrNotFound) {
				result.Missing++
			} else {
				result.Failures = append(result.Failures, Failure{MailID: id, Reason: err.Error()})
			}
			continue
		}
		switch outcome.Status {
		case ClaimGranted:
			result.Granted++
			result.Grants = append(result.Grants, outcome.Grants...)
		case ClaimAlready:
			result.Already++
		case ClaimExpired:
			result.Expired++
		}
	}
	sort.Slice(result.Grants, func(i, j int) bool {
		if result.Grants[i].ItemID == result.Grants[j].ItemID {
			return result.Grants[i].Count < result.Grants[j].Count
		}
		return result.Grants[i].ItemID < result.Grants[j].ItemID
	})
	sort.Slice(result.Failures, func(i, j int) bool {
		return result.Failures[i].MailID < result.Failures[j].MailID
	})
	return result
}

// ClaimAll claims every mail currently owned by recipient.
func (s *Store) ClaimAll(recipient string, now time.Time) BatchResult {
	ids := make([]string, 0, len(s.order))
	for _, id := range s.order {
		if s.mails[id].Recipient == recipient {
			ids = append(ids, id)
		}
	}
	sort.Strings(ids)
	return s.ClaimBatch(recipient, ids, now)
}

// file: internal/mailclaim/compensation.go
// tier: L1
// verify: go test ./internal/mailclaim/
package mailclaim

import "time"

// IssueCompensation creates a compensation mail once per key. A replay returns
// the original mail ID and writes a duplicate entry to the audit log.
func (s *Store) IssueCompensation(c Compensation, at time.Time) (CompensationResult, error) {
	if c.Key == "" {
		return CompensationResult{}, ErrEmptyKey
	}
	if c.Recipient == "" {
		return CompensationResult{}, ErrEmptyID
	}
	if c.Reason == "" {
		return CompensationResult{}, ErrEmptyReason
	}
	if !validGrants(c.Grants) {
		return CompensationResult{}, ErrNoGrants
	}
	if id, ok := s.compensations[c.Key]; ok {
		s.audit = append(s.audit, AuditEntry{
			At: at, Action: "compensation", Key: c.Key,
			Recipient: c.Recipient, MailID: id, Duplicate: true,
		})
		return CompensationResult{MailID: id, Duplicate: true}, nil
	}

	mailID := "comp-" + c.Key
	if _, ok := s.mails[mailID]; ok {
		return CompensationResult{}, ErrCompensationID
	}
	s.mails[mailID] = &Mail{
		ID:        mailID,
		Recipient: c.Recipient,
		Title:     "补偿：" + c.Reason,
		Grants:    cloneGrants(c.Grants),
		ExpiresAt: c.ExpiresAt,
	}
	s.order = append(s.order, mailID)
	s.compensations[c.Key] = mailID
	s.version++
	s.audit = append(s.audit, AuditEntry{
		At: at, Action: "compensation", Key: c.Key,
		Recipient: c.Recipient, MailID: mailID,
	})
	return CompensationResult{MailID: mailID}, nil
}

func (s *Store) Audit() []AuditEntry {
	return append([]AuditEntry(nil), s.audit...)
}

func (s *Store) Version() uint64 {
	return s.version
}

// file: internal/mailclaim/reddot.go
// tier: L1
// verify: go test ./internal/mailclaim/
package mailclaim

import "time"

// RedDot derives every badge count from the same mail list. A second counter
// maintained by a template or a client is the bug, not the cache.
func (s *Store) RedDot(recipient string, now time.Time, soon time.Duration) RedDot {
	if soon < 0 {
		soon = 0
	}
	dot := RedDot{Version: s.version}
	deadline := now.Add(soon)
	for _, m := range s.mails {
		if m.Recipient != recipient {
			continue
		}
		if !m.Read {
			dot.Unread++
		}
		if m.Claimed || now.After(m.ExpiresAt) || len(m.Grants) == 0 {
			continue
		}
		dot.Claimable++
		if !m.ExpiresAt.After(deadline) {
			dot.ExpiringSoon++
		}
	}
	return dot
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/mailclaim
$ go vet ./internal/mailclaim/...
$ go test -count=1 ./internal/mailclaim/
ok  	gsarchlab/internal/mailclaim