@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/cache/singleflight_test.go

@@ -0,0 +1,211 @@
+package cache
+
+import (
+	"errors"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSingleflight_OnlyOneCallExecutes(t *testing.T) {
+	var g singleflightGroup
+	var callCount atomic.Int64
+
+	const goroutines = 20
+	var wg sync.WaitGroup
+	results := make([]any, goroutines)
+	errs := make([]error, goroutines)
+
+	wg.Add(goroutines)
+	// 用 ready channel 确保所有 goroutine 尽量同时发起调用
+	ready := make(chan struct{})
+
+	for i := 0; i < goroutines; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			<-ready
+			val, err, _ := g.do("same-key", func() (any, error) {
+				callCount.Add(1)
+				time.Sleep(20 * time.Millisecond) // 模拟慢操作
+				return "result", nil
+			})
+			results[i] = val
+			errs[i] = err
+		}()
+	}
+
+	close(ready)
+	wg.Wait()
+
+	// 只应执行一次真实调用
+	assert.Equal(t, int64(1), callCount.Load(), "loader 应只执行一次")
+
+	// 所有 goroutine 都应获得正确结果
+	for i, res := range results {
+		require.NoError(t, errs[i])
+		assert.Equal(t, "result", res)
+	}
+}
+
+func TestSingleflight_SharedReturnValue(t *testing.T) {
+	var g singleflightGroup
+
+	const goroutines = 10
+	var wg sync.WaitGroup
+	sharedFlags := make([]bool, goroutines)
+
+	ready := make(chan struct{})
+	wg.Add(goroutines)
+
+	for i := 0; i < goroutines; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			<-ready
+			_, _, shared := g.do("shared-key", func() (any, error) {
+				time.Sleep(30 * time.Millisecond)
+				return "v", nil
+			})
+			sharedFlags[i] = shared
+		}()
+	}
+
+	close(ready)
+	wg.Wait()
+
+	// 第一个完成的 goroutine shared=false（自己执行），其余 shared=true
+	// 因为并发启动时机不同，至少应有一个 shared=true（有其他 goroutine 共享了结果）
+	sharedCount := 0
+	for _, s := range sharedFlags {
+		if s {
+			sharedCount++
+		}
+	}
+	assert.Greater(t, sharedCount, 0, "至少有一个 goroutine 应共享结果（shared=true）")
+}
+
+func TestSingleflight_DifferentKeysExecuteIndependently(t *testing.T) {
+	var g singleflightGroup
+	var callCountA, callCountB atomic.Int64
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+
+	go func() {
+		defer wg.Done()
+		g.do("key-a", func() (any, error) {
+			callCountA.Add(1)
+			return "a", nil
+		})
+	}()
+
+	go func() {
+		defer wg.Done()
+		g.do("key-b", func() (any, error) {
+			callCountB.Add(1)
+			return "b", nil
+		})
+	}()
+
+	wg.Wait()
+
+	assert.Equal(t, int64(1), callCountA.Load(), "key-a loader 应执行一次")
+	assert.Equal(t, int64(1), callCountB.Load(), "key-b loader 应执行一次")
+}
+
+func TestSingleflight_ErrorPropagation(t *testing.T) {
+	var g singleflightGroup
+	expectedErr := errors.New("loader error")
+
+	const goroutines = 10
+	var wg sync.WaitGroup
+	errs := make([]error, goroutines)
+
+	ready := make(chan struct{})
+	wg.Add(goroutines)
+
+	for i := 0; i < goroutines; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			<-ready
+			_, err, _ := g.do("error-key", func() (any, error) {
+				time.Sleep(20 * time.Millisecond)
+				return nil, expectedErr
+			})
+			errs[i] = err
+		}()
+	}
+
+	close(ready)
+	wg.Wait()
+
+	// 所有等待者都应收到相同的错误
+	for i, err := range errs {
+		assert.ErrorIs(t, err, expectedErr, "goroutine %d 应收到 loader 错误", i)
+	}
+}
+
+func TestSingleflight_SequentialCallsEachExecute(t *testing.T) {
+	var g singleflightGroup
+	var callCount atomic.Int64
+
+	// 顺序调用（前一次完成后再发起）：每次都应执行
+	for i := 0; i < 3; i++ {
+		g.do("seq-key", func() (any, error) {
+			callCount.Add(1)
+			return "v", nil
+		})
+	}
+
+	assert.Equal(t, int64(3), callCount.Load(), "顺序调用每次都应独立执行")
+}
+
+func TestSingleflight_ReturnValueCorrect(t *testing.T) {
+	var g singleflightGroup
+
+	val, err, shared := g.do("single", func() (any, error) {
+		return 42, nil
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, 42, val)
+	// 单个调用（无并发等待者）shared 应为 false
+	assert.False(t, shared, "单次调用无共享者，shared 应为 false")
+}
+
+func TestSingleflight_NilResultPropagated(t *testing.T) {
+	var g singleflightGroup
+
+	const goroutines = 5
+	var wg sync.WaitGroup
+	results := make([]any, goroutines)
+
+	ready := make(chan struct{})
+	wg.Add(goroutines)
+
+	for i := 0; i < goroutines; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			<-ready
+			val, _, _ := g.do("nil-key", func() (any, error) {
+				time.Sleep(10 * time.Millisecond)
+				return nil, nil //nolint:nilnil // 测试 nil 值传播场景
+			})
+			results[i] = val
+		}()
+	}
+
+	close(ready)
+	wg.Wait()
+
+	for i, res := range results {
+		assert.Nil(t, res, "goroutine %d 应收到 nil 结果", i)
+	}
+}

