@things-factory/scheduler 9.0.2 → 9.0.5

package/helps/scheduler/scheduler.ko.md

@@ -5,6 +5,115 @@
 - 호출된 이벤트가 실패할 경우 정책에 따라서 일정 시간 이후 재시도 수행
 - 스케줄러 처리의 부하를 분산하기 위해서 새롭게 설계된 구조로서 스케줄러는 데이터베이스 기반의 큐 구조를 사용하여 모든 스케줄 데이터를 관리
 
+## 🚀 독창적인 기능들
+
+### 1. 5차원 클라이언트 식별자 시스템
+
+스케줄러는 단순한 UUID 기반 식별을 넘어서는 독창적인 5차원 클라이언트 식별 시스템을 사용합니다:
+
+```json
+{
+  "client": {
+    "application": "data-collection-app",
+    "group": "domain-123",
+    "type": "data-set",
+    "key": "sensor-001",
+    "operation": "collect"
+  }
+}
+```
+
+**주요 장점:**
+
+- **비즈니스 컨텍스트 인식**: 식별자가 기술적 ID가 아닌 비즈니스 의미를 반영
+- **중복 방지**: 5개 요소가 모두 일치할 때만 동일한 스케줄로 인식
+- **자연스러운 조직화**: application → group → type → key → operation의 계층적 구조
+- **유연한 필터링**: 클라이언트 속성의 조합으로 스케줄 필터링 가능
+
+### 2. 혁신적인 스케줄 타입
+
+#### delay-recur: 혁신적인 반복 패턴
+
+```json
+{
+  "type": "delay-recur",
+  "schedule": "30",
+  "timezone": "UTC"
+}
+```
+
+- **간단한 반복**: 복잡한 cron 표현식 없이 30초 간격 반복
+- **실시간 최적화**: 모니터링, 하트비트, 데이터 동기화에 완벽
+- **리소스 효율성**: 전통적인 cron 기반 접근법보다 가벼움
+
+#### 포괄적인 스케줄 타입 지원
+
+- **now**: 즉시 실행
+- **delay**: 일회성 지연 실행
+- **date**: 특정 날짜/시간 실행
+- **cron**: 전통적인 cron 기반 스케줄링
+- **delay-recur**: 혁신적인 반복 패턴
+
+### 3. 고급 실패 처리
+
+#### retry_dlq: 하이브리드 실패 정책
+
+```json
+{
+  "failed_policy": "retry_dlq",
+  "retry_wait": 60,
+  "max_retry_count": 3
+}
+```
+
+**3단계 실패 처리:**
+
+1. **즉시 재시도**: 지수 백오프를 통한 빠른 재시도
+2. **최대 재시도**: 설정된 최대 시도 횟수까지
+3. **Dead Letter Queue**: 실패한 작업을 DLQ로 이동하여 나중에 처리
+
+**장점:**
+
+- **시스템 안정성**: 무한 재시도 루프 방지
+- **데이터 보존**: 실패 시에도 데이터 손실 없음
+- **문제 진단**: DLQ를 통한 실패 원인 분석 가능
+
+### 4. 히스토리 인식 스케줄링
+
+#### history_check: 실행 히스토리 관리
+
+```json
+{
+  "history_check": true
+}
+```
+
+**기능:**
+
+- **중복 방지**: 이미 완료된 작업의 재실행 방지
+- **상태 기반 의사결정**: 실행 히스토리를 기반으로 한 스케줄링 결정
+- **감사 추적**: 규정 준수 및 디버깅을 위한 완전한 실행 히스토리
+
+### 5. 도메인 인식 콜백 시스템
+
+#### 멀티 테넌트 지원
+
+```json
+{
+  "task": {
+    "connection": {
+      "host": "http://localhost:3000/domain/company/callback-schedule-for-dataset"
+    }
+  }
+}
+```
+
+**장점:**
+
+- **테넌트 격리**: 각 도메인의 스케줄이 독립적으로 처리
+- **자동 URL 생성**: 도메인 컨텍스트가 콜백 URL에 자동 포함
+- **보안**: 도메인 기반 접근 제어 및 데이터 격리
+
 ### 스케줄러의 주기적 처리에 대한 Diagram
 
 ![Periodic Scheduler Diagram](./assets/updated-scheduler-diagram-periodic.png 'Periodic Scheduler Diagram')
