@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/checkoutbff/contracts.go

@@ -0,0 +1,125 @@
+package checkoutbff
+
+import "time"
+
+const (
+	TargetTypeCatalogPrice        = "catalog_price"
+	TargetTypeBenefitUpgradeQuote = "benefit_upgrade_quote"
+	TargetTypeCreditTopUpQuote    = "credit_top_up_quote"
+)
+
+// DelegatedActor 是产品 BFF 从当前已认证会话提取的委托主体。
+type DelegatedActor struct {
+	SubjectToken string
+}
+
+// SessionTargetRequest 指定 Checkout owner 可以解析的公开业务目标。
+type SessionTargetRequest struct {
+	Type      string `json:"type"`
+	Reference string `json:"reference"`
+}
+
+// BillingJurisdiction 是创建会话时冻结的计税国家事实。
+type BillingJurisdiction struct {
+	CountryCode string `json:"country_code"`
+}
+
+// CreateSessionRequest 是产品 façade 提交给 Platform Checkout owner 的受信任命令。
+type CreateSessionRequest struct {
+	Target              SessionTargetRequest `json:"target"`
+	Currency            string               `json:"currency"`
+	Quantity            int                  `json:"quantity"`
+	CouponCode          *string              `json:"coupon_code,omitempty"`
+	SurfaceCode         string               `json:"surface_code"`
+	BillingJurisdiction BillingJurisdiction  `json:"billing_jurisdiction"`
+	CustomerEmail       string               `json:"customer_email"`
+}
+
+// RequestContext 承载跨服务调用允许透传的非秘密请求上下文。
+type RequestContext struct {
+	// AppVersion 是产品应用版本。
+	AppVersion string
+	// ClientPlatform 是客户端运行平台。
+	ClientPlatform string
+	// ClientType 是客户端形态。
+	ClientType string
+	// ClientVersion 是客户端实现版本。
+	ClientVersion string
+	// ClientLocale 是客户端显式选择的语言区域。
+	ClientLocale string
+	// AcceptLanguage 是入口请求的语言偏好。
+	AcceptLanguage string
+	// DeviceID 是产品边界提供的设备引用。
+	DeviceID string
+	// ClientIP 是受信任入口解析的客户端网络地址。
+	ClientIP string
+	// GeoCountryCode 是受信任入口解析的国家代码。
+	GeoCountryCode string
+	// GeoCity 是受信任入口解析的城市。
+	GeoCity string
+	// SessionID 是产品会话的稳定引用。
+	SessionID string
+	// TouchID 是营销触点的稳定引用。
+	TouchID string
+	// CampaignID 是营销活动的稳定引用。
+	CampaignID string
+	// AttributionSource 是归因来源编码。
+	AttributionSource string
+	// RequestID 是入口请求的追踪引用。
+	RequestID string
+	// Traceparent 是 W3C Trace Context 父级标识。
+	Traceparent string
+	// Tracestate 是 W3C Trace Context 供应商状态。
+	Tracestate string
+	// Baggage 是 W3C 追踪上下文附加信息。
+	Baggage string
+	// UserAgent 是入口请求的客户端代理标识。
+	UserAgent string
+}
+
+// SessionResponse 是创建会话后返回的稳定 Checkout 能力。
+type SessionResponse struct {
+	CheckoutSessionNo string    `json:"checkout_session_no"`
+	ExpiresAt         time.Time `json:"expires_at"`
+	CheckoutURL       string    `json:"checkout_url"`
+}
+
+// ReissueAuthorizationResponse 是重新签发会话入口后的稳定 Checkout 能力。
+type ReissueAuthorizationResponse struct {
+	CheckoutSessionNo string    `json:"checkout_session_no"`
+	ExpiresAt         time.Time `json:"expires_at"`
+	CheckoutURL       string    `json:"checkout_url"`
+}
+
+// CheckoutResultTarget 是结账结果关联的 canonical 业务目标。
+type CheckoutResultTarget struct {
+	Type      string `json:"type"`
+	Reference string `json:"reference"`
+	Name      string `json:"name"`
+}
+
+// CheckoutResult 是商业、资金与履约 owner 汇总出的终态事实。
+type CheckoutResult struct {
+	SettlementKind       *string `json:"settlement_kind"`
+	OrderNo              *string `json:"order_no"`
+	Amount               *string `json:"amount"`
+	Currency             *string `json:"currency"`
+	Quantity             *int    `json:"quantity"`
+	WinningExecutionNo   *string `json:"winning_execution_no"`
+	AuthorizationGrantNo *string `json:"authorization_grant_no"`
+	CommercialStatus     *string `json:"commercial_status"`
+	FinancialStatus      *string `json:"financial_status"`
+	FulfillmentStatus    *string `json:"fulfillment_status"`
+	CompensationReason   *string `json:"compensation_reason"`
+	CompensationStatus   *string `json:"compensation_status"`
+	SuccessReturnURL     string  `json:"success_return_url"`
+	CancelReturnURL      string  `json:"cancel_return_url"`
+}
+
+// CheckoutResultResponse 是当前会话的服务端权威终态结果。
+type CheckoutResultResponse struct {
+	CheckoutSessionNo string               `json:"checkout_session_no"`
+	Status            string               `json:"status"`
+	Target            CheckoutResultTarget `json:"target"`
+	Result            CheckoutResult       `json:"result"`
+}