package/dist/resources/templates/go-backend/internal/core/cache/warming.go

@@ -0,0 +1,86 @@
+package cache
+
+import (
+	"context"
+
+	"go.uber.org/zap"
+)
+
+// WarmEntry 缓存预热条目
+type WarmEntry struct {
+	Key    string
+	Loader func(ctx context.Context) (any, error)
+}
+
+// Warmer 缓存预热接口
+//
+// 各模块实现此接口，在应用启动时注册预热数据。
+type Warmer interface {
+	// WarmUp 返回需要预热的缓存条目列表
+	WarmUp(ctx context.Context) ([]WarmEntry, error)
+	// Namespace 返回此预热器所属的命名空间配置
+	Namespace() *NamespaceConfig
+	// Name 返回预热器名称（用于日志和指标）
+	Name() string
+}
+
+// WarmupRegistry 预热注册表
+type WarmupRegistry struct {
+	warmers []Warmer
+	logger  *zap.Logger
+}
+
+// NewWarmupRegistry 创建预热注册表
+func NewWarmupRegistry(logger *zap.Logger) *WarmupRegistry {
+	return &WarmupRegistry{
+		logger: logger.Named("WarmupRegistry"),
+	}
+}
+
+// Register 注册一个缓存预热器
+func (r *WarmupRegistry) Register(warmer Warmer) {
+	r.warmers = append(r.warmers, warmer)
+}
+
+// RunAll 执行所有已注册的预热器
+func (r *WarmupRegistry) RunAll(ctx context.Context, mgr *Manager) error {
+	if len(r.warmers) == 0 {
+		r.logger.Debug("no cache warmers registered")
+		return nil
+	}
+
+	r.logger.Info("starting cache warmup", zap.Int("warmerCount", len(r.warmers)))
+
+	for _, w := range r.warmers {
+		entries, err := w.WarmUp(ctx)
+		if err != nil {
+			r.logger.Error("warmer failed to produce entries",
+				zap.String("warmer", w.Name()), zap.Error(err))
+			continue
+		}
+
+		ns := w.Namespace()
+		var successCount, failCount int
+
+		for _, entry := range entries {
+			if err := mgr.Get(ctx, ns, entry.Key, new(any), entry.Loader); err != nil {
+				failCount++
+				r.logger.Warn("warmup entry failed",
+					zap.String("warmer", w.Name()),
+					zap.String("key", entry.Key),
+					zap.Error(err))
+			} else {
+				successCount++
+			}
+		}
+
+		r.logger.Info("warmer completed",
+			zap.String("warmer", w.Name()),
+			zap.Int("success", successCount),
+			zap.Int("failed", failCount),
+			zap.Int("total", len(entries)),
+		)
+	}
+
+	return nil
+}

package/dist/resources/templates/go-backend/internal/core/clock/clock.go

