《游戏服务端架构·核心系统与契约》7.2 任务事件与进度服务

// file: internal/questprogress/questprogress.go
// tier: L1
// verify: go test ./internal/questprogress/
package questprogress

import (
	"errors"
	"fmt"
	"slices"
	"strconv"
	"strings"
)

// Status is the only lifecycle a quest may have. There is no failed state:
// a failed quest is still active and its progress is not rolled back.
type Status int

const (
	StatusLocked Status = iota
	StatusActive
	StatusCompleted
)

// Objective is one counter. Gate defers counting until another quest is
// completed; deferred events are replayed from the retained log.
type Objective struct {
	Kind   string
	Target string
	Need   int64
	Gate   string
}

type Quest struct {
	ID         string
	Prereqs    []string
	Objectives []Objective
}

// Event is an already-normalised domain fact. ID is the idempotency key and
// must stay stable across redelivery, retries and cross-day compensation.
type Event struct {
	ID     string
	Kind   string
	Target string
	Amount int64
}

var (
	ErrUnknownQuest  = errors.New("questprogress: unknown quest")
	ErrAlreadyActive = errors.New("questprogress: quest already active")
	ErrPrereq        = errors.New("questprogress: prerequisite not completed")
	ErrEmptyEvent    = errors.New("questprogress: empty event id")
	ErrInvalidEvent  = errors.New("questprogress: invalid event")
	ErrInvalidQuest  = errors.New("questprogress: invalid quest")
)

type Result struct {
	Duplicate bool
	Advanced  []string
	Completed []string
}

type player struct {
	status   map[string]Status
	progress map[string][]int64
	seen     map[string]bool
	applied  map[string]bool
	log      []Event
}

type Service struct {
	quests  map[string]Quest
	order   []string
	players map[string]*player
}

// New validates the whole catalog before serving anything: a broken chain
// must fail deployment, not one player's quest at runtime.
func New(quests []Quest) (*Service, error) {
	s := &Service{quests: map[string]Quest{}, players: map[string]*player{}}
	for _, q := range quests {
		if strings.TrimSpace(q.ID) == "" || len(q.Objectives) == 0 {
			return nil, fmt.Errorf("%w: quest %q", ErrInvalidQuest, q.ID)
		}
		if _, ok := s.quests[q.ID]; ok {
			return nil, fmt.Errorf("%w: duplicate %q", ErrInvalidQuest, q.ID)
		}
		for _, o := range q.Objectives {
			if strings.TrimSpace(o.Kind) == "" || o.Need <= 0 {
				return nil, fmt.Errorf("%w: quest %q objective", ErrInvalidQuest, q.ID)
			}
		}
		s.quests[q.ID] = q
		s.order = append(s.order, q.ID)
	}
	for _, q := range quests {
		for _, pre := range q.Prereqs {
			if _, ok := s.quests[pre]; !ok {
				return nil, fmt.Errorf("%w: %q needs %q", ErrInvalidQuest, q.ID, pre)
			}
		}
		for _, o := range q.Objectives {
			if o.Gate == "" {
				continue
			}
			if _, ok := s.quests[o.Gate]; !ok {
				return nil, fmt.Errorf("%w: %q gate %q", ErrInvalidQuest, q.ID, o.Gate)
			}
		}
	}
	if s.hasCycle() {
		return nil, fmt.Errorf("%w: prerequisite cycle", ErrInvalidQuest)
	}
	return s, nil
}

func (s *Service) hasCycle() bool {
	color := map[string]int{}
	var visit func(string) bool
	visit = func(id string) bool {
		switch color[id] {
		case 1:
			return true
		case 2:
			return false
		}
		color[id] = 1
		for _, pre := range s.quests[id].Prereqs {
			if visit(pre) {
				return true
			}
		}
		color[id] = 2
		return false
	}
	for _, id := range s.order {
		if visit(id) {
			return true
		}
	}
	return false
}

