@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/common/types/types_test.go

@@ -0,0 +1,295 @@
+package types
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestPaginationQuery_Normalize 验证 Normalize 填充默认值和边界裁剪
+func TestPaginationQuery_Normalize(t *testing.T) {
+	tests := []struct {
+		name          string
+		input         PaginationQuery
+		wantPage      int
+		wantPageSize  int
+		wantSortBy    string
+		wantSortOrder SortOrder
+	}{
+		{
+			name:          "零值应全部填充默认值",
+			input:         PaginationQuery{},
+			wantPage:      DefaultPage,
+			wantPageSize:  DefaultPageSize,
+			wantSortBy:    DefaultSortField,
+			wantSortOrder: DefaultSortOrder,
+		},
+		{
+			name:          "负数 Page 应重置为默认页码",
+			input:         PaginationQuery{PageParams: PageParams{Page: -1, PageSize: 10}},
+			wantPage:      DefaultPage,
+			wantPageSize:  10,
+			wantSortBy:    DefaultSortField,
+			wantSortOrder: DefaultSortOrder,
+		},
+		{
+			name:          "PageSize 超过 MaxPageSize 应裁剪为默认值",
+			input:         PaginationQuery{PageParams: PageParams{Page: 2, PageSize: MaxPageSize + 1}},
+			wantPage:      2,
+			wantPageSize:  DefaultPageSize,
+			wantSortBy:    DefaultSortField,
+			wantSortOrder: DefaultSortOrder,
+		},
+		{
+			name:          "PageSize 恰好等于 MaxPageSize 不应被裁剪",
+			input:         PaginationQuery{PageParams: PageParams{Page: 1, PageSize: MaxPageSize}},
+			wantPage:      1,
+			wantPageSize:  MaxPageSize,
+			wantSortBy:    DefaultSortField,
+			wantSortOrder: DefaultSortOrder,
+		},
+		{
+			name:          "PageSize 为负数应重置为默认值",
+			input:         PaginationQuery{PageParams: PageParams{Page: 1, PageSize: -5}},
+			wantPage:      1,
+			wantPageSize:  DefaultPageSize,
+			wantSortBy:    DefaultSortField,
+			wantSortOrder: DefaultSortOrder,
+		},
+		{
+			name:          "已设置的合法值不应被覆盖",
+			input:         PaginationQuery{PageParams: PageParams{Page: 3, PageSize: 50}, SortBy: "name", SortOrder: SortOrderASC},
+			wantPage:      3,
+			wantPageSize:  50,
+			wantSortBy:    "name",
+			wantSortOrder: SortOrderASC,
+		},
+		{
+			name:          "SortBy 为空应填充默认排序字段",
+			input:         PaginationQuery{PageParams: PageParams{Page: 1, PageSize: 10}, SortOrder: SortOrderASC},
+			wantPage:      1,
+			wantPageSize:  10,
+			wantSortBy:    DefaultSortField,
+			wantSortOrder: SortOrderASC,
+		},
+		{
+			name:          "SortOrder 为空应填充默认排序方向",
+			input:         PaginationQuery{PageParams: PageParams{Page: 1, PageSize: 10}, SortBy: "updated_at"},
+			wantPage:      1,
+			wantPageSize:  10,
+			wantSortBy:    "updated_at",
+			wantSortOrder: DefaultSortOrder,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			q := tc.input
+			q.Normalize()
+			assert.Equal(t, tc.wantPage, q.Page, "Page 不匹配")
+			assert.Equal(t, tc.wantPageSize, q.PageSize, "PageSize 不匹配")
+			assert.Equal(t, tc.wantSortBy, q.SortBy, "SortBy 不匹配")
+			assert.Equal(t, tc.wantSortOrder, q.SortOrder, "SortOrder 不匹配")
+		})
+	}
+}
+
+// TestPaginationQuery_Offset 验证 Offset 计算正确
+func TestPaginationQuery_Offset(t *testing.T) {
+	tests := []struct {
+		name       string
+		page       int
+		pageSize   int
+		wantOffset int
+	}{
+		{
+			name:       "第 1 页 offset 应为 0",
+			page:       1,
+			pageSize:   20,
+			wantOffset: 0,
+		},
+		{
+			name:       "第 2 页每页 20 条 offset 应为 20",
+			page:       2,
+			pageSize:   20,
+			wantOffset: 20,
+		},
+		{
+			name:       "第 3 页每页 10 条 offset 应为 20",
+			page:       3,
+			pageSize:   10,
+			wantOffset: 20,
+		},
+		{
+			name:       "第 5 页每页 100 条 offset 应为 400",
+			page:       5,
+			pageSize:   100,
+			wantOffset: 400,
+		},
+		{
+			name:       "第 1 页每页 1 条 offset 应为 0",
+			page:       1,
+			pageSize:   1,
+			wantOffset: 0,
+		},
+		{
+			name:       "第 10 页每页 1 条 offset 应为 9",
+			page:       10,
+			pageSize:   1,
+			wantOffset: 9,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			q := &PaginationQuery{PageParams: PageParams{Page: tc.page, PageSize: tc.pageSize}}
+			assert.Equal(t, tc.wantOffset, q.Offset())
+		})
+	}
+}
+
+// TestBulkPageParams_Normalize 验证大批量分页参数的默认值与边界
+func TestBulkPageParams_Normalize(t *testing.T) {
+	tests := []struct {
+		name         string
+		input        BulkPageParams
+		wantPage     int
+		wantPageSize int
+	}{
+		{
+			name:         "零值应填充默认值",
+			input:        BulkPageParams{},
+			wantPage:     DefaultPage,
+			wantPageSize: DefaultPageSize,
+		},
+		{
+			name:         "最大页大小应保留",
+			input:        BulkPageParams{Page: 2, PageSize: BulkMaxPageSize},
+			wantPage:     2,
+			wantPageSize: BulkMaxPageSize,
+		},
+		{
+			name:         "超过最大页大小应回退默认值",
+			input:        BulkPageParams{Page: 2, PageSize: BulkMaxPageSize + 1},
+			wantPage:     2,
+			wantPageSize: DefaultPageSize,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			params := tc.input
+			params.Normalize()
+			assert.Equal(t, tc.wantPage, params.Page)
+			assert.Equal(t, tc.wantPageSize, params.PageSize)
+		})
+	}
+}
+
+// TestBulkPageParams_Offset 验证大批量分页偏移计算
+func TestBulkPageParams_Offset(t *testing.T) {
+	params := BulkPageParams{Page: 3, PageSize: BulkMaxPageSize}
+	assert.Equal(t, 2000, params.Offset())
+}
+
+// TestContextKeyConstants 验证 ContextKey 常量值正确
+func TestContextKeyConstants(t *testing.T) {
+	assert.Equal(t, ContextKey("requestId"), ContextKeyRequestID)
+	assert.Equal(t, ContextKey("userIdentity"), ContextKeyUserIdentity)
+	assert.Equal(t, ContextKey("sessionId"), ContextKeySessionID)
+	assert.Equal(t, ContextKey("accessTokenJti"), ContextKeyAccessTokenJTI)
+	assert.Equal(t, ContextKey("accessTokenExpiresAt"), ContextKeyAccessTokenExpiresAt)
+	assert.Equal(t, ContextKey("productCode"), ContextKeyProductCode)
+	assert.Equal(t, ContextKey("clientContext"), ContextKeyClientContext)
+	assert.Equal(t, ContextKey("tenantId"), ContextKeyTenantID)
+	assert.Equal(t, ContextKey("tenant"), ContextKeyTenant)
+	assert.Equal(t, ContextKey("startTime"), ContextKeyStartTime)
+}
+
+// TestHeaderConstants 验证请求/内部/响应 Header 常量值正确
+func TestHeaderConstants(t *testing.T) {
+	// 外部请求 Header
+	assert.Equal(t, "X-Request-ID", HeaderRequestID)
+	assert.Equal(t, "X-Correlation-ID", HeaderCorrelationID)
+	assert.Equal(t, "X-Client-Type", HeaderClientType)
+	assert.Equal(t, "X-Client-Version", HeaderClientVersion)
+	assert.Equal(t, "X-Client-Platform", HeaderClientPlatform)
+	assert.Equal(t, "X-Device-ID", HeaderDeviceID)
+	assert.Equal(t, "X-Idempotency-Key", HeaderIdempotencyKey)
+	assert.Equal(t, "X-Checkout-Session-Token", HeaderCheckoutSessionToken)
+	assert.Equal(t, "X-Checkout-Return-State", HeaderCheckoutReturnState)
+	assert.Equal(t, "X-App-Version", HeaderAppVersion)
+	assert.Equal(t, "X-Attribution-Source", HeaderAttributionSource)
+	assert.Equal(t, "X-Internal-User-ID", HeaderInternalUserID)
+	assert.Equal(t, "X-OneX-Product-Code", HeaderOneXProductCode)
+	assert.Equal(t, "X-OneX-Application-Code", HeaderOneXApplicationCode)
+	assert.Equal(t, "X-Onex-Guest-Capability", HeaderOneXGuestCapability)
+
+	// 内部 Header（APISIX 注入）
+	assert.Equal(t, "X-User-ID", HeaderUserID)
+	assert.Equal(t, "X-User-Type", HeaderUserType)
+	assert.Equal(t, "X-Session-ID", HeaderSessionID)
+	assert.Equal(t, "X-Token-JTI", HeaderTokenJTI)
+	assert.Equal(t, "X-Token-Expires-At", HeaderTokenExpiresAt)
+	assert.Equal(t, "X-Tenant-ID", HeaderTenantID)
+	assert.Equal(t, "X-Auth-Product-Code", HeaderAuthProductCode)
+	assert.Equal(t, "X-Product-Code", HeaderProductCode)
+	assert.Equal(t, "X-Forwarded-For", HeaderXForwardedFor)
+	assert.Equal(t, "X-Real-IP", HeaderXRealIP)
+	assert.Equal(t, "X-Forwarded-Proto", HeaderXForwardedProto)
+
+	// 响应 Header
+	assert.Equal(t, "X-RateLimit-Limit", HeaderRateLimitLimit)
+	assert.Equal(t, "X-RateLimit-Remaining", HeaderRateLimitRemaining)
+	assert.Equal(t, "X-RateLimit-Reset", HeaderRateLimitReset)
+	assert.Equal(t, "Retry-After", HeaderRetryAfter)
+}
+
+// TestUserRoleConstants 验证用户角色字符串值正确
+func TestUserRoleConstants(t *testing.T) {
+	assert.Equal(t, UserRole("guest"), UserRoleGuest)
+	assert.Equal(t, UserRole("user"), UserRoleUser)
+	assert.Equal(t, UserRole("vip"), UserRoleVIP)
+	assert.Equal(t, UserRole("admin"), UserRoleAdmin)
+	assert.Equal(t, UserRole("super_admin"), UserRoleSuperAdmin)
+}
+
+func TestProductConstants(t *testing.T) {
+	assert.Equal(t, Product("platform"), ProductPlatform)
+}
+
+// TestPaginationDefaults 验证分页默认常量值正确
+func TestPaginationDefaults(t *testing.T) {
+	assert.Equal(t, 1, DefaultPage)
+	assert.Equal(t, 20, DefaultPageSize)
+	assert.Equal(t, 100, MaxPageSize)
+	assert.Equal(t, 200, AdminMaxPageSize)
+	assert.Equal(t, 1000, BulkMaxPageSize)
+	assert.Equal(t, "created_at", DefaultSortField)
+	assert.Equal(t, SortOrderDESC, DefaultSortOrder)
+}
+
+// TestLookupCurrencyMeta 验证标准货币元数据可动态解析
+func TestLookupCurrencyMeta(t *testing.T) {
+	meta, ok := LookupCurrencyMeta("cny")
+	assert.True(t, ok)
+	assert.Equal(t, "CNY", meta.Code)
+	assert.Equal(t, "CN¥", meta.Symbol)
+	assert.Equal(t, 2, meta.DecimalPlaces)
+
+	meta, ok = LookupCurrencyMeta("bhd")
+	assert.True(t, ok)
+	assert.Equal(t, "BHD", meta.Code)
+	assert.Equal(t, 3, meta.DecimalPlaces)
+
+	_, ok = LookupCurrencyMeta("XYZ")
+	assert.False(t, ok)
+}
+
+// TestIsSupportedCurrency 验证标准货币合法性判断
+func TestIsSupportedCurrency(t *testing.T) {
+	assert.True(t, IsSupportedCurrency("USD"))
+	assert.True(t, IsSupportedCurrency("jpy"))
+	assert.True(t, IsSupportedCurrency("nzd"))
+	assert.False(t, IsSupportedCurrency("XYZ"))
+}

