@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,310 @@
+package middleware
+
+import (
+	"context"
+	"fmt"
+	"math/rand" //nolint:gosec // G404: 用于限流键随机字符串，不需要密码学安全
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/utils"
+	"{{module}}/pkg/apierror"
+)
+
+// RateLimitResult 滑动窗口限流结果
+type RateLimitResult struct {
+	// Allowed 是否允许请求
+	Allowed bool
+	// Remaining 剩余请求次数
+	Remaining int
+	// ResetTime 重置时间（毫秒）
+	ResetTime int64
+	// Total 窗口内总请求数
+	Total int
+}
+
+// ThrottleKeyFunc 自定义限流键生成函数
+type ThrottleKeyFunc func(c *gin.Context) string
+
+// ThrottleOptions 限流中间件选项
+type ThrottleOptions struct {
+	// TierConfig 按用户类型的限流配置，nil 时使用默认值
+	TierConfig *utils.ThrottleTierConfig
+	// Logger Zap 日志实例
+	Logger *zap.Logger
+}
+
+// Throttle 基于 Redis 的分布式限流中间件（滑动窗口算法）
+func Throttle(rdb *redis.Client, opts ThrottleOptions) gin.HandlerFunc {
+	tierConfig := utils.DefaultThrottleTierConfig
+	if opts.TierConfig != nil {
+		tierConfig = *opts.TierConfig
+	}
+	logger := opts.Logger
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	return func(c *gin.Context) {
+		// 检查是否跳过限流
+		if skip, exists := c.Get(throttleSkipKey); exists {
+			if b, ok := skip.(bool); ok && b {
+				c.Next()
+				return
+			}
+		}
+
+		// Redis 不可用时放行
+		if rdb == nil {
+			c.Next()
+			return
+		}
+
+		// 获取限流配置
+		config := getThrottleConfig(c, tierConfig)
+
+		// 生成限流键
+		key := generateThrottleKey(c)
+
+		// 使用滑动窗口算法检查限流
+		ctx := context.Background()
+		result, err := checkRateLimit(ctx, rdb, key, config)
+		if err != nil {
+			logger.Warn("rate limit check failed, allowing request", zap.Error(err))
+			c.Next()
+			return
+		}
+
+		// 设置限流响应头
+		setRateLimitHeaders(c, result, config)
+
+		if !result.Allowed {
+			apiErr := apierror.TooManyRequests()
+			WriteAPIError(c, apiErr)
+			c.Abort()
+			return
+		}
+
+		c.Next()
+	}
+}
+
+// ThrottleWithConfig 为特定路由配置限流参数的中间件
+func ThrottleWithConfig(rdb *redis.Client, config utils.ThrottleConfig, logger *zap.Logger) gin.HandlerFunc {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	return func(c *gin.Context) {
+		if rdb == nil {
+			c.Next()
+			return
+		}
+
+		key := generateThrottleKey(c)
+
+		ctx := context.Background()
+		result, err := checkRateLimit(ctx, rdb, key, config)
+		if err != nil {
+			logger.Warn("rate limit check failed, allowing request", zap.Error(err))
+			c.Next()
+			return
+		}
+
+		setRateLimitHeaders(c, result, config)
+
+		if !result.Allowed {
+			apiErr := apierror.TooManyRequests()
+			WriteAPIError(c, apiErr)
+			c.Abort()
+			return
+		}
+
+		c.Next()
+	}
+}
+
+// SkipThrottle 标记当前请求跳过限流
+func SkipThrottle() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Set(throttleSkipKey, true)
+		c.Next()
+	}
+}
+
+// SetThrottleConfig 设置路由级别的限流配置（在路由注册时使用）
+func SetThrottleConfig(config utils.ThrottleConfig) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Set(throttleConfigKey, config)
+		c.Next()
+	}
+}
+
+// SetThrottleKeyFunc 设置自定义限流键生成函数
+func SetThrottleKeyFunc(fn ThrottleKeyFunc) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Set(throttleKeyFuncKey, fn)
+		c.Next()
+	}
+}
+
+// 内部上下文键
+const (
+	throttleSkipKey    = "__skipThrottle"
+	throttleConfigKey  = "__throttleConfig"
+	throttleKeyFuncKey = "__throttleKeyFunc"
+)
+
+// getThrottleConfig 获取当前请求的限流配置
+// 优先级：路由配置 > 用户类型默认值
+func getThrottleConfig(c *gin.Context, tierConfig utils.ThrottleTierConfig) utils.ThrottleConfig {
+	if v, exists := c.Get(throttleConfigKey); exists {
+		if cfg, ok := v.(utils.ThrottleConfig); ok {
+			return cfg
+		}
+	}
+
+	userType := getUserType(c)
+	switch userType {
+	case "admin", "super_admin":
+		return tierConfig.Admin
+	case "vip":
+		return tierConfig.VIP
+	case "user":
+		return tierConfig.User
+	default:
+		return tierConfig.Guest
+	}
+}
+
+// getUserType 确定用于限流层级的用户类型
+func getUserType(c *gin.Context) string {
+	identity := GetUserIdentity(c)
+	if identity == nil {
+		return "guest"
+	}
+
+	t := strings.ToLower(identity.Type)
+	switch t {
+	case "admin", "super_admin":
+		return t
+	case "vip":
+		return "vip"
+	case "user":
+		return "user"
+	default:
+		return "user"
+	}
+}
+
+// generateThrottleKey 生成限流的唯一键
+func generateThrottleKey(c *gin.Context) string {
+	if fn, exists := c.Get(throttleKeyFuncKey); exists {
+		if keyFunc, ok := fn.(ThrottleKeyFunc); ok {
+			return fmt.Sprintf("%s:%s", utils.ThrottleKeyPrefix, keyFunc(c))
+		}
+	}
+
+	// 获取标识符（用户 ID 或 IP 地址）
+	identifier := c.ClientIP()
+	identity := GetUserIdentity(c)
+	if identity != nil && identity.UserID.Valid() {
+		identifier = strconv.FormatInt(identity.UserID.Int64(), 10)
+	}
+
+	// 获取路由标识
+	route := getRouteIdentifier(c)
+
+	return fmt.Sprintf("%s:%s:%s", utils.ThrottleKeyPrefix, identifier, route)
+}
+
+// getRouteIdentifier 获取唯一的路由标识符
+func getRouteIdentifier(c *gin.Context) string {
+	method := strings.ToUpper(c.Request.Method)
+	path := c.FullPath()
+	if path == "" {
+		path = strings.SplitN(c.Request.URL.Path, "?", 2)[0]
+	}
+	return fmt.Sprintf("%s:%s", method, path)
+}
+
+// checkRateLimit 使用 Redis 实现滑动窗口限流算法
+//
+// 滑动窗口算法：
+// 1. 使用有序集合存储请求时间戳
+// 2. 移除过期条目（窗口外的）
+// 3. 统计剩余条目数量
+// 4. 如果未超限则添加新请求
+func checkRateLimit(ctx context.Context, rdb *redis.Client, key string, config utils.ThrottleConfig) (*RateLimitResult, error) {
+	now := time.Now().UnixMilli()
+	windowStart := now - int64(config.TTL)*1000
+
+	member := fmt.Sprintf("%d-%s", now, throttleRandomString(9))
+
+	pipe := rdb.TxPipeline()
+	pipe.ZRemRangeByScore(ctx, key, "0", strconv.FormatInt(windowStart, 10))
+	countCmd := pipe.ZCard(ctx, key)
+	pipe.ZAdd(ctx, key, redis.Z{Score: float64(now), Member: member})
+	pipe.PExpire(ctx, key, time.Duration(config.TTL)*time.Second)
+
+	_, err := pipe.Exec(ctx)
+	if err != nil {
+		return &RateLimitResult{
+			Allowed:   true,
+			Remaining: config.Limit,
+			ResetTime: int64(config.TTL) * 1000,
+		}, err
+	}
+
+	currentCount := int(countCmd.Val())
+	allowed := currentCount < config.Limit
+	remaining := config.Limit - currentCount - 1
+	if remaining < 0 {
+		remaining = 0
+	}
+
+	resetTime := int64(config.TTL) * 1000
+
+	if !allowed {
+		rdb.ZRem(ctx, key, member)
+		remaining = 0
+	}
+
+	total := currentCount
+	if allowed {
+		total++
+	}
+
+	return &RateLimitResult{
+		Allowed:   allowed,
+		Remaining: remaining,
+		ResetTime: resetTime,
+		Total:     total,
+	}, nil
+}
+
+// setRateLimitHeaders 在响应中设置标准限流头
+func setRateLimitHeaders(c *gin.Context, result *RateLimitResult, config utils.ThrottleConfig) {
+	c.Header("X-RateLimit-Limit", strconv.Itoa(config.Limit))
+	c.Header("X-RateLimit-Remaining", strconv.Itoa(result.Remaining))
+	c.Header("X-RateLimit-Reset", strconv.FormatInt(result.ResetTime/1000, 10))
+
+	if !result.Allowed {
+		c.Header("Retry-After", strconv.FormatInt(result.ResetTime/1000, 10))
+	}
+}
+
+// throttleRandomString 生成随机字符串（用于限流键唯一成员）
+func throttleRandomString(n int) string {
+	const letters = "abcdefghijklmnopqrstuvwxyz0123456789"
+	b := make([]byte, n)
+	for i := range b {
+		b[i] = letters[rand.Intn(len(letters))] //nolint:gosec // G404: 用于限流键随机字符串，不需要密码学安全
+	}
+	return string(b)
+}

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

