@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/middleware/middleware_test.go

@@ -0,0 +1,1516 @@
+package middleware
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zaptest/observer"
+
+	"{{module}}/internal/common/ctxutil"
+	"{{module}}/internal/common/iamscope"
+	"{{module}}/internal/common/types"
+	coreclock "{{module}}/internal/core/clock"
+	"{{module}}/internal/core/config"
+	iamdomain "{{module}}/internal/integrations/onex/iam"
+	"{{module}}/pkg/apierror"
+)
+
+func init() {
+	gin.SetMode(gin.TestMode)
+}
+
+func TestLoggingRedactsSensitiveQueryValues(t *testing.T) {
+	core, logs := observer.New(zap.InfoLevel)
+	logger := zap.New(core)
+	engine := gin.New()
+	engine.Use(LoggingWithConfig(logger, config.LogConfig{
+		RequestSuccessLevel:      "info",
+		RequestSuccessSampleRate: 1,
+		RequestSlowThreshold:     time.Second,
+	}))
+	engine.GET("/api/v1/ws", func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/ws?token=jwt-secret&page=1", nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+	require.Len(t, logs.All(), 1)
+	fields := logs.All()[0].ContextMap()
+	assert.Equal(t, "/api/v1/ws?page=1&token=redacted", fields["path"])
+}
+
+func TestLoggingUsesInboundURLSnapshot(t *testing.T) {
+	core, logs := observer.New(zap.InfoLevel)
+	logger := zap.New(core)
+	engine := gin.New()
+	engine.Use(LoggingWithConfig(logger, config.LogConfig{
+		RequestSuccessLevel:      "info",
+		RequestSuccessSampleRate: 1,
+		RequestSlowThreshold:     time.Second,
+	}))
+	engine.GET("/api/v1/ws", func(c *gin.Context) {
+		c.Request.URL.RawQuery = "token=handler-secret"
+		c.Status(http.StatusOK)
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/ws?page=1", nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+	require.Len(t, logs.All(), 1)
+	fields := logs.All()[0].ContextMap()
+	assert.Equal(t, "/api/v1/ws?page=1", fields["path"])
+}
+
+func TestLoggingRedactsSensitivePathParameter(t *testing.T) {
+	core, logs := observer.New(zap.InfoLevel)
+	logger := zap.New(core)
+	engine := gin.New()
+	engine.Use(LoggingWithConfig(logger, config.LogConfig{
+		RequestSuccessLevel:      "info",
+		RequestSuccessSampleRate: 1,
+		RequestSlowThreshold:     time.Second,
+	}))
+	engine.GET("/iap/google/orders/by-token/:purchaseToken", func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/iap/google/orders/by-token/secret-purchase-token", nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+	require.Len(t, logs.All(), 1)
+	fields := logs.All()[0].ContextMap()
+	assert.Equal(t, "/iap/google/orders/by-token/:purchaseToken", fields["path"])
+	assert.NotContains(t, fields["path"], "secret-purchase-token")
+}
+
+func TestLoggingRecordsErrorMetadataWithoutRawErrorText(t *testing.T) {
+	core, logs := observer.New(zap.DebugLevel)
+	logger := zap.New(core)
+	engine := gin.New()
+	engine.Use(LoggingWithConfig(logger, config.LogConfig{
+		RequestSuccessLevel:      "debug",
+		RequestSuccessSampleRate: 0,
+		RequestSlowThreshold:     time.Second,
+	}))
+	engine.GET("/api/v1/orders/:id", func(c *gin.Context) {
+		_ = c.Error(fmt.Errorf("pq: duplicate key users_email_key email=user@example.com token=token-secret")).SetType(gin.ErrorTypePrivate)
+		_ = c.Error(apierror.BadRequest(apierror.CodeValidationFailed, "invalid email user@example.com with token-secret")).SetType(gin.ErrorTypeBind)
+		c.Status(http.StatusBadRequest)
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/orders/order-1", nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusBadRequest, w.Code)
+	require.Len(t, logs.All(), 1)
+	fields := logs.All()[0].ContextMap()
+	assert.EqualValues(t, 2, fields["error_count"])
+	assert.EqualValues(t, uint64(gin.ErrorTypePrivate|gin.ErrorTypeBind), fields["error_type"])
+	assert.Equal(t, apierror.CodeValidationFailed, fields["error_code"])
+	assert.NotContains(t, fields, "error")
+	encoded, err := json.Marshal(fields)
+	require.NoError(t, err)
+	for _, secret := range []string{"duplicate key", "users_email_key", "user@example.com", "token-secret"} {
+		assert.NotContains(t, string(encoded), secret)
+	}
+}
+
+func TestRecoveryUsesRouteTemplateForPaymentResultToken(t *testing.T) {
+	core, logs := observer.New(zap.ErrorLevel)
+	logger := zap.New(core)
+	engine := gin.New()
+	engine.Use(Recovery(logger))
+	engine.GET("/api/v1/payment-results/:paymentResultToken", func(*gin.Context) {
+		panic("payment result handler failure")
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/payment-results/secret-result-token", nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusInternalServerError, w.Code)
+	require.Len(t, logs.All(), 1)
+	fields := logs.All()[0].ContextMap()
+	assert.Equal(t, "/api/v1/payment-results/:paymentResultToken", fields["path"])
+	assert.NotContains(t, fields["path"], "secret-result-token")
+	assert.Equal(t, "string", fields["panic_type"])
+	assert.NotContains(t, fields, "panic")
+	assert.NotContains(t, w.Body.String(), "payment result handler failure")
+}
+
+func TestLoggingSuppressesNormalSuccessfulReads(t *testing.T) {
+	core, logs := observer.New(zap.DebugLevel)
+	logger := zap.New(core)
+	engine := gin.New()
+	engine.Use(LoggingWithConfig(logger, config.LogConfig{
+		RequestSuccessLevel:      "debug",
+		RequestSuccessSampleRate: 0,
+		RequestSlowThreshold:     time.Second,
+	}))
+	engine.GET("/api/v1/templates", func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/templates", nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+	assert.Empty(t, logs.All())
+}
+
+func TestLoggingKeepsWriteAndFailureSignals(t *testing.T) {
+	core, logs := observer.New(zap.DebugLevel)
+	logger := zap.New(core)
+	engine := gin.New()
+	engine.Use(LoggingWithConfig(logger, config.LogConfig{
+		RequestSuccessLevel:      "debug",
+		RequestSuccessSampleRate: 0,
+		RequestSlowThreshold:     time.Second,
+	}))
+	engine.POST("/test/resources", func(c *gin.Context) {
+		c.Status(http.StatusCreated)
+	})
+	engine.GET("/test/resources/:id", func(c *gin.Context) {
+		c.Status(http.StatusInternalServerError)
+	})
+
+	postReq := httptest.NewRequest(http.MethodPost, "/test/resources", nil)
+	postW := httptest.NewRecorder()
+	engine.ServeHTTP(postW, postReq)
+
+	getReq := httptest.NewRequest(http.MethodGet, "/test/resources/1", nil)
+	getW := httptest.NewRecorder()
+	engine.ServeHTTP(getW, getReq)
+
+	require.Equal(t, http.StatusCreated, postW.Code)
+	require.Equal(t, http.StatusInternalServerError, getW.Code)
+	require.Len(t, logs.All(), 2)
+	assert.Equal(t, zap.InfoLevel, logs.All()[0].Level)
+	assert.Equal(t, zap.ErrorLevel, logs.All()[1].Level)
+}
+
+func TestSummarizeScopeConstraintUsesBoundedShape(t *testing.T) {
+	scope := iamscope.ScopeConstraint{
+		AllowGroups: [][]iamscope.DimPredicate{
+			{
+				{Dimension: iamscope.ScopeDimensionProduct, Operator: iamscope.ScopeOpEquals, Values: []string{"catalog"}},
+				{Dimension: iamscope.ScopeDimensionCreatedBySelf, Operator: iamscope.ScopeOpSelf},
+			},
+		},
+		DenyGroups: [][]iamscope.DimPredicate{
+			{
+				{Dimension: iamscope.ScopeDimensionTenant, Operator: iamscope.ScopeOpEquals, Values: []string{"1"}},
+			},
+		},
+	}
+
+	require.Equal(t, "allow_groups=1;deny_groups=1;dimensions=created_by_self,product,tenant", summarizeScopeConstraint(scope))
+	require.Equal(t, "unbounded", summarizeScopeConstraint(iamscope.NewUnboundedScope()))
+	require.Equal(t, "empty", summarizeScopeConstraint(iamscope.ScopeConstraint{}))
+}
+
+// newTestContext 创建带有真实 http.Request 的测试用 gin.Context
+//
+//nolint:unparam // method 保留参数以支持未来不同 HTTP 方法的测试
+func newTestContext(method, path string) (*gin.Context, *httptest.ResponseRecorder) {
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(method, path, nil)
+	return c, w
+}
+
+var testGatewayTokenExpiresAt = time.Unix(2_200_003_600, 0).UTC()
+
+type fakeGatewayBlacklistChecker struct {
+	revokedJTIs     map[string]bool
+	err             error
+	sessionErr      error
+	sessionOK       *bool
+	sessionID       int64
+	identityID      types.IdentityID
+	userID          types.UserID
+	userPublicID    string
+	authProductCode string
+	accessMode      GatewayIdentityAccessMode
+	accessErr       error
+	resolveCalls    int
+}
+
+func (f *fakeGatewayBlacklistChecker) ResolveGatewayAuthState(_ context.Context, req GatewayAuthStateRequest) (GatewayAuthState, error) {
+	f.resolveCalls++
+	if f.err != nil {
+		return GatewayAuthState{}, f.err
+	}
+	if f.revokedJTIs[req.TokenJTI] {
+		return GatewayAuthState{}, nil
+	}
+	if f.sessionErr != nil {
+		return GatewayAuthState{}, f.sessionErr
+	}
+	f.sessionID = req.SessionID
+	f.identityID = req.IdentityID
+	f.userPublicID = req.UserPublicID
+	f.authProductCode = req.AuthProductCode
+	var resolvedUserID int64
+	if _, scanErr := fmt.Sscanf(req.UserPublicID, "usr_%d", &resolvedUserID); scanErr == nil && resolvedUserID > 0 {
+		f.userID = types.UserID(resolvedUserID)
+	} else {
+		f.userID = types.UserID(12)
+	}
+	if f.sessionOK != nil && !*f.sessionOK {
+		return GatewayAuthState{}, nil
+	}
+	if f.accessErr != nil {
+		return GatewayAuthState{}, f.accessErr
+	}
+	accessMode := f.accessMode
+	if accessMode == "" {
+		accessMode = GatewayIdentityAccessModeAllowed
+	}
+	return GatewayAuthState{Active: true, UserID: f.userID, AccessMode: accessMode}, nil
+}
+
+func newGatewayIdentityMiddleware(checker GatewayAuthStateChecker) gin.HandlerFunc {
+	return GatewayIdentity(checker)
+}
+
+func applyGatewayAuthHeaders(req *http.Request, userID, sessionID int64, jti, tenantID string) {
+	applyGatewayAuthHeadersWithIdentity(req, userID, userID, sessionID, jti, tenantID)
+}
+
+func applyGatewayAuthHeadersWithIdentity(req *http.Request, userID, identityID, sessionID int64, jti, tenantID string) {
+	req.Header.Set(types.HeaderUserPublicID, fmt.Sprintf("usr_%d", userID))
+	req.Header.Set(types.HeaderIdentityID, fmt.Sprintf("%d", identityID))
+	req.Header.Set(types.HeaderUserType, "user")
+	req.Header.Set(types.HeaderSessionID, fmt.Sprintf("%d", sessionID))
+	req.Header.Set(types.HeaderTokenJTI, jti)
+	req.Header.Set(types.HeaderTokenExpiresAt, fmt.Sprintf("%d", testGatewayTokenExpiresAt.Unix()))
+	req.Header.Set(types.HeaderTenantID, tenantID)
+	req.Header.Set(types.HeaderAuthProductCode, "test-product")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// GatewayIdentity 测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestGatewayIdentity_NoIdentityHeadersPasses 验证公开路由在无网关注入身份时保持放行
+func TestGatewayIdentity_NoIdentityHeadersPasses(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{}))
+	engine.GET("/", func(ctx *gin.Context) {
+		identity := GetUserIdentity(ctx)
+		sessionID, hasSession := GetSessionID(ctx)
+		assert.Nil(t, identity, "公开路由不应注入身份")
+		assert.False(t, hasSession)
+		assert.Zero(t, sessionID)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestGatewayIdentity_ValidHeadersInjectIdentityAndSession 验证合法网关头可注入 identity 与会话上下文
+func TestGatewayIdentity_ValidHeadersInjectIdentityAndSession(t *testing.T) {
+	engine := gin.New()
+	checker := &fakeGatewayBlacklistChecker{}
+	engine.Use(newGatewayIdentityMiddleware(checker))
+	engine.GET("/", func(ctx *gin.Context) {
+		identity := GetUserIdentity(ctx)
+		sessionID, hasSession := GetSessionID(ctx)
+		tokenJTI, hasJTI := GetAccessTokenJTI(ctx)
+		expiresAt, hasExpiresAt := GetAccessTokenExpiresAt(ctx)
+
+		require.NotNil(t, identity)
+		assert.True(t, hasSession)
+		assert.True(t, hasJTI)
+		assert.True(t, hasExpiresAt)
+		assert.Equal(t, types.UserID(12), identity.UserID)
+		assert.Equal(t, "usr_12", identity.UserPublicID)
+		assert.Equal(t, types.IdentityID(11), identity.IdentityID)
+		assert.Equal(t, "user", identity.Type)
+		assert.Equal(t, "tenant-abc", identity.TenantID)
+		assert.Equal(t, int64(9001), sessionID)
+		assert.Equal(t, "jti-valid", tokenJTI)
+		assert.Equal(t, testGatewayTokenExpiresAt, expiresAt)
+		assert.Equal(t, int64(11), ctxutil.IdentityIDFromContext(ctx.Request.Context()))
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	applyGatewayAuthHeadersWithIdentity(req, 12, 11, 9001, "jti-valid", "tenant-abc")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, int64(9001), checker.sessionID)
+	assert.Equal(t, types.IdentityID(11), checker.identityID)
+	assert.Equal(t, types.UserID(12), checker.userID)
+	assert.Equal(t, "usr_12", checker.userPublicID)
+	assert.Equal(t, "test-product", checker.authProductCode)
+	assert.Empty(t, req.Header.Get(types.HeaderProductCode))
+}
+
+// TestGatewayIdentity_RevokedTokenReturnsUnauthorized 验证命中黑名单的访问令牌被拒绝
+func TestGatewayIdentity_RevokedTokenReturnsUnauthorized(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{
+		revokedJTIs: map[string]bool{
+			"jti-revoked": true,
+		},
+	}))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	applyGatewayAuthHeaders(req, 42, 9001, "jti-revoked", "tenant-abc")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusUnauthorized, w.Code)
+
+	var body apierror.ErrorResponse
+	err := json.Unmarshal(w.Body.Bytes(), &body)
+	require.NoError(t, err)
+	assert.Equal(t, apierror.CodeUnauthorized, body.Error.Code)
+}
+
+// TestGatewayIdentity_InvalidGatewayHeadersReturnsUnauthorized 验证网关认证事实缺失或非法时请求被拒绝
+func TestGatewayIdentity_InvalidGatewayHeadersReturnsUnauthorized(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{}))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderUserPublicID, "usr_12")
+	req.Header.Set(types.HeaderIdentityID, "11")
+	req.Header.Set(types.HeaderSessionID, "not-a-number")
+	req.Header.Set(types.HeaderTokenJTI, "jti-invalid")
+	req.Header.Set(types.HeaderTokenExpiresAt, fmt.Sprintf("%d", testGatewayTokenExpiresAt.Unix()))
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusUnauthorized, w.Code)
+
+	var body apierror.ErrorResponse
+	err := json.Unmarshal(w.Body.Bytes(), &body)
+	require.NoError(t, err)
+	assert.Equal(t, apierror.CodeUnauthorized, body.Error.Code)
+}
+
+// TestGatewayIdentity_BlacklistServiceUnavailableReturns503 验证撤销态查询失败时按 fail-closed 返回 503
+func TestGatewayIdentity_BlacklistServiceUnavailableReturns503(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{
+		err: assert.AnError,
+	}))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	applyGatewayAuthHeaders(req, 42, 9001, "jti-blacklist-error", "tenant-abc")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusServiceUnavailable, w.Code)
+
+	var body apierror.ErrorResponse
+	err := json.Unmarshal(w.Body.Bytes(), &body)
+	require.NoError(t, err)
+	assert.Equal(t, apierror.CodeServiceUnavailable, body.Error.Code)
+}
+
+// TestGatewayIdentity_InactiveSessionReturnsUnauthorized 验证会话撤销后访问立即失效
+func TestGatewayIdentity_InactiveSessionReturnsUnauthorized(t *testing.T) {
+	inactive := false
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{
+		sessionOK: &inactive,
+	}))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	applyGatewayAuthHeaders(req, 42, 9001, "jti-inactive-session", "tenant-abc")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusUnauthorized, w.Code)
+}
+
+// TestGatewayIdentity_PendingDeletionBlocksNormalRoutes 验证冷静期账号无法访问普通受保护路由
+func TestGatewayIdentity_PendingDeletionBlocksNormalRoutes(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{
+		accessMode: GatewayIdentityAccessModePendingDeletion,
+	}))
+	engine.GET("/api/v1/viewer", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/viewer", nil)
+	applyGatewayAuthHeaders(req, 42, 9001, "jti-pending-deletion", "tenant-abc")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusForbidden, w.Code)
+	var body apierror.ErrorResponse
+	err := json.Unmarshal(w.Body.Bytes(), &body)
+	require.NoError(t, err)
+	assert.Equal(t, apierror.CodeAccountPendingDeletion, body.Error.Code)
+}
+
+// TestGatewayIdentity_PendingDeletionAllowsCancelRoute 验证冷静期账号仍可取消注销
+func TestGatewayIdentity_PendingDeletionAllowsCancelRoute(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{
+		accessMode: GatewayIdentityAccessModePendingDeletion,
+	}))
+	engine.POST("/api/v1/deletion/cancel", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/deletion/cancel", nil)
+	applyGatewayAuthHeaders(req, 42, 9001, "jti-cancel-allowed", "tenant-abc")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+func TestGatewayIdentity_VerificationRequiredUsesMethodBoundAllowlist(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name       string
+		method     string
+		path       string
+		wantStatus int
+		wantCode   string
+	}{
+		{name: "email verification", method: http.MethodPost, path: "/api/v1/auth/verify-email", wantStatus: http.StatusOK},
+		{name: "verification resend", method: http.MethodPost, path: "/api/v1/auth/resend-verification", wantStatus: http.StatusOK},
+		{name: "logout", method: http.MethodPost, path: "/api/v1/auth/logout", wantStatus: http.StatusOK},
+		{name: "platform user info", method: http.MethodGet, path: "/api/v1/users/me", wantStatus: http.StatusOK},
+		{name: "browser session", method: http.MethodGet, path: "/api/onex/session", wantStatus: http.StatusOK},
+		{name: "guest activation completion", method: http.MethodPost, path: "/api/onex/auth/password-recovery/verify-code", wantStatus: http.StatusOK},
+		{name: "wrong verification method", method: http.MethodGet, path: "/api/v1/auth/verify-email", wantStatus: http.StatusForbidden, wantCode: apierror.CodeAccountNotVerified},
+		{name: "viewer denied", method: http.MethodGet, path: "/api/onex/viewer", wantStatus: http.StatusForbidden, wantCode: apierror.CodeAccountNotVerified},
+		{name: "checkout denied", method: http.MethodPost, path: "/api/v1/checkout-sessions", wantStatus: http.StatusForbidden, wantCode: apierror.CodeAccountNotVerified},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			engine := gin.New()
+			engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{
+				accessMode: GatewayIdentityAccessModeVerificationRequired,
+			}))
+			engine.Handle(tt.method, tt.path, func(ctx *gin.Context) { ctx.Status(http.StatusOK) })
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest(tt.method, tt.path, nil)
+			applyGatewayAuthHeaders(req, 42, 9001, "jti-verification-required", "tenant-abc")
+			engine.ServeHTTP(w, req)
+
+			assert.Equal(t, tt.wantStatus, w.Code)
+			if tt.wantCode != "" {
+				var body apierror.ErrorResponse
+				require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))
+				assert.Equal(t, tt.wantCode, body.Error.Code)
+			}
+		})
+	}
+}
+
+func TestGatewayIdentity_UnknownAccessModeFailsClosed(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{accessMode: "future_state"}))
+	engine.GET("/api/v1/users/me", func(ctx *gin.Context) { ctx.Status(http.StatusOK) })
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/users/me", nil)
+	applyGatewayAuthHeaders(req, 42, 9001, "jti-unknown-mode", "tenant-abc")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusForbidden, w.Code)
+	var body apierror.ErrorResponse
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))
+	assert.Equal(t, apierror.CodeAccessDenied, body.Error.Code)
+}
+
+// TestCORS_ExposeCheckoutClientHeaders 验证本地联调 CORS 允许新的 checkout 客户端上下文头。
+func TestCORS_ExposeCheckoutClientHeaders(t *testing.T) {
+	engine := gin.New()
+	engine.Use(CORS())
+	engine.OPTIONS("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodOptions, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusNoContent, w.Code)
+	allowHeaders := w.Header().Get("Access-Control-Allow-Headers")
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderClientLocale))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderClientTimezone))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderClientTimezoneOffset))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderClientScreenWidth))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderClientJavaScriptEnabled))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderClientCookiesEnabled))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderProductCode))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderDeviceID))
+	assert.True(t, strings.Contains(allowHeaders, "Checkout-Client-Nonce"))
+	assert.True(t, strings.Contains(allowHeaders, "Checkout-Presentation-Accept"))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderIdempotencyKey))
+	for _, header := range strings.Split(allowHeaders, ", ") {
+		assert.NotEqual(t, "Idempotency-Key", header)
+	}
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderAttributionSource))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderAttributionTouchID))
+	assert.True(t, strings.Contains(allowHeaders, types.HeaderAttributionCampaignID))
+}
+
+// ═══════════════════════════════════════════════════════════════
+// RequireIdentity 测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestRequireIdentity_WithIdentity 验证已设置 identity 时请求通过
+func TestRequireIdentity_WithIdentity(t *testing.T) {
+	engine := gin.New()
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{UserID: 1, Type: "user"})
+	}, RequireIdentity(), func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	// 先用 GatewayIdentity 注入 identity，再用 RequireIdentity 验证
+	engine2 := gin.New()
+	engine2.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{}), RequireIdentity())
+	engine2.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	applyGatewayAuthHeaders(req, 1, 1001, "jti-req-identity", "tenant-1")
+	engine2.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestRequireIdentity_WithoutIdentity 验证无 identity 时返回 401
+func TestRequireIdentity_WithoutIdentity(t *testing.T) {
+	engine := gin.New()
+	engine.Use(newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{}), RequireIdentity())
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	// 不设置网关认证事实，GatewayIdentity 放行，RequireIdentity 应返回 401
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusUnauthorized, w.Code)
+
+	var body apierror.ErrorResponse
+	err := json.Unmarshal(w.Body.Bytes(), &body)
+	require.NoError(t, err)
+	assert.Equal(t, apierror.CodeUnauthorized, body.Error.Code)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// ProductContext 测试
+// ═══════════════════════════════════════════════════════════════
+
+type middlewareProductContextReader struct {
+	snapshots  map[string]iamdomain.ProductContextSnapshot
+	err        error
+	resolvedAt []time.Time
+}
+
+func (r *middlewareProductContextReader) ReadProductContextAt(
+	_ context.Context,
+	productCode string,
+	resolvedAt time.Time,
+) (iamdomain.ProductContextSnapshot, error) {
+	r.resolvedAt = append(r.resolvedAt, resolvedAt)
+	if r.err != nil {
+		return iamdomain.ProductContextSnapshot{}, r.err
+	}
+	snapshot, ok := r.snapshots[productCode]
+	if !ok {
+		return iamdomain.ProductContextSnapshot{}, iamdomain.ErrProductContextNotFound
+	}
+	return snapshot, nil
+}
+
+func TestProductContext_UsesInjectedResolutionBoundary(t *testing.T) {
+	fixedAt := time.Date(2026, time.July, 10, 8, 30, 0, 0, time.UTC)
+	tests := []struct {
+		name       string
+		resolvedAt time.Time
+		wantStatus int
+	}{
+		{name: "exact boundary", resolvedAt: fixedAt, wantStatus: http.StatusOK},
+		{name: "future by one nanosecond", resolvedAt: fixedAt.Add(time.Nanosecond), wantStatus: http.StatusServiceUnavailable},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			reader := productContextReader("catalog")
+			snapshot := reader.snapshots["catalog"]
+			snapshot.ResolvedAt = tc.resolvedAt
+			reader.snapshots["catalog"] = snapshot
+			engine := gin.New()
+			engine.Use(ProductContext(reader, coreclock.NewManualClock(fixedAt)))
+			engine.GET("/", func(ctx *gin.Context) { ctx.Status(http.StatusOK) })
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodGet, "/", nil)
+			req.Header.Set(types.HeaderProductCode, "catalog")
+			engine.ServeHTTP(w, req)
+
+			assert.Equal(t, tc.wantStatus, w.Code)
+			require.Equal(t, []time.Time{fixedAt}, reader.resolvedAt)
+		})
+	}
+}
+
+func productContextReader(productCodes ...string) *middlewareProductContextReader {
+	snapshots := make(map[string]iamdomain.ProductContextSnapshot, len(productCodes))
+	resolvedAt := time.Now().UTC().Add(-time.Minute)
+	for _, productCode := range productCodes {
+		snapshots[productCode] = iamdomain.ProductContextSnapshot{
+			ProductCode:        productCode,
+			ProductKind:        "application",
+			LifecycleStatus:    "active",
+			ContextVersion:     1,
+			ContextFingerprint: strings.Repeat("a", 64),
+			Attributes: []iamdomain.ProductAttributeFact{
+				{Code: "product_kind", Value: json.RawMessage(`"application"`)},
+			},
+			Capabilities: make([]iamdomain.ProductCapabilityFact, 0),
+			ResolvedAt:   resolvedAt,
+		}
+	}
+	return &middlewareProductContextReader{snapshots: snapshots}
+}
+
+// TestProductContext_ValidCode 验证合法产品码被设置到 context
+func TestProductContext_ValidCode(t *testing.T) {
+	validCodes := []types.Product{
+		types.ProductPlatform,
+		types.Product("catalog"),
+		types.Product("new_dynamic_product"),
+	}
+
+	for _, code := range validCodes {
+		t.Run(string(code), func(t *testing.T) {
+			engine := gin.New()
+			engine.Use(ProductContext(productContextReader(string(code)), coreclock.NewSystemClock()))
+			engine.GET("/", func(ctx *gin.Context) {
+				got := GetProductCode(ctx)
+				assert.Equal(t, code, got)
+				ctx.Status(http.StatusOK)
+			})
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodGet, "/", nil)
+			req.Header.Set(types.HeaderProductCode, string(code))
+			engine.ServeHTTP(w, req)
+
+			assert.Equal(t, http.StatusOK, w.Code)
+		})
+	}
+}
+
+func TestProductContext_ValidOneXProductCodeForIAMServiceToken(t *testing.T) {
+	dynamicProduct := types.Product("external-product")
+	engine := gin.New()
+	engine.Use(ProductContext(productContextReader(string(dynamicProduct)), coreclock.NewSystemClock()))
+	engine.GET("/", func(ctx *gin.Context) {
+		assert.Equal(t, dynamicProduct, GetProductCode(ctx))
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set("Authorization", "Bearer iamt_test.token")
+	req.Header.Set(types.HeaderOneXProductCode, string(dynamicProduct))
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+func TestProductContext_IgnoresOneXProductCodeWithoutIAMServiceToken(t *testing.T) {
+	dynamicProduct := types.Product("external-product")
+	engine := gin.New()
+	engine.Use(ProductContext(productContextReader(), coreclock.NewSystemClock()))
+	engine.GET("/", func(ctx *gin.Context) {
+		assert.Equal(t, types.Product(""), GetProductCode(ctx))
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderOneXProductCode, string(dynamicProduct))
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+func TestProductContext_RejectsMismatchedProductHeaders(t *testing.T) {
+	dynamicProduct := types.Product("external-product")
+	engine := gin.New()
+	engine.Use(ProductContext(
+		productContextReader(string(types.Product("catalog")), string(dynamicProduct)),
+		coreclock.NewSystemClock(),
+	))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderProductCode, string(types.Product("catalog")))
+	req.Header.Set(types.HeaderOneXProductCode, string(dynamicProduct))
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+// TestProductContext_MissingHeader 验证无 X-Product-Code 时请求被放行，context 中无产品码
+func TestProductContext_MissingHeader(t *testing.T) {
+	engine := gin.New()
+	engine.Use(ProductContext(productContextReader(), coreclock.NewSystemClock()))
+	engine.GET("/", func(ctx *gin.Context) {
+		got := GetProductCode(ctx)
+		assert.Equal(t, types.Product(""), got)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestProductContext_UnknownCode 验证未知产品码返回 400
+func TestProductContext_UnknownCode(t *testing.T) {
+	engine := gin.New()
+	engine.Use(ProductContext(productContextReader(), coreclock.NewSystemClock()))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderProductCode, "unknown_product")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+
+	var body apierror.ErrorResponse
+	err := json.Unmarshal(w.Body.Bytes(), &body)
+	require.NoError(t, err)
+	assert.Equal(t, apierror.CodeInvalidOperation, body.Error.Code)
+	assert.Contains(t, body.Error.Message, "unknown_product")
+}
+
+func TestProductContext_ReaderFailureFailsClosed(t *testing.T) {
+	engine := gin.New()
+	engine.Use(ProductContext(
+		&middlewareProductContextReader{err: errors.New("product database unavailable")},
+		coreclock.NewSystemClock(),
+	))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderProductCode, "catalog")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusServiceUnavailable, w.Code)
+	var body apierror.ErrorResponse
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))
+	assert.Equal(t, apierror.CodeServiceUnavailable, body.Error.Code)
+}
+
+func TestProductContext_RejectsSnapshotAdmissionInvariantViolations(t *testing.T) {
+	valid := productContextReader("catalog").snapshots["catalog"]
+	now := time.Now().UTC()
+	expiredAt := now.Add(-time.Second)
+	futureResolvedAt := now.Add(time.Minute)
+
+	tests := []struct {
+		name   string
+		mutate func(*iamdomain.ProductContextSnapshot)
+	}{
+		{name: "zero version", mutate: func(snapshot *iamdomain.ProductContextSnapshot) { snapshot.ContextVersion = 0 }},
+		{name: "empty fingerprint", mutate: func(snapshot *iamdomain.ProductContextSnapshot) { snapshot.ContextFingerprint = "" }},
+		{name: "zero resolved time", mutate: func(snapshot *iamdomain.ProductContextSnapshot) { snapshot.ResolvedAt = time.Time{} }},
+		{name: "future resolved time", mutate: func(snapshot *iamdomain.ProductContextSnapshot) { snapshot.ResolvedAt = futureResolvedAt }},
+		{name: "expired snapshot", mutate: func(snapshot *iamdomain.ProductContextSnapshot) { snapshot.ExpiresAt = &expiredAt }},
+		{name: "unresolved attributes", mutate: func(snapshot *iamdomain.ProductContextSnapshot) { snapshot.Attributes = nil }},
+		{name: "unresolved capabilities", mutate: func(snapshot *iamdomain.ProductContextSnapshot) { snapshot.Capabilities = nil }},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			snapshot := valid
+			snapshot.Attributes = append([]iamdomain.ProductAttributeFact(nil), valid.Attributes...)
+			snapshot.Capabilities = append([]iamdomain.ProductCapabilityFact(nil), valid.Capabilities...)
+			tc.mutate(&snapshot)
+			engine := gin.New()
+			engine.Use(ProductContext(
+				&middlewareProductContextReader{snapshots: map[string]iamdomain.ProductContextSnapshot{"catalog": snapshot}},
+				coreclock.NewSystemClock(),
+			))
+			engine.GET("/", func(ctx *gin.Context) { ctx.Status(http.StatusOK) })
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodGet, "/", nil)
+			req.Header.Set(types.HeaderProductCode, "catalog")
+			engine.ServeHTTP(w, req)
+
+			assert.Equal(t, http.StatusServiceUnavailable, w.Code)
+		})
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// ClientContext 测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestClientContext_AllHeaders 验证所有客户端 Header 被正确提取
+func TestClientContext_AllHeaders(t *testing.T) {
+	engine := gin.New()
+	engine.Use(ClientContext())
+	engine.GET("/", func(ctx *gin.Context) {
+		cc := GetClientContext(ctx)
+		require.NotNil(t, cc)
+		assert.Equal(t, "mobile", cc.Type)
+		assert.Equal(t, "1.2.3", cc.Version)
+		assert.Equal(t, "iOS", cc.Platform)
+		assert.Equal(t, "device-123", cc.DeviceID)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderClientType, "mobile")
+	req.Header.Set(types.HeaderClientVersion, "1.2.3")
+	req.Header.Set(types.HeaderClientPlatform, "iOS")
+	req.Header.Set(types.HeaderDeviceID, "device-123")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestClientContext_AlwaysSetsContext 验证无 Header 时 ClientContext 仍然被设置（非 nil）
+func TestClientContext_AlwaysSetsContext(t *testing.T) {
+	engine := gin.New()
+	engine.Use(ClientContext())
+	engine.GET("/", func(ctx *gin.Context) {
+		cc := GetClientContext(ctx)
+		// ClientContext 总是注入，即使 Header 为空
+		require.NotNil(t, cc)
+		assert.Equal(t, "", cc.Type)
+		assert.Equal(t, "", cc.Version)
+		assert.Equal(t, "", cc.Platform)
+		assert.Equal(t, "", cc.DeviceID)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestClientContext_LegacyAppVersionFallback 验证旧版 X-App-Version 可回退到 Version
+func TestClientContext_LegacyAppVersionFallback(t *testing.T) {
+	engine := gin.New()
+	engine.Use(ClientContext())
+	engine.GET("/", func(ctx *gin.Context) {
+		cc := GetClientContext(ctx)
+		require.NotNil(t, cc)
+		assert.Equal(t, "2.3.4", cc.Version)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderAppVersion, "2.3.4")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestClientContext_XRealIPTakesPrecedence 验证 X-Real-IP 优先于 ClientIP
+func TestClientContext_XRealIPTakesPrecedence(t *testing.T) {
+	engine := gin.New()
+	engine.Use(ClientContext())
+	engine.GET("/", func(ctx *gin.Context) {
+		cc := GetClientContext(ctx)
+		require.NotNil(t, cc)
+		assert.Equal(t, "203.0.113.1", cc.IP)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderXRealIP, "203.0.113.1")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// RequestID 测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestRequestID_UseExistingHeader 验证已有 X-Request-ID 时直接使用
+func TestRequestID_UseExistingHeader(t *testing.T) {
+	existingID := "test-request-id-12345"
+
+	engine := gin.New()
+	engine.Use(RequestID())
+	engine.GET("/", func(ctx *gin.Context) {
+		id := GetRequestID(ctx)
+		assert.Equal(t, existingID, id)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderRequestID, existingID)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	// 验证响应头包含相同的 request ID
+	assert.Equal(t, existingID, w.Header().Get(types.HeaderRequestID))
+}
+
+// TestRequestID_UseCorrelationIDFallback 验证无 X-Request-ID 时使用 X-Correlation-ID
+func TestRequestID_UseCorrelationIDFallback(t *testing.T) {
+	correlationID := "corr-id-abc"
+
+	engine := gin.New()
+	engine.Use(RequestID())
+	engine.GET("/", func(ctx *gin.Context) {
+		id := GetRequestID(ctx)
+		assert.Equal(t, correlationID, id)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderCorrelationID, correlationID)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, correlationID, w.Header().Get(types.HeaderRequestID))
+}
+
+// TestRequestID_GeneratesUUIDWhenMissing 验证无任何 ID Header 时生成 UUID
+func TestRequestID_GeneratesUUIDWhenMissing(t *testing.T) {
+	engine := gin.New()
+	engine.Use(RequestID())
+	engine.GET("/", func(ctx *gin.Context) {
+		id := GetRequestID(ctx)
+		assert.NotEmpty(t, id, "自动生成的 request ID 不应为空")
+		// UUID 格式：8-4-4-4-12 十六进制
+		assert.Len(t, id, 36, "UUID 长度应为 36 字符")
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.NotEmpty(t, w.Header().Get(types.HeaderRequestID), "响应头应包含生成的 request ID")
+}
+
+// TestRequestID_XRequestIDPriorityOverCorrelationID 验证 X-Request-ID 优先级高于 X-Correlation-ID
+func TestRequestID_XRequestIDPriorityOverCorrelationID(t *testing.T) {
+	requestID := "primary-id"
+	correlationID := "secondary-id"
+
+	engine := gin.New()
+	engine.Use(RequestID())
+	engine.GET("/", func(ctx *gin.Context) {
+		id := GetRequestID(ctx)
+		assert.Equal(t, requestID, id)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderRequestID, requestID)
+	req.Header.Set(types.HeaderCorrelationID, correlationID)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestGetRequestID_WhenNotSet 验证 context 中无 request ID 时返回空字符串
+func TestGetRequestID_WhenNotSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	id := GetRequestID(c)
+	assert.Equal(t, "", id)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// helpers.go 测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestGetUserIdentity_WhenSet 验证 context 中有 identity 时正确返回
+func TestGetUserIdentity_WhenSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	expected := &types.UserIdentity{UserID: 99, Type: "admin"}
+	c.Set(string(types.ContextKeyUserIdentity), expected)
+
+	got := GetUserIdentity(c)
+	require.NotNil(t, got)
+	assert.Equal(t, expected.UserID, got.UserID)
+	assert.Equal(t, expected.Type, got.Type)
+}
+
+// TestGetUserIdentity_WhenNotSet 验证 context 中无 identity 时返回 nil
+func TestGetUserIdentity_WhenNotSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	got := GetUserIdentity(c)
+	assert.Nil(t, got)
+}
+
+// TestGetUserIdentity_WrongType 验证 context 中类型不匹配时返回 nil
+func TestGetUserIdentity_WrongType(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	c.Set(string(types.ContextKeyUserIdentity), "wrong-type-value")
+	got := GetUserIdentity(c)
+	assert.Nil(t, got)
+}
+
+// TestGetUserID_WhenIdentitySet 验证有 identity 时正确返回 user ID
+func TestGetUserID_WhenIdentitySet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	c.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{UserID: 55})
+	assert.Equal(t, types.UserID(55), GetUserID(c))
+}
+
+// TestGetUserID_WhenNotSet 验证无 identity 时返回 0
+func TestGetUserID_WhenNotSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	assert.Equal(t, types.UserID(0), GetUserID(c))
+}
+
+// TestGetProductCode_WhenSet 验证 context 中有产品码时正确返回
+func TestGetProductCode_WhenSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	c.Set(string(types.ContextKeyProductCode), types.ProductPlatform)
+	got := GetProductCode(c)
+	assert.Equal(t, types.ProductPlatform, got)
+}
+
+// TestGetProductCode_WhenNotSet 验证 context 中无产品码时返回空字符串
+func TestGetProductCode_WhenNotSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	got := GetProductCode(c)
+	assert.Equal(t, types.Product(""), got)
+}
+
+// TestGetProductCode_WrongType 验证 context 中类型不匹配时返回空字符串
+func TestGetProductCode_WrongType(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	c.Set(string(types.ContextKeyProductCode), 12345)
+	got := GetProductCode(c)
+	assert.Equal(t, types.Product(""), got)
+}
+
+// TestGetClientContext_WhenSet 验证 context 中有 ClientContext 时正确返回
+func TestGetClientContext_WhenSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	expected := &types.ClientContext{Type: "web", Version: "2.0.0", Platform: "Web"}
+	c.Set(string(types.ContextKeyClientContext), expected)
+
+	got := GetClientContext(c)
+	require.NotNil(t, got)
+	assert.Equal(t, "web", got.Type)
+	assert.Equal(t, "2.0.0", got.Version)
+	assert.Equal(t, "Web", got.Platform)
+}
+
+// TestGetClientContext_WhenNotSet 验证 context 中无 ClientContext 时返回 nil
+func TestGetClientContext_WhenNotSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	got := GetClientContext(c)
+	assert.Nil(t, got)
+}
+
+// TestGetClientContext_WrongType 验证 context 中类型不匹配时返回 nil
+func TestGetClientContext_WrongType(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	c.Set(string(types.ContextKeyClientContext), "bad-type")
+	got := GetClientContext(c)
+	assert.Nil(t, got)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Recovery 测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestRecovery_HandlesStringPanic 验证字符串 panic 被捕获并返回 500
+func TestRecovery_HandlesStringPanic(t *testing.T) {
+	logger := zap.NewNop()
+
+	engine := gin.New()
+	engine.Use(Recovery(logger))
+	engine.GET("/", func(ctx *gin.Context) {
+		panic("something went terribly wrong")
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusInternalServerError, w.Code)
+
+	var body apierror.ErrorResponse
+	err := json.Unmarshal(w.Body.Bytes(), &body)
+	require.NoError(t, err)
+	assert.Equal(t, apierror.CodeInternalError, body.Error.Code)
+}
+
+// TestRecovery_HandlesErrorPanic 验证 error panic 被捕获并返回 500
+func TestRecovery_HandlesErrorPanic(t *testing.T) {
+	logger := zap.NewNop()
+
+	engine := gin.New()
+	engine.Use(Recovery(logger))
+	engine.GET("/", func(ctx *gin.Context) {
+		panic(fmt.Errorf("db connection lost"))
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusInternalServerError, w.Code)
+}
+
+// TestRecovery_NoPanicPassesThrough 验证无 panic 时正常请求通过
+func TestRecovery_NoPanicPassesThrough(t *testing.T) {
+	logger := zap.NewNop()
+
+	engine := gin.New()
+	engine.Use(Recovery(logger))
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestRecovery_HandlesIntPanic 验证整型 panic 被捕获并返回 500
+func TestRecovery_HandlesIntPanic(t *testing.T) {
+	logger := zap.NewNop()
+
+	engine := gin.New()
+	engine.Use(Recovery(logger))
+	engine.GET("/", func(ctx *gin.Context) {
+		panic(42)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusInternalServerError, w.Code)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Tenant 中间件测试（无 DB/Redis 依赖）
+// ═══════════════════════════════════════════════════════════════
+
+// TestTenant_ValidIDFromHeader 验证从 X-Tenant-ID Header 提取租户 ID
+func TestTenant_ValidIDFromHeader(t *testing.T) {
+	engine := gin.New()
+	engine.Use(Tenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		tenantID := GetTenantID(ctx)
+		assert.Equal(t, "valid-tenant-id", tenantID)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderTenantID, "valid-tenant-id")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestTenant_MissingTenantID 验证无租户 ID 时返回 400
+func TestTenant_MissingTenantID(t *testing.T) {
+	engine := gin.New()
+	engine.Use(Tenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+// TestTenant_InvalidIDFormat 验证格式非法的租户 ID 返回 400
+func TestTenant_InvalidIDFormat(t *testing.T) {
+	engine := gin.New()
+	engine.Use(Tenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	// 长度小于 minTenantIDLength(3)
+	req.Header.Set(types.HeaderTenantID, "ab")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+// TestTenant_ValidUUID 验证 UUID 格式的租户 ID 通过
+func TestTenant_ValidUUID(t *testing.T) {
+	engine := gin.New()
+	engine.Use(Tenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		tenantID := GetTenantID(ctx)
+		assert.Equal(t, "550e8400-e29b-41d4-a716-446655440000", tenantID)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderTenantID, "550e8400-e29b-41d4-a716-446655440000")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestTenant_SuperAdminCanAccessAnyTenant 验证超级管理员可访问任意租户
+func TestTenant_SuperAdminCanAccessAnyTenant(t *testing.T) {
+	engine := gin.New()
+	engine.Use(func(ctx *gin.Context) {
+		ctx.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{
+			UserID:   1,
+			Type:     "super_admin",
+			TenantID: "my-tenant",
+		})
+		ctx.Next()
+	})
+	engine.Use(Tenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	// super_admin 访问其他租户
+	req.Header.Set(types.HeaderTenantID, "other-tenant")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestTenant_UserCannotAccessOtherTenant 验证普通用户无法访问不属于自己的租户
+func TestTenant_UserCannotAccessOtherTenant(t *testing.T) {
+	engine := gin.New()
+	engine.Use(func(ctx *gin.Context) {
+		ctx.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{
+			UserID:   1,
+			Type:     "user",
+			TenantID: "my-tenant",
+		})
+		ctx.Next()
+	})
+	engine.Use(Tenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderTenantID, "another-tenant")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusForbidden, w.Code)
+}
+
+// TestGetTenantID_WhenSet 验证 GetTenantID 从 context 正确取值
+func TestGetTenantID_WhenSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	c.Set(string(types.ContextKeyTenantID), "my-tenant-123")
+	assert.Equal(t, "my-tenant-123", GetTenantID(c))
+}
+
+// TestGetTenantID_WhenNotSet 验证 GetTenantID 无值时返回空字符串
+func TestGetTenantID_WhenNotSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	assert.Equal(t, "", GetTenantID(c))
+}
+
+// TestGetTenantInfo_WhenSet 验证 GetTenantInfo 从 context 正确取值
+func TestGetTenantInfo_WhenSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	info := &types.TenantInfo{ID: "abc", Status: types.TenantStatusActive}
+	c.Set(string(types.ContextKeyTenant), info)
+
+	got := GetTenantInfo(c)
+	require.NotNil(t, got)
+	assert.Equal(t, "abc", got.ID)
+	assert.Equal(t, types.TenantStatusActive, got.Status)
+}
+
+// TestGetTenantInfo_WhenNotSet 验证 GetTenantInfo 无值时返回 nil
+func TestGetTenantInfo_WhenNotSet(t *testing.T) {
+	c, _ := newTestContext(http.MethodGet, "/")
+	assert.Nil(t, GetTenantInfo(c))
+}
+
+// ═══════════════════════════════════════════════════════════════
+// OptionalTenant 测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestOptionalTenant_WithValidID 验证 OptionalTenant 有合法租户 ID 时注入 context
+func TestOptionalTenant_WithValidID(t *testing.T) {
+	engine := gin.New()
+	engine.Use(OptionalTenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		tenantID := GetTenantID(ctx)
+		assert.Equal(t, "opt-tenant", tenantID)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderTenantID, "opt-tenant")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestOptionalTenant_WithMissingID 验证 OptionalTenant 无租户 ID 时不阻断，context 中无租户 ID
+func TestOptionalTenant_WithMissingID(t *testing.T) {
+	engine := gin.New()
+	engine.Use(OptionalTenant())
+	engine.GET("/", func(ctx *gin.Context) {
+		tenantID := GetTenantID(ctx)
+		assert.Equal(t, "", tenantID)
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 中间件链集成测试
+// ═══════════════════════════════════════════════════════════════
+
+// TestMiddlewareChain_GatewayIdentityAndProductContext 验证 GatewayIdentity 和 ProductContext 组合使用
+func TestMiddlewareChain_GatewayIdentityAndProductContext(t *testing.T) {
+	engine := gin.New()
+	engine.Use(
+		RequestID(),
+		newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{}),
+		ProductContext(productContextReader(string(types.ProductPlatform)), coreclock.NewSystemClock()),
+		ClientContext(),
+	)
+	engine.GET("/", func(ctx *gin.Context) {
+		// 验证所有 context 值都已注入
+		assert.NotEmpty(t, GetRequestID(ctx))
+		identity := GetUserIdentity(ctx)
+		require.NotNil(t, identity)
+		assert.Equal(t, types.UserID(123), identity.UserID)
+
+		product := GetProductCode(ctx)
+		assert.Equal(t, types.ProductPlatform, product)
+
+		cc := GetClientContext(ctx)
+		require.NotNil(t, cc)
+		assert.Equal(t, "web", cc.Type)
+
+		ctx.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	applyGatewayAuthHeaders(req, 123, 7001, "jti-chain", "tenant-chain")
+	req.Header.Set(types.HeaderProductCode, string(types.ProductPlatform))
+	req.Header.Set(types.HeaderClientType, "web")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+// TestMiddlewareChain_RecoveryWithGatewayIdentity 验证 Recovery 在复杂中间件链中可捕获 panic
+func TestMiddlewareChain_RecoveryWithGatewayIdentity(t *testing.T) {
+	logger := zap.NewNop()
+
+	engine := gin.New()
+	engine.Use(Recovery(logger), newGatewayIdentityMiddleware(&fakeGatewayBlacklistChecker{}))
+	engine.GET("/", func(ctx *gin.Context) {
+		panic("handler panic after auth")
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	applyGatewayAuthHeaders(req, 1, 8001, "jti-recovery", "tenant-recovery")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusInternalServerError, w.Code)
+}