《互联网产品的服务端架构·交易、增长与平台化》13.1 下单→支付→履约→对账

// file: internal/growthbase/flow.go
// tier: L1
// verify: go test ./internal/growthbase/

package growthbase

import (
	"fmt"
	"strings"
)

// Stage 是交易链路中的一个阶段。
type Stage string

const (
	StageOrder     Stage = "order"
	StagePay       Stage = "pay"
	StageFulfill   Stage = "fulfill"
	StageReconcile Stage = "reconcile"
)

// Step 是链路中的一个步骤。Async 只对履约与对账阶段有意义。
type Step struct {
	Name  string
	Stage Stage
	Async bool
}

// Flow 是一条按顺序排列的交易链路。
type Flow struct {
	Steps []Step
}

var stageRank = map[Stage]int{
	StageOrder:     0,
	StagePay:       1,
	StageFulfill:   2,
	StageReconcile: 3,
}

// Validate 检查链路是否覆盖四个阶段且顺序正确。
//
// 下单与支付必须是同步步骤：调用方要在这两步拿到确定结果，才能决定
// 是否继续。履约与对账允许异步，因为它们依赖仓库、物流和渠道文件，
// 这些外部系统的响应时间不可控。
func Validate(f Flow) error {
	if len(f.Steps) == 0 {
		return fmt.Errorf("growthbase: flow has no steps")
	}
	seen := make(map[string]struct{}, len(f.Steps))
	present := make(map[Stage]struct{}, len(stageRank))
	last := -1
	for i, s := range f.Steps {
		name := strings.TrimSpace(s.Name)
		if name == "" {
			return fmt.Errorf("growthbase: step %d has empty name", i)
		}
		if _, ok := seen[name]; ok {
			return fmt.Errorf("growthbase: duplicate step name %q", name)
		}
		seen[name] = struct{}{}

		rank, ok := stageRank[s.Stage]
		if !ok {
			return fmt.Errorf("growthbase: step %q has unknown stage %q", name, s.Stage)
		}
		if rank < last {
			return fmt.Errorf("growthbase: step %q stage %q is out of order", name, s.Stage)
		}
		last = rank
		present[s.Stage] = struct{}{}

		if s.Async && (s.Stage == StageOrder || s.Stage == StagePay) {
			return fmt.Errorf("growthbase: step %q stage %q must be synchronous", name, s.Stage)
		}
	}
	for _, st := range []Stage{StageOrder, StagePay, StageFulfill, StageReconcile} {
		if _, ok := present[st]; !ok {
			return fmt.Errorf("growthbase: flow is missing stage %q", st)
		}
	}
	return nil
}

// file: internal/growthbase/flow_test.go
// tier: L1
// verify: go test ./internal/growthbase/

package growthbase

import (
	"strings"
	"testing"
)

func fullFlow() Flow {
	return Flow{Steps: []Step{
		{Name: "create-order", Stage: StageOrder},
		{Name: "pay-order", Stage: StagePay},
		{Name: "ship", Stage: StageFulfill, Async: true},
		{Name: "reconcile", Stage: StageReconcile, Async: true},
	}}
}

func TestValidateAcceptsFullFlow(t *testing.T) {
	if err := Validate(fullFlow()); err != nil {
		t.Fatalf("valid flow rejected: %v", err)
	}
}

func TestValidateRejects(t *testing.T) {
	cases := []struct {
		name string
		flow Flow
		want string
	}{
		{"empty", Flow{}, "no steps"},
		{"missing-stage", Flow{Steps: []Step{
			{Name: "create-order", Stage: StageOrder},
			{Name: "pay-order", Stage: StagePay},
			{Name: "ship", Stage: StageFulfill},
		}}, `missing stage "reconcile"`},
		{"out-of-order", Flow{Steps: []Step{
			{Name: "create-order", Stage: StageOrder},
			{Name: "ship", Stage: StageFulfill},
			{Name: "pay-order", Stage: StagePay},
			{Name: "reconcile", Stage: StageReconcile},
		}}, "out of order"},
		{"async-order", Flow{Steps: []Step{
			{Name: "create-order", Stage: StageOrder, Async: true},
			{Name: "pay-order", Stage: StagePay},
			{Name: "ship", Stage: StageFulfill},
			{Name: "reconcile", Stage: StageReconcile},
		}}, "must be synchronous"},
		{"async-pay", Flow{Steps: []Step{
			{Name: "create-order", Stage: StageOrder},
			{Name: "pay-order", Stage: StagePay, Async: true},
			{Name: "ship", Stage: StageFulfill},
			{Name: "reconcile", Stage: StageReconcile},
		}}, "must be synchronous"},
		{"empty-name", Flow{Steps: []Step{
			{Name: "  ", Stage: StageOrder},
			{Name: "pay-order", Stage: StagePay},
			{Name: "ship", Stage: StageFulfill},
			{Name: "reconcile", Stage: StageReconcile},
		}}, "empty name"},
		{"duplicate-name", Flow{Steps: []Step{
			{Name: "create-order", Stage: StageOrder},
			{Name: "pay-order", Stage: StagePay},
			{Name: "ship", Stage: StageFulfill},
			{Name: "ship", Stage: StageReconcile},
		}}, "duplicate step name"},
		{"unknown-stage", Flow{Steps: []Step{
			{Name: "create-order", Stage: StageOrder},
			{Name: "pay-order", Stage: StagePay},
			{Name: "ship", Stage: StageFulfill},
			{Name: "settle", Stage: Stage("settle")},
		}}, "unknown stage"},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			err := Validate(c.flow)
			if err == nil {
				t.Fatal("want error, got nil")
			}
			if !strings.Contains(err.Error(), c.want) {
				t.Fatalf("error %q does not contain %q", err, c.want)
			}
		})
	}
}

cd .local/checks/webapp-lab && go test ./internal/growthbase/ -run 'TestValidate' -count=1 -v

=== RUN   TestValidateAcceptsFullFlow
--- PASS: TestValidateAcceptsFullFlow (0.00s)
=== RUN   TestValidateRejects
=== RUN   TestValidateRejects/empty
=== RUN   TestValidateRejects/missing-stage
=== RUN   TestValidateRejects/out-of-order
=== RUN   TestValidateRejects/async-order
=== RUN   TestValidateRejects/async-pay
=== RUN   TestValidateRejects/empty-name
=== RUN   TestValidateRejects/duplicate-name
=== RUN   TestValidateRejects/unknown-stage
--- PASS: TestValidateRejects (0.00s)
    --- PASS: TestValidateRejects/empty (0.00s)
    --- PASS: TestValidateRejects/missing-stage (0.00s)
    --- PASS: TestValidateRejects/out-of-order (0.00s)
    --- PASS: TestValidateRejects/async-order (0.00s)
    --- PASS: TestValidateRejects/async-pay (0.00s)
    --- PASS: TestValidateRejects/empty-name (0.00s)
    --- PASS: TestValidateRejects/duplicate-name (0.00s)
    --- PASS: TestValidateRejects/unknown-stage (0.00s)
PASS
ok  	webapp/internal/growthbase	0.277s