@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/jwtkeyring/registry.go

@@ -0,0 +1,60 @@
+package jwtkeyring
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+)
+
+// Registry 合并多个签名域的公开密钥，并保证 kid 全局唯一。
+type Registry struct {
+	mu         sync.RWMutex
+	keys       map[string]JSONWebKey
+	namespaces map[string]struct{}
+}
+
+// NewRegistry 创建空的公钥注册表。
+func NewRegistry() *Registry {
+	return &Registry{keys: make(map[string]JSONWebKey), namespaces: make(map[string]struct{})}
+}
+
+// Register 注册一个签名域的公钥集合。
+func (r *Registry) Register(namespace string, ring *KeyRing) error {
+	if r == nil || ring == nil || strings.TrimSpace(namespace) == "" {
+		return fmt.Errorf("JWKS registry registration is invalid")
+	}
+	namespace = strings.TrimSpace(namespace)
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if _, duplicate := r.namespaces[namespace]; duplicate {
+		return fmt.Errorf("JWKS namespace %q is already registered", namespace)
+	}
+	keys := ring.JSONWebKeySet().Keys
+	for _, key := range keys {
+		if _, duplicate := r.keys[key.KeyID]; duplicate {
+			return fmt.Errorf("JWKS key id %q is duplicated across signing domains", key.KeyID)
+		}
+	}
+	for _, key := range keys {
+		r.keys[key.KeyID] = key
+	}
+	r.namespaces[namespace] = struct{}{}
+	return nil
+}
+
+// JSONWebKeySet 返回所有签名域稳定排序后的统一 JWKS。
+func (r *Registry) JSONWebKeySet() JSONWebKeySet {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	keyIDs := make([]string, 0, len(r.keys))
+	for keyID := range r.keys {
+		keyIDs = append(keyIDs, keyID)
+	}
+	sort.Strings(keyIDs)
+	result := JSONWebKeySet{Keys: make([]JSONWebKey, 0, len(keyIDs))}
+	for _, keyID := range keyIDs {
+		result.Keys = append(result.Keys, r.keys[keyID])
+	}
+	return result
+}

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

@@ -0,0 +1,53 @@
+package logger
+
+import (
+	"fmt"
+
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+
+	"{{module}}/internal/core/config"
+)
+
+// New 创建 Zap Logger
+func New(cfg *config.LogConfig) (*zap.Logger, error) {
+	var zapCfg zap.Config
+
+	if cfg.Env == "production" {
+		zapCfg = zap.NewProductionConfig()
+	} else {
+		zapCfg = zap.NewDevelopmentConfig()
+		zapCfg.EncoderConfig.EncodeLevel = zapcore.CapitalColorLevelEncoder
+	}
+
+	zapCfg.Level = zap.NewAtomicLevelAt(parseLevel(cfg.Level))
+	zapCfg.EncoderConfig.TimeKey = "timestamp"
+	zapCfg.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
+
+	logger, err := zapCfg.Build(
+		zap.AddCallerSkip(0),
+		zap.AddStacktrace(zap.ErrorLevel),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("build logger: %w", err)
+	}
+
+	return logger, nil
+}
+
+func parseLevel(level string) zapcore.Level {
+	switch level {
+	case "debug":
+		return zap.DebugLevel
+	case "info":
+		return zap.InfoLevel
+	case "warn":
+		return zap.WarnLevel
+	case "error":
+		return zap.ErrorLevel
+	case "fatal":
+		return zap.FatalLevel
+	default:
+		return zap.InfoLevel
+	}
+}

package/dist/resources/templates/go-backend/internal/core/logger/logger_test.go