package/dist/resources/templates/go-backend/internal/common/utils/constants.go

@@ -0,0 +1,100 @@
+package utils
+
+// ═══════════════════════════════════════════════════════════════
+// 加密相关常量
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	// Argon2idTimeCost Argon2 时间开销（迭代次数）
+	Argon2idTimeCost uint32 = 3
+	// Argon2idMemoryCost Argon2 内存开销（KB），OWASP 推荐 64 MB
+	Argon2idMemoryCost uint32 = 65536
+	// Argon2idParallelism Argon2 并行度（线程数）
+	Argon2idParallelism uint8 = 4
+	// Argon2idKeyLength Argon2 输出密钥长度（字节）
+	Argon2idKeyLength uint32 = 32
+	// Argon2idSaltLength Argon2 盐值长度（字节）
+	Argon2idSaltLength = 16
+
+	// DefaultRandomStringLength 随机字符串生成的默认长度
+	DefaultRandomStringLength = 32
+	// DefaultNumericCodeLength 数字验证码的默认长度
+	DefaultNumericCodeLength = 6
+	// NumericBase 生成随机数字的基数（0-9）
+	NumericBase = 10
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 金额计算相关常量
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	// CalculationPrecision 内部计算精度（10 位小数）
+	CalculationPrecision = 10
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 幂等性相关常量
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	// DefaultIdempotencyTTL 幂等性缓存的默认 TTL（秒），24 小时
+	DefaultIdempotencyTTL = 86400
+	// IdempotencyCachePrefix 幂等性缓存键前缀
+	IdempotencyCachePrefix = "idempotency"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 限流相关常量
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	// ThrottleKeyPrefix 限流缓存键前缀
+	ThrottleKeyPrefix = "throttle"
+)
+
+// ThrottleConfig 限流配置
+type ThrottleConfig struct {
+	// Limit 时间窗口内允许的最大请求数
+	Limit int
+	// TTL 时间窗口（秒）
+	TTL int
+}
+
+// ThrottleTierConfig 按用户类型的限流配置
+type ThrottleTierConfig struct {
+	// Guest 访客限流配置
+	Guest ThrottleConfig
+	// User 普通用户限流配置
+	User ThrottleConfig
+	// VIP VIP 用户限流配置
+	VIP ThrottleConfig
+	// Admin 管理员限流配置
+	Admin ThrottleConfig
+}
+
+// DefaultThrottleTierConfig 按用户类型的默认速率限制
+var DefaultThrottleTierConfig = ThrottleTierConfig{
+	Guest: ThrottleConfig{Limit: 30, TTL: 60},
+	User:  ThrottleConfig{Limit: 100, TTL: 60},
+	VIP:   ThrottleConfig{Limit: 300, TTL: 60},
+	Admin: ThrottleConfig{Limit: 1000, TTL: 60},
+}
+
+// 常用场景的预定义限流配置
+var (
+	// ThrottlePresetVeryStrict 非常严格：每分钟 3 次请求（密码重置、OTP）
+	ThrottlePresetVeryStrict = ThrottleConfig{Limit: 3, TTL: 60}
+	// ThrottlePresetStrict 严格：每分钟 10 次请求（登录尝试、文件上传）
+	ThrottlePresetStrict = ThrottleConfig{Limit: 10, TTL: 60}
+	// ThrottlePresetModerate 中等：每分钟 60 次请求（常规 API 端点）
+	ThrottlePresetModerate = ThrottleConfig{Limit: 60, TTL: 60}
+	// ThrottlePresetRelaxed 宽松：每分钟 200 次请求（读取密集型端点）
+	ThrottlePresetRelaxed = ThrottleConfig{Limit: 200, TTL: 60}
+	// ThrottlePresetVeryRelaxed 非常宽松：每分钟 500 次请求（静态资源）
+	ThrottlePresetVeryRelaxed = ThrottleConfig{Limit: 500, TTL: 60}
+	// ThrottlePresetHourly100 每小时限制：每小时 100 次请求（报告生成）
+	ThrottlePresetHourly100 = ThrottleConfig{Limit: 100, TTL: 3600}
+	// ThrottlePresetDaily1000 每日限制：每天 1000 次请求（API 密钥限制）
+	ThrottlePresetDaily1000 = ThrottleConfig{Limit: 1000, TTL: 86400}
+)