@@ -0,0 +1,23 @@
+package middleware
+
+import (
+	"net"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/internal/common/types"
+)
+
+// ResolveTrustedClientIP 返回经 Gin trusted proxy 规则解析后的客户端 IP。
+func ResolveTrustedClientIP(c *gin.Context) string {
+	if c == nil {
+		return ""
+	}
+	resolvedIP := c.ClientIP()
+	canonicalIP := net.ParseIP(strings.TrimSpace(c.GetHeader(types.HeaderXRealIP)))
+	if canonicalIP == nil || resolvedIP == c.RemoteIP() {
+		return resolvedIP
+	}
+	return canonicalIP.String()
+}

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

@@ -0,0 +1,60 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+
+	"{{module}}/internal/common/types"
+)
+
+func TestClientContextUsesCanonicalRealIPFromTrustedProxy(t *testing.T) {
+	t.Parallel()
+
+	engine := gin.New()
+	require.NoError(t, engine.SetTrustedProxies([]string{"192.0.2.0/24"}))
+	engine.Use(ClientContext())
+	engine.GET("/", func(ctx *gin.Context) {
+		clientContext := GetClientContext(ctx)
+		require.NotNil(t, clientContext)
+		require.Equal(t, "203.0.113.42", clientContext.IP)
+		ctx.Status(http.StatusNoContent)
+	})
+
+	recorder := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodGet, "/", nil)
+	request.RemoteAddr = "192.0.2.10:43120"
+	request.Header.Set("X-Forwarded-For", "198.51.100.77")
+	request.Header.Set(types.HeaderXRealIP, "203.0.113.42")
+
+	engine.ServeHTTP(recorder, request)
+
+	require.Equal(t, http.StatusNoContent, recorder.Code)
+}
+
+func TestClientContextRejectsCanonicalRealIPFromUntrustedPeer(t *testing.T) {
+	t.Parallel()
+
+	engine := gin.New()
+	require.NoError(t, engine.SetTrustedProxies([]string{"10.0.0.0/8"}))
+	engine.Use(ClientContext())
+	engine.GET("/", func(ctx *gin.Context) {
+		clientContext := GetClientContext(ctx)
+		require.NotNil(t, clientContext)
+		require.Equal(t, "192.0.2.10", clientContext.IP)
+		ctx.Status(http.StatusNoContent)
+	})
+
+	recorder := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodGet, "/", nil)
+	request.RemoteAddr = "192.0.2.10:43120"
+	request.Header.Set("X-Forwarded-For", "198.51.100.77")
+	request.Header.Set(types.HeaderXRealIP, "203.0.113.42")
+
+	engine.ServeHTTP(recorder, request)
+
+	require.Equal(t, http.StatusNoContent, recorder.Code)
+}

