@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,160 @@
+package middleware
+
+import (
+	"context"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/contentaccess"
+	"{{module}}/internal/common/principal"
+	"{{module}}/internal/common/types"
+)
+
+// ContentAccessResolveInput middleware 解析 Principal 时的最小输入。
+//
+// 字段含义对齐 accesspolicy.application.ResolveContentAccessInput，但只保留
+// middleware 自身能从 gin.Context 推导出的字段。生产 adapter 在 cmd/ 层把本结构
+// 映射到 application.ResolveContentAccessInput，避免 common/middleware 反向 import
+// platform/accesspolicy/application 形成循环。
+type ContentAccessResolveInput struct {
+	// ProductCode 当前请求产品标识
+	ProductCode string
+	// UserID 当前请求用户 ID 指针，nil 表示匿名
+	UserID *int64
+	// SessionID 网关注入的会话 ID（来自 X-Session-ID）
+	SessionID string
+	// AttributionSource 归因来源（来自 X-Attribution-Source）
+	AttributionSource string
+	// CountryCode 网关注入的国家代码（来自 X-GeoIP-Country-Code）
+	CountryCode string
+}
+
+// ContentAccessDecision 内容访问决策投影，仅暴露 middleware 实际写入 Principal 的字段。
+//
+// 字段对齐内容访问策略决策结果，但通过本接口隔离 application 层依赖，
+// 避免 common/middleware → platform/accesspolicy/application 反向 import 形成环。
+type ContentAccessDecision struct {
+	EffectiveLevel  int64
+	ContentRating   string
+	Decision        string
+	Source          string
+	MatchedRuleCode string
+	ReasonCode      string
+}
+
+// ContentAccessResolver 内容访问决策依赖，仅暴露 middleware 实际消费的方法。
+//
+// 由消费方（middleware）定义接口（Go 惯例 + 项目 Cross-Module Communication 规则），
+// 生产实现是一个 thin adapter（cmd/ 层组装）：把 ContentAccessResolveInput 翻译为
+// application.ResolveContentAccessInput 并调用 *AccessPolicyService.ResolveContentAccess。
+// 测试可注入 fake。
+type ContentAccessResolver interface {
+	ResolveContentAccess(ctx context.Context, input ContentAccessResolveInput) (ContentAccessDecision, error)
+}
+
+// PrincipalContext 在 authenticated 路由组注入 *principal.Principal。
+//
+// 行业对齐：
+//   - Stripe Entitlements API：backend-owned resolution, fail-closed
+//   - GitHub Permissions：per-request resolve from DB, no header-based bypass
+//
+// 失败模式：fail-closed（resolve 错误 → ContentAccess.Level=0 + 结构化日志）。
+// 不阻断请求，因为业务侧已经按 level=0 默认拒绝 mature 内容；告警走 zap.Error。
+func PrincipalContext(resolver ContentAccessResolver, logger *zap.Logger) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// Principal 内部 UserID 字段仍为 int64（Wave 4 会迁移到 types.UserID）
+		// 当前 wave 在边界显式 .Int64() 转换，避免污染 Principal 已有契约。
+		userID := GetUserID(c).Int64()
+		productCode := string(GetProductCode(c))
+		p := buildPrincipal(c, resolver, logger, userID, productCode, true)
+		principal.WithPrincipal(c, p)
+		c.Next()
+	}
+}
+
+// OptionalPrincipalContext 公开路由组的 Principal 注入（允许 userID == 0 匿名）。
+//
+// 匿名场景仍进入 resolver，按归因来源、国家等公开策略得到 ContentAccess。
+// 已登录场景同样进入 resolver，并叠加用户授予、注册国家等策略上下文。
+func OptionalPrincipalContext(resolver ContentAccessResolver, logger *zap.Logger) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := GetUserID(c).Int64()
+		productCode := string(GetProductCode(c))
+		p := buildPrincipal(c, resolver, logger, userID, productCode, false)
+		principal.WithPrincipal(c, p)
+		c.Next()
+	}
+}
+
+// buildPrincipal 构造 Principal，封装 fail-closed 默认值与决策解析。
+//
+// requireAuth=true 时，匿名请求直接落到默认决策（不调用 resolver）；
+// requireAuth=false 时，匿名请求仍会进入 resolver 走默认策略链。
+func buildPrincipal(
+	c *gin.Context,
+	resolver ContentAccessResolver,
+	logger *zap.Logger,
+	userID int64,
+	productCode string,
+	requireAuth bool,
+) *principal.Principal {
+	p := &principal.Principal{
+		UserID:      userID,
+		ProductCode: types.Product(productCode),
+		ContentAccess: principal.ContentAccess{
+			Level:    contentaccess.LevelCompliant,
+			Rating:   contentaccess.RatingCompliant,
+			Decision: "allow",
+			Source:   "default",
+		},
+	}
+	// 缺少产品上下文 / resolver 不可用 → 使用默认 fail-closed Principal
+	if productCode == "" || resolver == nil {
+		return p
+	}
+
+	input := ContentAccessResolveInput{
+		ProductCode:       productCode,
+		SessionID:         strings.TrimSpace(c.GetHeader(types.HeaderSessionID)),
+		AttributionSource: strings.TrimSpace(c.GetHeader(types.HeaderAttributionSource)),
+		CountryCode:       geoCountryCode(c),
+	}
+	if userID > 0 {
+		uid := userID
+		input.UserID = &uid
+	} else if requireAuth {
+		// 强制认证路径下若仍出现 userID==0（中间件链异常），保守返回默认 Principal
+		return p
+	}
+
+	result, err := resolver.ResolveContentAccess(c.Request.Context(), input)
+	if err != nil {
+		logger.Error("principal: resolve content access failed, fail-closed to compliant",
+			zap.Int64("userId", userID),
+			zap.String("productCode", productCode),
+			zap.Error(err),
+		)
+		return p
+	}
+
+	p.ContentAccess = principal.ContentAccess{
+		Level:      result.EffectiveLevel,
+		Rating:     result.ContentRating,
+		Decision:   result.Decision,
+		Source:     result.Source,
+		RuleCode:   result.MatchedRuleCode,
+		ReasonCode: result.ReasonCode,
+	}
+	return p
+}
+
+func geoCountryCode(c *gin.Context) string {
+	if clientCtx := GetClientContext(c); clientCtx != nil {
+		if countryCode := strings.TrimSpace(clientCtx.GeoCountryCode); countryCode != "" {
+			return countryCode
+		}
+	}
+	return strings.TrimSpace(c.GetHeader(types.HeaderGeoIPCountryCode))
+}

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