@@ -0,0 +1,66 @@
+package clock
+
+import (
+	"sync"
+	"time"
+)
+
+// Clock 提供统一当前时间读取接口。
+//
+// 设计原因：
+//   - 业务层只依赖“当前时间”能力，不直接耦合系统时钟；
+//   - 生产环境使用系统时钟，测试和模拟场景可注入可推进时钟；
+//   - 统一入口后，续费、冷静期、清理任务都能用同一套时间控制模型。
+type Clock interface {
+	Now() time.Time
+}
+
+// systemClock 使用系统当前时间。
+type systemClock struct{}
+
+// NewSystemClock 创建系统时钟实现。
+func NewSystemClock() Clock {
+	return systemClock{}
+}
+
+// Now 返回系统当前时间。
+func (systemClock) Now() time.Time {
+	return time.Now()
+}
+
+// ManualClock 提供可手动推进的时钟实现。
+//
+// 设计原因：
+//   - 测试需要在不等待真实时间流逝的情况下推进订阅、冷静期和保留期；
+//   - 模拟场景必须保证读取一致性，因此需要带锁的可变时钟。
+type ManualClock struct {
+	mu  sync.RWMutex
+	now time.Time
+}
+
+// NewManualClock 创建手动时钟。
+func NewManualClock(now time.Time) *ManualClock {
+	return &ManualClock{now: now}
+}
+
+// Now 返回当前冻结时间。
+func (c *ManualClock) Now() time.Time {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.now
+}
+
+// Set 直接设置当前时间。
+func (c *ManualClock) Set(now time.Time) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.now = now
+}
+
+// Advance 按指定时长推进当前时间。
+func (c *ManualClock) Advance(delta time.Duration) time.Time {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.now = c.now.Add(delta)
+	return c.now
+}

package/dist/resources/templates/go-backend/internal/core/clock/clock_test.go

@@ -0,0 +1,26 @@
+package clock_test
+
+import (
+	"testing"
+	"time"
+
+	"{{module}}/internal/core/clock"
+)
+
+func TestManualClockAdvance(t *testing.T) {
+	base := time.Date(2026, 4, 15, 10, 0, 0, 0, time.UTC)
+	manual := clock.NewManualClock(base)
+
+	if got := manual.Now(); !got.Equal(base) {
+		t.Fatalf("Now() = %v, want %v", got, base)
+	}
+
+	target := manual.Advance(90 * time.Minute)
+	want := base.Add(90 * time.Minute)
+	if !target.Equal(want) {
+		t.Fatalf("Advance() = %v, want %v", target, want)
+	}
+	if got := manual.Now(); !got.Equal(want) {
+		t.Fatalf("Now() after advance = %v, want %v", got, want)
+	}
+}

package/dist/resources/templates/go-backend/internal/core/clock/runtime_clock.go