package/dist/resources/templates/go-backend/internal/common/utils/crypto.go

@@ -0,0 +1,158 @@
+package utils
+
+import (
+	"crypto/md5" //nolint:gosec // G501: MD5 用于内容指纹，非密码学场景
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"math/big"
+	"strings"
+
+	"github.com/google/uuid"
+	"golang.org/x/crypto/argon2"
+)
+
+// CryptoUtil 加密工具
+type CryptoUtil struct{}
+
+// HashPassword 密码哈希（使用 Argon2id，OWASP 推荐）
+func (CryptoUtil) HashPassword(password string) (string, error) {
+	salt := make([]byte, Argon2idSaltLength)
+	if _, err := rand.Read(salt); err != nil {
+		return "", fmt.Errorf("generate salt: %w", err)
+	}
+
+	hash := argon2.IDKey(
+		[]byte(password),
+		salt,
+		Argon2idTimeCost,
+		Argon2idMemoryCost,
+		Argon2idParallelism,
+		Argon2idKeyLength,
+	)
+
+	// 格式: $argon2id$v=19$m=65536,t=3,p=4$<salt>$<hash>
+	b64Salt := base64.RawStdEncoding.EncodeToString(salt)
+	b64Hash := base64.RawStdEncoding.EncodeToString(hash)
+
+	encoded := fmt.Sprintf(
+		"$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
+		argon2.Version, Argon2idMemoryCost, Argon2idTimeCost, Argon2idParallelism,
+		b64Salt, b64Hash,
+	)
+
+	return encoded, nil
+}
+
+// VerifyPassword 验证密码
+func (CryptoUtil) VerifyPassword(password, encodedHash string) (bool, error) {
+	params, salt, hash, err := decodeArgon2Hash(encodedHash)
+	if err != nil {
+		return false, err
+	}
+
+	computed := argon2.IDKey(
+		[]byte(password),
+		salt,
+		params.timeCost,
+		params.memoryCost,
+		params.parallelism,
+		params.keyLength,
+	)
+
+	return subtle.ConstantTimeCompare(hash, computed) == 1, nil
+}
+
+// GenerateRandomString 生成随机十六进制字符串
+func (CryptoUtil) GenerateRandomString(length ...int) string {
+	n := DefaultRandomStringLength
+	if len(length) > 0 && length[0] > 0 {
+		n = length[0]
+	}
+
+	// 每两个十六进制字符需要一个字节
+	byteLen := (n + 1) / 2
+	b := make([]byte, byteLen)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)[:n]
+}
+
+// GenerateNumericCode 生成随机数字验证码
+func (CryptoUtil) GenerateNumericCode(length ...int) string {
+	n := DefaultNumericCodeLength
+	if len(length) > 0 && length[0] > 0 {
+		n = length[0]
+	}
+
+	code := make([]byte, n)
+	for i := range code {
+		num, _ := rand.Int(rand.Reader, big.NewInt(int64(NumericBase)))
+		code[i] = byte('0' + num.Int64())
+	}
+	return string(code)
+}
+
+// MD5 计算 MD5 哈希
+func (CryptoUtil) MD5(text string) string {
+	h := md5.Sum([]byte(text)) //nolint:gosec // G401: MD5 用于内容指纹，非密码学场景
+	return hex.EncodeToString(h[:])
+}
+
+// SHA256 计算 SHA256 哈希
+func (CryptoUtil) SHA256(text string) string {
+	h := sha256.Sum256([]byte(text))
+	return hex.EncodeToString(h[:])
+}
+
+// UUID 生成 UUID v4
+func (CryptoUtil) UUID() string {
+	return uuid.New().String()
+}
+
+// Crypto 全局 CryptoUtil 实例
+var Crypto CryptoUtil
+
+// argon2Params 内部参数结构体
+type argon2Params struct {
+	memoryCost  uint32
+	timeCost    uint32
+	parallelism uint8
+	keyLength   uint32
+}
+
+// decodeArgon2Hash 解析 Argon2 编码格式的哈希
+func decodeArgon2Hash(encoded string) (*argon2Params, []byte, []byte, error) {
+	parts := strings.Split(encoded, "$")
+	if len(parts) != 6 {
+		return nil, nil, nil, fmt.Errorf("invalid argon2 hash format")
+	}
+
+	var version int
+	if _, err := fmt.Sscanf(parts[2], "v=%d", &version); err != nil {
+		return nil, nil, nil, fmt.Errorf("parse version: %w", err)
+	}
+	if version != argon2.Version {
+		return nil, nil, nil, fmt.Errorf("incompatible argon2 version: %d", version)
+	}
+
+	p := &argon2Params{}
+	if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &p.memoryCost, &p.timeCost, &p.parallelism); err != nil {
+		return nil, nil, nil, fmt.Errorf("parse params: %w", err)
+	}
+
+	salt, err := base64.RawStdEncoding.DecodeString(parts[4])
+	if err != nil {
+		return nil, nil, nil, fmt.Errorf("decode salt: %w", err)
+	}
+
+	hash, err := base64.RawStdEncoding.DecodeString(parts[5])
+	if err != nil {
+		return nil, nil, nil, fmt.Errorf("decode hash: %w", err)
+	}
+	p.keyLength = uint32(len(hash)) //nolint:gosec // G115: hash 长度由 argon2 输出决定，不会溢出
+
+	return p, salt, hash, nil
+}