@stackonward/cli 0.0.1 → 1.0.1

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

@@ -0,0 +1,107 @@
+package utils
+
+import "strings"
+
+// 本文件统一管理跨模块的 pointer 辅助函数。
+//
+// 命名风格对齐 Stripe Go SDK / AWS SDK v1：
+//   - StringPtr / Int64Ptr / BoolPtr / Float64Ptr：值 → 指针
+//   - StringValue：指针 → 值（nil 安全）
+//
+// 业务专用变体：
+//   - StringPtrIfNotBlank：strings.TrimSpace 后空字符串归一为 nil
+//   - Int64PtrIfPositive：value <= 0 归一为 nil（ID/外键场景）
+//   - CloneStringPtr：nil 安全克隆 + TrimSpace 归一
+
+// EqualPtr 比较两个可比较类型指针的空值与底层值。
+func EqualPtr[T comparable](left, right *T) bool {
+	if left == nil || right == nil {
+		return left == nil && right == nil
+	}
+	return *left == *right
+}
+
+// StringPtr 返回字符串值的指针副本（无条件）。
+// 等价于 Stripe Go SDK 的 stripe.String。
+func StringPtr(s string) *string { return &s }
+
+// StringValue 解引用 *string，nil 时返回空字符串。
+// 等价于 Stripe Go SDK 的 stripe.StringValue。
+func StringValue(p *string) string {
+	if p == nil {
+		return ""
+	}
+	return *p
+}
+
+// StringValueTrimmed 解引用 *string 并 TrimSpace；nil 时返回空字符串。
+//
+// 业务变体：当上游可能带空白填充（CSV 导入、PHP 序列化字符串等）时使用，
+// 避免视觉空白与 NULL 语义混淆。
+func StringValueTrimmed(p *string) string {
+	if p == nil {
+		return ""
+	}
+	return strings.TrimSpace(*p)
+}
+
+// Int64Ptr 返回 int64 值的指针副本（无条件）。
+// 等价于 Stripe Go SDK 的 stripe.Int64。
+func Int64Ptr(i int64) *int64 { return &i }
+
+// Int64Value 解引用 *int64，nil 时返回 0。
+// 等价于 Stripe Go SDK 的 stripe.Int64Value。
+//
+// 用于把可空 ID（PaymentID / RefundID 等）安全转成 int64 字面量参与日志 /
+// 事件 payload — 0 在这些场景表示"未关联"。
+func Int64Value(p *int64) int64 {
+	if p == nil {
+		return 0
+	}
+	return *p
+}
+
+// BoolPtr 返回 bool 值的指针副本（无条件）。
+// 等价于 Stripe Go SDK 的 stripe.Bool。
+func BoolPtr(b bool) *bool { return &b }
+
+// Float64Ptr 返回 float64 值的指针副本（无条件）。
+func Float64Ptr(f float64) *float64 { return &f }
+
+// StringPtrIfNotBlank 在 strings.TrimSpace 后非空才返回指针，否则返回 nil。
+//
+// 用于把可空业务字段（电话、备注、外部 ID）写入 nullable 列时，避免空字符串
+// 与 NULL 的语义混用。各模块此前自行复制 strPtrOrNil / stringPtrIfNotBlank /
+// stringPtr 等变体，统一收敛到本函数。
+func StringPtrIfNotBlank(s string) *string {
+	trimmed := strings.TrimSpace(s)
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}
+
+// Int64PtrIfPositive 仅当 value > 0 时返回指针，否则返回 nil。
+//
+// 用于可空外键 / 可选 ID 场景：0 与负数都视为“未设置”，写入 nullable 列时归一为 NULL。
+func Int64PtrIfPositive(value int64) *int64 {
+	if value <= 0 {
+		return nil
+	}
+	return &value
+}
+
+// CloneStringPtr 克隆 *string，并对内容做 TrimSpace；空值归一为 nil。
+//
+// 用于在 DTO → entity 映射时复制调用方传入的可空字符串：避免共享底层
+// 字符串地址，同时把视觉空字符串（"   "）归一为 nil。
+func CloneStringPtr(value *string) *string {
+	if value == nil {
+		return nil
+	}
+	trimmed := strings.TrimSpace(*value)
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}

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

@@ -0,0 +1,15 @@
+package utils
+
+import "testing"
+
+func TestEqualPtr(t *testing.T) {
+	t.Parallel()
+
+	one := int64(1)
+	otherOne := int64(1)
+	two := int64(2)
+	if !EqualPtr[int64](nil, nil) || EqualPtr(nil, &one) || EqualPtr(&one, nil) ||
+		!EqualPtr(&one, &otherOne) || EqualPtr(&one, &two) {
+		t.Fatal("EqualPtr() pointer equality contract failed")
+	}
+}

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

