@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/schedule/recorder.go

@@ -0,0 +1,305 @@
+package schedule
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// RunTrigger 标识任务运行的触发来源。
+type RunTrigger string
+
+const (
+	// RunTriggerCron 表示由 worker cron 自动触发。
+	RunTriggerCron RunTrigger = "cron"
+	// RunTriggerManualRun 表示由后台调度中心手动触发。
+	RunTriggerManualRun RunTrigger = "manual_run"
+	// RunTriggerManualSweep 表示由后台手动执行生命周期 sweep 触发。
+	RunTriggerManualSweep RunTrigger = "manual_sweep"
+)
+
+// RunStatus 标识单次任务运行状态。
+type RunStatus string
+
+const (
+	// RunStatusRunning 表示任务正在运行。
+	RunStatusRunning RunStatus = "running"
+	// RunStatusSucceeded 表示任务运行成功。
+	RunStatusSucceeded RunStatus = "succeeded"
+	// RunStatusFailed 表示任务运行失败。
+	RunStatusFailed RunStatus = "failed"
+	// RunStatusSkipped 表示任务因调度策略未执行。
+	RunStatusSkipped RunStatus = "skipped"
+	// RunStatusCanceled 表示任务在控制面取消请求后停止。
+	RunStatusCanceled RunStatus = "canceled"
+)
+
+// RunEventType 标识运行事件时间线类型。
+type RunEventType string
+
+const (
+	// RunEventStarted 表示任务开始。
+	RunEventStarted RunEventType = "started"
+	// RunEventSucceeded 表示任务成功结束。
+	RunEventSucceeded RunEventType = "succeeded"
+	// RunEventFailed 表示任务失败结束。
+	RunEventFailed RunEventType = "failed"
+	// RunEventSkipped 表示任务被调度策略跳过。
+	RunEventSkipped RunEventType = "skipped"
+	// RunEventProgress 表示任务处理器上报的有界执行进度。
+	RunEventProgress RunEventType = "progress"
+	// RunEventPolicyEvaluated 表示本次触发已完成控制策略判定。
+	RunEventPolicyEvaluated RunEventType = "policy_evaluated"
+	// RunEventAttemptStarted 表示任务处理器单次尝试开始。
+	RunEventAttemptStarted RunEventType = "attempt_started"
+	// RunEventAttemptSucceeded 表示任务处理器单次尝试成功。
+	RunEventAttemptSucceeded RunEventType = "attempt_succeeded"
+	// RunEventAttemptFailed 表示任务处理器单次尝试失败。
+	RunEventAttemptFailed RunEventType = "attempt_failed"
+	// RunEventRetrying 表示任务失败后进入重试等待。
+	RunEventRetrying RunEventType = "retrying"
+	// RunEventRuntimeExceeded 表示任务耗时超过控制面阈值。
+	RunEventRuntimeExceeded RunEventType = "runtime_exceeded"
+	// RunEventCancelRequested 表示控制面请求取消本次执行。
+	RunEventCancelRequested RunEventType = "cancel_requested"
+	// RunEventCanceled 表示本次执行确认取消。
+	RunEventCanceled RunEventType = "canceled"
+)
+
+// ControlStatus 标识任务控制状态。
+type ControlStatus string
+
+const (
+	// ControlStatusActive 表示任务按计划运行。
+	ControlStatusActive ControlStatus = "active"
+	// ControlStatusPaused 表示任务被后台暂停。
+	ControlStatusPaused ControlStatus = "paused"
+)
+
+// ConcurrencyPolicy 标识同一任务实例并发策略。
+type ConcurrencyPolicy string
+
+const (
+	// ConcurrencyPolicyForbid 表示同一任务运行中时跳过新触发。
+	ConcurrencyPolicyForbid ConcurrencyPolicy = "forbid"
+	// ConcurrencyPolicyAllow 表示允许同一任务重叠执行。
+	ConcurrencyPolicyAllow ConcurrencyPolicy = "allow"
+)
+
+// DispatchStatus 标识后台手动调度命令状态。
+type DispatchStatus string
+
+const (
+	// DispatchStatusPending 表示命令等待 worker 认领。
+	DispatchStatusPending DispatchStatus = "pending"
+	// DispatchStatusClaimed 表示命令已被 worker 认领。
+	DispatchStatusClaimed DispatchStatus = "claimed"
+	// DispatchStatusSucceeded 表示命令执行成功。
+	DispatchStatusSucceeded DispatchStatus = "succeeded"
+	// DispatchStatusFailed 表示命令执行失败。
+	DispatchStatusFailed DispatchStatus = "failed"
+	// DispatchStatusSkipped 表示命令被策略跳过。
+	DispatchStatusSkipped DispatchStatus = "skipped"
+	// DispatchStatusCancelRequested 表示命令已收到取消请求。
+	DispatchStatusCancelRequested DispatchStatus = "cancel_requested"
+	// DispatchStatusCanceled 表示命令已确认取消。
+	DispatchStatusCanceled DispatchStatus = "canceled"
+)
+
+// ErrTaskAlreadyRunning 表示持久化层拒绝创建运行记录，因为同一任务仍有有效执行租约。
+var ErrTaskAlreadyRunning = errors.New("scheduler task is already running")
+
+// ErrTaskRuntimeExceeded 表示任务执行超过控制面配置的最大运行时间。
+var ErrTaskRuntimeExceeded = errors.New("task runtime exceeded control threshold")
+
+// TaskRunStart 是 recorder 持久化运行开始事件的输入契约。
+type TaskRunStart struct {
+	TaskName       string
+	TaskType       TaskType
+	Pattern        string
+	Trigger        RunTrigger
+	DispatchID     int64
+	CorrelationID  string
+	OperatorUserID *int64
+	Reason         string
+	Runtime        string
+	StartedAt      time.Time
+	Metadata       map[string]any
+}
+
+// TaskRunCompletion 是 recorder 持久化运行完成事件的输入契约。
+type TaskRunCompletion struct {
+	RunID             int64
+	TaskName          string
+	TaskType          TaskType
+	Pattern           string
+	Trigger           RunTrigger
+	DispatchID        int64
+	CorrelationID     string
+	OperatorUserID    *int64
+	Reason            string
+	Runtime           string
+	StartedAt         time.Time
+	FinishedAt        time.Time
+	DurationMs        int64
+	Status            RunStatus
+	Error             string
+	CancelRequestedAt *time.Time
+	Metadata          map[string]any
+}
+
+// TaskRunEventRecord 是 recorder 持久化运行事件的输入契约。
+type TaskRunEventRecord struct {
+	RunID     int64
+	EventType RunEventType
+	Level     string
+	Stage     string
+	Message   string
+	Payload   map[string]any
+	CreatedAt time.Time
+}
+
+// RunRecorder 将调度器运行状态持久化到外部存储。
+//
+// 调度器只依赖该窄接口，避免 core/schedule 反向依赖具体业务模块或数据库实现。
+type RunRecorder interface {
+	UpsertTask(ctx context.Context, task RegisteredTask) error
+	StartRun(ctx context.Context, start TaskRunStart) (int64, error)
+	RecordRunEvent(ctx context.Context, event TaskRunEventRecord) error
+	CompleteRun(ctx context.Context, completion TaskRunCompletion) error
+}
+
+// RuntimeExceededRunExpirer 清理进程异常退出后遗留的超时运行记录。
+type RuntimeExceededRunExpirer interface {
+	ExpireRuntimeExceededRuns(ctx context.Context, now time.Time) (int64, error)
+}
+
+// TaskControlRegistration 是调度器向控制面登记任务定义的输入。
+type TaskControlRegistration struct {
+	// TaskName 是代码层唯一任务名称。
+	TaskName string
+	// TaskType 是任务触发类型。
+	TaskType TaskType
+	// DisplayName 是首次登记时的后台展示名称。
+	DisplayName string
+	// Description 是首次登记时的任务职责说明。
+	Description string
+	// DefaultPattern 是代码发布的默认调度表达式。
+	DefaultPattern string
+	// Pattern 是本次注册请求使用的调度表达式。
+	Pattern string
+	// SourceRuntime 是注册任务的运行时名称。
+	SourceRuntime string
+	// ConcurrencyPolicy 是首次登记时的并发策略。
+	ConcurrencyPolicy ConcurrencyPolicy
+	// ManualRunEnabled 是首次登记时的手动执行开关。
+	ManualRunEnabled bool
+	// MaxRuntimeSeconds 是首次登记时的最大运行秒数。
+	MaxRuntimeSeconds int
+	// RetryMaxAttempts 是首次登记时的最大重试次数。
+	RetryMaxAttempts int
+	// RetryBackoffSeconds 是首次登记时的退避秒数。
+	RetryBackoffSeconds int
+	// RegisteredAt 是最近一次代码注册时间。
+	RegisteredAt time.Time
+	// NextRunAt 是当前运行时计算出的下次执行时间。
+	NextRunAt *time.Time
+}
+
+// TaskRegistrationOptions 描述任务首次登记时写入控制面的默认策略。
+type TaskRegistrationOptions struct {
+	// DisplayName 是调度中心展示名称。
+	DisplayName string
+	// Description 是调度任务职责说明。
+	Description string
+	// ConcurrencyPolicy 是同名任务的并发策略。
+	ConcurrencyPolicy ConcurrencyPolicy
+	// ManualRunEnabled 表示是否允许运营人员手动触发。
+	ManualRunEnabled bool
+	// MaxRuntimeSeconds 是单次执行的最大运行秒数。
+	MaxRuntimeSeconds int
+	// RetryMaxAttempts 是失败后的最大重试次数。
+	RetryMaxAttempts int
+	// RetryBackoffSeconds 是相邻重试之间的退避秒数。
+	RetryBackoffSeconds int
+}
+
+// RunSkippedError 表示处理器有意跳过本次执行且不应重试。
+type RunSkippedError struct {
+	// Reason 是写入运行时间线的规范化跳过原因。
+	Reason string
+}
+
+// Error 返回跳过原因。
+func (e RunSkippedError) Error() string {
+	return e.Reason
+}
+
+// TaskControl 是控制面返回给调度器的运行策略。
+type TaskControl struct {
+	TaskName            string
+	Pattern             string
+	Timezone            string
+	ControlStatus       ControlStatus
+	ManualRunEnabled    bool
+	ConcurrencyPolicy   ConcurrencyPolicy
+	MaxRuntimeSeconds   int
+	RetryMaxAttempts    int
+	RetryBackoffSeconds int
+	DefinitionRevision  int64
+}
+
+// ControlStore 保存调度控制面状态。
+type ControlStore interface {
+	RegisterTaskControl(ctx context.Context, registration TaskControlRegistration) (*TaskControl, error)
+	GetTaskControl(ctx context.Context, taskName string) (*TaskControl, error)
+	ListTaskControls(ctx context.Context) ([]TaskControl, error)
+}
+
+// TaskDispatch 是后台调度中心写入、worker 认领执行的命令。
+type TaskDispatch struct {
+	ID             int64
+	TaskName       string
+	DispatchType   string
+	ClaimToken     string
+	CorrelationID  string
+	OperatorUserID *int64
+	Reason         string
+	Payload        map[string]any
+}
+
+// DispatchLeaseState 是 worker 心跳续约后的控制面状态。
+type DispatchLeaseState struct {
+	CancelRequested   bool
+	CancelRequestedAt *time.Time
+	CancelReason      string
+}
+
+// TaskRunOptions 描述一次非 cron 执行的触发上下文。
+type TaskRunOptions struct {
+	Trigger        RunTrigger
+	DispatchID     int64
+	CorrelationID  string
+	OperatorUserID *int64
+	Reason         string
+	Runtime        string
+	Metadata       map[string]any
+}
+
+// TaskRunResult 是调度器执行后的控制面回执。
+type TaskRunResult struct {
+	RunID             int64
+	Status            RunStatus
+	Error             string
+	Skipped           bool
+	SkipReason        string
+	Canceled          bool
+	CancelRequestedAt *time.Time
+}
+
+// DispatchStore 保存后台手动调度命令。
+type DispatchStore interface {
+	ClaimPendingDispatches(ctx context.Context, runtime string, limit int, now time.Time) ([]TaskDispatch, error)
+	HeartbeatDispatch(ctx context.Context, dispatchID int64, runID int64, runtime string, claimToken string, heartbeatAt time.Time) (*DispatchLeaseState, error)
+	CompleteDispatch(ctx context.Context, dispatchID int64, runID int64, claimToken string, result TaskRunResult, finishedAt time.Time) error
+}

