contract

type IDGenerator interface {
	// New 새로운 고유한 TaskInstanceID를 생성하여 반환합니다.
	//
	// 반환되는 ID는 시스템 전체에서 고유성이 보장되어야 하며,
	// 동시에 여러 고루틴에서 호출되어도 안전해야 합니다.
	//
	// 반환값:
	//   - TaskInstanceID: 고유한 작업 인스턴스 ID
	New() TaskInstanceID
}

type Notification struct {
	// NotifierID 알림을 전송할 대상 알림 채널(Notifier)의 식별자입니다. (Optional)
	// 이 값이 비어있다면(""), 애플리케이션 또는 시스템의 기본 알림 채널(Notifier)로 전송됩니다.
	NotifierID NotifierID

	// TaskID 이 알림을 생성한 작업(Task)의 종류를 나타내는 식별자입니다. (Optional)
	// 예: "NaverShopping", "KurlyCheck" 등 비즈니스 로직의 큰 카테고리를 의미합니다.
	TaskID TaskID

	// CommandID 해당 작업 내에서 실행된 구체적인 명령어 식별자입니다. (Optional)
	// 예: "CheckPrice", "MonitorStock" 등 작업 내부의 세부 동작을 구분합니다.
	CommandID TaskCommandID

	// InstanceID 작업이 실제로 실행될 때 부여되는 고유한 인스턴스 ID입니다. (Optional)
	// 스케줄러에 의해 주기적으로 반복 실행되는 작업의 경우, 각 회차를 구분하고 로그를 추적(Trace)하는 데 사용됩니다.
	InstanceID TaskInstanceID

	// Title 알림의 제목입니다. (Optional)
	Title string

	// Message 전달하고자 하는 알림의 본문 내용입니다. (Required)
	Message string

	// Elapsed 작업 실행에 소요된 시간입니다. (Optional)
	Elapsed time.Duration

	// ErrorOccurred 이 알림이 에러 상황을 알리는 것인지의 여부입니다.
	ErrorOccurred bool

	// Cancelable 해당 작업이 취소 가능한지의 여부입니다.
	Cancelable bool
}

type NotificationHealthChecker interface {
	// Health 시스템이 정상적으로 동작 중인지 검사합니다.
	Health() error
}

type NotificationSender interface {
	// Notify 알림 메시지 발송을 요청합니다.
	//
	// 이 메서드는 일반적으로 비동기적으로 동작할 수 있으며(구현체에 따라 다름),
	// 전송 요청이 성공적으로 큐에 적재되거나 시스템에 수락되었을 때 nil을 반환합니다.
	// 즉, nil 반환이 반드시 "최종 사용자 도달"을 보장하는 것은 아닙니다.
	//
	// 파라미터:
	//   - ctx: 요청의 컨텍스트 (Timeout, Cancellation 전파 용도)
	//   - notification: 전송할 알림의 상세 내용 (메시지, 수신처, 메타데이터 등)
	//
	// 반환값:
	//   - error: 요청 검증 실패, 큐 포화 상태, 또는 일시적 시스템 장애 시 에러를 반환합니다.
	Notify(ctx context.Context, notification Notification) error

	// SupportsHTML 지정된 Notifier가 HTML 형식의 메시지 본문을 지원하는지의 여부를 반환합니다.
	SupportsHTML(notifierID NotifierID) bool
}

type NotifierID string

type TaskCanceler interface {
	// Cancel 특정 작업 인스턴스의 실행을 중단 요청합니다.
	Cancel(instanceID TaskInstanceID) error
}

type TaskCommandID string

type TaskExecutor interface {
	TaskSubmitter
	TaskCanceler
}

type TaskID string

type TaskInstanceID string

type TaskResultStore interface {
	// Save 작업 결과를 저장합니다.
	//
	// 동일한 taskID와 commandID 조합으로 Save를 호출하면 기존 데이터를 덮어씁니다.
	Save(taskID TaskID, commandID TaskCommandID, v any) error

	// Load 저장된 작업 결과를 불러옵니다.
	//
	// 저장된 데이터가 없는 경우 ErrTaskResultNotFound 에러를 반환합니다.
	// 호출자는 이 에러를 확인하여 최초 실행 여부를 판단해야 합니다.
	Load(taskID TaskID, commandID TaskCommandID, v any) error
}

type TaskRunBy int

type TaskSubmitRequest struct {
	// TaskID 실행하고자 하는 작업의 종류를 식별하는 고유 ID입니다. (Required)
	// 예: "NAVER", "KURLY"
	TaskID TaskID

	// CommandID 해당 작업 내에서 수행할 구체적인 명령어 ID입니다. (Required)
	// 예: "CheckPrice", "MonitorStock"
	CommandID TaskCommandID

	// NotifierID 알림을 전송할 대상 채널(Notifier)의 식별자입니다. (Optional)
	// 특정 메신저나 채널로 알림을 강제하고 싶을 때 사용합니다.
	// 이 값을 지정하지 않거나 빈 문자열("")일 경우, 해당 Task 설정에 정의된 기본 Notifier가 자동으로 사용됩니다.
	NotifierID NotifierID

	// NotifyOnStart 작업 실행 시작 시점에 즉시 알림을 발송할지 여부를 결정합니다. (Optional)
	// - true: 작업이 큐에서 꺼내져 실행되는 즉시 "작업 시작" 알림을 전송합니다. 장기 실행 작업의 경우 즉각적인 피드백을 제공하여 UX를 향상시킬 수 있습니다.
	// - false: 시작 알림을 보내지 않고, 작업 결과(성공/실패)에 대한 알림만 전송합니다. (기본값)
	NotifyOnStart bool

	// RunBy 이 작업을 요청한 실행 주체를 나타냅니다. (Required)
	// 로깅, 감사, 그리고 알림 메시지 포맷팅 시 "누가 실행했는지"를 구별하기 위해 사용됩니다.
	// 예: TaskRunByUser(사용자 수동 실행), TaskRunByScheduler(스케줄러 자동 실행)
	RunBy TaskRunBy
}

type TaskSubmitter interface {
	// Submit 작업을 실행 요청 대기열(Queue)에 등록합니다.
	Submit(ctx context.Context, req *TaskSubmitRequest) error
}