《MMO 服务器开发》15.2 附件、过期与流拍结算

// file: internal/mail/claim.go
// tier: L1
// verify: go test ./internal/mail/

package mail

import (
	"errors"
	"time"
)

// ErrAlreadyClaimed is returned when a claim targets an attachment that has
// already been granted.
var ErrAlreadyClaimed = errors.New("mail: attachment already claimed")

// ErrMailExpired is returned when a claim targets a mail past its ExpireAt.
var ErrMailExpired = errors.New("mail: mail expired")

// ErrNoAttachment is returned when the attachment index is out of range.
var ErrNoAttachment = errors.New("mail: no such attachment")

// Grant is the outcome of a claim or an expiry sweep: what the bag service must
// add for the player. Bound grants are non-tradeable (auction settlement).
type Grant struct {
	Player PlayerID
	Att    Attachment
	Bound  bool
}

// stateLocked returns the per-attachment claim flags for id, sized to n. It
// lives in the mailbox rather than the Mail value so a List snapshot cannot be
// mutated by a later claim.
func (mb *Mailbox) stateLocked(id MailID, n int) []bool {
	if mb.claimed == nil {
		mb.claimed = make(map[MailID][]bool)
	}
	s, ok := mb.claimed[id]
	if !ok || len(s) != n {
		s = make([]bool, n)
		mb.claimed[id] = s
	}
	return s
}

// Claim grants attachment idx of mail id exactly once. A repeat call for the
// same (id, idx) returns ErrAlreadyClaimed; the mail is left in place so the
// player can still read the body and claim the rest.
func (mb *Mailbox) Claim(id MailID, idx int, now time.Time) (Grant, error) {
	mb.mu.Lock()
	defer mb.mu.Unlock()
	m, ok := mb.mails[id]
	if !ok {
		return Grant{}, ErrNoSuchMail
	}
	if !m.ExpireAt.IsZero() && !now.Before(m.ExpireAt) {
		return Grant{}, ErrMailExpired
	}
	if idx < 0 || idx >= len(m.Attachments) {
		return Grant{}, ErrNoAttachment
	}
	flags := mb.stateLocked(id, len(m.Attachments))
	if flags[idx] {
		return Grant{}, ErrAlreadyClaimed
	}
	flags[idx] = true
	if allTrue(flags) {
		m.Claimed = true
	}
	return Grant{Player: mb.owner, Att: m.Attachments[idx]}, nil
}

// ClaimAll grants every still-unclaimed attachment in one call and marks the
// mail claimed. Already-claimed slots are skipped, so the call is idempotent at
// the mail level: a second ClaimAll returns no grants and no error.
func (mb *Mailbox) ClaimAll(id MailID, now time.Time) ([]Grant, error) {
	mb.mu.Lock()
	defer mb.mu.Unlock()
	m, ok := mb.mails[id]
	if !ok {
		return nil, ErrNoSuchMail
	}
	if !m.ExpireAt.IsZero() && !now.Before(m.ExpireAt) {
		return nil, ErrMailExpired
	}
	flags := mb.stateLocked(id, len(m.Attachments))
	var out []Grant
	for i, a := range m.Attachments {
		if flags[i] {
			continue
		}
		flags[i] = true
		out = append(out, Grant{Player: mb.owner, Att: a})
	}
	m.Claimed = true
	return out, nil
}

// Discard deletes a mail the player no longer wants. Only a fully claimed mail
// may be discarded, so an unclaimed attachment can never be silently dropped.
func (mb *Mailbox) Discard(id MailID) error {
	mb.mu.Lock()
	defer mb.mu.Unlock()
	m, ok := mb.mails[id]
	if !ok {
		return ErrNoSuchMail
	}
	if !m.Claimed {
		return ErrAlreadyClaimed
	}
	mb.remove(id)
	return nil
}

func allTrue(b []bool) bool {
	for _, v := range b {
		if !v {
			return false
		}
	}
	return true
}

// snippet: internal/mail/expire.go

// Sweep 遍历邮箱，过期所有 ExpireAt <= now 的邮件。玩家没领的附件不会丢：
// KindNormal 邮件把原始物品交给背包，KindAuctionReturn 邮件把物品过一遍 conv
// 并返回一个绑定 Grant。随后邮件被删除，其 ID 仍留在去重集里。
func (mb *Mailbox) Sweep(now time.Time, conv func(Attachment) Attachment) []Grant {
	mb.mu.Lock()
	defer mb.mu.Unlock()
	var out []Grant
	// 先复制 order：循环里会调用 remove，直接遍历会被边删边走搞乱索引。
	for _, id := range append([]MailID(nil), mb.order...) {
		m := mb.mails[id]
		if m.ExpireAt.IsZero() || now.Before(m.ExpireAt) {
			continue
		}
		flags := mb.stateLocked(id, len(m.Attachments))
		for i, a := range m.Attachments {
			if flags[i] {
				continue
			}
			if m.Kind == KindAuctionReturn && conv != nil {
				out = append(out, Grant{Player: mb.owner, Att: conv(a), Bound: true})
			} else {
				out = append(out, Grant{Player: mb.owner, Att: a})
			}
		}
		mb.remove(id)
	}
	return out
}

// snippet: internal/mail/claim_test.go（节选）

func TestSweepSettlesFailedAuctionAsBound(t *testing.T) {
	mb := NewMailbox(7, 16, time.Hour)
	m := withAttach(5, 9001)
	m.Kind = KindAuctionReturn
	m.ExpireAt = base.Add(time.Hour)
	_ = mb.Deliver(m, base)

	// 把流拍物品折算成绑定货币：1 件 -> 50 金币。
	gold := func(a Attachment) Attachment { return Attachment{ItemID: 1, Count: a.Count * 50} }
	grants := mb.Sweep(base.Add(2*time.Hour), gold)
	if len(grants) != 1 || !grants[0].Bound {
		t.Fatalf("settlement = %+v, want one bound grant", grants)
	}
}