@@ -34,11 +143,107 @@
 - 스케줄러 서비스는 Restful 기반의 수평 확장이 가능한 스케줄러 서비스.
 - MSA 기반의 어플리케이션 환경에서 기존 어플리케이션이 수행하는 스케줄링 모듈에 대해서, 별도의 스케줄링 서비스를 분리해서 제공하는 서비스를 제공합니다.
 
+## 🎯 사용 사례 및 모범 사례
+
+### 실시간 모니터링
+
+```json
+{
+  "name": "sensor-monitoring",
+  "client": {
+    "application": "iot-platform",
+    "group": "factory-001",
+    "type": "sensor",
+    "key": "temperature-sensor-01",
+    "operation": "monitor"
+  },
+  "type": "delay-recur",
+  "schedule": "30",
+  "timezone": "Asia/Seoul",
+  "task": {
+    "type": "rest",
+    "connection": {
+      "host": "http://localhost:3000/api/sensor/collect",
+      "headers": { "Content-Type": "application/json" }
+    },
+    "data": { "sensorId": "temp-001", "threshold": 25 },
+    "history_check": true,
+    "failed_policy": "retry_dlq",
+    "retry_wait": 60,
+    "max_retry_count": 3
+  }
+}
+```
+
+### 데이터 동기화
+
+```json
+{
+  "name": "data-sync",
+  "client": {
+    "application": "erp-system",
+    "group": "company-abc",
+    "type": "inventory",
+    "key": "daily-sync",
+    "operation": "sync"
+  },
+  "type": "cron",
+  "schedule": "0 2 * * *",
+  "timezone": "Asia/Seoul",
+  "task": {
+    "type": "kafka",
+    "connection": {
+      "host": "localhost:9092",
+      "topic": "inventory-sync"
+    },
+    "data": { "syncType": "full", "timestamp": "2024-01-01T02:00:00Z" },
+    "history_check": true,
+    "failed_policy": "retry_dlq",
+    "retry_wait": 300,
+    "max_retry_count": 5
+  }
+}
+```
+
+### 보고서 생성
+
+```json
+{
+  "name": "daily-report",
+  "client": {
+    "application": "analytics-platform",
+    "group": "marketing-team",
+    "type": "report",
+    "key": "daily-metrics",
+    "operation": "generate"
+  },
+  "type": "cron",
+  "schedule": "0 9 * * 1-5",
+  "timezone": "Asia/Seoul",
+  "task": {
+    "type": "rest",
+    "connection": {
+      "host": "http://localhost:3000/api/reports/generate",
+      "headers": { "Authorization": "Bearer ..." }
+    },
+    "data": { "reportType": "daily", "recipients": ["team@company.com"] },
+    "history_check": true,
+    "failed_policy": "retry",
+    "retry_wait": 1800,
+    "max_retry_count": 2
+  }
+}
+```
+
 ## 사용 가능한 용도
 
 - 크론(cron) 기반의 스케줄잡(Schedule Job) 핸들러
 - 특정한 날짜 혹은 특정한 주기로 실행되는 태스크 실행 엔진
 - 특정한 이벤트를 등록 관리하고, 이벤트를 기반으로 특정 기능을 실행하거나 데이터를 전달하는 브로커
+- **실시간 모니터링**: delay-recur를 사용한 짧은 간격의 연속 모니터링
+- **데이터 동기화**: 시스템 간의 주기적 데이터 동기화
+- **보고서 생성**: 자동화된 보고서 생성 및 배포
+- **IoT 디바이스 관리**: IoT 디바이스 통신 및 데이터 수집 관리
 
 ### Schedule
 
@@ -119,7 +324,6 @@
   ```
 
 - cron: cron format을 기반으로 스케줄이 동작합니다.
-
   - 기본적인 5개 포맷을 사용합니다.
   - 초 단위 스케줄리을 실행하기 위해서는 6개 시간 요소가 필요하면, 첫번째 요소가 초를 지정합니다.
 
@@ -183,3 +387,77 @@
     }
   }
   ```