package/dist/resources/templates/go-backend/internal/common/money/currency.go

@@ -0,0 +1,25 @@
+package money
+
+import (
+	"{{module}}/internal/common/types"
+)
+
+// DecimalPlaces 返回指定货币的小数位数（ISO 4217 标准）。
+//
+// 标准注册表中的货币按真实精度返回；未知货币兜底 2 位（兼容
+// 历史 fallback 行为，仅用于非严格展示路径）。需要严格货币校验
+// 的入口应在调用前通过 types.IsSupportedCurrency 拦截。
+//
+// Example:
+//
+//	DecimalPlaces("USD") // 2
+//	DecimalPlaces("JPY") // 0
+//	DecimalPlaces("BHD") // 3
+//	DecimalPlaces("XYZ") // 2 (fallback)
+func DecimalPlaces(currencyCode string) int {
+	meta, ok := types.LookupCurrencyMeta(currencyCode)
+	if ok {
+		return meta.DecimalPlaces
+	}
+	return 2
+}

package/dist/resources/templates/go-backend/internal/common/money/errors.go

@@ -0,0 +1,23 @@
+// Package money 提供精确小数金额格式化与跨网关单位转换。
+//
+// 错误哨兵集中在本文件，调用方使用 errors.Is 判别。
+package money
+
+import "errors"
+
+// ErrInvalidAmount 金额字符串无法解析为有效十进制数。
+//
+// 触发场景：
+//   - decimal 字符串包含非数字字符（如 "abc"）
+//   - 多个小数点（如 "1.2.3"）
+//   - 整数部分非法（如 "abc.00"）
+//   - 网关编码场景下小数位数超出货币精度（如 USD "9.999"）
+var ErrInvalidAmount = errors.New("money: invalid amount")
+
+// ErrEmptyAmount 严格版接口在 amount 为空字符串时返回此错误。
+//
+// 兜底版函数（OrZero 系列）遇到空字符串会按货币精度返回零值，不抛错。
+var ErrEmptyAmount = errors.New("money: empty amount")
+
+// ErrInvalidDivisor 金额整数除法的除数不是正整数。
+var ErrInvalidDivisor = errors.New("money: invalid divisor")

