@digiforce-nc/plugin-workflow-dynamic-calculation

Plugin đăng ký node tính toán động trong workflow, mở rộng plugin-workflow. Thực thi biểu thức hoặc công thức tại runtime bằng evaluator engine, cho phép tính toán phức tạp dựa trên dữ liệu workflow.

Plugin này làm gì?

Node Dynamic Calculation nhận một biểu thức (expression) hoặc công thức (formula) và tính toán giá trị tại runtime. Biểu thức có thể tham chiếu biến workflow, dữ liệu bản ghi, kết quả node trước. Sử dụng evaluator engine để đảm bảo an toàn và hiệu suất.

So với Simple Function (biểu thức đơn giản), Dynamic Calculation hỗ trợ:

Nhiều evaluator engine (math.js, formula.js, built-in)
Biểu thức phức tạp hơn với hàm toán học, chuỗi, logic
Scope mapping linh hoạt giữa biến workflow và biến trong biểu thức

Cấu hình

Tham số	Kiểu	Mô tả
`engine`	`string`	Evaluator sử dụng: `math.js`, `formula.js`, hoặc built-in
`expression`	`string`	Biểu thức tính toán (ví dụ: `price * quantity * (1 - discount)`)
`scope`	`object`	Mapping tên biến trong biểu thức sang giá trị từ workflow
`outputType`	`string`	Kiểu kết quả mong muốn: `number`, `string`, `boolean`

Input / Output

Hướng	Dữ liệu	Mô tả
Input	`expression`	Biểu thức cần tính toán
Input	`scope variables`	Giá trị các biến tham chiếu trong biểu thức
Output	`result`	Kết quả tính toán
Output	`type`	Kiểu dữ liệu kết quả thực tế

Tính năng chính

#	Tính năng	Chi tiết
1	Biểu thức linh hoạt	Viết biểu thức toán học, logic, chuỗi tùy ý
2	Nhiều evaluator	Hỗ trợ math.js, formula.js, built-in
3	Scope mapping	Map biến workflow vào tên biến trong biểu thức
4	An toàn	Evaluator sandbox, không truy cập hệ thống
5	Type casting	Tự động ép kiểu kết quả theo outputType

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

#	Kịch bản	Mô tả
1	Tính tổng đơn hàng	`sum(items.price * items.qty) + shippingFee - coupon`
2	Tính hoa hồng	`revenue * commissionRate` với rate từ cấu hình role
3	Điểm ưu tiên	`age * 0.3 + orderCount * 0.5 + loyaltyYears * 0.2`
4	Phân loại	`score >= 80 ? "A" : score >= 60 ? "B" : "C"`
5	Lãi suất kép	`principal * pow(1 + rate/12, months) - principal`

So sánh với các node tính toán khác

Đặc điểm	Simple Function	Dynamic Calculation	JavaScript
Độ phức tạp	Thấp	Trung bình	Cao
UI	Biểu thức đơn	Biểu thức + scope	Code editor
Engine	Built-in	math.js, formula.js	VM sandbox
Phù hợp	Phép tính đơn giản	Công thức phức tạp	Logic tùy ý

Lưu ý quan trọng

Chọn engine phù hợp: math.js cho phép tính phức tạp, built-in cho biểu thức đơn giản
Biến scope phải được khai báo đầy đủ - biến không tồn tại sẽ gây lỗi runtime
Kết quả chia cho 0 trả về Infinity hoặc NaN tùy engine - cần xử lý trong node sau
Biểu thức quá phức tạp có thể ảnh hưởng hiệu suất - cân nhắc dùng JavaScript node
Type casting có thể mất dữ liệu: number sang string OK, string sang number có thể NaN

Dependencies

Package	Vai trò
`@digiforce-nc/plugin-workflow`	Workflow engine (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/evaluators`	Evaluator engine (peer)