《MMO 服务器开发》10.2 事件上报与进度服务

 战斗结算 ──(击杀 5001 ×3)──┐
 背包变动 ──(获得 7001 ×2)──┼──► Event{Kind, Target, Delta} ──► 进度服务
 NPC 对话 ──(对话 3021 ×1)──┘
 场景移动 ──(进入区域 88  ×1)─┘

// file: internal/quest/progress.go
// tier: L1
// verify: go test ./internal/quest/

package quest

import (
	"errors"
)

// PlayerID is the globally unique character id (same width as every other
// subsystem in the book).
type PlayerID uint64

// ObjKind is the objective family. Two objectives match an event only when both
// the kind and the target id agree.
type ObjKind uint8

const (
	ObjKill    ObjKind = iota // kill N of a monster
	ObjCollect                // hold N of an item
	ObjTalk                   // talk to an NPC
	ObjReach                  // arrive at a location id
)

// Objective is one completion requirement of a quest.
type Objective struct {
	Kind   ObjKind
	Target uint32
	Need   int
}

// Quest is a definition plus its objectives. 10.1's Graph only needs QuestDef;
// the progress service needs the objectives too, so it carries both.
type Quest struct {
	Def        QuestDef
	Objectives []Objective
}

// Event is what gameplay emits: "this player just killed monster 1003, three
// times". It is intentionally tiny — combat, inventory and NPC dialogue all
// lower their own semantics into this one shape before it reaches the quest
// service, so the service never learns about skills or item slots.
type Event struct {
	Kind   ObjKind
	Target uint32
	Delta  int
}

// ActiveQuest is one accepted-but-unfinished quest with per-objective counters.
type ActiveQuest struct {
	ID     QuestID
	Counts []int
	Ready  bool // every objective met; waiting for the finish request
}

// Book is one player's quest state. It is mutated only on the owning player's
// goroutine (single-writer), so it carries no lock; sharing it across goroutines
// is the caller's bug, not this type's.
type Book struct {
	PlayerID  PlayerID
	Completed map[QuestID]bool
	Active    map[QuestID]*ActiveQuest
	quests    map[QuestID]Quest
}

// ErrAlreadyActive / ErrNotActive / ErrNotReady describe the three ways a
// state-machine request can be rejected.
var (
	ErrAlreadyActive = errors.New("quest: already active")
	ErrNotActive     = errors.New("quest: not active")
	ErrNotReady      = errors.New("quest: objectives incomplete")
)

// NewBook builds an empty quest book over a static, read-only quest table.
func NewBook(pid PlayerID, quests map[QuestID]Quest) *Book {
	return &Book{
		PlayerID:  pid,
		Completed: map[QuestID]bool{},
		Active:    map[QuestID]*ActiveQuest{},
		quests:    quests,
	}
}

// Accept starts a quest. Prerequisites are checked by the caller against 10.1's
// Graph (they depend on the *completed* set, which lives here); this method only
// guards the local state machine so a duplicated CmdQuestAcceptReq cannot fork a
// second copy of the same quest.
func (b *Book) Accept(id QuestID) (*ActiveQuest, error) {
	if b.Completed[id] {
		return nil, ErrAlreadyActive
	}
	if _, ok := b.Active[id]; ok {
		return nil, ErrAlreadyActive
	}
	q, ok := b.quests[id]
	if !ok {
		return nil, ErrNotActive // unknown id: treat as not acceptable
	}
	aq := &ActiveQuest{ID: id, Counts: make([]int, len(q.Objectives))}
	b.Active[id] = aq
	return aq, nil
}

// Apply folds one gameplay event into every active quest and returns the quest
// IDs that became ready to finish *because of this event*. Counters are clamped
// at Need, so an over-delivered event (a single AoE that kills twelve) cannot
// overflow and a replay of the same event cannot push past the target.
func (b *Book) Apply(ev Event) []QuestID {
	var ready []QuestID
	for _, aq := range b.Active {
		q := b.quests[aq.ID]
		changed := false
		for i, o := range q.Objectives {
			if o.Kind != ev.Kind || o.Target != ev.Target {
				continue
			}
			before := aq.Counts[i]
			aq.Counts[i] = clamp(before+ev.Delta, o.Need)
			if aq.Counts[i] != before {
				changed = true
			}
		}
		if changed && !aq.Ready && b.allMet(aq, q) {
			aq.Ready = true
			ready = append(ready, aq.ID)
		}
	}
	sortIDs(ready)
	return ready
}