package/dist/resources/templates/go-backend/internal/common/money/format.go

@@ -0,0 +1,123 @@
+package money
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/shopspring/decimal"
+
+	"{{module}}/internal/common/types"
+)
+
+// strictDecimalRe 严格十进制字符串正则：可选负号 + 整数部分 + 可选小数部分。
+//
+// 必须前置校验，否则 big.Rat.SetString 会接受 "1e2" / "5e9999" / "0x10" / "1/2" / "+5"
+// 等多种非财务格式（"5e9999" 会展开为 >9999 位 big.Int，构成 CPU/内存 DoS 向量）。
+// 本正则与 Stripe API、Shopify GraphQL Money scalar、Java BigDecimal(String) 拒绝
+// 上述格式的口径一致，仅接受 /^-?\d+(?:\.\d+)?$/。
+var strictDecimalRe = regexp.MustCompile(`^-?\d+(?:\.\d+)?$`)
+
+// FormatMajor 严格版：按货币精度格式化十进制字符串金额。
+//
+// fail-loud 错误传递（D5 合规）：
+//   - amount 为空 → ErrEmptyAmount
+//   - amount 非法十进制字符串 → ErrInvalidAmount
+//
+// currencyCode 未知货币使用 2 位精度兜底（保留 catalog 等无 currency 场景的兼容性）。
+// 舍入采用 banker's rounding (HALF_EVEN) —— 财务展示行业标准（Stripe Dashboard /
+// AWS Billing / Java BigDecimal HALF_EVEN）。
+//
+// Example:
+//
+//	FormatMajor("9.9900", "USD") // ("9.99", nil)
+//	FormatMajor("",       "USD") // ("",     ErrEmptyAmount)
+//	FormatMajor("abc",    "USD") // ("",     ErrInvalidAmount)
+func FormatMajor(amount, currencyCode string) (string, error) {
+	dp := DecimalPlaces(currencyCode)
+	if amount == "" {
+		return "", ErrEmptyAmount
+	}
+	if !strictDecimalRe.MatchString(amount) {
+		return "", fmt.Errorf("%w: %q", ErrInvalidAmount, amount)
+	}
+	value, err := decimal.NewFromString(amount)
+	if err != nil {
+		return "", fmt.Errorf("%w: %q", ErrInvalidAmount, amount)
+	}
+	return formatDecimalBankerRounding(value, dp), nil
+}
+
+// FormatMajorOrZero 兜底版：按货币精度格式化十进制字符串金额，解析失败返回零值。
+//
+// 与 FormatMajor 的差异：
+//   - 空字符串 → 按货币精度的零（USD → "0.00"，JPY → "0"）
+//   - 非法字符串 → 同上零值（fail-closed，避免 raw decimal 泄漏到前端）
+//
+// 命名后缀 OrZero 显式承诺"接受 fallback"，与 D5（forbid silent skip）的语义意图一致：
+// 调用方主动选择兜底行为，不再是函数内偷偷吞错。
+//
+// 设计权衡（INDUSTRY-5 信号缺失的取舍）：
+//   - 不接受 *zap.Logger 参数：utils/money 是基础包，引入 logger 依赖会反向污染依赖图
+//     （core/logger 依赖 utils 风险）；同时 VO 层调用频次极高，每次落日志会刷屏。
+//   - 不返回 (string, bool)：调用方多达数十处 VO ToXxxResponse，全部双返回会让 VO
+//     转换函数变冗长，违反"VO 仅做格式化"的边界。
+//   - 仍是 fail-closed silent fallback —— 唯一不变量：上游 service 必须保证写入
+//     合法 decimal（model.go decimal(19,4) 列约束 + Recalculate fail-loud 保证）。
+//     若仍出现非法值传入本函数，说明数据已被绕过 ORM 直接写入 — 那是 DB 完整性
+//     bug，不是 VO 责任。
+//   - 如需 strict 错误信号，调用方应改用 FormatMajor（严格版，返回 error）。
+//
+// 仅展示层使用：上游 service 必须保证传入合法 decimal，否则零值会污染响应。
+func FormatMajorOrZero(amount, currencyCode string) string {
+	dp := DecimalPlaces(currencyCode)
+	if amount == "" {
+		return zeroWithDecimals(dp)
+	}
+	// 严格正则前置：避免 big.Rat.SetString 展开 "5e9999" 等指数 payload 触发 CPU/内存 DoS。
+	if !strictDecimalRe.MatchString(amount) {
+		return zeroWithDecimals(dp)
+	}
+	value, err := decimal.NewFromString(amount)
+	if err != nil {
+		return zeroWithDecimals(dp)
+	}
+	return formatDecimalBankerRounding(value, dp)
+}
+
+// FormatMajorWithCurrencySymbolOrZero 按 ISO 4217 精度格式化金额，并附加货币显示符号。
+func FormatMajorWithCurrencySymbolOrZero(amount, currencyCode string) string {
+	formatted := FormatMajorOrZero(amount, currencyCode)
+	normalizedCurrency := strings.ToUpper(strings.TrimSpace(currencyCode))
+	if normalizedCurrency == "" {
+		return formatted
+	}
+	symbol := normalizedCurrency
+	if meta, ok := types.LookupCurrencyMeta(normalizedCurrency); ok {
+		symbol = meta.Symbol
+	}
+	return symbol + formatted
+}
+
+// FormatMajorPtrOrZero 兜底版（nil-safe 单字段）：金额为 *string，货币为定值。
+//
+// nil 透传 nil；非 nil 调用 FormatMajorOrZero（解析失败按零值兜底）。
+func FormatMajorPtrOrZero(amount *string, currencyCode string) *string {
+	if amount == nil {
+		return nil
+	}
+	formatted := FormatMajorOrZero(*amount, currencyCode)
+	return &formatted
+}
+
+// FormatMajorPtrsOrZero 兜底版（nil-safe 双字段）：金额与货币均为 *string。
+//
+// 任一为 nil 透传 nil；两者都非 nil 时调用 FormatMajorOrZero。
+// 用于折扣等可空货币 + 可空金额场景（百分比折扣无 currency 时透传 nil）。
+func FormatMajorPtrsOrZero(amount, currencyCode *string) *string {
+	if amount == nil || currencyCode == nil {
+		return nil
+	}
+	formatted := FormatMajorOrZero(*amount, *currencyCode)
+	return &formatted
+}