@things-factory/scheduler 9.0.3 → 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

package/helps/scheduler/scheduler.zh.md

@@ -1,50 +1,255 @@
-# 스케줄러 서비스
+# 调度器服务
 
-- Scheduler에 등록되는 모든 이벤트들은 cron을 포함한 여러 형태의 스케줄 타입 및 값이 지정
-- 사용자가 지정한 스케줄 형태에 따라서 이벤트가 호출되며, 일반적으로 호출된 이벤트는 사용자가 등록 시에 지정한 rest api를 호출
-- 호출된 이벤트가 실패할 경우 정책에 따라서 일정 시간 이후 재시도 수행
-- 스케줄러 처리의 부하를 분산하기 위해서 새롭게 설계된 구조로서 스케줄러는 데이터베이스 기반의 큐 구조를 사용하여 모든 스케줄 데이터를 관리
+- 在调度器中注册的所有事件都使用各种调度类型和值（包括cron）进行指定
+- 根据用户指定的调度类型调用事件，通常调用的事件会调用注册时指定的REST API
+- 如果调用的事件失败，会根据策略在特定时间后重试
+- 为了分散调度器处理的负载，新设计的结构使用基于数据库的队列来管理所有调度数据
 
-### 스케줄러의 주기적 처리에 대한 Diagram
+## 🚀 独特功能
+
+### 1. 五维客户端标识符系统
+
+调度器使用独特的五维客户端标识系统，超越了简单的基于UUID的标识：
+
+```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"
+}
+```
+
+- **简单重复**：30秒间隔，无需复杂的cron表达式
+- **实时优化**：完美适用于监控、心跳和数据同步
+- **资源效率**：比传统的基于cron的方法更轻量
+
+#### 全面的调度类型支持
+
+- **now**：立即执行
+- **delay**：一次性延迟执行
+- **date**：特定日期/时间执行
+- **cron**：传统的基于cron的调度
+- **delay-recur**：创新的重复模式
+
+### 3. 高级失败处理
+
+#### retry_dlq：混合失败策略
+
+```json
+{
+  "failed_policy": "retry_dlq",
+  "retry_wait": 60,
+  "max_retry_count": 3
+}
+```
+
+**三阶段失败处理：**
+
+1. **立即重试**：通过指数退避进行快速重试
+2. **最大重试**：最多配置的最大尝试次数
+3. **死信队列**：失败的任务移动到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中
+- **安全性**：基于域的访问控制和数据隔离
+
+### 调度器周期性处理的图表
 
 ![Periodic Scheduler Diagram](./assets/updated-scheduler-diagram-periodic.png 'Periodic Scheduler Diagram')
 
-- 구조가 간결하고 추가적인 다른 서비스 없이 운용 가능하다는 점이 장점
-- 각 인스턴스가 휴지 기간 없이 주기적으로 깨어나서 데이터베이스 내에 스케줄 큐를 확인해야 한다는 점이 단점.
+- **优势**：结构简单，无需额外服务即可运行
+- **劣势**：每个实例必须周期性唤醒并检查数据库中的调度队列，无空闲期
 
-### (대안) 스케줄러의 깨어나는 시점을 또다른 모니터링 인스턴스가 주기적으로 확인해서 모든 스케줄러에게 Publish하는 구조
+### 替代方案：监控实例周期性检查调度器唤醒时间并向所有调度器发布的结构
 
 ![Pubsub Scheduler Diagram](./assets/updated-scheduler-diagram-pubsub.png 'Pubsub Scheduler Diagram')
 
-- 모든 인스턴스는 모니터링 인스턴스를 통해서 받는 다음 스케줄의 타임스탬프 정보에 의해서 스케줄 처리를 수행.
-- 추가적인 서비스(redis) 필요하며, 개별 인스턴스는 지속적으로 다음 스케줄에 대한 정보를 가지고 있어야 함.
+- 所有实例基于从监控实例接收的下一个调度时间戳信息处理调度
+- **要求**：需要额外服务（如Redis），每个实例必须持续持有下一个调度的信息
 
-## MSA 기반의 스케줄러 서비스
+## MSA中的调度器服务
 
 ![MSA Scheduler Service](./assets/scheduler-service-msa.png 'MSA Scheduler Service')
 
-- 기존의 어플리케이션 구조에서 스케줄링 잡을 처리하는 스케줄러 서비스가 클라우드 기반의 수평 스케일링 구조에서 기능 수행이 불가능.
-- 별도의 스케줄러 서비스가 필요. 이러한 스케줄 작업을 수행하는 서비스는 다수 존재하지만 스케줄러 역할만을 수행하는 분리된 서비스가 없음.
-- 클라우드 환경에서 사용 가능한 수평적인 확장이 가능한 서비스 개발이 필요.
+- 传统应用程序结构中处理调度作业的调度器服务无法在基于云的水平扩展架构中运行
+- 需要单独的调度器服务。虽然有许多此类任务的服务，但没有专门仅用于调度角色的服务
+- 需要可在云环境中水平扩展的可扩展服务
 