package/dist/resources/templates/go-backend/internal/common/checkoutbff/platform_client.go

@@ -0,0 +1,212 @@
+package checkoutbff
+
+import (
+	"context"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"{{module}}/internal/common/internalservice"
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/config"
+	"{{module}}/internal/core/httpclient"
+	"{{module}}/pkg/apierror"
+)
+
+const platformOutboundIdentityName = "platform"
+
+type delegatedAccessTokenExchanger interface {
+	Exchange(context.Context, string, string) (string, error)
+}
+
+// PlatformClient 适配 Platform Checkout 的 IAM 内部合同。
+type PlatformClient struct {
+	client      *httpclient.Client
+	baseURL     string
+	delegations delegatedAccessTokenExchanger
+	productCode string
+}
+
+// NewPlatformClient 创建由产品 BFF 固定发送身份访问的 Checkout 客户端。
+func NewPlatformClient(
+	client *httpclient.Client,
+	cfg *config.Config,
+	delegations *internalservice.DelegatedAccessTokenExchanger,
+) (*PlatformClient, error) {
+	if delegations == nil {
+		return nil, apierror.Internal("Checkout platform client dependencies are not configured")
+	}
+	return newPlatformClient(client, cfg, delegations)
+}
+
+func newPlatformClient(
+	client *httpclient.Client,
+	cfg *config.Config,
+	delegations delegatedAccessTokenExchanger,
+) (*PlatformClient, error) {
+	if client == nil || cfg == nil || delegations == nil {
+		return nil, apierror.Internal("Checkout platform client dependencies are not configured")
+	}
+	baseURL := strings.TrimRight(strings.TrimSpace(cfg.InternalService.PlatformBaseURL), "/")
+	parsed, err := url.Parse(baseURL)
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" || parsed.Path != "/internal/v1" {
+		return nil, apierror.Internal("Checkout platform base URL is invalid")
+	}
+	identity, ok := cfg.InternalService.OutboundIdentities[platformOutboundIdentityName]
+	if !ok || len(identity.AllowedProductCodes) != 1 {
+		return nil, apierror.Internal("Checkout platform identity is invalid")
+	}
+	productCode := strings.TrimSpace(identity.AllowedProductCodes[0])
+	if productCode == "" || strings.TrimSpace(identity.ExpectedServiceAccountCode) == "" {
+		return nil, apierror.Internal("Checkout platform identity is invalid")
+	}
+	retry := httpclient.RetryConfig{
+		MaxRetries: 2, RetryDelay: 100 * time.Millisecond, UseExponentialBackoff: true, MaxDelay: time.Second,
+		RetryableStatusCodes: []int{http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout},
+		RetryOnNetworkError:  true,
+	}
+	return &PlatformClient{
+		client: client.WithOptions(httpclient.Options{
+			Timeout:        cfg.InternalService.RequestTimeout,
+			Retry:          &retry,
+			RedirectPolicy: httpclient.PreserveRedirectResponsePolicy(),
+		}),
+		baseURL: baseURL, delegations: delegations, productCode: productCode,
+	}, nil
+}
+
+// CreateSession 创建 canonical Checkout Session。
+func (client *PlatformClient) CreateSession(
+	ctx context.Context,
+	actor DelegatedActor,
+	req CreateSessionRequest,
+	idempotencyKey string,
+	requestContext RequestContext,
+) (SessionResponse, error) {
+	var result SessionResponse
+	if err := client.call(
+		ctx, actor, http.MethodPost, "/checkout-sessions", http.StatusCreated,
+		req, &result, idempotencyKey, requestContext,
+	); err != nil {
+		return SessionResponse{}, err
+	}
+	if strings.TrimSpace(result.CheckoutSessionNo) == "" || strings.TrimSpace(result.CheckoutURL) == "" || result.ExpiresAt.IsZero() {
+		return SessionResponse{}, invalidPlatformContract()
+	}
+	return result, nil
+}
+
+// QueryResult 按当前委托主体读取 canonical Checkout 终态结果。
+func (client *PlatformClient) QueryResult(
+	ctx context.Context,
+	checkoutSessionNo string,
+	actor DelegatedActor,
+	requestContext RequestContext,
+) (CheckoutResultResponse, error) {
+	var result CheckoutResultResponse
+	err := client.call(
+		ctx, actor, http.MethodGet, "/checkout-results/"+url.PathEscape(checkoutSessionNo),
+		http.StatusOK, nil, &result, "", requestContext,
+	)
+	if err != nil {
+		return CheckoutResultResponse{}, err
+	}
+	if result.CheckoutSessionNo != checkoutSessionNo || strings.TrimSpace(result.Status) == "" ||
+		strings.TrimSpace(result.Target.Type) == "" || strings.TrimSpace(result.Target.Reference) == "" {
+		return CheckoutResultResponse{}, invalidPlatformContract()
+	}
+	return result, nil
+}
+
+// ReissueAuthorization 为当前委托主体重新签发 canonical Checkout 入口。
+func (client *PlatformClient) ReissueAuthorization(
+	ctx context.Context,
+	checkoutSessionNo string,
+	actor DelegatedActor,
+	idempotencyKey string,
+	requestContext RequestContext,
+) (ReissueAuthorizationResponse, error) {
+	var result ReissueAuthorizationResponse
+	err := client.call(
+		ctx, actor, http.MethodPost,
+		"/checkout-sessions/"+url.PathEscape(checkoutSessionNo)+"/authorizations/reissue",
+		http.StatusOK, nil, &result, idempotencyKey, requestContext,
+	)
+	if err != nil {
+		return ReissueAuthorizationResponse{}, err
+	}
+	if result.CheckoutSessionNo != checkoutSessionNo || strings.TrimSpace(result.CheckoutURL) == "" || result.ExpiresAt.IsZero() {
+		return ReissueAuthorizationResponse{}, invalidPlatformContract()
+	}
+	return result, nil
+}
+
+func (client *PlatformClient) call(
+	ctx context.Context,
+	actor DelegatedActor,
+	method string,
+	path string,
+	expectedStatus int,
+	body any,
+	result any,
+	idempotencyKey string,
+	requestContext RequestContext,
+) error {
+	delegation, err := client.delegations.Exchange(ctx, actor.SubjectToken, client.productCode)
+	if err != nil {
+		return platformUnavailable()
+	}
+	headers := map[string]string{"Authorization": "Bearer " + delegation}
+	headers[types.HeaderProductCode] = client.productCode
+	headers["Accept"] = "application/json"
+	copyRequestContextHeaders(headers, requestContext)
+	if value := strings.TrimSpace(idempotencyKey); value != "" {
+		headers[types.HeaderIdempotencyKey] = value
+	}
+	var response *httpclient.Response
+	if strings.TrimSpace(idempotencyKey) != "" {
+		response, err = client.client.DoWithHeaders(ctx, method, client.baseURL+path, body, result, headers)
+	} else {
+		response, err = client.client.DoOnceWithHeaders(ctx, method, client.baseURL+path, body, result, headers)
+	}
+	if err != nil {
+		return platformUnavailable()
+	}
+	if response.StatusCode != expectedStatus {
+		return apierror.DecodeHTTPResponse(
+			response.StatusCode,
+			response.Headers,
+			response.Body,
+			apierror.New(http.StatusBadGateway, apierror.TypeAPI, "checkout_platform_contract_invalid", "Checkout platform returned an invalid error contract"),
+		)
+	}
+	return nil
+}
+
+func copyRequestContextHeaders(headers map[string]string, requestContext RequestContext) {
+	values := map[string]string{
+		types.HeaderAppVersion: requestContext.AppVersion, types.HeaderClientPlatform: requestContext.ClientPlatform,
+		types.HeaderClientType: requestContext.ClientType, types.HeaderClientVersion: requestContext.ClientVersion,
+		types.HeaderClientLocale: requestContext.ClientLocale, "Accept-Language": requestContext.AcceptLanguage,
+		types.HeaderDeviceID: requestContext.DeviceID, types.HeaderXRealIP: requestContext.ClientIP,
+		types.HeaderGeoIPCountryCode: requestContext.GeoCountryCode, types.HeaderGeoIPCity: requestContext.GeoCity,
+		types.HeaderSessionID: requestContext.SessionID, types.HeaderAttributionTouchID: requestContext.TouchID,
+		types.HeaderAttributionCampaignID: requestContext.CampaignID, types.HeaderAttributionSource: requestContext.AttributionSource,
+		types.HeaderRequestID: requestContext.RequestID, "traceparent": requestContext.Traceparent,
+		"tracestate": requestContext.Tracestate, "baggage": requestContext.Baggage, "User-Agent": requestContext.UserAgent,
+	}
+	for key, value := range values {
+		if value = strings.TrimSpace(value); value != "" {
+			headers[key] = value
+		}
+	}
+}
+
+func platformUnavailable() *apierror.APIError {
+	return apierror.New(http.StatusServiceUnavailable, apierror.TypeAPI, apierror.CodeServiceUnavailable, "Checkout platform is unavailable")
+}
+
+func invalidPlatformContract() *apierror.APIError {
+	return apierror.New(http.StatusBadGateway, apierror.TypeAPI, "checkout_platform_contract_invalid", "Checkout platform returned an invalid success contract")
+}