+
+## 🔧 고급 설정
+
+### 재시도 정책
+
+#### ignore
+
+- 재시도 시도 없음
+- 중요하지 않은 작업에 적합
+
+#### retry
+
+- 지수 백오프를 통한 단순 재시도
+- 일시적 실패에 좋음
+
+#### retry_dlq
+
+- Dead Letter Queue 폴백을 통한 재시도
+- 데이터 보존이 필요한 중요 작업에 최적
+
+### 히스토리 체크 설정
+
+#### true
+
+- 중복 실행 방지
+- 실행 히스토리 유지
+- 데이터 수집 및 보고서에 적합
+
+#### false
+
+- 다중 실행 허용
+- 히스토리 추적 없음
+- 실시간 모니터링에 적합
+
+### 타임존 고려사항
+
+- **글로벌 배포**: 다중 타임존 지원
+- **업무 시간**: 현지 업무 시간 기준 스케줄 실행
+- **DST 처리**: 자동 일광절약시간 조정
+
+## 🚀 성능 최적화
+
+### 모범 사례
+
+1. **짧은 간격에는 delay-recur 사용**: 빈번한 작업에 cron보다 효율적
+2. **데이터 작업에는 history_check 구현**: 중복 데이터 처리 방지
+3. **적절한 재시도 정책 구성**: 신뢰성과 성능의 균형
+4. **타임존 인식 스케줄링 사용**: 정확한 실행 시간 보장
+5. **DLQ 모니터링**: 정기적으로 실패한 작업 확인 및 처리
+
+### 확장 고려사항
+
+- **수평 확장**: 여러 스케줄러 인스턴스가 동시에 실행 가능
+- **부하 분산**: 데이터베이스 기반 큐가 인스턴스 간 부하 분산
+- **장애 복구 지원**: 인스턴스 다운 시 자동 장애 복구
+- **리소스 관리**: 지능형 스케줄링을 통한 효율적인 리소스 활용
+
+## 🔍 모니터링 및 문제 해결
+
+### 모니터링해야 할 주요 지표
+
+- **실행 성공률**: 성공적인 작업 실행 비율
+- **재시도 빈도**: 작업당 재시도 횟수
+- **DLQ 크기**: Dead Letter Queue의 작업 수
+- **실행 시간**: 작업 완료 평균 시간
+- **스케줄 정확도**: 예상 실행 시간과의 편차
+
+### 일반적인 문제 및 해결책
+
+1. **높은 재시도율**: 네트워크 연결성 및 대상 서비스 가용성 확인
+2. **DLQ 오버플로우**: 실패한 작업 검토 및 근본 원인 수정
+3. **실행 누락**: 타임존 설정 및 스케줄 표현식 확인
+4. **성능 문제**: 빈번한 작업에는 delay-recur 사용 고려
+5. **중복 실행**: 적절한 작업에 history_check 활성화

package/helps/scheduler/scheduler.md

@@ -5,6 +5,115 @@
 - If an invoked event fails, it retries after a certain period, as defined by the policy.
 - To distribute the load of scheduler processing, a newly designed structure uses a database-based queue to manage all schedule data.
 