@@ -0,0 +1,24 @@
+package utils
+
+import "strings"
+
+// ContainsFold 判断字符串切片中是否存在与 target 经 TrimSpace + 大小写不敏感比对相等的元素。
+//
+// 与 Go 1.21+ stdlib `slices.Contains` 的差异：
+//   - stdlib `slices.Contains` 仅做 == 精确匹配；本函数对两侧都执行 TrimSpace + ToLower。
+//   - target 经规范化后为空字符串时直接返回 false（避免空查询误命中含空白字符的元素）。
+//
+// 适用场景：dispute reason code / country code / attribution source 等业务上需要
+// 大小写不敏感且容忍前后空白的字符串匹配。case-sensitive 直接使用 stdlib slices.Contains。
+func ContainsFold(values []string, target string) bool {
+	needle := strings.ToLower(strings.TrimSpace(target))
+	if needle == "" {
+		return false
+	}
+	for i := range values {
+		if strings.ToLower(strings.TrimSpace(values[i])) == needle {
+			return true
+		}
+	}
+	return false
+}

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

@@ -0,0 +1,110 @@
+package utils
+
+import (
+	"fmt"
+	"strconv"
+	"sync"
+	"time"
+)
+
+// 雪花算法常量
+const (
+	snowflakeEpoch    = int64(1704067200000) // 2024-01-01 00:00:00 UTC
+	workerIDBits      = 5
+	datacenterIDBits  = 5
+	sequenceBits      = 12
+	maxWorkerID       = (1 << workerIDBits) - 1
+	maxDatacenterID   = (1 << datacenterIDBits) - 1
+	maxSequence       = (1 << sequenceBits) - 1
+	workerIDShift     = sequenceBits
+	datacenterIDShift = sequenceBits + workerIDBits
+	timestampShift    = sequenceBits + workerIDBits + datacenterIDBits
+)
+
+// SnowflakeUtil 雪花算法 ID 生成器
+// 64 位结构: 1 位符号位 + 41 位时间戳 + 10 位机器 ID + 12 位序列号
+type SnowflakeUtil struct {
+	mu            sync.Mutex
+	workerID      int64
+	datacenterID  int64
+	sequence      int64
+	lastTimestamp int64
+}
+
+// NewSnowflakeUtil 创建雪花算法 ID 生成器
+func NewSnowflakeUtil(workerID, datacenterID int) (*SnowflakeUtil, error) {
+	if workerID < 0 || workerID > maxWorkerID {
+		return nil, fmt.Errorf("worker ID must be between 0 and %d", maxWorkerID)
+	}
+	if datacenterID < 0 || datacenterID > maxDatacenterID {
+		return nil, fmt.Errorf("datacenter ID must be between 0 and %d", maxDatacenterID)
+	}
+
+	return &SnowflakeUtil{
+		workerID:      int64(workerID),
+		datacenterID:  int64(datacenterID),
+		sequence:      0,
+		lastTimestamp: -1,
+	}, nil
+}
+
+// NextID 生成下一个 ID
+func (s *SnowflakeUtil) NextID() (int64, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	timestamp := s.currentTimestamp()
+
+	if timestamp < s.lastTimestamp {
+		return 0, fmt.Errorf("clock moved backwards")
+	}
+
+	if timestamp == s.lastTimestamp {
+		s.sequence = (s.sequence + 1) & maxSequence
+		if s.sequence == 0 {
+			timestamp = s.waitNextMillis(s.lastTimestamp)
+		}
+	} else {
+		s.sequence = 0
+	}
+
+	s.lastTimestamp = timestamp
+
+	id := ((timestamp - snowflakeEpoch) << timestampShift) |
+		(s.datacenterID << datacenterIDShift) |
+		(s.workerID << workerIDShift) |
+		s.sequence
+
+	return id, nil
+}
+
+// NextIDString 生成字符串格式的 ID
+func (s *SnowflakeUtil) NextIDString() (string, error) {
+	id, err := s.NextID()
+	if err != nil {
+		return "", err
+	}
+	return strconv.FormatInt(id, 10), nil
+}
+
+// currentTimestamp 获取当前时间戳（毫秒）
+func (s *SnowflakeUtil) currentTimestamp() int64 {
+	return time.Now().UnixMilli()
+}
+
+// waitNextMillis 等待下一毫秒
+func (s *SnowflakeUtil) waitNextMillis(lastTimestamp int64) int64 {
+	timestamp := s.currentTimestamp()
+	for timestamp <= lastTimestamp {
+		timestamp = s.currentTimestamp()
+	}
+	return timestamp
+}
+
+// DefaultSnowflake 默认雪花算法实例（workerID=1, datacenterID=1）
+var DefaultSnowflake *SnowflakeUtil
+
+func init() {
+	// 默认实例初始化不会失败，因为参数在合法范围内
+	DefaultSnowflake, _ = NewSnowflakeUtil(1, 1)
+}

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