-## 서비스 개요
+## 服务概述
 
 ![Scalable Scheduler Service](./assets/scheduler-service-scalable.png 'Scalable Scheduler Service')
 
-- 스케줄러 서비스는 Restful 기반의 수평 확장이 가능한 스케줄러 서비스.
-- MSA 기반의 어플리케이션 환경에서 기존 어플리케이션이 수행하는 스케줄링 모듈에 대해서, 별도의 스케줄링 서비스를 분리해서 제공하는 서비스를 제공합니다.
+- 调度器服务是基于RESTful架构的水平可扩展调度服务
+- 它提供了一种服务，在基于MSA的应用程序环境中将调度模块与现有应用程序分离
 
-## 사용 가능한 용도
+## 🎯 使用案例和最佳实践
 
-- 크론(cron) 기반의 스케줄잡(Schedule Job) 핸들러
-- 특정한 날짜 혹은 특정한 주기로 실행되는 태스크 실행 엔진
-- 특정한 이벤트를 등록 관리하고, 이벤트를 기반으로 특정 기능을 실행하거나 데이터를 전달하는 브로커
+### 实时监控
 
-### Schedule
+```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
+  }
+}
+```
+
+### 数据同步
 
-#### Format
+```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的调度作业处理器**：用于在特定间隔处理任务
+- **任务执行引擎**：用于在特定日期或特定间隔执行任务
+- **事件驱动的任务处理器**：用于注册和管理事件，并基于这些事件执行特定任务或传输数据
+- **实时监控**：使用delay-recur进行短间隔的连续监控
+- **数据同步**：系统间的周期性数据同步
+- **报告生成**：自动化报告生成和分发
+- **IoT设备管理**：管理IoT设备通信和数据收集
+
+### 调度
+
+#### 格式
+
+注册调度的格式示例如下：
 
 ```json
 {
@@ -73,28 +278,28 @@
 }
 ```
 
-- name: 스케줄의 이름
-- client: 클라이언트 정보를 표현합니다. 실제 스케줄은 5개의 요소가 모두 일치할 때 동일한 스케줄로 인식
-  - operation: 공정과 같은 별도의 스케줄 용도를 표현
-  - application: 클라이언트 어플리케이션 이름
-  - group: 도메인 정보
-  - key: 스케줄 구분을 위한 별도의 키
-  - 타입: 해당 스케줄 자체에 대한 리소스 타입
-- type: 스케줄 타입으로서 크게, cron, now, date, delay, delay-recur으로 구성됩니다. 자세한 설명은 다음 항목을 참조
-- schedule: 스케줄 타입에 따라 별도의 문자열이 지정됩니다. 자세한 설명은 아래 'Scheduler Type'을 참조.
-- timezone: 스케줄 처리를 위한 타임존 문자열(예. Asiz/Seoul)을 지정.
-- task: 해당 스케줄이 처리되어야할 때 필요한 태스크 정보를 포함.
-  - type: 태스크의 타입으로서, 크게 rest, kafka, redis 중 하나를 지정. rest의 경우 post만 지원합니다.
-  - connection: 해당 태스크가 수행되기 위한 연결 정보
-    - host: 서버 연결 정보
-    - topic: kafka와 redis 타입일 때 지정.
-    - headers: rest 타입일 경우 선택적으로 지정.
-  - data: 해당 태스크 수행 시 전달되어야 하는데이터를 지정
-  - history_check: 스케줄의 등록, 실행, 삭제, 재실행에 대한 히스토리를 별도의 DB에 저장.
-
-### Schedule Type
-
-- delay: 특정한 시간(초) 동안 대기 후에 스케줄을 실행합니다.
+- **name**：调度的名称
+- **client**：表示客户端信息。只有当所有五个元素都匹配时，调度才被认为是相同的
+  - **operation**：表示特定的调度目的，如流程
+  - **application**：客户端应用程序的名称
+  - **group**：域信息
+  - **key**：用于调度区分的单独密钥
+  - **type**：调度本身的资源类型
+- **type**：主要类型包括`cron`、`now`、`date`、`delay`和`delay-recur`。详细描述请参阅"调度器类型"部分
+- **schedule**：根据调度类型指定的字符串。详情请参阅"调度器类型"
+- **timezone**：用于调度处理的时区字符串（如`Asia/Seoul`）
+- **task**：包含调度触发时需要执行的必要任务信息
+  - **type**：指定任务类型，如`rest`、`kafka`或`redis`。对于`rest`，仅支持POST
+  - **connection**：任务执行的连接信息
+    - **host**：服务器连接信息
+    - **topic**：用于`kafka`和`redis`类型
+    - **headers**：对于`rest`类型可选
+  - **data**：指定任务执行期间要传递的数据
+  - **history_check**：在单独的数据库中保存调度注册、执行、删除和重新执行的历史记录
+
+### 调度类型
+
+- **delay**：等待特定时间（秒）后执行调度
 
   ```json
   {
@@ -106,7 +311,7 @@
   }
   ```
 
-- delay-recur: 특정 시간(초) 동안 대기 후에 실행되는 스케줄을 반복 합니다.
+- **delay-recur**：等待特定时间（秒）后重复执行调度
 
   ```json
   {
@@ -118,10 +323,9 @@
   }
   ```
 
-- cron: cron format을 기반으로 스케줄이 동작합니다.
-
-  - 기본적인 5개 포맷을 사용합니다.
-  - 초 단위 스케줄리을 실행하기 위해서는 6개 시간 요소가 필요하면, 첫번째 요소가 초를 지정합니다.
+- **cron**：基于cron格式运行
+  - 使用基本的五元素格式
+  - 对于秒级调度，需要六元素格式，其中第一个元素指定秒
 
   ```json
   {
@@ -133,7 +337,7 @@
   }
   ```
 
-- date: 특정한 일자 및 시간을 지정.(ISO 포맷, YYYY-MM-DDThh:mm:ss)
+- **date**：指定特定日期和时间（ISO格式，`YYYY-MM-DDThh:mm:ss`）
 
   ```json
   {
@@ -145,7 +349,8 @@
   }
   ```
 
-- now: 바로 지금 해당 스케줄을 실행
+- **now**：立即执行调度
+
   ```json
   {
     ...
@@ -156,9 +361,9 @@
   }
   ```
 
-### Task Type
+### 任务类型
 
-- Rest
+- **Rest**
 
   ```json
   {
@@ -171,7 +376,7 @@
   }
   ```
 
-- Kafka & Redis
+- **Kafka & Redis**
 
   ```json
   {
@@ -183,3 +388,77 @@
     }
   }
   ```
+
+## 🔧 高级配置
+
+### 重试策略
+
+#### ignore
+
+- 无重试尝试
+- 适用于非关键任务
+
+#### retry
+
+- 带指数退避的简单重试
+- 适用于临时失败
+
+#### retry_dlq
+
+- 带死信队列回退的重试
+- 最适合需要数据保护的关键任务
+
+### 历史检查配置
+
+#### true
+
+- 防止重复执行
+- 维护执行历史
+- 适用于数据收集和报告
+
+#### false
+
+- 允许多次执行
+- 无历史跟踪
+- 适用于实时监控
+
+### 时区考虑
+
+- **全球部署**：支持多时区
+- **营业时间**：基于当地营业时间的调度执行
+- **DST处理**：自动夏令时调整
+
+## 🚀 性能优化
+
+### 最佳实践
+
+1. **对短间隔使用delay-recur**：比cron更高效用于频繁任务
+2. **对数据任务实现history_check**：防止重复数据处理
+3. **配置适当的重试策略**：平衡可靠性和性能
+4. **使用时区感知调度**：确保准确的执行时间
+5. **监控DLQ**：定期检查和处理失败的任务
+
+### 扩展考虑
+
+- **水平扩展**：多个调度器实例可以同时运行
+- **负载分布**：基于数据库的队列在实例间分布负载
+- **故障转移支持**：实例宕机时自动故障转移
+- **资源管理**：通过智能调度实现高效的资源利用
+
+## 🔍 监控和故障排除
+
+### 要监控的关键指标
+
+- **执行成功率**：成功任务执行的百分比
+- **重试频率**：每个任务的重试次数
+- **DLQ大小**：死信队列中的任务数量
+- **执行时间**：任务完成的平均时间
+- **调度准确性**：与预期执行时间的偏差
+
+### 常见问题和解决方案
+
+1. **高重试率**：检查网络连接和目标服务可用性
+2. **DLQ溢出**：审查失败的任务并修复根本原因
+3. **执行遗漏**：验证时区设置和调度表达式
+4. **性能问题**：考虑对频繁任务使用delay-recur
+5. **重复执行**：对适当的任务启用history_check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/scheduler",
-  "version": "9.0.3",
+  "version": "9.0.5",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -29,9 +29,9 @@
   "dependencies": {
     "@operato/graphql": "^9.0.0",
     "@operato/shell": "^9.0.0",
-    "@things-factory/auth-base": "^9.0.2",
-    "@things-factory/scheduler-client": "^9.0.2",
-    "@things-factory/shell": "^9.0.0"
+    "@things-factory/auth-base": "^9.0.5",
+    "@things-factory/scheduler-client": "^9.0.5",
+    "@things-factory/shell": "^9.0.5"
   },
-  "gitHead": "38583ad6c3eab8533e0602e81c8d8ca64ef12f1d"
+  "gitHead": "da760d5cf77e2495da74360b1cdc1f99f13bb65f"
 }