《后端架构设计·演进与治理》11.2 黄金路径与自助服务：从工单到模板

// file: internal/platform/idp/selfservice.go
// tier: L2
// verify: go test ./internal/platform/idp/ -count=1 -run 'TestSelfService'
package idp

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

type RequestState string

const (
	StateRequested    RequestState = "REQUESTED"
	StateApproved     RequestState = "APPROVED"
	StateProvisioning RequestState = "PROVISIONING"
	StateValidating   RequestState = "VALIDATING"
	StateReady        RequestState = "READY"
	StateFailed       RequestState = "FAILED"
	StateRolledBack   RequestState = "ROLLED_BACK"
)

var (
	ErrInvalidTransition = errors.New("idp: invalid transition")
	ErrRetryExhausted    = errors.New("idp: retry budget exhausted")
)

type GoldenPath struct {
	ID, CapabilityID string
	Version          int
	AllowedEnvs      []string
	RequiredLabels   []string
	Steps            []string
}

// Validate rejects a template that cannot be executed repeatably.
func (t GoldenPath) Validate() error {
	if blank(t.ID) || t.Version < 1 || blank(t.CapabilityID) || len(t.Steps) == 0 || len(t.AllowedEnvs) == 0 {
		return errors.New("golden path: id, version, capability, steps and envs are required")
	}
	return nil
}

type Request struct {
	ID, Team, CapabilityID, Env, IdempotencyKey string
	Labels                                      map[string]string
}

// Provisioner is the side-effecting adapter. Every method must be idempotent
// because retries replay the same request.
type Provisioner interface {
	Provision(ctx context.Context, req Request, step string) error
	Validate(ctx context.Context, req Request) error
	Rollback(ctx context.Context, req Request) error
}

type Transition struct {
	From, To RequestState
	At       time.Time
	Reason   string
}

type Machine struct {
	template  GoldenPath
	policy    GoldenPathPolicy
	prov      Provisioner
	req       Request
	now       func() time.Time
	state     RequestState
	history   []Transition
	attempts  int
	completed []string
}

func NewMachine(t GoldenPath, p GoldenPathPolicy, prov Provisioner, req Request, now func() time.Time) (*Machine, error) {
	if err := t.Validate(); err != nil {
		return nil, err
	}
	if prov == nil || now == nil {
		return nil, errors.New("idp: machine needs a provisioner and a clock")
	}
	if errs := p.Check(t, req); len(errs) > 0 {
		return nil, errors.Join(errs...)
	}
	if p.MaxAttempts < 1 {
		p.MaxAttempts = 1
	}
	m := &Machine{template: t, policy: p, prov: prov, req: req, now: now, state: StateRequested}
	m.history = append(m.history, Transition{To: StateRequested, At: now(), Reason: "created"})
	return m, nil
}

func (m *Machine) State() RequestState { return m.state }

func (m *Machine) transition(to RequestState, reason string) {
	m.history = append(m.history, Transition{From: m.state, To: to, At: m.now(), Reason: reason})
	m.state = to
}

// Approve is idempotent: approving an approved request is not an error.
func (m *Machine) Approve(actor, reason string) (bool, error) {
	if m.state == StateApproved {
		return false, nil
	}
	if m.state != StateRequested {
		return false, fmt.Errorf("%w: approve from %s", ErrInvalidTransition, m.state)
	}
	if blank(actor) {
		return false, errors.New("idp: approver is empty")
	}
	m.transition(StateApproved, reason)
	return true, nil
}

// Run executes every step then validates the result.
func (m *Machine) Run(ctx context.Context) error {
	switch m.state {
	case StateReady:
		return nil
	case StateApproved:
	default:
		return fmt.Errorf("%w: run from %s", ErrInvalidTransition, m.state)
	}
	if m.attempts == 0 {
		m.attempts = 1
	}
	m.transition(StateProvisioning, "approved")
	return m.execute(ctx)
}

func (m *Machine) execute(ctx context.Context) error {
	for _, step := range m.template.Steps {
		if err := m.prov.Provision(ctx, m.req, step); err != nil {
			m.transition(StateFailed, "provision "+step+": "+err.Error())
			return fmt.Errorf("idp: provision %s: %w", step, err)
		}
		m.completed = append(m.completed, step)
	}
	m.transition(StateValidating, "provisioned")
	if err := m.prov.Validate(ctx, m.req); err != nil {
		m.transition(StateFailed, "validate: "+err.Error())
		return fmt.Errorf("idp: validate: %w", err)
	}
	m.transition(StateReady, "validated")
	return nil
}

// Retry replays the template after a failure, within the attempt budget.
func (m *Machine) Retry(ctx context.Context) error {
	if m.state != StateFailed {
		return fmt.Errorf("%w: retry from %s", ErrInvalidTransition, m.state)
	}
	if m.attempts >= m.policy.MaxAttempts {
		return fmt.Errorf("%w: attempts=%d", ErrRetryExhausted, m.attempts)
	}
	m.attempts++
	m.completed = nil
	m.transition(StateProvisioning, "retry")
	return m.execute(ctx)
}

// Rollback is idempotent and only valid after a failure.
func (m *Machine) Rollback(ctx context.Context, reason string) error {
	switch m.state {
	case StateRolledBack:
		return nil
	case StateFailed:
	default:
		return fmt.Errorf("%w: rollback from %s", ErrInvalidTransition, m.state)
	}
	if err := m.prov.Rollback(ctx, m.req); err != nil {
		return fmt.Errorf("idp: rollback: %w", err)
	}
	m.transition(StateRolledBack, reason)
	return nil
}