@@ -0,0 +1,316 @@
+package utils
+
+import (
+	"strconv"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ── 构造函数验证 ───────────────────────────────────────────────────────────────
+
+func TestNewSnowflakeUtil_ValidParams(t *testing.T) {
+	// 合法参数范围内应成功创建实例
+	cases := []struct {
+		name         string
+		workerID     int
+		datacenterID int
+	}{
+		{name: "最小值", workerID: 0, datacenterID: 0},
+		{name: "最大值", workerID: maxWorkerID, datacenterID: maxDatacenterID},
+		{name: "中间值", workerID: 1, datacenterID: 1},
+		{name: "workerID=31", workerID: 31, datacenterID: 0},
+		{name: "datacenterID=31", workerID: 0, datacenterID: 31},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			s, err := NewSnowflakeUtil(tc.workerID, tc.datacenterID)
+			require.NoError(t, err)
+			assert.NotNil(t, s)
+		})
+	}
+}
+
+func TestNewSnowflakeUtil_InvalidWorkerID(t *testing.T) {
+	// workerID 超出范围应返回 error
+	cases := []struct {
+		name     string
+		workerID int
+	}{
+		{name: "负数", workerID: -1},
+		{name: "超过最大值", workerID: maxWorkerID + 1},
+		{name: "极大值", workerID: 9999},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			s, err := NewSnowflakeUtil(tc.workerID, 0)
+			assert.Error(t, err)
+			assert.Nil(t, s)
+		})
+	}
+}
+
+func TestNewSnowflakeUtil_InvalidDatacenterID(t *testing.T) {
+	// datacenterID 超出范围应返回 error
+	cases := []struct {
+		name         string
+		datacenterID int
+	}{
+		{name: "负数", datacenterID: -1},
+		{name: "超过最大值", datacenterID: maxDatacenterID + 1},
+		{name: "极大值", datacenterID: 9999},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			s, err := NewSnowflakeUtil(0, tc.datacenterID)
+			assert.Error(t, err)
+			assert.Nil(t, s)
+		})
+	}
+}
+
+// ── NextID ────────────────────────────────────────────────────────────────────
+
+func TestNextID_ReturnsPositiveInt64(t *testing.T) {
+	// 生成的 ID 必须是正整数
+	s, err := NewSnowflakeUtil(1, 1)
+	require.NoError(t, err)
+
+	id, err := s.NextID()
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0), "ID 必须为正整数")
+}
+
+func TestNextID_SequentialIDsAreIncreasing(t *testing.T) {
+	// 顺序生成的 ID 应严格递增（雪花算法保证单机单调性）
+	s, err := NewSnowflakeUtil(1, 1)
+	require.NoError(t, err)
+
+	const count = 100
+	prev, err := s.NextID()
+	require.NoError(t, err)
+
+	for i := 1; i < count; i++ {
+		curr, err := s.NextID()
+		require.NoError(t, err)
+		assert.Greater(t, curr, prev, "第 %d 个 ID 应大于第 %d 个", i+1, i)
+		prev = curr
+	}
+}
+
+func TestNextID_10000UniqueSequentialIDs(t *testing.T) {
+	// 顺序生成 10,000 个 ID，所有 ID 应唯一
+	s, err := NewSnowflakeUtil(1, 1)
+	require.NoError(t, err)
+
+	const count = 10_000
+	seen := make(map[int64]struct{}, count)
+
+	for i := 0; i < count; i++ {
+		id, err := s.NextID()
+		require.NoError(t, err)
+		_, duplicate := seen[id]
+		assert.False(t, duplicate, "第 %d 次生成的 ID %d 已存在（重复）", i+1, id)
+		seen[id] = struct{}{}
+	}
+
+	assert.Equal(t, count, len(seen))
+}
+
+// ── NextIDString ──────────────────────────────────────────────────────────────
+
+func TestNextIDString_ReturnsNonEmptyString(t *testing.T) {
+	// 字符串格式的 ID 不应为空
+	s, err := NewSnowflakeUtil(1, 1)
+	require.NoError(t, err)
+
+	idStr, err := s.NextIDString()
+	require.NoError(t, err)
+	assert.NotEmpty(t, idStr)
+}
+
+func TestNextIDString_MatchesNextID(t *testing.T) {
+	// NextIDString 的数值应与 NextID 的值一致（通过独立实例各生成一个来验证格式）
+	s, err := NewSnowflakeUtil(2, 2)
+	require.NoError(t, err)
+
+	idStr, err := s.NextIDString()
+	require.NoError(t, err)
+
+	// 验证字符串可解析为有效的正整数
+	parsed, parseErr := strconv.ParseInt(idStr, 10, 64)
+	require.NoError(t, parseErr, "IDString 应为有效整数字符串，实际值: %s", idStr)
+	assert.Greater(t, parsed, int64(0))
+}
+
+func TestNextIDString_ParsableAsInt64(t *testing.T) {
+	// 多次生成，每次均可解析为正 int64
+	s, err := NewSnowflakeUtil(1, 1)
+	require.NoError(t, err)
+
+	for i := 0; i < 50; i++ {
+		idStr, err := s.NextIDString()
+		require.NoError(t, err)
+
+		parsed, parseErr := strconv.ParseInt(idStr, 10, 64)
+		require.NoError(t, parseErr)
+		assert.Greater(t, parsed, int64(0))
+	}
+}
+
+// ── 并发安全 ──────────────────────────────────────────────────────────────────
+
+func TestNextID_ConcurrentUniqueness(t *testing.T) {
+	// 50 个 goroutine 各生成 200 个 ID，总计 10,000 个，所有 ID 应唯一
+	const goroutines = 50
+	const idsPerGoroutine = 200
+	const total = goroutines * idsPerGoroutine
+
+	s, err := NewSnowflakeUtil(1, 1)
+	require.NoError(t, err)
+
+	results := make(chan int64, total)
+	var wg sync.WaitGroup
+
+	for g := 0; g < goroutines; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < idsPerGoroutine; i++ {
+				id, err := s.NextID()
+				if err != nil {
+					// 极端情况下时钟回拨，记录为 0 触发后续重复检测失败
+					results <- 0
+					return
+				}
+				results <- id
+			}
+		}()
+	}
+
+	wg.Wait()
+	close(results)
+
+	seen := make(map[int64]struct{}, total)
+	for id := range results {
+		require.NotEqual(t, int64(0), id, "生成 ID 时发生错误（时钟回拨或其他问题）")
+		_, duplicate := seen[id]
+		assert.False(t, duplicate, "并发生成时出现重复 ID: %d", id)
+		seen[id] = struct{}{}
+	}
+
+	assert.Equal(t, total, len(seen), "并发生成的所有 ID 应唯一")
+}
+
+func TestNextIDString_ConcurrentUniqueness(t *testing.T) {
+	// 并发验证 NextIDString 的唯一性
+	const goroutines = 20
+	const idsPerGoroutine = 100
+	const total = goroutines * idsPerGoroutine
+
+	s, err := NewSnowflakeUtil(3, 3)
+	require.NoError(t, err)
+
+	results := make(chan string, total)
+	var wg sync.WaitGroup
+
+	for g := 0; g < goroutines; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < idsPerGoroutine; i++ {
+				idStr, err := s.NextIDString()
+				if err != nil {
+					results <- ""
+					return
+				}
+				results <- idStr
+			}
+		}()
+	}
+
+	wg.Wait()
+	close(results)
+
+	seen := make(map[string]struct{}, total)
+	for idStr := range results {
+		require.NotEmpty(t, idStr, "并发生成时出现空字符串 ID")
+		_, duplicate := seen[idStr]
+		assert.False(t, duplicate, "并发生成时出现重复 ID 字符串: %s", idStr)
+		seen[idStr] = struct{}{}
+	}
+
+	assert.Equal(t, total, len(seen))
+}
+
+// ── 不同机器 ID 的 ID 区分性 ─────────────────────────────────────────────────
+
+func TestNextID_DifferentWorkerIDsProduceDifferentIDs(t *testing.T) {
+	// 不同 workerID 的实例在同一时刻生成的 ID 应不同
+	s1, err1 := NewSnowflakeUtil(0, 0)
+	s2, err2 := NewSnowflakeUtil(1, 0)
+	require.NoError(t, err1)
+	require.NoError(t, err2)
+
+	seen := make(map[int64]struct{})
+	const count = 100
+
+	for i := 0; i < count; i++ {
+		id1, err := s1.NextID()
+		require.NoError(t, err)
+		id2, err := s2.NextID()
+		require.NoError(t, err)
+
+		seen[id1] = struct{}{}
+		seen[id2] = struct{}{}
+	}
+
+	// 两个实例各生成 count 个，总共 2*count 个应全部唯一
+	assert.Equal(t, 2*count, len(seen))
+}
+
+// ── DefaultSnowflake ──────────────────────────────────────────────────────────
+
+func TestDefaultSnowflake_IsInitialized(t *testing.T) {
+	// 全局默认实例应已初始化（非 nil）
+	assert.NotNil(t, DefaultSnowflake)
+}
+
+func TestDefaultSnowflake_CanGenerateID(t *testing.T) {
+	// 全局默认实例应可正常生成 ID
+	id, err := DefaultSnowflake.NextID()
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+}
+
+func TestDefaultSnowflake_CanGenerateIDString(t *testing.T) {
+	// 全局默认实例应可正常生成字符串格式 ID
+	idStr, err := DefaultSnowflake.NextIDString()
+	require.NoError(t, err)
+	assert.NotEmpty(t, idStr)
+
+	parsed, err := strconv.ParseInt(idStr, 10, 64)
+	require.NoError(t, err)
+	assert.Greater(t, parsed, int64(0))
+}
+
+func TestDefaultSnowflake_UniqueIDs(t *testing.T) {
+	// 默认实例连续生成 1000 个 ID，应全部唯一
+	const count = 1000
+	seen := make(map[int64]struct{}, count)
+
+	for i := 0; i < count; i++ {
+		id, err := DefaultSnowflake.NextID()
+		require.NoError(t, err)
+		_, duplicate := seen[id]
+		assert.False(t, duplicate, "DefaultSnowflake 出现重复 ID: %d", id)
+		seen[id] = struct{}{}
+	}
+
+	assert.Equal(t, count, len(seen))
+}

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