@@ -0,0 +1,283 @@
+package clock
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"{{module}}/internal/common/utils"
+	"{{module}}/internal/core/config"
+)
+
+const (
+	runtimeClockScopePlatform = "platform"
+	defaultCacheTTL           = time.Second
+)
+
+// RuntimeMode 运行时时钟模式。
+type RuntimeMode string
+
+const (
+	// RuntimeModeRealtime 使用系统实时时钟。
+	RuntimeModeRealtime RuntimeMode = "realtime"
+	// RuntimeModeFrozen 使用后台推进的冻结时钟。
+	RuntimeModeFrozen RuntimeMode = "frozen"
+)
+
+// RuntimeClockState 运行时时钟控制状态。
+type RuntimeClockState struct {
+	ID        int64       `gorm:"column:id;primaryKey;autoIncrement"`
+	CreatedAt time.Time   `gorm:"column:created_at;autoCreateTime:milli"`
+	UpdatedAt time.Time   `gorm:"column:updated_at;autoUpdateTime:milli"`
+	Scope     string      `gorm:"column:scope;type:varchar(50);not null;uniqueIndex:uk_runtime_clock_scope"`
+	Mode      RuntimeMode `gorm:"column:mode;type:varchar(20);not null;default:'realtime'"`
+	FrozenAt  *time.Time  `gorm:"column:frozen_at;type:timestamptz(3)"`
+	Reason    *string     `gorm:"column:reason;type:varchar(500)"`
+	UpdatedBy *int64      `gorm:"column:updated_by;type:bigint"`
+}
+
+// TableName 指定运行时时钟控制表名。
+func (RuntimeClockState) TableName() string {
+	return "sys_runtime_clock_controls"
+}
+
+// RuntimeClock 提供进程级统一时间读取和后台控制能力。
+//
+// 设计原因：
+//   - 业务时间推进必须有持久化真值，不能依赖单进程内存变量；
+//   - 非生产环境需要像 Stripe Test Clock 一样冻结并推进平台逻辑时间；
+//   - 多个 API / Worker 进程通过短 TTL 刷新同一份 DB 状态，保证最终一致。
+type RuntimeClock struct {
+	logger   *zap.Logger
+	db       *gorm.DB
+	env      string
+	cacheTTL time.Duration
+
+	mu       sync.RWMutex
+	cached   *RuntimeClockState
+	cachedAt time.Time
+}
+
+// NewRuntimeClock 创建运行时可控时钟。
+func NewRuntimeClock(logger *zap.Logger, db *gorm.DB, cfg *config.Config) *RuntimeClock {
+	return &RuntimeClock{
+		logger:   logger.Named("RuntimeClock"),
+		db:       db,
+		env:      cfg.App.Env,
+		cacheTTL: defaultCacheTTL,
+	}
+}
+
+// Now 返回当前有效时间。
+func (c *RuntimeClock) Now() time.Time {
+	now := time.Now().UTC()
+	if !c.IsControllable() {
+		return now
+	}
+
+	state, err := c.getState(context.Background(), now)
+	if err != nil {
+		c.logger.Warn("failed to load runtime clock state, falling back to realtime", zap.Error(err))
+		return now
+	}
+	if state.Mode == RuntimeModeFrozen && state.FrozenAt != nil {
+		return state.FrozenAt.UTC()
+	}
+	return now
+}
+
+// IsControllable 返回当前环境是否允许后台控制时钟。
+func (c *RuntimeClock) IsControllable() bool {
+	return c.env != "production"
+}
+
+// Environment 返回当前应用环境。
+func (c *RuntimeClock) Environment() string {
+	return c.env
+}
+
+// GetState 读取当前运行时时钟状态。
+func (c *RuntimeClock) GetState(ctx context.Context) (*RuntimeClockState, error) {
+	state, err := c.getState(ctx, time.Now().UTC())
+	if err != nil {
+		return nil, err
+	}
+	return cloneRuntimeClockState(state), nil
+}
+
+// Freeze 冻结到指定时间。
+func (c *RuntimeClock) Freeze(ctx context.Context, frozenAt time.Time, reason string, updatedBy *int64) (*RuntimeClockState, error) {
+	if err := c.ensureControllable(); err != nil {
+		return nil, err
+	}
+
+	state := &RuntimeClockState{
+		Scope:     runtimeClockScopePlatform,
+		Mode:      RuntimeModeFrozen,
+		FrozenAt:  timePtr(frozenAt.UTC()),
+		Reason:    utils.StringPtrIfNotBlank(reason),
+		UpdatedBy: cloneInt64Ptr(updatedBy),
+	}
+	if err := c.saveState(ctx, state); err != nil {
+		return nil, err
+	}
+	return cloneRuntimeClockState(state), nil
+}
+
+// Advance 按指定时长推进冻结时钟。
+func (c *RuntimeClock) Advance(ctx context.Context, delta time.Duration, reason string, updatedBy *int64) (*RuntimeClockState, error) {
+	if err := c.ensureControllable(); err != nil {
+		return nil, err
+	}
+	if delta <= 0 {
+		return nil, fmt.Errorf("advance duration must be greater than zero")
+	}
+
+	current, err := c.GetState(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if current.Mode != RuntimeModeFrozen || current.FrozenAt == nil {
+		return nil, fmt.Errorf("runtime clock is not frozen")
+	}
+
+	next := current.FrozenAt.Add(delta).UTC()
+	return c.Freeze(ctx, next, reason, updatedBy)
+}
+
+// Reset 切回系统实时时钟。
+func (c *RuntimeClock) Reset(ctx context.Context, reason string, updatedBy *int64) (*RuntimeClockState, error) {
+	if err := c.ensureControllable(); err != nil {
+		return nil, err
+	}
+
+	state := &RuntimeClockState{
+		Scope:     runtimeClockScopePlatform,
+		Mode:      RuntimeModeRealtime,
+		FrozenAt:  nil,
+		Reason:    utils.StringPtrIfNotBlank(reason),
+		UpdatedBy: cloneInt64Ptr(updatedBy),
+	}
+	if err := c.saveState(ctx, state); err != nil {
+		return nil, err
+	}
+	return cloneRuntimeClockState(state), nil
+}
+
+func (c *RuntimeClock) ensureControllable() error {
+	if c.IsControllable() {
+		return nil
+	}
+	return fmt.Errorf("runtime clock control is disabled in production")
+}
+
+func (c *RuntimeClock) getState(ctx context.Context, now time.Time) (*RuntimeClockState, error) {
+	c.mu.RLock()
+	if c.cached != nil && now.Sub(c.cachedAt) < c.cacheTTL {
+		state := cloneRuntimeClockState(c.cached)
+		c.mu.RUnlock()
+		return state, nil
+	}
+	c.mu.RUnlock()
+
+	var state RuntimeClockState
+	err := c.db.WithContext(ctx).
+		Where("scope = ?", runtimeClockScopePlatform).
+		Take(&state).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			state = RuntimeClockState{
+				Scope: runtimeClockScopePlatform,
+				Mode:  RuntimeModeRealtime,
+			}
+		} else {
+			return nil, fmt.Errorf("load runtime clock state: %w", err)
+		}
+	}
+
+	c.mu.Lock()
+	c.cached = cloneRuntimeClockState(&state)
+	c.cachedAt = now
+	c.mu.Unlock()
+
+	return cloneRuntimeClockState(&state), nil
+}
+
+func (c *RuntimeClock) saveState(ctx context.Context, state *RuntimeClockState) error {
+	if err := c.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns: []clause.Column{{Name: "scope"}},
+			DoUpdates: clause.Assignments(map[string]any{
+				"mode":       state.Mode,
+				"frozen_at":  state.FrozenAt,
+				"reason":     state.Reason,
+				"updated_by": state.UpdatedBy,
+				"updated_at": gorm.Expr("CURRENT_TIMESTAMP"),
+			}),
+		}).
+		Create(state).Error; err != nil {
+		return fmt.Errorf("save runtime clock state: %w", err)
+	}
+
+	c.mu.Lock()
+	c.cached = nil
+	c.cachedAt = time.Time{}
+	c.mu.Unlock()
+
+	fresh, err := c.GetState(ctx)
+	if err != nil {
+		return err
+	}
+
+	c.mu.Lock()
+	c.cached = cloneRuntimeClockState(fresh)
+	c.cachedAt = time.Now().UTC()
+	c.mu.Unlock()
+	return nil
+}
+
+func cloneRuntimeClockState(state *RuntimeClockState) *RuntimeClockState {
+	if state == nil {
+		return nil
+	}
+	cloned := *state
+	if state.FrozenAt != nil {
+		value := state.FrozenAt.UTC()
+		cloned.FrozenAt = &value
+	}
+	cloned.Reason = cloneStringPtr(state.Reason)
+	cloned.UpdatedBy = cloneInt64Ptr(state.UpdatedBy)
+	return &cloned
+}
+
+// cloneStringPtr 与 cloneInt64Ptr 是 runtime clock state 专用的零拷贝指针克隆。
+//
+// 与 utils.CloneStringPtr 的差异：本地版本**不做** TrimSpace，因为
+// runtime clock 的 Reason 字段需要逐字保留运维输入（包括前后空白），用于
+// 重放故障时的精确语义比对。utils.CloneStringPtr 的 trim 语义会破坏审计语义。
+func cloneStringPtr(value *string) *string {
+	if value == nil {
+		return nil
+	}
+	cloned := *value
+	return &cloned
+}
+
+func cloneInt64Ptr(value *int64) *int64 {
+	if value == nil {
+		return nil
+	}
+	cloned := *value
+	return &cloned
+}
+
+func timePtr(value time.Time) *time.Time {
+	cloned := value.UTC()
+	return &cloned
+}