《游戏服务端架构·核心系统与契约》11.2 退款、对账与差异处理

requested ──approve──> approved ──start──> processing ──succeed──> succeeded
    │                     │                    │
    ├──reject──> rejected │                    └──fail──> failed ──start──┐
    └──hold────> held ────┘                                            │
                    │                                                   │
                    └──reject──> rejected        processing <───────────┘

channel_forced ──> approved        risk ──> held

// file: internal/refundrecon/recon.go
// tier: L1
// verify: go test ./internal/refundrecon/
package refundrecon

import (
	"fmt"
	"sort"
)

type BillLine struct {
	ChannelOrderID string
	OrderID        string
	AmountCents    int64
	Currency       string
	Status         string // paid | refunded
}

type OrderRecord struct {
	OrderID        string
	ChannelOrderID string
	AmountCents    int64
	Currency       string
	Status         string // created | paid | delivered | refunded | closed
}

type DiscrepancyKind string

const (
	KindMissingInternal DiscrepancyKind = "missing_internal"
	KindMissingChannel  DiscrepancyKind = "missing_channel"
	KindAmountMismatch  DiscrepancyKind = "amount_mismatch"
	KindStatusMismatch  DiscrepancyKind = "status_mismatch"
	KindDuplicateBill   DiscrepancyKind = "duplicate_bill"
)

type Resolution string

const (
	ResolveAuto     Resolution = "auto"
	ResolveManual   Resolution = "manual"
	ResolveSuspense Resolution = "suspense"
)

type Discrepancy struct {
	Kind       DiscrepancyKind
	Key        string
	Detail     string
	Resolution Resolution
}

type Policy struct {
	// StatusAutoSync lets a paid bill line move a still-created order forward.
	// It never adjusts money and never overrides a closed order.
	StatusAutoSync bool
}

type Report struct {
	Matched       int
	BillCents     int64
	InternalCents int64
	Discrepancies []Discrepancy
}

// Reconcile compares one day's channel bill with internal orders. Money
// differences are never auto-corrected: they go to manual review or suspense.
func Reconcile(bill []BillLine, orders []OrderRecord, policy Policy) Report {
	var report Report
	byChannel := make(map[string]OrderRecord, len(orders))
	byID := make(map[string]OrderRecord, len(orders))
	for _, o := range orders {
		byID[o.OrderID] = o
		if o.ChannelOrderID != "" {
			byChannel[o.ChannelOrderID] = o
		}
	}
	seen := make(map[string]bool, len(bill))
	for _, line := range bill {
		key := line.ChannelOrderID
		if key == "" {
			key = line.OrderID
		}
		if key == "" {
			report.BillCents += line.AmountCents
			report.add(KindMissingInternal, "<empty>", "bill line has no order key", ResolveSuspense)
			continue
		}
		if seen[key] {
			report.add(KindDuplicateBill, key, "bill line repeated", ResolveManual)
			continue
		}
		seen[key] = true
		report.BillCents += line.AmountCents
		o, ok := byChannel[line.ChannelOrderID]
		if !ok {
			o, ok = byID[line.OrderID]
		}
		if !ok {
			report.add(KindMissingInternal, key, "channel took money without an internal order", ResolveSuspense)
			continue
		}
		if o.AmountCents != line.AmountCents {
			report.add(KindAmountMismatch, key, fmt.Sprintf("bill %d, internal %d", line.AmountCents, o.AmountCents), ResolveManual)
			continue
		}
		if !statusCompatible(line.Status, o.Status) {
			res := ResolveManual
			if policy.StatusAutoSync && line.Status == "paid" && o.Status == "created" {
				res = ResolveAuto
			}
			report.add(KindStatusMismatch, key, fmt.Sprintf("bill %s, internal %s", line.Status, o.Status), res)
			continue
		}
		report.Matched++
	}
	for _, o := range orders {
		switch o.Status {
		case "paid", "delivered", "refunded":
			report.InternalCents += o.AmountCents
		default:
			continue
		}
		key := o.ChannelOrderID
		if key == "" {
			key = o.OrderID
		}
		if !seen[key] {
			report.add(KindMissingChannel, key, "internal order absent from bill", ResolveManual)
		}
	}
	sort.Slice(report.Discrepancies, func(i, j int) bool {
		if report.Discrepancies[i].Kind != report.Discrepancies[j].Kind {
			return report.Discrepancies[i].Kind < report.Discrepancies[j].Kind
		}
		return report.Discrepancies[i].Key < report.Discrepancies[j].Key
	})
	return report
}

func (r *Report) add(kind DiscrepancyKind, key, detail string, res Resolution) {
	r.Discrepancies = append(r.Discrepancies, Discrepancy{Kind: kind, Key: key, Detail: detail, Resolution: res})
}

func statusCompatible(billStatus, internalStatus string) bool {
	switch billStatus {
	case "paid":
		return internalStatus == "paid" || internalStatus == "delivered"
	case "refunded":
		return internalStatus == "refunded"
	default:
		return billStatus == internalStatus
	}
}