@things-factory/scheduler 9.0.2 → 9.0.5

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.2",
+  "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": "5cf452159e611eea93c23010706ecfc6543405ba"
+  "gitHead": "da760d5cf77e2495da74360b1cdc1f99f13bb65f"
 }