@@ -0,0 +1,194 @@
+package logger_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"go.uber.org/zap/zaptest/observer"
+
+	"{{module}}/internal/core/config"
+	"{{module}}/internal/core/logger"
+)
+
+// newObservedLogger 构建一个可观测日志记录的 zap.Logger（用于验证日志输出）
+func newObservedLogger(level zapcore.Level) (*zap.Logger, *observer.ObservedLogs) {
+	core, logs := observer.New(level)
+	return zap.New(core), logs
+}
+
+func TestNew_DevelopmentConfig(t *testing.T) {
+	cfg := &config.LogConfig{
+		Level: "debug",
+		Env:   "development",
+	}
+
+	log, err := logger.New(cfg)
+
+	require.NoError(t, err)
+	assert.NotNil(t, log)
+}
+
+func TestNew_ProductionConfig(t *testing.T) {
+	cfg := &config.LogConfig{
+		Level: "info",
+		Env:   "production",
+	}
+
+	log, err := logger.New(cfg)
+
+	require.NoError(t, err)
+	assert.NotNil(t, log)
+}
+
+func TestNew_AllLogLevels(t *testing.T) {
+	levels := []string{"debug", "info", "warn", "error", "fatal", "unknown"}
+
+	for _, lvl := range levels {
+		t.Run("level="+lvl, func(t *testing.T) {
+			cfg := &config.LogConfig{
+				Level: lvl,
+				Env:   "development",
+			}
+
+			log, err := logger.New(cfg)
+
+			require.NoError(t, err)
+			assert.NotNil(t, log, "logger must be non-nil for level %q", lvl)
+		})
+	}
+}
+
+func TestLogger_WriteWithoutPanic(t *testing.T) {
+	cfg := &config.LogConfig{
+		Level: "debug",
+		Env:   "development",
+	}
+
+	log, err := logger.New(cfg)
+	require.NoError(t, err)
+	require.NotNil(t, log)
+
+	// 确保每种日志方法不会 panic
+	assert.NotPanics(t, func() {
+		log.Debug("debug message", zap.String("key", "value"))
+	})
+	assert.NotPanics(t, func() {
+		log.Info("info message", zap.Int("count", 42))
+	})
+	assert.NotPanics(t, func() {
+		log.Warn("warn message", zap.Bool("flag", true))
+	})
+	assert.NotPanics(t, func() {
+		log.Error("error message", zap.String("reason", "test"))
+	})
+}
+
+func TestLogger_ProductionWriteWithoutPanic(t *testing.T) {
+	cfg := &config.LogConfig{
+		Level: "info",
+		Env:   "production",
+	}
+
+	log, err := logger.New(cfg)
+	require.NoError(t, err)
+	require.NotNil(t, log)
+
+	assert.NotPanics(t, func() {
+		log.Info("production info message")
+	})
+	assert.NotPanics(t, func() {
+		log.Warn("production warn message")
+	})
+	assert.NotPanics(t, func() {
+		log.Error("production error message")
+	})
+}
+
+func TestLogger_LevelFiltering(t *testing.T) {
+	// 使用 zaptest/observer 验证日志级别过滤
+	t.Run("warn level filters out debug and info", func(t *testing.T) {
+		core, logs := observer.New(zapcore.WarnLevel)
+		log := zap.New(core)
+
+		log.Debug("debug should be filtered")
+		log.Info("info should be filtered")
+		log.Warn("warn should pass")
+		log.Error("error should pass")
+
+		// 只有 warn 和 error 通过
+		assert.Equal(t, 2, logs.Len())
+		assert.Equal(t, zapcore.WarnLevel, logs.All()[0].Level)
+		assert.Equal(t, zapcore.ErrorLevel, logs.All()[1].Level)
+	})
+
+	t.Run("debug level passes all messages", func(t *testing.T) {
+		core, logs := observer.New(zapcore.DebugLevel)
+		log := zap.New(core)
+
+		log.Debug("debug message")
+		log.Info("info message")
+		log.Warn("warn message")
+		log.Error("error message")
+
+		assert.Equal(t, 4, logs.Len())
+	})
+
+	t.Run("error level filters debug, info, warn", func(t *testing.T) {
+		core, logs := observer.New(zapcore.ErrorLevel)
+		log := zap.New(core)
+
+		log.Debug("debug should be filtered")
+		log.Info("info should be filtered")
+		log.Warn("warn should be filtered")
+		log.Error("error should pass")
+
+		assert.Equal(t, 1, logs.Len())
+		assert.Equal(t, zapcore.ErrorLevel, logs.All()[0].Level)
+	})
+}
+
+func TestLogger_StructuredFields(t *testing.T) {
+	core, logs := newObservedLogger(zapcore.DebugLevel)
+
+	core.Info("user created",
+		zap.Int64("userId", 42),
+		zap.String("email", "user@example.com"),
+	)
+
+	require.Equal(t, 1, logs.Len())
+	entry := logs.All()[0]
+	assert.Equal(t, "user created", entry.Message)
+	assert.Equal(t, int64(42), entry.ContextMap()["userId"])
+	assert.Equal(t, "user@example.com", entry.ContextMap()["email"])
+}
+
+func TestLogger_Named(t *testing.T) {
+	cfg := &config.LogConfig{
+		Level: "debug",
+		Env:   "development",
+	}
+
+	log, err := logger.New(cfg)
+	require.NoError(t, err)
+
+	// Named 返回子日志器，不应 panic
+	assert.NotPanics(t, func() {
+		named := log.Named("ServiceLayer")
+		named.Info("named logger works")
+	})
+}
+
+func TestLogger_WithFields(t *testing.T) {
+	core, logs := newObservedLogger(zapcore.DebugLevel)
+
+	// With 附加字段
+	withLogger := core.With(zap.String("requestId", "req-abc-123"))
+	withLogger.Info("request processed")
+
+	require.Equal(t, 1, logs.Len())
+	entry := logs.All()[0]
+	assert.Equal(t, "req-abc-123", entry.ContextMap()["requestId"])
+}