+## 🚀 Unique Features
+
+### 1. Five-Dimensional Client Identifier System
+
+The scheduler uses a unique 5-dimensional client identification system that goes beyond simple UUID-based identification:
+
+```json
+{
+  "client": {
+    "application": "data-collection-app",
+    "group": "domain-123",
+    "type": "data-set",
+    "key": "sensor-001",
+    "operation": "collect"
+  }
+}
+```
+
+**Key Benefits:**
+
+- **Business Context Awareness**: Identifiers reflect business meaning rather than technical IDs
+- **Duplicate Prevention**: Only schedules with all 5 elements matching are considered identical
+- **Natural Organization**: Hierarchical organization from application → group → type → key → operation
+- **Flexible Filtering**: Filter schedules by any combination of client properties
+
+### 2. Innovative Schedule Types
+
+#### delay-recur: Revolutionary Recurring Pattern
+
+```json
+{
+  "type": "delay-recur",
+  "schedule": "30",
+  "timezone": "UTC"
+}
+```
+
+- **Simple Recurrence**: 30-second intervals without complex cron expressions
+- **Real-time Optimization**: Perfect for monitoring, heartbeat, and data synchronization
+- **Resource Efficiency**: Lightweight compared to traditional cron-based approaches
+
+#### Comprehensive Schedule Type Support
+
+- **now**: Immediate execution
+- **delay**: One-time delayed execution
+- **date**: Specific date/time execution
+- **cron**: Traditional cron-based scheduling
+- **delay-recur**: Innovative recurring pattern
+
+### 3. Advanced Failure Handling
+
+#### retry_dlq: Hybrid Failure Policy
+
+```json
+{
+  "failed_policy": "retry_dlq",
+  "retry_wait": 60,
+  "max_retry_count": 3
+}
+```
+
+**Three-Stage Failure Handling:**
+
+1. **Immediate Retry**: Quick retry with exponential backoff
+2. **Maximum Retries**: Up to configured maximum attempts
+3. **Dead Letter Queue**: Failed tasks moved to DLQ for later processing
+
+**Benefits:**
+
+- **System Stability**: Prevents infinite retry loops
+- **Data Preservation**: No data loss even with failures
+- **Problem Diagnosis**: DLQ enables failure analysis
+
+### 4. History-Aware Scheduling
+
+#### history_check: Execution History Management
+
+```json
+{
+  "history_check": true
+}
+```
+
+**Features:**
+
+- **Duplicate Prevention**: Avoids re-executing already completed tasks
+- **State-Based Decisions**: Makes scheduling decisions based on execution history
+- **Audit Trail**: Complete execution history for compliance and debugging
+
+### 5. Domain-Aware Callback System
+
+#### Multi-Tenant Support
+
+```json
+{
+  "task": {
+    "connection": {
+      "host": "http://localhost:3000/domain/company/callback-schedule-for-dataset"
+    }
+  }
+}
+```
+
+**Benefits:**
+
+- **Tenant Isolation**: Each domain's schedules are processed independently
+- **Automatic URL Generation**: Domain context automatically included in callback URLs
+- **Security**: Domain-based access control and data isolation
+
 ### Diagram for Periodic Processing in the Scheduler
 
 ![Periodic Scheduler Diagram](./assets/updated-scheduler-diagram-periodic.png 'Periodic Scheduler Diagram')
@@ -24,7 +133,7 @@
 ![MSA Scheduler Service](./assets/scheduler-service-msa.png 'MSA Scheduler Service')
 
 - The traditional application structure for processing scheduling jobs cannot function in a cloud-based horizontal scaling architecture.
-- A separate scheduler service is needed. While there are many services for such tasks, there isn’t a dedicated service solely for the role of scheduling.
+- A separate scheduler service is needed. While there are many services for such tasks, there isn't a dedicated service solely for the role of scheduling.
 - A scalable service that can be horizontally expanded in a cloud environment is required.
 
 ## Service Overview
@@ -34,11 +143,107 @@
 - Scheduler service is a horizontally scalable scheduling service based on RESTful architecture.
 - It provides a service that separates scheduling modules from existing applications in MSA-based environments.
 
+## 🎯 Use Cases and Best Practices
+
+### Real-Time Monitoring
+
+```json
+{
+  "name": "sensor-monitoring",
+  "client": {
+    "application": "iot-platform",
+    "group": "factory-001",
+    "type": "sensor",
+    "key": "temperature-sensor-01",
+    "operation": "monitor"
+  },
+  "type": "delay-recur",
+  "schedule": "30",
+  "timezone": "Asia/Seoul",
+  "task": {
+    "type": "rest",
+    "connection": {
+      "host": "http://localhost:3000/api/sensor/collect",
+      "headers": { "Content-Type": "application/json" }
+    },
+    "data": { "sensorId": "temp-001", "threshold": 25 },
+    "history_check": true,
+    "failed_policy": "retry_dlq",
+    "retry_wait": 60,
+    "max_retry_count": 3
+  }
+}
+```
+
+### Data Synchronization
+
+```json
+{
+  "name": "data-sync",
+  "client": {
+    "application": "erp-system",
+    "group": "company-abc",
+    "type": "inventory",
+    "key": "daily-sync",
+    "operation": "sync"
+  },
+  "type": "cron",
+  "schedule": "0 2 * * *",
+  "timezone": "Asia/Seoul",
+  "task": {
+    "type": "kafka",
+    "connection": {
+      "host": "localhost:9092",
+      "topic": "inventory-sync"
+    },
+    "data": { "syncType": "full", "timestamp": "2024-01-01T02:00:00Z" },
+    "history_check": true,
+    "failed_policy": "retry_dlq",
+    "retry_wait": 300,
+    "max_retry_count": 5
+  }
+}
+```
+
+### Report Generation
+
+```json
+{
+  "name": "daily-report",
+  "client": {
+    "application": "analytics-platform",
+    "group": "marketing-team",
+    "type": "report",
+    "key": "daily-metrics",
+    "operation": "generate"
+  },
+  "type": "cron",
+  "schedule": "0 9 * * 1-5",
+  "timezone": "Asia/Seoul",
+  "task": {
+    "type": "rest",
+    "connection": {
+      "host": "http://localhost:3000/api/reports/generate",
+      "headers": { "Authorization": "Bearer ..." }
+    },
+    "data": { "reportType": "daily", "recipients": ["team@company.com"] },
+    "history_check": true,
+    "failed_policy": "retry",
+    "retry_wait": 1800,
+    "max_retry_count": 2
+  }
+}
+```
+
 ## Usable Scenarios
 
 - **Cron-Based Schedule Job Handlers**: For processing tasks at specific intervals.
 - **Task Execution Engines**: For executing tasks on specific dates or at specific intervals.
 - **Event-Driven Task Handlers**: For registering and managing events, and executing specific tasks or transferring data based on those events.
