《游戏服务端架构·核心系统与契约》1.1 账号、角色、设备与租户

合并：
ACTIVE --begin--> MERGING --complete--> MERGED
                     |
                     +--abort--> ACTIVE

注销：
ACTIVE --request--> DELETING --purge(宽限期后)--> DELETED
                        |
                        +--cancel(截止前)--> ACTIVE

// file: internal/account/model.go
// tier: L1
// verify: go test ./internal/account/
package account

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

// Status is the lifecycle of an account. MERGING and DELETING are reversible;
// MERGED and DELETED are terminal. Rows are never removed: terminal rows become
// tombstones so a retired id cannot be recycled by a later registration.
type Status string

const (
	Active   Status = "ACTIVE"
	Merging  Status = "MERGING"
	Merged   Status = "MERGED"
	Deleting Status = "DELETING"
	Deleted  Status = "DELETED"
)

type RoleStatus string

const (
	RoleActive  RoleStatus = "ACTIVE"
	RoleFrozen  RoleStatus = "FROZEN"
	RoleDeleted RoleStatus = "DELETED"
)

var (
	ErrNotFound         = errors.New("account: not found")
	ErrBadState         = errors.New("account: transition not allowed")
	ErrTenantMismatch   = errors.New("account: tenant mismatch")
	ErrCrossTenantMerge = errors.New("account: cross-tenant merge disabled")
	ErrRoleNotOwned     = errors.New("account: role does not belong to account")
	ErrGraceActive      = errors.New("account: deletion grace still active")
	ErrGraceExpired     = errors.New("account: deletion grace expired")
	ErrSelfMerge        = errors.New("account: cannot merge into itself")
	ErrDeviceFull       = errors.New("account: device account limit reached")
)

// Tenant is one shipped product. It owns the deletion clock because the
// retention obligation belongs to the product, not to the platform.
type Tenant struct {
	ID          string
	DeleteGrace time.Duration
}

// Account is the identity subject: it holds credentials and survives products.
// HomeTenant records where it first appeared, for residency and audit only.
type Account struct {
	ID         string
	HomeTenant string
	Status     Status
	MergedInto string
	DeleteAt   time.Time
	Roles      map[string]*Role
	Devices    map[string]struct{}
}

// Role is the play subject inside one tenant. It can move between accounts,
// but it never crosses a tenant boundary, because its data lives there.
type Role struct {
	ID        string
	AccountID string
	TenantID  string
	Name      string
	Status    RoleStatus
}

// Device is a credential carrier, not an owner. One device may hold several
// accounts (shared tablet, net cafe) and one account may use several devices.
// Device ids are tenant-scoped so the platform cannot correlate players
// across products by hardware.
type Device struct {
	ID       string
	TenantID string
	Accounts map[string]struct{}
}

type MergePolicy struct {
	AllowCrossTenant bool
	RenameOnConflict bool
}

// Store is an in-memory reference model. Production splits these tables across
// services, but keeps the same state machine and uniqueness rules.
type Store struct {
	tenants  map[string]Tenant
	accounts map[string]*Account
	roles    map[string]*Role
	devices  map[string]*Device
	policy   MergePolicy
	clock    func() time.Time
	seq      int

	// MaxAccountsPerDevice bounds casual account sharing; zero means unlimited.
	MaxAccountsPerDevice int
}

func NewStore(clock func() time.Time, policy MergePolicy, tenants ...Tenant) *Store {
	s := &Store{
		tenants:  make(map[string]Tenant, len(tenants)),
		accounts: make(map[string]*Account),
		roles:    make(map[string]*Role),
		devices:  make(map[string]*Device),
		policy:   policy,
		clock:    clock,
	}
	for _, t := range tenants {
		s.tenants[t.ID] = t
	}
	return s
}

func (s *Store) next(prefix string) string {
	s.seq++
	return fmt.Sprintf("%s-%03d", prefix, s.seq)
}

func (s *Store) CreateAccount(home string) (*Account, error) {
	if _, ok := s.tenants[home]; !ok {
		return nil, ErrTenantMismatch
	}
	a := &Account{
		ID:         s.next("acc"),
		HomeTenant: home,
		Status:     Active,
		Roles:      map[string]*Role{},
		Devices:    map[string]struct{}{},
	}
	s.accounts[a.ID] = a
	return a, nil
}

func (s *Store) CreateRole(accountID, tenantID, name string) (*Role, error) {
	a, ok := s.accounts[accountID]
	if !ok {
		return nil, ErrNotFound
	}
	if a.Status != Active {
		return nil, ErrBadState
	}
	if _, ok := s.tenants[tenantID]; !ok {
		return nil, ErrTenantMismatch
	}
	r := &Role{
		ID:        s.next("role"),
		AccountID: accountID,
		TenantID:  tenantID,
		Name:      name,
		Status:    RoleActive,
	}
	s.roles[r.ID] = r
	a.Roles[r.ID] = r
	return r, nil
}

func (s *Store) AttachDevice(deviceID, tenantID, accountID string) error {
	if _, ok := s.tenants[tenantID]; !ok {
		return ErrTenantMismatch
	}
	a, ok := s.accounts[accountID]
	if !ok {
		return ErrNotFound
	}
	if a.Status != Active {
		return ErrBadState
	}
	d, ok := s.devices[deviceID]
	if !ok {
		d = &Device{ID: deviceID, TenantID: tenantID, Accounts: map[string]struct{}{}}
		s.devices[deviceID] = d
	}
	if d.TenantID != tenantID {
		return ErrTenantMismatch
	}
	if _, ok := d.Accounts[accountID]; ok {
		return nil
	}
	if s.MaxAccountsPerDevice > 0 && len(d.Accounts) >= s.MaxAccountsPerDevice {
		return ErrDeviceFull
	}
	d.Accounts[accountID] = struct{}{}
	a.Devices[deviceID] = struct{}{}
	return nil
}

// Authorize is the ownership check every gameplay request goes through: the
// account must be active, the role must belong to it, and both must agree on
// the tenant carried by the request.
func (s *Store) Authorize(accountID, roleID, tenantID string) error {
	a, ok := s.accounts[accountID]
	if !ok || a.Status != Active {
		return ErrNotFound
	}
	r, ok := s.roles[roleID]
	if !ok {
		return ErrNotFound
	}
	if r.AccountID != accountID {
		return ErrRoleNotOwned
	}
	if r.TenantID != tenantID || r.Status != RoleActive {
		return ErrTenantMismatch
	}
	return nil
}

$ go test -count=1 ./internal/account/
ok  	gsarchlab/internal/account	0.242s