@digiforce-nc/plugin-workflow-delay

Plugin đăng ký node trì hoãn (delay) trong workflow, mở rộng plugin-workflow. Tạm dừng workflow trong khoảng thời gian cố định hoặc đến một thời điểm cụ thể trước khi tiếp tục.

Plugin này làm gì?

Node Delay tạm dừng luồng workflow trong một khoảng thời gian. Hỗ trợ hai chế độ: trì hoãn cố định (ví dụ: 5 phút) hoặc chờ đến thời điểm cụ thể (ví dụ: 9:00 sáng ngày mai). Sau khi hết thời gian, workflow tự động tiếp tục.

Delay job được lưu vào database - đảm bảo không bị mất khi server restart. Scheduler kiểm tra định kỳ và resume workflow đúng thời điểm.

Cấu hình

Tham số	Kiểu	Mô tả
`mode`	`string`	`duration` (khoảng thời gian) hoặc `datetime` (thời điểm cụ thể)
`duration`	`number`	Thời gian trì hoãn (dùng khi mode = duration)
`unit`	`string`	Đơn vị: `seconds`, `minutes`, `hours`, `days`
`datetime`	`string`	Thời điểm đích (dùng khi mode = datetime)
`endOn`	`object`	Biến workflow chứa thời điểm đích (thay cho datetime cố định)

Input / Output

Hướng	Dữ liệu	Mô tả
Input	`duration / datetime`	Thời gian chờ hoặc thời điểm đích
Input	`context`	Context workflow được giữ nguyên qua delay
Output	`resumedAt`	Thời điểm thực tế workflow tiếp tục
Output	`context`	Context workflow (không thay đổi)

Tính năng chính

#	Tính năng	Chi tiết
1	Fixed duration	Trì hoãn khoảng thời gian cố định (giây, phút, giờ, ngày)
2	Target datetime	Chờ đến thời điểm cụ thể
3	Dynamic datetime	Lấy thời điểm đích từ biến workflow
4	Persistent	Delay được lưu vào DB, app restart không mất job
5	Chính xác	Sử dụng scheduler đảm bảo trigger đúng thời điểm

Trường hợp sử dụng

#	Kịch bản	Mô tả
1	Nhắc nhở sau X phút	Delay 30 phút rồi gửi reminder nếu chưa xử lý
2	Gửi email sáng mai	Delay đến 9:00 ngày tiếp theo rồi gửi email tổng hợp
3	Cooling period	Delay 24h trước khi xóa tài khoản vĩnh viễn
4	Scheduled publish	Delay đến thời điểm publish đã cấu hình trên bản ghi
5	Retry với backoff	Delay tăng dần (1s, 5s, 30s) giữa các lần retry

So sánh hai chế độ delay

Đặc điểm	Duration	Datetime
Tính từ	Thời điểm node chạy	Thời điểm cố định
Ví dụ	"sau 30 phút"	"lúc 9:00 ngày mai"
Dynamic	Chỉ duration	Từ biến workflow
Phù hợp	Reminder, retry	Scheduled tasks

Lưu ý quan trọng

Delay job lưu trong DB - restart server sẽ reschedule tất cả pending delays
Thời gian thực tế resume có thể trễ vài giây so với cấu hình (do polling interval)
Không nên dùng delay quá ngắn (dưới 1 giây) - dùng node khác thay thế
Mode datetime sử dụng timezone server, cẩn thận khi deploy multi-region
Workflow state (biến, context) được serialize và lưu DB, đảm bảo toàn vẹn qua delay

Dependencies

Package	Vai trò
`@digiforce-nc/plugin-workflow`	Workflow engine (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/database`	Database - lưu trữ delay job (peer)