@@ -0,0 +1,16 @@
+package utils
+
+import "strings"
+
+// FirstNonEmptyString 返回首个 TrimSpace 后非空的字符串；全部为空时返回空字符串。
+//
+// 用于在多个候选字段中选取首个有效值（API 网关响应、迁移工具读取多源 ID 等场景）。
+// 各模块此前自行复制 firstNonEmptyString，统一收敛到 utils 以避免 R8 违规。
+func FirstNonEmptyString(values ...string) string {
+	for _, value := range values {
+		if trimmed := strings.TrimSpace(value); trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}

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

@@ -0,0 +1,42 @@
+package utils
+
+import "time"
+
+// RFC3339Milli OneX 平台统一的时间序列化格式（RFC3339 毫秒精度，带时区偏移）。
+//
+// 对应 Stripe / GitHub / AWS API 普遍采用的 ISO 8601 毫秒输出形态，
+// 例如 "2026-04-29T08:30:15.123Z" 或 "2026-04-29T16:30:15.123+08:00"。
+// 各 vo / vo_admin 文件历史上分别命名为 timeFormatRFC3339Milli / iso8601Milli，
+// 现统一收敛到本常量。
+const RFC3339Milli = "2006-01-02T15:04:05.000Z07:00"
+
+// FormatTimeRFC3339MilliUTC 先归一化到 UTC，再按 RFC3339Milli 格式化。
+//
+// 适用场景：跨产品 / 跨地域 admin VO 输出时，强制统一为 UTC（带 'Z' 后缀），
+// 避免不同部署节点本地时区影响 API 响应。
+func FormatTimeRFC3339MilliUTC(t time.Time) string {
+	return t.UTC().Format(RFC3339Milli)
+}
+
+// FormatTimePtr 把 *time.Time 格式化为 *string，nil 透传 nil，保留输入时区。
+//
+// 适用场景：上层调用方已把时间归一化到目标时区（典型为 UTC），
+// 此处只做最终字符串化。如需 UTC 归一化，使用 FormatTimePtrUTC。
+func FormatTimePtr(t *time.Time) *string {
+	if t == nil {
+		return nil
+	}
+	s := t.Format(RFC3339Milli)
+	return &s
+}
+
+// FormatTimePtrUTC 把 *time.Time 归一化到 UTC 后格式化为 *string，nil 透传 nil。
+//
+// 与 FormatTimeRFC3339MilliUTC 配套。Admin VO 推荐使用此变体。
+func FormatTimePtrUTC(t *time.Time) *string {
+	if t == nil {
+		return nil
+	}
+	s := t.UTC().Format(RFC3339Milli)
+	return &s
+}