@@ -0,0 +1,355 @@
+package middleware
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/contentaccess"
+	"{{module}}/internal/common/principal"
+	"{{module}}/internal/common/types"
+)
+
+// fakeContentAccessResolver 测试用 ContentAccessResolver 实现。
+//
+// 消费方（test）定义 fake，避免引入 platform/accesspolicy 依赖；
+// captures 最近一次调用，便于断言入参（userID / productCode 透传）。
+type fakeContentAccessResolver struct {
+	result ContentAccessDecision
+	err    error
+
+	called   bool
+	gotInput ContentAccessResolveInput
+}
+
+func (f *fakeContentAccessResolver) ResolveContentAccess(
+	_ context.Context,
+	input ContentAccessResolveInput,
+) (ContentAccessDecision, error) {
+	f.called = true
+	f.gotInput = input
+	if f.err != nil {
+		return ContentAccessDecision{}, f.err
+	}
+	return f.result, nil
+}
+
+// TestPrincipalContext 覆盖 PrincipalContext / OptionalPrincipalContext 四种核心场景：
+//  1. 已登录用户 + resolve 成功 → Principal 携带 service 返回的 Level/Source
+//  2. 已登录用户 + resolve 失败 → fail-closed 至 default compliant
+//  3. 公开路由（OptionalPrincipalContext）+ 匿名用户 → 仍调用 resolver，沿用其默认策略
+//  4. 强制认证路由（PrincipalContext）+ 匿名用户 → 跳过 resolver，直接 fail-closed
+func TestPrincipalContext(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tests := []struct {
+		name string
+		// 路由：true=PrincipalContext (require auth)，false=OptionalPrincipalContext
+		requireAuth bool
+		// 是否模拟网关注入登录态
+		authenticated bool
+		// resolver 返回值
+		resolverResult ContentAccessDecision
+		resolverErr    error
+		// 期望
+		expectResolverCalled bool
+		expectLevel          int64
+		expectRating         string
+		expectDecision       string
+		expectSource         string
+		expectRuleCode       string
+		expectReasonCode     string
+		expectAuthenticated  bool
+	}{
+		{
+			name:          "authenticated user resolve OK populates Principal from service result",
+			requireAuth:   true,
+			authenticated: true,
+			resolverResult: ContentAccessDecision{
+				EffectiveLevel:  contentaccess.LevelMature,
+				ContentRating:   contentaccess.RatingMature,
+				Decision:        "allow",
+				Source:          "subscription",
+				MatchedRuleCode: "rule_subscriber_mature",
+				ReasonCode:      "",
+			},
+			expectResolverCalled: true,
+			expectLevel:          contentaccess.LevelMature,
+			expectRating:         contentaccess.RatingMature,
+			expectDecision:       "allow",
+			expectSource:         "subscription",
+			expectRuleCode:       "rule_subscriber_mature",
+			expectReasonCode:     "",
+			expectAuthenticated:  true,
+		},
+		{
+			name:                 "authenticated user resolve error fails closed to default compliant",
+			requireAuth:          true,
+			authenticated:        true,
+			resolverErr:          errors.New("policy lookup blew up"),
+			expectResolverCalled: true,
+			expectLevel:          contentaccess.LevelCompliant,
+			expectRating:         contentaccess.RatingCompliant,
+			expectDecision:       "allow",
+			expectSource:         "default",
+			expectAuthenticated:  true,
+		},
+		{
+			name:          "anonymous on optional route still resolved via default policy",
+			requireAuth:   false,
+			authenticated: false,
+			resolverResult: ContentAccessDecision{
+				EffectiveLevel: contentaccess.LevelCompliant,
+				ContentRating:  contentaccess.RatingCompliant,
+				Decision:       "allow",
+				Source:         "anonymous",
+			},
+			expectResolverCalled: true,
+			expectLevel:          contentaccess.LevelCompliant,
+			expectRating:         contentaccess.RatingCompliant,
+			expectDecision:       "allow",
+			expectSource:         "anonymous",
+			expectAuthenticated:  false,
+		},
+		{
+			name:                 "anonymous on require-auth route skips resolver and stays on fail-closed default",
+			requireAuth:          true,
+			authenticated:        false,
+			expectResolverCalled: false,
+			expectLevel:          contentaccess.LevelCompliant,
+			expectRating:         contentaccess.RatingCompliant,
+			expectDecision:       "allow",
+			expectSource:         "default",
+			expectAuthenticated:  false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			resolver := &fakeContentAccessResolver{
+				result: tc.resolverResult,
+				err:    tc.resolverErr,
+			}
+			logger := zap.NewNop()
+
+			engine := gin.New()
+			// 模拟 gateway middleware：从身份上下文 / X-Product-Code 注入 ctx
+			engine.Use(func(c *gin.Context) {
+				if userPublicID := c.GetHeader(types.HeaderUserPublicID); userPublicID != "" {
+					c.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{
+						UserID:       42,
+						UserPublicID: userPublicID,
+						Type:         "user",
+					})
+				}
+				if pc := c.GetHeader(types.HeaderProductCode); pc != "" {
+					c.Set(string(types.ContextKeyProductCode), types.Product(pc))
+				}
+				c.Next()
+			})
+
+			if tc.requireAuth {
+				engine.Use(PrincipalContext(resolver, logger))
+			} else {
+				engine.Use(OptionalPrincipalContext(resolver, logger))
+			}
+
+			var captured *principal.Principal
+			engine.GET("/", func(c *gin.Context) {
+				captured = principal.Get(c)
+				c.Status(http.StatusOK)
+			})
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodGet, "/", nil)
+			if tc.authenticated {
+				req.Header.Set(types.HeaderUserPublicID, "usr_42")
+			}
+			req.Header.Set(types.HeaderProductCode, string(types.Product("product_alpha")))
+			engine.ServeHTTP(w, req)
+
+			assert.Equal(t, http.StatusOK, w.Code)
+			assert.Equal(t, tc.expectResolverCalled, resolver.called, "resolver invocation expectation")
+
+			require.NotNil(t, captured, "Principal must be injected on every request")
+			assert.Equal(t, tc.expectAuthenticated, captured.IsAuthenticated())
+			if tc.expectAuthenticated {
+				assert.Equal(t, int64(42), captured.UserID)
+			} else {
+				assert.Equal(t, int64(0), captured.UserID)
+			}
+			assert.Equal(t, types.Product("product_alpha"), captured.ProductCode)
+			assert.Equal(t, tc.expectLevel, captured.ContentAccess.Level)
+			assert.Equal(t, tc.expectRating, captured.ContentAccess.Rating)
+			assert.Equal(t, tc.expectDecision, captured.ContentAccess.Decision)
+			assert.Equal(t, tc.expectSource, captured.ContentAccess.Source)
+			assert.Equal(t, tc.expectRuleCode, captured.ContentAccess.RuleCode)
+			assert.Equal(t, tc.expectReasonCode, captured.ContentAccess.ReasonCode)
+
+			// 验证 resolver 透传字段
+			if tc.expectResolverCalled {
+				assert.Equal(t, string(types.Product("product_alpha")), resolver.gotInput.ProductCode)
+				if tc.expectAuthenticated {
+					require.NotNil(t, resolver.gotInput.UserID)
+					assert.Equal(t, int64(42), *resolver.gotInput.UserID)
+				} else {
+					assert.Nil(t, resolver.gotInput.UserID, "anonymous request must send nil UserID")
+				}
+			}
+		})
+	}
+}
+
+// TestPrincipalContext_FromContextReadable 验证 service 层（仅 context.Context）也能读到 Principal
+func TestPrincipalContext_FromContextReadable(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	resolver := &fakeContentAccessResolver{
+		result: ContentAccessDecision{
+			EffectiveLevel: contentaccess.LevelMature,
+			ContentRating:  contentaccess.RatingMature,
+			Decision:       "allow",
+			Source:         "subscription",
+		},
+	}
+
+	engine := gin.New()
+	engine.Use(func(c *gin.Context) {
+		c.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{UserID: 7, Type: "user"})
+		c.Set(string(types.ContextKeyProductCode), types.Product("product_alpha"))
+		c.Next()
+	})
+	engine.Use(PrincipalContext(resolver, zap.NewNop()))
+
+	var fromCtx *principal.Principal
+	engine.GET("/", func(c *gin.Context) {
+		// service 层只能拿到 context.Context，应能读到同一个 Principal
+		fromCtx = principal.FromContext(c.Request.Context())
+		c.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	require.NotNil(t, fromCtx)
+	assert.Equal(t, int64(7), fromCtx.UserID)
+	assert.Equal(t, contentaccess.LevelMature, fromCtx.ContentAccess.Level)
+}
+
+// TestPrincipalContext_ForwardsGeoCountry 验证国家码进入内容访问策略输入。
+func TestPrincipalContext_ForwardsGeoCountry(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	resolver := &fakeContentAccessResolver{
+		result: ContentAccessDecision{
+			EffectiveLevel: contentaccess.LevelCompliant,
+			ContentRating:  contentaccess.RatingCompliant,
+			Decision:       "allow",
+			Source:         "policy",
+		},
+	}
+
+	engine := gin.New()
+	engine.Use(ClientContext())
+	engine.Use(func(c *gin.Context) {
+		c.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{UserID: 11, Type: "user"})
+		c.Set(string(types.ContextKeyProductCode), types.Product("product_alpha"))
+		c.Next()
+	})
+	engine.Use(PrincipalContext(resolver, zap.NewNop()))
+	engine.GET("/", func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderGeoIPCountryCode, "SG")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	require.True(t, resolver.called)
+	assert.Equal(t, "SG", resolver.gotInput.CountryCode)
+}
+
+// TestPrincipalContext_ForwardsAttributionHeader 验证广告归因进入内容访问策略输入。
+func TestPrincipalContext_ForwardsAttributionHeader(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	resolver := &fakeContentAccessResolver{
+		result: ContentAccessDecision{
+			EffectiveLevel: contentaccess.LevelMature,
+			ContentRating:  contentaccess.RatingMature,
+			Decision:       "allow",
+			Source:         "policy",
+		},
+	}
+
+	engine := gin.New()
+	engine.Use(func(c *gin.Context) {
+		c.Set(string(types.ContextKeyProductCode), types.Product("product_alpha"))
+		c.Next()
+	})
+	engine.Use(OptionalPrincipalContext(resolver, zap.NewNop()))
+	engine.GET("/", func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set(types.HeaderAttributionSource, "youtube_shorts")
+	engine.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	require.True(t, resolver.called)
+	assert.Equal(t, "youtube_shorts", resolver.gotInput.AttributionSource)
+}
+
+// TestPrincipalContext_MissingProductCodeFallsBackToDefault 验证缺少产品码时跳过 resolver
+func TestPrincipalContext_MissingProductCodeFallsBackToDefault(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	resolver := &fakeContentAccessResolver{}
+	engine := gin.New()
+	engine.Use(func(c *gin.Context) {
+		c.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{UserID: 9, Type: "user"})
+		// 不注入 ProductCode
+		c.Next()
+	})
+	engine.Use(PrincipalContext(resolver, zap.NewNop()))
+
+	var captured *principal.Principal
+	engine.GET("/", func(c *gin.Context) {
+		captured = principal.Get(c)
+		c.Status(http.StatusOK)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	engine.ServeHTTP(w, req)
+
+	require.NotNil(t, captured)
+	assert.False(t, resolver.called, "resolver must not be called without productCode")
+	assert.Equal(t, contentaccess.LevelCompliant, captured.ContentAccess.Level)
+	assert.Equal(t, "default", captured.ContentAccess.Source)
+}
+
+// TestPrincipal_MustGetPanicsWithoutMiddleware 验证 MustGet 在中间件未注册时 panic
+func TestPrincipal_MustGetPanicsWithoutMiddleware(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+
+	assert.Panics(t, func() {
+		_ = principal.MustGet(c)
+	})
+}

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

@@ -0,0 +1,100 @@
+package middleware
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/internal/common/types"
+	coreclock "{{module}}/internal/core/clock"
+	iamdomain "{{module}}/internal/integrations/onex/iam"
+	"{{module}}/pkg/apierror"
+)
+
+// ProductContext 从 X-Product-Code Header 提取产品标识并存入 context
+//
+// 宽松模式：Header 缺失时跳过（允许平台级路由不传 product code）。
+// 产品级路由应额外使用 RequireProductCode() 强制要求。
+func ProductContext(reader iamdomain.ProductAuthorizationContextReader, clock coreclock.Clock) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		code, apiErr := productCodeFromRequestHeaders(c)
+		if apiErr != nil {
+			abortWithAPIError(c, apiErr)
+			return
+		}
+		if code == "" {
+			c.Next()
+			return
+		}
+
+		resolvedAt := clock.Now().UTC()
+		snapshot, err := iamdomain.ResolveProductContextSnapshot(c.Request.Context(), reader, code, resolvedAt)
+		if err != nil {
+			abortWithAPIError(c, productContextAPIError(code, err))
+			return
+		}
+
+		c.Request = c.Request.WithContext(iamdomain.ContextWithProductContextSnapshot(c.Request.Context(), snapshot))
+		c.Set(string(types.ContextKeyProductCode), types.Product(code))
+		c.Next()
+	}
+}
+
+func productCodeFromRequestHeaders(c *gin.Context) (string, *apierror.APIError) {
+	productCode := strings.TrimSpace(c.GetHeader(types.HeaderProductCode))
+	oneXProductCode := strings.TrimSpace(c.GetHeader(types.HeaderOneXProductCode))
+	if productCode != "" && oneXProductCode != "" && productCode != oneXProductCode {
+		return "", apierror.BadRequest(
+			apierror.CodeInvalidOperation,
+			types.HeaderProductCode+" and "+types.HeaderOneXProductCode+" must match",
+		)
+	}
+	if productCode != "" {
+		return productCode, nil
+	}
+	if oneXProductCode != "" && isIAMServiceTokenAuthorizationHeader(c.GetHeader("Authorization")) {
+		return oneXProductCode, nil
+	}
+	return "", nil
+}
+
+func isIAMServiceTokenAuthorizationHeader(value string) bool {
+	return strings.HasPrefix(strings.ToLower(strings.TrimSpace(value)), "bearer iamt_")
+}
+
+// RequireProductCode 强制要求请求携带合法的 X-Product-Code Header
+//
+// 用于产品级路由（CMS、媒体等按产品隔离的模块）。
+// 前端在选中产品后自动注入此 Header，未选产品时菜单不可见。
+// 参考：AWS Console 必须选 region 才能操作资源，GCP 必须选 project。
+func RequireProductCode() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if GetProductCode(c) == "" {
+			abortWithAPIError(c, apierror.BadRequest(
+				apierror.CodeInvalidOperation,
+				"X-Product-Code header is required. Select a product first",
+			))
+			return
+		}
+		c.Next()
+	}
+}
+
+func productContextAPIError(productCode string, err error) *apierror.APIError {
+	switch {
+	case errors.Is(err, iamdomain.ErrProductContextNotFound):
+		return apierror.BadRequest(apierror.CodeInvalidOperation, "Unknown product code: "+productCode)
+	case errors.Is(err, iamdomain.ErrProductContextInvalid),
+		errors.Is(err, iamdomain.ErrProductContextUnavailable):
+		return apierror.New(
+			http.StatusServiceUnavailable,
+			apierror.TypeAPI,
+			apierror.CodeServiceUnavailable,
+			"Product context is unavailable",
+		)
+	default:
+		return apierror.Internal("Product context resolution failed")
+	}
+}

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

@@ -0,0 +1,40 @@
+package middleware
+
+import (
+	"fmt"
+	"net/http"
+	"runtime/debug"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/requestprivacy"
+	"{{module}}/pkg/apierror"
+)
+
+// Recovery 捕获 panic 并返回 500 APIError 响应
+func Recovery(logger *zap.Logger) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		defer func() {
+			if r := recover(); r != nil {
+				stack := string(debug.Stack())
+
+				logger.Error("panic recovered",
+					zap.String("panic_type", fmt.Sprintf("%T", r)),
+					zap.String("stack", stack),
+					zap.String("method", c.Request.Method),
+					zap.String("path", requestprivacy.SanitizeRequestTarget(
+						c.Request.URL,
+						requestprivacy.RouteTemplateOrUnmatched(c.FullPath()),
+						requestprivacy.RedactSensitiveQueryValues,
+					)),
+					zap.String("clientIP", c.ClientIP()),
+				)
+
+				apiErr := apierror.Internal("Internal server error")
+				c.AbortWithStatusJSON(http.StatusInternalServerError, apiErr.ToResponse())
+			}
+		}()
+		c.Next()
+	}
+}