// Finish moves a ready quest into the completed set and returns it. It refuses
// a quest whose objectives are not met, which is the server-side half of the
// "client says I'm done" trust boundary.
func (b *Book) Finish(id QuestID) (*ActiveQuest, error) {
	aq, ok := b.Active[id]
	if !ok {
		return nil, ErrNotActive
	}
	if !aq.Ready {
		return nil, ErrNotReady
	}
	delete(b.Active, id)
	b.Completed[id] = true
	return aq, nil
}

func (b *Book) allMet(aq *ActiveQuest, q Quest) bool {
	for i, o := range q.Objectives {
		if aq.Counts[i] < o.Need {
			return false
		}
	}
	return true
}

func clamp(v, max int) int {
	if v < 0 {
		return 0
	}
	if v > max {
		return max
	}
	return v
}

// snippet: internal/quest/service.go（节选）

const (
	CmdQuestAcceptReq      = 0x0601
	CmdQuestProgressNotify = 0x0602
	CmdQuestFinishReq      = 0x0603
)

// freshSeq rejects a request whose seq was already handled. A dropped ack makes
// the client resend CmdQuestAcceptReq with the same seq; without this the second
// copy would hit ErrAlreadyActive and the client would wrongly conclude failure.
func (s *Service) freshSeq(pid PlayerID, seq uint32) bool {
	last, seen := s.dedup[pid]
	if seen && seq <= last {
		return false
	}
	s.dedup[pid] = seq
	return true
}

// HandleAccept processes a CmdQuestAcceptReq payload (u32 quest id). It checks
// the level gate and prerequisites against 10.1's graph, then starts the quest.
func (s *Service) HandleAccept(pid PlayerID, seq uint32, payload []byte) error {
	if len(payload) < 4 {
		return ErrShortFrame
	}
	if !s.freshSeq(pid, seq) {
		return nil // duplicate retransmit: idempotent no-op
	}
	id := QuestID(binary.BigEndian.Uint32(payload))
	def, ok := s.graph.Def(id)
	if !ok {
		return ErrNotActive
	}
	b := s.Book(pid)
	for _, p := range def.Prereqs {
		if !b.Completed[p] {
			return ErrNotReady
		}
	}
	_, err := b.Accept(id)
	return err
}

// snippet: internal/quest/progress_test.go（节选）

func TestFullQuestFlow(t *testing.T) {
	s := testService(t)
	const pid PlayerID = 42

	// Accept quest 100 (needs 3 kills of monster 5001).
	if err := s.HandleAccept(pid, 1, acceptPayload(100)); err != nil {
		t.Fatalf("accept 100: %v", err)
	}
	// Quest 101 is still blocked: its prereq 100 is not completed yet.
	if err := s.HandleAccept(pid, 2, acceptPayload(101)); err == nil {
		t.Fatal("accept 101 succeeded before prereq completed")
	}
	// One more kill crosses the threshold.
	if ready := s.HandleEvent(pid, Event{Kind: ObjKill, Target: 5001, Delta: 1}); !reflect.DeepEqual(ready, []QuestID{100}) {
		t.Fatalf("ready after 3 kills = %v, want [100]", ready)
	}
	// Over-delivery is clamped: a 10-kill event on a finished-in-progress quest
	// must not overflow the counter or re-fire the "ready" transition.
	if ready := s.HandleEvent(pid, Event{Kind: ObjKill, Target: 5001, Delta: 10}); len(ready) != 0 {
		t.Fatalf("over-delivery re-fired ready = %v", ready)
	}
	if err := s.HandleFinish(pid, 3, acceptPayload(100)); err != nil {
		t.Fatalf("finish 100: %v", err)
	}
	// Now 101 unlocks (prereq satisfied).
	if err := s.HandleAccept(pid, 4, acceptPayload(101)); err != nil {
		t.Fatalf("accept 101: %v", err)
	}
}