package/dist/resources/templates/go-backend/internal/core/schedule/run_context.go

@@ -0,0 +1,124 @@
+package schedule
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"go.uber.org/zap"
+)
+
+const (
+	runEventStageMaxRunes   = 80
+	runEventMessageMaxRunes = 500
+	runEventPayloadMaxKeys  = 64
+	runEventPayloadMaxBytes = 16 * 1024
+)
+
+type runEventReporterContextKey struct{}
+
+// TaskRunEvent 是任务处理器可写入当前运行时间线的事件。
+type TaskRunEvent struct {
+	// EventType 是事件类型；处理器只能上报 progress。
+	EventType RunEventType
+	// Level 是 info、warning 或 error，空值按 info 处理。
+	Level string
+	// Stage 是当前运行阶段。
+	Stage string
+	// Message 是不含敏感信息的事件摘要。
+	Message string
+	// Payload 是有界的结构化进度数据。
+	Payload map[string]any
+}
+
+// RunEventReporter 将处理器事件绑定到调度器创建的当前运行记录。
+type RunEventReporter interface {
+	// ReportRunEvent 写入一条经过校验的运行事件。
+	ReportRunEvent(ctx context.Context, event TaskRunEvent) error
+}
+
+type recorderRunEventReporter struct {
+	runID    int64
+	recorder RunRecorder
+	logger   *zap.Logger
+}
+
+// ReportRunEvent 向当前调度运行上报有界事件；未配置 recorder 时安全地忽略写入。
+func ReportRunEvent(ctx context.Context, event TaskRunEvent) error {
+	normalized, err := normalizeTaskRunEvent(event)
+	if err != nil {
+		return err
+	}
+	reporter, _ := ctx.Value(runEventReporterContextKey{}).(RunEventReporter)
+	if reporter == nil {
+		return nil
+	}
+	return reporter.ReportRunEvent(ctx, normalized)
+}
+
+func withRunEventReporter(ctx context.Context, runID int64, recorder RunRecorder, logger *zap.Logger) context.Context {
+	if runID <= 0 || recorder == nil {
+		return ctx
+	}
+	return context.WithValue(ctx, runEventReporterContextKey{}, &recorderRunEventReporter{
+		runID:    runID,
+		recorder: recorder,
+		logger:   logger,
+	})
+}
+
+func (r *recorderRunEventReporter) ReportRunEvent(ctx context.Context, event TaskRunEvent) error {
+	if err := r.recorder.RecordRunEvent(ctx, TaskRunEventRecord{
+		RunID:     r.runID,
+		EventType: event.EventType,
+		Level:     event.Level,
+		Stage:     event.Stage,
+		Message:   event.Message,
+		Payload:   event.Payload,
+		CreatedAt: time.Now().UTC(),
+	}); err != nil {
+		r.logger.Error("record scheduler task progress failed",
+			zap.Int64("runID", r.runID),
+			zap.String("stage", event.Stage),
+			zap.Error(err),
+		)
+	}
+	return nil
+}
+
+func normalizeTaskRunEvent(event TaskRunEvent) (TaskRunEvent, error) {
+	if event.EventType != RunEventProgress {
+		return TaskRunEvent{}, fmt.Errorf("task run event type must be %q", RunEventProgress)
+	}
+	event.Level = strings.TrimSpace(event.Level)
+	if event.Level == "" {
+		event.Level = "info"
+	}
+	switch event.Level {
+	case "info", "warning", "error":
+	default:
+		return TaskRunEvent{}, fmt.Errorf("task run event level %q is invalid", event.Level)
+	}
+	event.Stage = strings.TrimSpace(event.Stage)
+	if event.Stage == "" || utf8.RuneCountInString(event.Stage) > runEventStageMaxRunes {
+		return TaskRunEvent{}, fmt.Errorf("task run event stage must contain 1-%d characters", runEventStageMaxRunes)
+	}
+	event.Message = strings.TrimSpace(event.Message)
+	if event.Message == "" || utf8.RuneCountInString(event.Message) > runEventMessageMaxRunes {
+		return TaskRunEvent{}, fmt.Errorf("task run event message must contain 1-%d characters", runEventMessageMaxRunes)
+	}
+	if len(event.Payload) > runEventPayloadMaxKeys {
+		return TaskRunEvent{}, fmt.Errorf("task run event payload exceeds %d top-level keys", runEventPayloadMaxKeys)
+	}
+	payload, err := json.Marshal(event.Payload)
+	if err != nil {
+		return TaskRunEvent{}, fmt.Errorf("marshal task run event payload: %w", err)
+	}
+	if len(payload) > runEventPayloadMaxBytes {
+		return TaskRunEvent{}, fmt.Errorf("task run event payload exceeds %d bytes", runEventPayloadMaxBytes)
+	}
+	return event, nil
+}