package/dist/resources/templates/go-backend/internal/common/checkoutbff/platform_client_test.go

@@ -0,0 +1,319 @@
+package checkoutbff
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/config"
+	"{{module}}/internal/core/httpclient"
+	"{{module}}/pkg/apierror"
+)
+
+func TestPlatformClientCreatesSessionWithDelegatedAccessToken(t *testing.T) {
+	var body map[string]any
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost || r.URL.Path != "/internal/v1/checkout-sessions" {
+			t.Errorf("request = %s %s", r.Method, r.URL.Path)
+			http.Error(w, "unexpected request", http.StatusBadRequest)
+			return
+		}
+		if r.Header.Get("Authorization") != "Bearer delegated-token" || r.Header.Get("X-Product-Code") != "product_alpha" ||
+			r.Header.Get(types.HeaderIdempotencyKey) != "checkout-session-001" || r.Header.Get("X-Request-ID") != "request-001" ||
+			r.Header.Get(types.HeaderAttributionTouchID) != "touch-001" ||
+			r.Header.Get(types.HeaderAttributionCampaignID) != "campaign-001" ||
+			r.Header.Get(types.HeaderSessionID) != "701" || r.Header.Get(types.HeaderDeviceID) != "device-001" {
+			t.Errorf("headers = %#v", r.Header)
+			http.Error(w, "unexpected headers", http.StatusBadRequest)
+			return
+		}
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Errorf("decode request: %v", err)
+			http.Error(w, "invalid request", http.StatusBadRequest)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"checkout_session_no":"chs_001","checkout_url":"https://paykit.test/checkout?authorization_code=cha_001","expires_at":"2026-07-18T12:00:00Z"}`))
+	}))
+	defer server.Close()
+
+	var subjectToken, productCode string
+	exchanger := &delegatedAccessTokenExchangerStub{exchange: func(_ context.Context, subject, product string) (string, error) {
+		subjectToken = subject
+		productCode = product
+		return "delegated-token", nil
+	}}
+	client := newPlatformClientForTest(t, server.URL, exchanger)
+	coupon := "WELCOME10"
+	result, err := client.CreateSession(context.Background(), DelegatedActor{SubjectToken: "subject-token"}, CreateSessionRequest{
+		Target:   SessionTargetRequest{Type: TargetTypeCatalogPrice, Reference: "1"},
+		Currency: "USD", Quantity: 1, CouponCode: &coupon, SurfaceCode: "marketing_modal",
+		BillingJurisdiction: BillingJurisdiction{CountryCode: "US"}, CustomerEmail: "owner@example.com",
+	}, "checkout-session-001", RequestContext{
+		RequestID: "request-001", Traceparent: "00-test", UserAgent: "checkout-test",
+		TouchID: "touch-001", CampaignID: "campaign-001", SessionID: "701", DeviceID: "device-001",
+	})
+	if err != nil {
+		t.Fatalf("CreateSession() error = %v", err)
+	}
+	if result.CheckoutSessionNo != "chs_001" || result.CheckoutURL == "" {
+		t.Fatalf("result = %#v", result)
+	}
+	if subjectToken != "subject-token" || productCode != "product_alpha" {
+		t.Fatalf("token exchange input = subject %q, product %q", subjectToken, productCode)
+	}
+	expectedKeys := map[string]struct{}{
+		"target": {}, "currency": {}, "quantity": {}, "coupon_code": {}, "surface_code": {},
+		"billing_jurisdiction": {}, "customer_email": {},
+	}
+	if len(body) != len(expectedKeys) {
+		t.Fatalf("body fields = %#v", body)
+	}
+	for key := range body {
+		if _, ok := expectedKeys[key]; !ok {
+			t.Fatalf("request contains non-canonical field %q: %#v", key, body)
+		}
+	}
+	target, ok := body["target"].(map[string]any)
+	if !ok || target["type"] != TargetTypeCatalogPrice || target["reference"] != "1" {
+		t.Fatalf("target = %#v", body["target"])
+	}
+	jurisdiction, ok := body["billing_jurisdiction"].(map[string]any)
+	if !ok || jurisdiction["country_code"] != "US" {
+		t.Fatalf("billing_jurisdiction = %#v", body["billing_jurisdiction"])
+	}
+	for _, forbidden := range []string{
+		"locale", "country_code", "user_id", "identity_id", "principal_type", "purchase_option_id", "order_type", "redeem_challenge",
+	} {
+		if _, exists := body[forbidden]; exists {
+			t.Fatalf("request contains forbidden %s: %#v", forbidden, body)
+		}
+	}
+}
+
+func TestPlatformClientUsesCanonicalResultAndReissueRoutes(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer delegated-token" {
+			http.Error(w, "delegated authority missing", http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == "/internal/v1/checkout-results/chs_001":
+			body, err := io.ReadAll(r.Body)
+			if err != nil || len(body) != 0 {
+				t.Errorf("result request body = %q, err = %v", body, err)
+			}
+			_, _ = w.Write([]byte(`{
+				"checkout_session_no":"chs_001","status":"completed",
+				"target":{"type":"catalog_price","reference":"1","name":"ProductA Pro"},
+				"result":{"settlement_kind":"paid","order_no":"ord_001","amount":"9.99","currency":"USD","quantity":1,
+				"winning_execution_no":"che_001","authorization_grant_no":null,"commercial_status":"confirmed",
+				"financial_status":"paid","fulfillment_status":"fulfilled","compensation_reason":null,
+				"compensation_status":null,"success_return_url":"https://example.test/success?checkout_session_no=chs_001",
+				"cancel_return_url":"https://example.test/cancel?checkout_session_no=chs_001"}
+			}`))
+		case r.Method == http.MethodPost && r.URL.Path == "/internal/v1/checkout-sessions/chs_001/authorizations/reissue":
+			if r.Header.Get(types.HeaderIdempotencyKey) != "reissue-001" {
+				t.Errorf("idempotency header = %q", r.Header.Get(types.HeaderIdempotencyKey))
+			}
+			body, err := io.ReadAll(r.Body)
+			if err != nil || len(body) != 0 {
+				t.Errorf("reissue request body = %q, err = %v", body, err)
+			}
+			_, _ = w.Write([]byte(`{"checkout_session_no":"chs_001","checkout_url":"https://paykit.test/checkout?authorization_code=cha_002","expires_at":"2026-07-18T12:05:00Z"}`))
+		default:
+			http.Error(w, "unexpected request", http.StatusBadRequest)
+		}
+	}))
+	defer server.Close()
+
+	client := newPlatformClientForTest(t, server.URL, &delegatedAccessTokenExchangerStub{})
+	actor := DelegatedActor{SubjectToken: "subject-token"}
+	result, err := client.QueryResult(context.Background(), "chs_001", actor, RequestContext{})
+	if err != nil {
+		t.Fatalf("QueryResult() error = %v", err)
+	}
+	if result.CheckoutSessionNo != "chs_001" || result.Status != "completed" || result.Target.Reference != "1" ||
+		result.Result.OrderNo == nil || *result.Result.OrderNo != "ord_001" {
+		t.Fatalf("result = %#v", result)
+	}
+	reissued, err := client.ReissueAuthorization(context.Background(), "chs_001", actor, "reissue-001", RequestContext{})
+	if err != nil {
+		t.Fatalf("ReissueAuthorization() error = %v", err)
+	}
+	if reissued.CheckoutSessionNo != "chs_001" || reissued.CheckoutURL == "" {
+		t.Fatalf("reissued = %#v", reissued)
+	}
+}
+
+func TestPlatformClientRetriesOnlyIdempotentMutation(t *testing.T) {
+	var calls atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if calls.Add(1) == 1 {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			_, _ = w.Write([]byte(`{"error":{"type":"api_error","code":"service_unavailable","message":"unavailable"}}`))
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"checkout_session_no":"chs_002","checkout_url":"https://paykit.test/checkout?authorization_code=cha_002","expires_at":"2026-07-18T12:00:00Z"}`))
+	}))
+	defer server.Close()
+
+	client := newPlatformClientForTest(t, server.URL, &delegatedAccessTokenExchangerStub{})
+	_, err := client.CreateSession(context.Background(), DelegatedActor{SubjectToken: "subject-token"}, CreateSessionRequest{}, "checkout-session-002", RequestContext{})
+	if err != nil {
+		t.Fatalf("CreateSession() error = %v", err)
+	}
+	if calls.Load() != 2 {
+		t.Fatalf("idempotent mutation calls = %d", calls.Load())
+	}
+}
+
+func TestPlatformClientDoesNotRetryResultQuery(t *testing.T) {
+	var calls atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		calls.Add(1)
+		w.WriteHeader(http.StatusServiceUnavailable)
+		_, _ = w.Write([]byte(`{"error":{"type":"api_error","code":"service_unavailable","message":"unavailable"}}`))
+	}))
+	defer server.Close()
+
+	client := newPlatformClientForTest(t, server.URL, &delegatedAccessTokenExchangerStub{})
+	if _, err := client.QueryResult(context.Background(), "chs_003", DelegatedActor{SubjectToken: "subject-token"}, RequestContext{}); err == nil {
+		t.Fatal("QueryResult() accepted unavailable response")
+	}
+	if calls.Load() != 1 {
+		t.Fatalf("result query calls = %d", calls.Load())
+	}
+}
+
+func TestPlatformClientRejectsInvalidSuccessContract(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"checkout_session_no":"","checkout_url":"","expires_at":"0001-01-01T00:00:00Z"}`))
+	}))
+	defer server.Close()
+
+	client := newPlatformClientForTest(t, server.URL, &delegatedAccessTokenExchangerStub{})
+	if _, err := client.CreateSession(context.Background(), DelegatedActor{SubjectToken: "subject-token"}, CreateSessionRequest{}, "checkout-session-004", RequestContext{}); err == nil {
+		t.Fatal("CreateSession() accepted invalid success contract")
+	}
+}
+
+func TestPlatformClientPreservesCanonicalErrorEnvelope(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusUnprocessableEntity)
+		_, _ = w.Write([]byte(`{"error":{"type":"api_error","code":"checkout_surface_unavailable","message":"Checkout surface is unavailable"}}`))
+	}))
+	defer server.Close()
+
+	client := newPlatformClientForTest(t, server.URL, &delegatedAccessTokenExchangerStub{})
+	_, err := client.CreateSession(context.Background(), DelegatedActor{SubjectToken: "subject-token"}, CreateSessionRequest{}, "checkout-session-005", RequestContext{})
+	var apiErr *apierror.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("CreateSession() error = %v", err)
+	}
+	if apiErr.Status != http.StatusUnprocessableEntity || apiErr.Detail.Code != "checkout_surface_unavailable" {
+		t.Fatalf("CreateSession() error = %#v", apiErr)
+	}
+}
+
+func TestPlatformClientRejectsRedirectAsInvalidContract(t *testing.T) {
+	var targetCalls atomic.Int32
+	target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		targetCalls.Add(1)
+		w.WriteHeader(http.StatusCreated)
+	}))
+	defer target.Close()
+
+	redirect := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Location", target.URL)
+		w.WriteHeader(http.StatusFound)
+	}))
+	defer redirect.Close()
+
+	client := newPlatformClientForTest(t, redirect.URL, &delegatedAccessTokenExchangerStub{})
+	_, err := client.CreateSession(
+		context.Background(), DelegatedActor{SubjectToken: "subject-token"}, CreateSessionRequest{}, "checkout-session-redirect", RequestContext{},
+	)
+	var apiErr *apierror.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("CreateSession() error = %v", err)
+	}
+	if apiErr.Status != http.StatusBadGateway || apiErr.Detail.Code != "checkout_platform_contract_invalid" {
+		t.Fatalf("CreateSession() error = %#v", apiErr)
+	}
+	if targetCalls.Load() != 0 {
+		t.Fatalf("redirect target calls = %d, want 0", targetCalls.Load())
+	}
+}
+
+func TestPlatformClientFailsClosedWhenDelegationCannotBeIssued(t *testing.T) {
+	var calls atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+		calls.Add(1)
+	}))
+	defer server.Close()
+
+	exchanger := &delegatedAccessTokenExchangerStub{exchange: func(context.Context, string, string) (string, error) {
+		return "", errors.New("authority unavailable")
+	}}
+	client := newPlatformClientForTest(t, server.URL, exchanger)
+	_, err := client.CreateSession(context.Background(), DelegatedActor{SubjectToken: "subject-token"}, CreateSessionRequest{}, "checkout-session-006", RequestContext{})
+	var apiErr *apierror.APIError
+	if !errors.As(err, &apiErr) || apiErr.Status != http.StatusServiceUnavailable {
+		t.Fatalf("CreateSession() error = %#v", err)
+	}
+	if calls.Load() != 0 {
+		t.Fatalf("platform calls = %d, want 0", calls.Load())
+	}
+}
+
+func newPlatformClientForTest(
+	t *testing.T,
+	baseURL string,
+	exchanger delegatedAccessTokenExchanger,
+) *PlatformClient {
+	t.Helper()
+	client, err := newPlatformClient(httpclient.New(zap.NewNop()), &config.Config{InternalService: config.InternalServiceConfig{
+		PlatformBaseURL: baseURL + "/internal/v1", RequestTimeout: 2 * time.Second,
+		OutboundIdentities: map[string]config.InternalServiceIdentityConfig{
+			platformOutboundIdentityName: {
+				AllowedProductCodes: []string{"product_alpha"}, ExpectedServiceAccountCode: "svc_product_alpha_bff_prod",
+			},
+		},
+	}}, exchanger)
+	if err != nil {
+		t.Fatalf("newPlatformClient() error = %v", err)
+	}
+	return client
+}
+
+type delegatedAccessTokenExchangerStub struct {
+	exchange func(context.Context, string, string) (string, error)
+}
+
+func (stub *delegatedAccessTokenExchangerStub) Exchange(
+	ctx context.Context,
+	subjectToken string,
+	productCode string,
+) (string, error) {
+	if stub.exchange != nil {
+		return stub.exchange(ctx, subjectToken, productCode)
+	}
+	return "delegated-token", nil
+}