+- **Real-Time Monitoring**: For continuous monitoring with short intervals using delay-recur.
+- **Data Synchronization**: For periodic data synchronization between systems.
+- **Report Generation**: For automated report generation and distribution.
+- **IoT Device Management**: For managing IoT device communication and data collection.
 
 ### Schedule
 
@@ -119,7 +324,6 @@ An example of the format for registering a schedule is as follows:
   ```
 
 - **cron**: Operates based on the cron format.
-
   - Uses the basic five-element format.
   - For second-level schedules, a six-element format is required, where the first element specifies seconds.
 
@@ -184,3 +388,77 @@ An example of the format for registering a schedule is as follows:
     }
   }
   ```
+
+## 🔧 Advanced Configuration
+
+### Retry Policies
+
+#### ignore
+
+- No retry attempts
+- Suitable for non-critical tasks
+
+#### retry
+
+- Simple retry with exponential backoff
+- Good for transient failures
+
+#### retry_dlq
+
+- Retry with Dead Letter Queue fallback
+- Best for critical tasks requiring data preservation
+
+### History Check Configuration
+
+#### true
+
+- Prevents duplicate execution
+- Maintains execution history
+- Suitable for data collection and reporting
+
+#### false
+
+- Allows multiple executions
+- No history tracking
+- Suitable for real-time monitoring
+
+### Timezone Considerations
+
+- **Global Deployment**: Support for multiple timezones
+- **Business Hours**: Schedule execution based on local business hours
+- **DST Handling**: Automatic daylight saving time adjustments
+
+## 🚀 Performance Optimization
+
+### Best Practices
+
+1. **Use delay-recur for short intervals**: More efficient than cron for frequent tasks
+2. **Implement history_check for data tasks**: Prevents duplicate data processing
+3. **Configure appropriate retry policies**: Balance between reliability and performance
+4. **Use timezone-aware scheduling**: Ensure accurate execution times
+5. **Monitor DLQ**: Regularly check and process failed tasks
+
+### Scaling Considerations
+
+- **Horizontal Scaling**: Multiple scheduler instances can run simultaneously
+- **Load Distribution**: Database-based queue distributes load across instances
+- **Failover Support**: Automatic failover when instances go down
+- **Resource Management**: Efficient resource utilization through intelligent scheduling
+
+## 🔍 Monitoring and Troubleshooting
+
+### Key Metrics to Monitor
+
+- **Execution Success Rate**: Percentage of successful task executions
+- **Retry Frequency**: Number of retries per task
+- **DLQ Size**: Number of tasks in Dead Letter Queue
+- **Execution Time**: Average time for task completion
+- **Schedule Accuracy**: Deviation from expected execution times
+
+### Common Issues and Solutions
+
+1. **High Retry Rate**: Check network connectivity and target service availability
+2. **DLQ Overflow**: Review failed tasks and fix underlying issues
+3. **Missed Executions**: Verify timezone settings and schedule expressions
+4. **Performance Issues**: Consider using delay-recur for frequent tasks
+5. **Duplicate Executions**: Enable history_check for appropriate tasks