package/dist/resources/templates/go-backend/internal/core/schedule/run_context_test.go

@@ -0,0 +1,85 @@
+package schedule
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+type failingRunEventRecorder struct {
+	fakeRunRecorder
+	err error
+}
+
+func (r *failingRunEventRecorder) RecordRunEvent(context.Context, TaskRunEventRecord) error {
+	return r.err
+}
+
+func TestReportRunEventBindsCurrentRun(t *testing.T) {
+	recorder := &fakeRunRecorder{}
+	ctx := withRunEventReporter(context.Background(), 42, recorder, zap.NewNop())
+
+	if err := ReportRunEvent(ctx, TaskRunEvent{
+		EventType: RunEventProgress,
+		Stage:     "scan",
+		Message:   "Scan completed",
+		Payload:   map[string]any{"scanned": 7},
+	}); err != nil {
+		t.Fatalf("ReportRunEvent() error = %v", err)
+	}
+	if len(recorder.events) != 1 || recorder.events[0].RunID != 42 {
+		t.Fatalf("recorded events = %#v, want current run ID 42", recorder.events)
+	}
+	if recorder.events[0].Level != "info" || recorder.events[0].EventType != RunEventProgress {
+		t.Fatalf("recorded event = %#v, want normalized progress event", recorder.events[0])
+	}
+}
+
+func TestReportRunEventValidatesBoundariesWithoutRecorder(t *testing.T) {
+	if err := ReportRunEvent(context.Background(), TaskRunEvent{
+		EventType: RunEventSucceeded,
+		Stage:     "scan",
+		Message:   "invalid terminal event",
+	}); err == nil {
+		t.Fatal("ReportRunEvent() accepted a handler-owned terminal event")
+	}
+	if err := ReportRunEvent(context.Background(), TaskRunEvent{
+		EventType: RunEventProgress,
+		Stage:     strings.Repeat("x", runEventStageMaxRunes+1),
+		Message:   "invalid stage",
+	}); err == nil {
+		t.Fatal("ReportRunEvent() accepted an oversized stage")
+	}
+	if err := ReportRunEvent(context.Background(), TaskRunEvent{
+		EventType: RunEventProgress,
+		Stage:     "scan",
+		Message:   "invalid payload",
+		Payload:   map[string]any{"unsupported": make(chan struct{})},
+	}); err == nil {
+		t.Fatal("ReportRunEvent() accepted a non-JSON payload")
+	}
+	if err := ReportRunEvent(context.Background(), TaskRunEvent{
+		EventType: RunEventProgress,
+		Stage:     "scan",
+		Message:   "valid without recorder",
+	}); err != nil {
+		t.Fatalf("ReportRunEvent() without recorder error = %v", err)
+	}
+}
+
+func TestReportRunEventRecorderFailureIsNonFatal(t *testing.T) {
+	recorder := &failingRunEventRecorder{err: errors.New("persistence unavailable")}
+	ctx := withRunEventReporter(context.Background(), 9, recorder, zap.NewNop())
+
+	if err := ReportRunEvent(ctx, TaskRunEvent{
+		EventType: RunEventProgress,
+		Stage:     "recovery",
+		Message:   "Recovery completed",
+		Payload:   map[string]any{"completed": 1},
+	}); err != nil {
+		t.Fatalf("ReportRunEvent() exposed recorder failure = %v", err)
+	}
+}