《游戏服务端架构·核心系统与契约》11.3 防沉迷、实名与未成年人保护

登录/充值请求
      |
      v
+---------------------+        +------------------+
| 合规判定服务         |<------>| 实名认证服务      |
| CheckPlay/CheckPurchase |     | 返回年龄带/可信度 |
+---------------------+        +------------------+
      |
      | Decision: allow / limit / deny
      | + reason + remaining + nextAllowedAt
      v
+---------------------+        +------------------+
| 大厅、房间、充值服务 |------->| 执行：放行/限制/拒绝 |
+---------------------+        +------------------+

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

import (
	"errors"
	"time"
)

var (
	ErrBadRequest     = errors.New("compliance: invalid request")
	ErrIdentitySource = errors.New("compliance: identity source unavailable")
)

type Service struct {
	policy   Policy
	source   IdentitySource
	calendar Calendar
	now      func() time.Time
	auditor  Auditor
}

func New(policy Policy, source IdentitySource, calendar Calendar, now func() time.Time, auditor Auditor) *Service {
	if policy.Location == nil {
		policy.Location = time.FixedZone("CST", 8*60*60)
	}
	if calendar == nil {
		calendar = WeekendCalendar{}
	}
	if now == nil {
		now = time.Now
	}
	return &Service{policy: policy, source: source, calendar: calendar, now: now, auditor: auditor}
}

// CheckPlay decides whether an account may play now. A source outage fails
// closed: the returned decision is "deny", not an error the caller may ignore.
func (s *Service) CheckPlay(accountID string, usedToday time.Duration) (Decision, error) {
	if accountID == "" || usedToday < 0 {
		return Decision{}, ErrBadRequest
	}
	id, err := s.lookup(accountID)
	if err != nil {
		return s.finish(accountID, "play", Decision{Action: ActionDeny, Reason: ReasonSourceError}, usedToday, 0), nil
	}
	if !id.Verified || id.Band == BandUnknown {
		return s.finish(accountID, "play", Decision{Action: ActionDeny, Reason: ReasonUnverified}, usedToday, 0), nil
	}
	if id.Band == BandAdult {
		return s.finish(accountID, "play", Decision{Action: ActionAllow, Reason: ReasonOK, RemainingSeconds: -1}, usedToday, 0), nil
	}
	now := s.now().In(s.policy.Location)
	if !s.calendar.IsPlayDay(now) || !s.inWindow(now) {
		d := Decision{Action: ActionLimit, Reason: ReasonOutsideWindow, NextAllowedAt: s.nextWindow(now)}
		return s.finish(accountID, "play", d, usedToday, 0), nil
	}
	daily := s.policy.DailyLimit - usedToday
	if daily <= 0 {
		d := Decision{Action: ActionLimit, Reason: ReasonDailyLimit, NextAllowedAt: s.nextWindow(now)}
		return s.finish(accountID, "play", d, usedToday, 0), nil
	}
	end := time.Date(now.Year(), now.Month(), now.Day(),
		s.policy.WindowEndMinute/60, s.policy.WindowEndMinute%60, 0, 0, s.policy.Location)
	window := end.Sub(now)
	if window < daily {
		daily = window
	}
	d := Decision{Action: ActionAllow, Reason: ReasonOK, RemainingSeconds: int64(daily / time.Second)}
	return s.finish(accountID, "play", d, usedToday, 0), nil
}

func (s *Service) lookup(accountID string) (Identity, error) {
	if s.source == nil {
		return Identity{}, ErrIdentitySource
	}
	return s.source.Lookup(accountID)
}

func (s *Service) inWindow(now time.Time) bool {
	minute := now.Hour()*60 + now.Minute()
	return minute >= s.policy.WindowStartMinute && minute < s.policy.WindowEndMinute
}

func (s *Service) nextWindow(from time.Time) time.Time {
	for d := 0; d <= 14; d++ {
		day := time.Date(from.Year(), from.Month(), from.Day()+d, 0, 0, 0, 0, s.policy.Location)
		if !s.calendar.IsPlayDay(day) {
			continue
		}
		start := time.Date(day.Year(), day.Month(), day.Day(),
			s.policy.WindowStartMinute/60, s.policy.WindowStartMinute%60, 0, 0, s.policy.Location)
		if start.After(from) {
			return start
		}
	}
	return time.Time{}
}

func (s *Service) finish(accountID, kind string, d Decision, used time.Duration, amountCents int64) Decision {
	s.record(AuditEntry{
		At: s.now(), Subject: accountID, Kind: kind, Action: d.Action,
		Reason: d.Reason, UsedSeconds: int64(used / time.Second), AmountCents: amountCents,
	})
	return d
}

func (s *Service) record(e AuditEntry) {
	if s.auditor != nil {
		s.auditor.Record(e)
	}
}