@digiforce-nc/plugin-workflow-aggregate

Plugin đăng ký node tính toán tổng hợp (aggregate) trong workflow, mở rộng plugin-workflow. Thực hiện các phép tính count, sum, avg, min, max trên collection dữ liệu ngay trong luồng xử lý.

Plugin này làm gì?

Node Aggregate truy vấn dữ liệu từ một collection, áp dụng filter, rồi tính toán giá trị tổng hợp. Kết quả được lưu vào biến workflow để các node tiếp theo sử dụng cho logic điều kiện hoặc hiển thị.

Phép tính được thực thi ở tầng SQL (database aggregate function), không load toàn bộ dữ liệu vào memory - đảm bảo hiệu suất ngay cả với collection lớn.

Cấu hình

Tham số	Kiểu	Mô tả
`collection`	`string`	Collection cần tính toán tổng hợp
`aggregator`	`string`	Phép tính: `count`, `sum`, `avg`, `min`, `max`
`field`	`string`	Field tính toán (bắt buộc với sum, avg, min, max)
`filter`	`object`	Điều kiện lọc dữ liệu trước khi tính
`associated`	`boolean`	Tính trên dữ liệu association thay vì toàn bộ collection
`params`	`object`	Tham số bổ sung cho query

Input / Output

Hướng	Dữ liệu	Mô tả
Input	`collection`	Tên collection nguồn
Input	`filter`	Điều kiện lọc (hỗ trợ biến workflow trong filter)
Output	`result`	Giá trị tổng hợp (number)
Output	`dataType`	Kiểu dữ liệu kết quả: integer hoặc double

Tính năng chính

#	Tính năng	Chi tiết
1	5 phép tính	count, sum, avg, min, max - đáp ứng mọi nhu cầu thống kê
2	Filter linh hoạt	Lọc dữ liệu bằng điều kiện phức tạp trước khi tính
3	Biến động trong filter	Sử dụng biến từ node trước trong điều kiện lọc
4	Association	Tính toán trên dữ liệu quan hệ (hasMany, belongsToMany)
5	Hiệu suất cao	Sử dụng SQL aggregate thay vì load toàn bộ dữ liệu

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

#	Kịch bản	Mô tả
1	Đếm đơn hàng	Đếm số đơn hàng pending của khách hàng để quyết định ưu tiên
2	Tổng doanh thu	Tính sum trên field `amount` để kiểm tra ngưỡng phê duyệt
3	Trung bình đánh giá	Tính avg rating sản phẩm để tự động đánh dấu hot/trending
4	Kiểm tra tồn kho	Tính min stock để cảnh báo hết hàng
5	Giá trị cao nhất	Tính max trên field `bid` trong phiên đấu giá

Các phép tính hỗ trợ

Phép tính	Ý nghĩa	Yêu cầu field	Ví dụ kết quả
`count`	Đếm số bản ghi	Không	42
`sum`	Tổng giá trị	Có (kiểu số)	1500000
`avg`	Trung bình cộng	Có (kiểu số)	35000.5
`min`	Giá trị nhỏ nhất	Có	100
`max`	Giá trị lớn nhất	Có	999999

Lưu ý quan trọng

Với count, không cần chỉ định field - đếm tất cả bản ghi khớp filter
Với sum, avg, min, max - bắt buộc chỉ định field kiểu số
Filter hỗ trợ tất cả toán tử của collection filter: $eq, $gt, $lt, $in, ...
Kết quả avg trả về kiểu double, các phép tính khác trả về integer (trừ sum trên field decimal)
Nếu không có bản ghi nào khớp filter: count = 0, sum = 0, avg/min/max = null

Dependencies

Package	Vai trò
`@digiforce-nc/plugin-workflow`	Workflow engine (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/database`	Database ORM - thực thi aggregate query (peer)