《游戏服务端架构·规模化、全球化与成本》10.2 隐私、数据出境与删除权

// file: internal/privacydeletion/deletion.go
// tier: L1
// verify: go test ./internal/privacydeletion/
package privacydeletion

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

// DataClass groups stores by the obligation that governs them, not by the
// database engine. A single account deletion touches identity, payment,
// logs, backups and third parties, and each class can end in a different
// action.
type DataClass string

const (
	ClassIdentity   DataClass = "account_identity"
	ClassPayment    DataClass = "payment"
	ClassBehavior   DataClass = "behavior_log"
	ClassReplay     DataClass = "battle_replay"
	ClassContent    DataClass = "user_content"
	ClassBackup     DataClass = "backup"
	ClassThirdParty DataClass = "third_party"
)

// Action is what the plan does to one target. RetainHold is produced by the
// planner, never by the catalog: a legal hold overrides a delete or anonymize
// instruction and must remain visible in the completion proof.
type Action string

const (
	ActionDelete     Action = "delete"
	ActionAnonymize  Action = "anonymize"
	ActionTombstone  Action = "tombstone"
	ActionRetainHold Action = "retain_legal_hold"
)

func actionValid(a Action) bool {
	switch a {
	case ActionDelete, ActionAnonymize, ActionTombstone:
		return true
	default:
		return false
	}
}

// Target describes one store that must be touched. DependsOn orders the
// cascade: a cache invalidation that runs before the primary row is deleted
// will simply be repopulated by the next read.
type Target struct {
	Name         string
	Class        DataClass
	Region       string
	Action       Action
	RetainOnHold bool
	DependsOn    []string
}

// Request is a verified deletion request. Verified is explicit because an
// unverified request is an account-takeover vector, not a data subject right.
type Request struct {
	RequestID   string
	AccountID   string
	RequestedAt time.Time
	Verified    bool
	LegalHold   bool
}

// Step is one target with the action the planner selected after applying the
// hold policy. Execute consumes Steps, not Targets, so a hold cannot be
// silently dropped by a later code path.
type Step struct {
	Target Target
	Action Action
}

type Plan struct {
	RequestID string
	AccountID string
	CreatedAt time.Time
	Steps     []Step
}

// Receipt is evidence that one target completed. Evidence is target-specific
// (row count, object version, webhook id) and is covered by the proof digest.

var (
	ErrInvalidRequest    = errors.New("privacydeletion: request id and account id are required")
	ErrNotVerified       = errors.New("privacydeletion: request identity is not verified")
	ErrEmptyTarget       = errors.New("privacydeletion: empty target name")
	ErrDuplicateTarget   = errors.New("privacydeletion: duplicate target name")
	ErrBadAction         = errors.New("privacydeletion: unsupported catalog action")
	ErrUnknownDependency = errors.New("privacydeletion: unknown dependency")
	ErrCycle             = errors.New("privacydeletion: dependency cycle")
	ErrApply             = errors.New("privacydeletion: apply failed")
)

// BuildPlan validates the request and catalog, then orders targets with a
// deterministic topological sort. Ready targets are sorted by name so two
// runs over the same input produce the same proof digest.
func BuildPlan(catalog []Target, req Request) (Plan, error) {
	if req.RequestID == "" || req.AccountID == "" {
		return Plan{}, ErrInvalidRequest
	}
	if !req.Verified {
		return Plan{}, ErrNotVerified
	}
	byName := make(map[string]Target, len(catalog))
	for _, t := range catalog {
		if t.Name == "" {
			return Plan{}, ErrEmptyTarget
		}
		if _, ok := byName[t.Name]; ok {
			return Plan{}, fmt.Errorf("%w: %s", ErrDuplicateTarget, t.Name)
		}
		if !actionValid(t.Action) {
			return Plan{}, fmt.Errorf("%w: %s", ErrBadAction, t.Action)
		}
		byName[t.Name] = t
	}
	order, err := orderTargets(byName)
	if err != nil {
		return Plan{}, err
	}
	plan := Plan{
		RequestID: req.RequestID,
		AccountID: req.AccountID,
		CreatedAt: req.RequestedAt,
		Steps:     make([]Step, 0, len(order)),
	}
	for _, name := range order {
		t := byName[name]
		action := t.Action
		if req.LegalHold && t.RetainOnHold {
			action = ActionRetainHold
		}
		plan.Steps = append(plan.Steps, Step{Target: t, Action: action})
	}
	return plan, nil
}

func orderTargets(targets map[string]Target) ([]string, error) {
	indegree := make(map[string]int, len(targets))
	dependents := make(map[string][]string, len(targets))
	for name := range targets {
		indegree[name] = 0
	}
	for name, t := range targets {
		for _, dep := range t.DependsOn {
			if _, ok := targets[dep]; !ok {
				return nil, fmt.Errorf("%w: %s -> %s", ErrUnknownDependency, name, dep)
			}
			indegree[name]++
			dependents[dep] = append(dependents[dep], name)
		}
	}
	ready := make([]string, 0, len(targets))
	for name, n := range indegree {
		if n == 0 {
			ready = append(ready, name)
		}
	}
	sort.Strings(ready)
	order := make([]string, 0, len(targets))
	for len(ready) > 0 {
		name := ready[0]
		ready = ready[1:]
		order = append(order, name)
		for _, next := range dependents[name] {
			indegree[next]--
			if indegree[next] == 0 {
				ready = append(ready, next)
				sort.Strings(ready)
			}
		}
	}
	if len(order) != len(targets) {
		return nil, ErrCycle
	}
	return order, nil
}

// Execute runs steps in plan order and stops at the first failure. A failure
// returns no proof: a proof with missing receipts would let an incomplete
// cascade look finished. The caller persists progress separately and retries
// the remaining steps with the same request id.