package/dist/resources/templates/go-backend/internal/core/observability/metrics.go

@@ -0,0 +1,358 @@
+package observability
+
+import (
+	"strconv"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+	"go.uber.org/zap"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 直方图桶定义
+// ═══════════════════════════════════════════════════════════════
+
+var (
+	httpDurationBuckets      = []float64{0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10}
+	httpSizeBuckets          = []float64{100, 1000, 10000, 100000, 1000000}
+	dbQueryDurationBuckets   = []float64{0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5}
+	queueJobDurationBuckets  = []float64{0.1, 0.5, 1, 2.5, 5, 10, 30, 60, 120}
+	aiRequestDurationBuckets = []float64{0.1, 0.5, 1, 2.5, 5, 10, 30, 60}
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 指标服务
+// ═══════════════════════════════════════════════════════════════
+
+// MetricsService Prometheus 指标服务
+type MetricsService struct {
+	logger *zap.Logger
+
+	// HTTP 指标
+	HTTPRequestDuration *prometheus.HistogramVec
+	HTTPRequestsTotal   *prometheus.CounterVec
+	HTTPRequestSize     *prometheus.HistogramVec
+	HTTPResponseSize    *prometheus.HistogramVec
+	ActiveConnections   *prometheus.GaugeVec
+
+	// 数据库指标
+	DBQueryDuration     *prometheus.HistogramVec
+	DBConnectionsActive *prometheus.GaugeVec
+
+	// 缓存指标
+	CacheHitsTotal   *prometheus.CounterVec
+	CacheMissesTotal *prometheus.CounterVec
+
+	// 队列指标
+	QueueJobsTotal   *prometheus.CounterVec
+	QueueJobDuration *prometheus.HistogramVec
+
+	// AI 指标
+	AIRequestDuration *prometheus.HistogramVec
+	AITokensTotal     *prometheus.CounterVec
+
+	// 存储清理指标
+	AssetsHardDeletedTotal *prometheus.CounterVec
+	OSSDeletionsTotal      *prometheus.CounterVec
+	OSSDeletionDLQTotal    *prometheus.CounterVec
+
+	// Cron 任务统一记录最近成功时间与连续失败次数，供停摆告警使用。
+	// JobLastRunSuccess: 上次成功执行的 unix 时间戳，告警可用 `time() - <gauge>` 检测停摆
+	// JobConsecutiveFailures: 连续失败次数，3 次以上触发 P0 告警
+	JobLastRunSuccess      *prometheus.GaugeVec
+	JobConsecutiveFailures *prometheus.GaugeVec
+
+	// 退款 polling reconcile 指标（按 provider + outcome 分桶）
+	// outcome 取值：queried（查询完成）、unsupported（渠道仅支持 webhook）、errored（查询报错）
+	// 业内对照：Stripe Dashboard / Adyen Cockpit reconcile worker 都会暴露每次扫描的 outcome 计数
+	RefundReconcileTotal *prometheus.CounterVec
+}
+
+// NewMetricsService 创建指标服务
+func NewMetricsService(logger *zap.Logger) *MetricsService {
+	m := &MetricsService{
+		logger: logger.Named("Metrics"),
+
+		HTTPRequestDuration: promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Name:    "http_request_duration_seconds",
+			Help:    "Duration of HTTP requests in seconds",
+			Buckets: httpDurationBuckets,
+		}, []string{"method", "path", "status_code"}),
+
+		HTTPRequestsTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "http_requests_total",
+			Help: "Total number of HTTP requests",
+		}, []string{"method", "path", "status_code"}),
+
+		HTTPRequestSize: promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Name:    "http_request_size_bytes",
+			Help:    "Size of HTTP requests in bytes",
+			Buckets: httpSizeBuckets,
+		}, []string{"method", "path"}),
+
+		HTTPResponseSize: promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Name:    "http_response_size_bytes",
+			Help:    "Size of HTTP responses in bytes",
+			Buckets: httpSizeBuckets,
+		}, []string{"method", "path"}),
+
+		ActiveConnections: promauto.NewGaugeVec(prometheus.GaugeOpts{
+			Name: "active_connections",
+			Help: "Number of active connections",
+		}, []string{"type"}),
+
+		DBQueryDuration: promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Name:    "database_query_duration_seconds",
+			Help:    "Duration of database queries in seconds",
+			Buckets: dbQueryDurationBuckets,
+		}, []string{"operation", "table", "success"}),
+
+		DBConnectionsActive: promauto.NewGaugeVec(prometheus.GaugeOpts{
+			Name: "database_connections_active",
+			Help: "Number of active database connections",
+		}, []string{"pool"}),
+
+		CacheHitsTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "cache_hits_total",
+			Help: "Total number of cache hits",
+		}, []string{"cache", "operation"}),
+
+		CacheMissesTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "cache_misses_total",
+			Help: "Total number of cache misses",
+		}, []string{"cache", "operation"}),
+
+		QueueJobsTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "queue_jobs_total",
+			Help: "Total number of queue jobs",
+		}, []string{"queue", "job_type", "status"}),
+
+		QueueJobDuration: promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Name:    "queue_job_duration_seconds",
+			Help:    "Duration of queue jobs in seconds",
+			Buckets: queueJobDurationBuckets,
+		}, []string{"queue", "job_type", "status"}),
+
+		AIRequestDuration: promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Name:    "ai_request_duration_seconds",
+			Help:    "Duration of AI provider requests in seconds",
+			Buckets: aiRequestDurationBuckets,
+		}, []string{"provider", "model", "success"}),
+
+		AITokensTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "ai_tokens_total",
+			Help: "Total number of AI tokens used",
+		}, []string{"provider", "model", "type"}),
+
+		// 存储资产物理删除累计数（按产品分桶），保留期 cleanup job 触发
+		AssetsHardDeletedTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "storage_assets_hard_deleted_total",
+			Help: "Total number of storage assets hard-deleted by retention cleanup job",
+		}, []string{"product_code"}),
+
+		// OSS 物理删除累计数（按产品 + 结果分桶），cleanup job 与 retry job 共用
+		OSSDeletionsTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "storage_oss_deletions_total",
+			Help: "Total number of object storage delete attempts grouped by result",
+		}, []string{"product_code", "result"}),
+
+		// OSS 删除最终失败（进入死信）累计数
+		OSSDeletionDLQTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "storage_oss_deletion_dlq_total",
+			Help: "Total number of OSS deletions that exhausted retries and moved to dead status",
+		}, []string{"product_code"}),
+
+		// Cron job 上次成功执行的 unix 时间戳（停摆检测用）
+		JobLastRunSuccess: promauto.NewGaugeVec(prometheus.GaugeOpts{
+			Name: "cron_job_last_run_success_unix_timestamp",
+			Help: "Unix timestamp of the last successful cron job run; alert with time() - this gauge",
+		}, []string{"job_name"}),
+
+		// Cron job 连续失败次数（成功一次后清零）
+		JobConsecutiveFailures: promauto.NewGaugeVec(prometheus.GaugeOpts{
+			Name: "cron_job_consecutive_failures",
+			Help: "Consecutive failure count for a cron job; resets to 0 on success",
+		}, []string{"job_name"}),
+
+		// 退款 polling reconcile 累计数（按 provider + outcome 分桶），SyncProcessingRefunds 末尾 emit
+		RefundReconcileTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "payment_refund_reconcile_total",
+			Help: "Total number of refund polling reconcile attempts grouped by provider and outcome",
+		}, []string{"provider", "outcome"}),
+	}
+
+	m.logger.Info("prometheus metrics initialized")
+	return m
+}
+
+// ═══════════════════════════════════════════════════════════════
+// HTTP 指标记录
+// ═══════════════════════════════════════════════════════════════
+
+// RecordHTTPRequest 记录 HTTP 请求指标
+func (m *MetricsService) RecordHTTPRequest(method, path string, statusCode int, duration float64, requestSize, responseSize *float64) {
+	labels := prometheus.Labels{
+		"method":      method,
+		"path":        path,
+		"status_code": strconv.Itoa(statusCode),
+	}
+
+	m.HTTPRequestsTotal.With(labels).Inc()
+	m.HTTPRequestDuration.With(labels).Observe(duration)
+
+	if requestSize != nil {
+		m.HTTPRequestSize.With(prometheus.Labels{"method": method, "path": path}).Observe(*requestSize)
+	}
+	if responseSize != nil {
+		m.HTTPResponseSize.With(prometheus.Labels{"method": method, "path": path}).Observe(*responseSize)
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 数据库指标记录
+// ═══════════════════════════════════════════════════════════════
+
+// RecordDBQuery 记录数据库查询指标
+func (m *MetricsService) RecordDBQuery(operation, table string, duration float64, success bool) {
+	m.DBQueryDuration.With(prometheus.Labels{
+		"operation": operation,
+		"table":     table,
+		"success":   strconv.FormatBool(success),
+	}).Observe(duration)
+}
+
+// SetDBConnections 更新活跃数据库连接数
+func (m *MetricsService) SetDBConnections(pool string, count float64) {
+	m.DBConnectionsActive.With(prometheus.Labels{"pool": pool}).Set(count)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 缓存指标记录
+// ═══════════════════════════════════════════════════════════════
+
+// RecordCacheHit 记录缓存命中
+func (m *MetricsService) RecordCacheHit(cache, operation string) {
+	m.CacheHitsTotal.With(prometheus.Labels{"cache": cache, "operation": operation}).Inc()
+}
+
+// RecordCacheMiss 记录缓存未命中
+func (m *MetricsService) RecordCacheMiss(cache, operation string) {
+	m.CacheMissesTotal.With(prometheus.Labels{"cache": cache, "operation": operation}).Inc()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 队列指标记录
+// ═══════════════════════════════════════════════════════════════
+
+// RecordQueueJob 记录队列任务指标
+func (m *MetricsService) RecordQueueJob(queue, jobType, status string, duration *float64) {
+	m.QueueJobsTotal.With(prometheus.Labels{
+		"queue":    queue,
+		"job_type": jobType,
+		"status":   status,
+	}).Inc()
+
+	if duration != nil && status != "active" {
+		m.QueueJobDuration.With(prometheus.Labels{
+			"queue":    queue,
+			"job_type": jobType,
+			"status":   status,
+		}).Observe(*duration)
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AI 指标记录
+// ═══════════════════════════════════════════════════════════════
+
+// RecordAIRequest 记录 AI 请求指标
+func (m *MetricsService) RecordAIRequest(provider, model string, duration float64, success bool, inputTokens, outputTokens *float64) {
+	m.AIRequestDuration.With(prometheus.Labels{
+		"provider": provider,
+		"model":    model,
+		"success":  strconv.FormatBool(success),
+	}).Observe(duration)
+
+	if inputTokens != nil {
+		m.AITokensTotal.With(prometheus.Labels{
+			"provider": provider,
+			"model":    model,
+			"type":     "input",
+		}).Add(*inputTokens)
+	}
+
+	if outputTokens != nil {
+		m.AITokensTotal.With(prometheus.Labels{
+			"provider": provider,
+			"model":    model,
+			"type":     "output",
+		}).Add(*outputTokens)
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 连接数管理
+// ═══════════════════════════════════════════════════════════════
+
+// SetActiveConnections 设置活跃连接数
+func (m *MetricsService) SetActiveConnections(connType string, count float64) {
+	m.ActiveConnections.With(prometheus.Labels{"type": connType}).Set(count)
+}
+
+// IncrActiveConnections 增加活跃连接数
+func (m *MetricsService) IncrActiveConnections(connType string) {
+	m.ActiveConnections.With(prometheus.Labels{"type": connType}).Inc()
+}
+
+// DecrActiveConnections 减少活跃连接数
+func (m *MetricsService) DecrActiveConnections(connType string) {
+	m.ActiveConnections.With(prometheus.Labels{"type": connType}).Dec()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 计时器
+// ═══════════════════════════════════════════════════════════════
+
+// CreateTimer 创建用于测量持续时间的计时器，返回结束时的秒数
+func (m *MetricsService) CreateTimer() func() float64 {
+	start := time.Now()
+	return func() float64 {
+		return time.Since(start).Seconds()
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 退款 polling reconcile 指标记录
+// ═══════════════════════════════════════════════════════════════
+
+// RecordRefundReconcile 累加退款 polling outcome 计数
+//
+// 在单次 SyncProcessingRefunds 末尾按 provider + outcome 聚合上报，
+// outcome 取值：queried（query 完成）、unsupported（渠道仅支持 webhook）、errored（query 报错）。
+// count 为本次扫描内该 provider+outcome 的累计条数；count <= 0 时 no-op，避免 emit 噪声。
+func (m *MetricsService) RecordRefundReconcile(provider, outcome string, count int) {
+	if count <= 0 {
+		return
+	}
+	m.RefundReconcileTotal.With(prometheus.Labels{
+		"provider": provider,
+		"outcome":  outcome,
+	}).Add(float64(count))
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Cron job 观察者实现 schedule.jobObserver 的最小指标接口。
+// ═══════════════════════════════════════════════════════════════
+
+// JobSucceeded 记录 cron job 成功执行：写入 last_run_success 时间戳，连续失败计数清零。
+func (m *MetricsService) JobSucceeded(name string, ts time.Time) {
+	m.JobLastRunSuccess.WithLabelValues(name).Set(float64(ts.Unix()))
+	m.JobConsecutiveFailures.WithLabelValues(name).Set(0)
+}
+
+// JobFailed 记录 cron job 失败：连续失败次数 +1。
+// last_run_success 不更新，运维通过 `time() - last_run_success` 检测停摆。
+func (m *MetricsService) JobFailed(name string) {
+	m.JobConsecutiveFailures.WithLabelValues(name).Inc()
+}