// Accept checks prerequisites against completed status, never against partial
// progress, so a half-finished predecessor cannot leak progress.
func (s *Service) Accept(playerID, questID string) (Result, error) {
	q, ok := s.quests[questID]
	if !ok {
		return Result{}, fmt.Errorf("%w: %s", ErrUnknownQuest, questID)
	}
	p := s.state(playerID)
	switch p.status[questID] {
	case StatusActive:
		return Result{}, fmt.Errorf("%w: %s", ErrAlreadyActive, questID)
	case StatusCompleted:
		return Result{}, nil
	}
	for _, pre := range q.Prereqs {
		if p.status[pre] != StatusCompleted {
			return Result{}, fmt.Errorf("%w: %s needs %s", ErrPrereq, questID, pre)
		}
	}
	p.status[questID] = StatusActive
	res := Result{}
	s.replay(p, &res)
	s.drain(p, &res)
	return res, nil
}

// Ingest applies one event at most once per player. Redelivery returns
// Duplicate instead of an error: the caller should ack and move on.
func (s *Service) Ingest(playerID string, ev Event) (Result, error) {
	if strings.TrimSpace(ev.ID) == "" {
		return Result{}, ErrEmptyEvent
	}
	if strings.TrimSpace(ev.Kind) == "" || ev.Amount <= 0 {
		return Result{}, fmt.Errorf("%w: kind=%q amount=%d", ErrInvalidEvent, ev.Kind, ev.Amount)
	}
	p := s.state(playerID)
	if p.seen[ev.ID] {
		return Result{Duplicate: true}, nil
	}
	p.seen[ev.ID] = true
	p.log = append(p.log, ev)
	res := Result{}
	s.apply(p, ev, &res)
	s.drain(p, &res)
	return res, nil
}

func (s *Service) apply(p *player, ev Event, res *Result) {
	for _, qid := range s.order {
		if p.status[qid] != StatusActive {
			continue
		}
		changed := false
		for i, o := range s.quests[qid].Objectives {
			if o.Kind != ev.Kind || (o.Target != "" && o.Target != ev.Target) {
				continue
			}
			if o.Gate != "" && p.status[o.Gate] != StatusCompleted {
				continue
			}
			key := qid + "#" + strconv.Itoa(i) + "#" + ev.ID
			if p.applied[key] {
				continue
			}
			p.applied[key] = true
			before := p.progress[qid][i]
			next := before + ev.Amount
			if next > o.Need {
				next = o.Need
			}
			p.progress[qid][i] = next
			if next != before {
				changed = true
			}
		}
		if changed && !slices.Contains(res.Advanced, qid) {
			res.Advanced = append(res.Advanced, qid)
		}
	}
}

// drain completes every active quest whose objectives are full, then replays
// the log because a completion may open another quest's Gate. Applied keys
// make the replay safe; the loop stops when a pass completes nothing.
func (s *Service) drain(p *player, res *Result) {
	for {
		changed := false
		for _, qid := range s.order {
			if p.status[qid] != StatusActive || !s.done(p, qid) {
				continue
			}
			p.status[qid] = StatusCompleted
			res.Completed = append(res.Completed, qid)
			changed = true
		}
		if !changed {
			return
		}
		s.replay(p, res)
	}
}

func (s *Service) replay(p *player, res *Result) {
	for _, ev := range p.log {
		s.apply(p, ev, res)
	}
}

func (s *Service) done(p *player, qid string) bool {
	for i, o := range s.quests[qid].Objectives {
		if p.progress[qid][i] < o.Need {
			return false
		}
	}
	return true
}

func (s *Service) state(playerID string) *player {
	p := s.players[playerID]
	if p != nil {
		return p
	}
	p = &player{status: map[string]Status{}, progress: map[string][]int64{}, seen: map[string]bool{}, applied: map[string]bool{}}
	for _, id := range s.order {
		p.progress[id] = make([]int64, len(s.quests[id].Objectives))
	}
	s.players[playerID] = p
	return p
}

func (s *Service) Status(playerID, questID string) Status {
	p := s.players[playerID]
	if p == nil {
		return StatusLocked
	}
	return p.status[questID]
}

func (s *Service) Progress(playerID, questID string) []int64 {
	p := s.players[playerID]
	if p == nil {
		return nil
	}
	return append([]int64(nil), p.progress[questID]...)
}