// file: internal/platform/idp/selfservice_test.go
// tier: L2
// verify: go test ./internal/platform/idp/ -count=1 -run 'TestSelfService'
package idp

import (
	"context"
	"testing"
	"time"
)

type testClock struct{ cur time.Time }

func (c *testClock) Now() time.Time {
	c.cur = c.cur.Add(time.Minute)
	return c.cur
}

type fakeProvisioner struct {
	failStep    string
	provisioned []string
	rollbacks   int
}

func (f *fakeProvisioner) Provision(_ context.Context, _ Request, step string) error {
	if step == f.failStep {
		return errors.New("injected provision failure")
	}
	f.provisioned = append(f.provisioned, step)
	return nil
}

func (f *fakeProvisioner) Validate(_ context.Context, _ Request) error { return nil }

func (f *fakeProvisioner) Rollback(_ context.Context, _ Request) error {
	f.rollbacks++
	return nil
}

func testTemplate() GoldenPath {
	return GoldenPath{ID: "svc-template", Version: 3, CapabilityID: "cap-deploy",
		AllowedEnvs: []string{"dev", "staging"}, RequiredLabels: []string{"owner", "cost-center"},
		Steps: []string{"database", "queue", "workload"}}
}

func testRequest() Request {
	return Request{ID: "req-1", Team: "order", CapabilityID: "cap-deploy", Env: "staging",
		Labels: map[string]string{"owner": "order", "cost-center": "cc-42"}, IdempotencyKey: "idem-1"}
}

func newTestMachine(t *testing.T, prov Provisioner, p GoldenPathPolicy) (*Machine, *testClock) {
	t.Helper()
	clk := &testClock{cur: time.Date(2026, 11, 1, 9, 0, 0, 0, time.UTC)}
	m, err := NewMachine(testTemplate(), p, prov, testRequest(), clk.Now)
	if err != nil {
		t.Fatalf("NewMachine: %v", err)
	}
	return m, clk
}

func TestSelfServiceHappyPath(t *testing.T) {
	prov := &fakeProvisioner{}
	m, clk := newTestMachine(t, prov, GoldenPathPolicy{MaxAttempts: 2})
	changed, err := m.Approve("lead", "budget approved")
	if err != nil || !changed {
		t.Fatalf("approve = %v, %v", changed, err)
	}
	if changed, err = m.Approve("lead", "duplicate click"); err != nil || changed {
		t.Fatalf("duplicate approve = %v, %v", changed, err)
	}
	if err := m.Run(context.Background()); err != nil {
		t.Fatalf("run: %v", err)
	}
	h := m.history
	if m.State() != StateReady || len(prov.provisioned) != 3 || len(h) != 5 || h[0].At != clk.cur.Add(-4*time.Minute) {
		t.Fatalf("state=%s provisioned=%v history=%+v", m.State(), prov.provisioned, h)
	}
	if err := m.Run(context.Background()); err != nil {
		t.Fatalf("idempotent run: %v", err)
	}
	t.Logf("state=%s steps=%v transitions=%d last_at=%s", m.State(), m.completed, len(h), h[4].At.Format(time.RFC3339))
}

func TestSelfServiceFailureAndRollback(t *testing.T) {
	prov := &fakeProvisioner{failStep: "queue"}
	m, _ := newTestMachine(t, prov, GoldenPathPolicy{MaxAttempts: 2})
	if _, err := m.Approve("lead", "ok"); err != nil {
		t.Fatalf("approve: %v", err)
	}
	if err := m.Run(context.Background()); err == nil || m.State() != StateFailed || len(m.completed) != 1 {
		t.Fatalf("run err=%v state=%s completed=%v", err, m.State(), m.completed)
	}
	if err := m.Rollback(context.Background(), "provision failed"); err != nil {
		t.Fatalf("rollback: %v", err)
	}
	t.Logf("failed_at=queue completed=%v state=%s rollbacks=%d", m.completed, m.State(), prov.rollbacks)
}

$ go test ./internal/platform/idp/ -count=1 -v -run 'TestSelfService'
=== RUN   TestSelfServicePolicy
    policy_test.go:31: missing_team -> request: id and team are required
    policy_test.go:31: wrong_env -> request: env "prod" is not allowed
    policy_test.go:31: missing_label -> request: label "cost-center" is required
    policy_test.go:31: wrong_capability -> request: capability "cap-db" does not match template "cap-deploy"
    policy_test.go:31: missing_idempotency -> request: idempotency key is required
--- PASS: TestSelfServicePolicy (0.00s)
=== RUN   TestSelfServiceHappyPath
    selfservice_test.go:82: state=READY steps=[database queue workload] transitions=5 last_at=2026-11-01T09:05:00Z
--- PASS: TestSelfServiceHappyPath (0.00s)
=== RUN   TestSelfServiceFailureAndRollback
    selfservice_test.go:97: failed_at=queue completed=[database] state=ROLLED_BACK rollbacks=1
--- PASS: TestSelfServiceFailureAndRollback (0.00s)
=== RUN   TestSelfServiceRetryBudget
    selfservice_test.go:115: state=FAILED retries_exhausted=true
--- PASS: TestSelfServiceRetryBudget (0.00s)
PASS
ok  	archlab/internal/platform/idp	0.229s