Cài đặt và sử dụng — Data Visualization

Tổng quan

Plugin data-visualization cung cấp khả năng trực quan hóa dữ liệu từ các collection trong hệ thống. Hỗ trợ nhiều loại biểu đồ (bar, line, pie, area...) được render bằng G2Plot hoặc ECharts, tích hợp trực tiếp vào trang dưới dạng block.

Yêu cầu hệ thống

Thành phần	Yêu cầu
Server Digiforce	Phiên bản >= 1.0
Database	PostgreSQL, MySQL, SQLite hoặc MariaDB
Plugin phụ thuộc	`plugin-acl` (kiểm tra quyền), `plugin-data-source-main`

Bước 1: Kích hoạt plugin

Truy cập Settings → Plugin Manager
Tìm plugin-data-visualization
Bật công tắc Enable
Khởi động lại server nếu hệ thống yêu cầu

Khi kích hoạt, plugin đăng ký resource charts với action queryData — cho phép giao diện gửi truy vấn lấy dữ liệu biểu đồ.

Bước 2: Thêm biểu đồ vào trang

Mở trang cần thêm biểu đồ (hoặc tạo trang mới)
Nhấn Add block → Chart
Hệ thống hiển thị Chart Block Designer — giao diện thiết kế biểu đồ

Bước 3: Cấu hình truy vấn dữ liệu

Trong Chart Block Designer, bạn cần cấu hình:

Chọn nguồn dữ liệu

Trường	Mô tả
Data source	Chọn data source (mặc định: `main`)
Collection	Chọn collection chứa dữ liệu

Cấu hình Measures (Số liệu)

Measures là các trường số liệu cần tổng hợp:

Thuộc tính	Mô tả	Ví dụ
Field	Trường dữ liệu	`amount`, `quantity`
Aggregation	Hàm tổng hợp	`sum`, `count`, `avg`, `min`, `max`
Alias	Tên hiển thị	`Tổng doanh thu`
Distinct	Đếm/tổng hợp giá trị duy nhất	`true` / `false`

Các hàm aggregation được hỗ trợ

sum — Tổng | count — Đếm | avg — Trung bình | min — Nhỏ nhất | max — Lớn nhất

Cấu hình Dimensions (Chiều phân tích)

Dimensions là các trường dùng để nhóm/phân loại dữ liệu:

Thuộc tính	Mô tả	Ví dụ
Field	Trường phân nhóm	`status`, `category`, `createdAt`
Format	Định dạng (cho date/time)	`YYYY-MM`, `YYYY-Q`
Alias	Tên hiển thị	`Tháng`

Bộ lọc (Filter)

Thêm điều kiện lọc dữ liệu cho biểu đồ. Hỗ trợ đầy đủ các filter operator của Digiforce ($eq, $gt, $lt, $in, v.v.) và template variables (biến ngữ cảnh).

Sắp xếp (Order)

Thuộc tính	Mô tả
Field	Trường sắp xếp
Order	`ASC` (tăng dần) hoặc `DESC` (giảm dần)
Nulls	`first` (giá trị null lên đầu) hoặc `last` (null xuống cuối)

Giới hạn (Limit)

Mặc định trả về tối đa 2000 bản ghi. Có thể điều chỉnh qua tham số limit và offset.

Bước 4: Chọn loại biểu đồ

Loại biểu đồ	Mô tả	Phù hợp cho
Bar	Biểu đồ cột dọc/ngang	So sánh giá trị giữa các nhóm
Line	Biểu đồ đường	Xu hướng theo thời gian
Pie	Biểu đồ tròn	Tỷ lệ phần trăm
Area	Biểu đồ vùng	Xu hướng với tổng tích lũy
Table	Bảng thống kê	Dữ liệu chi tiết dạng bảng

Plugin hỗ trợ hai thư viện render:

G2Plot: Đơn giản, dễ sử dụng, phù hợp cho biểu đồ cơ bản
ECharts: Tùy biến cao, phù hợp cho biểu đồ phức tạp

Cơ chế Cache

Plugin tích hợp hệ thống cache để tối ưu hiệu năng:

Tham số	Mô tả	Mặc định
enabled	Bật/tắt cache cho biểu đồ	`false`
ttl	Thời gian cache sống (giây)	`30`

Khi cache được bật:

Kết quả query được lưu trong memory cache (tối đa 1000 entries)
Request trùng uid sẽ trả về kết quả từ cache
Nhấn Refresh trên biểu đồ để bỏ qua cache và query lại

Tạo Dashboard

Để tạo dashboard hoàn chỉnh:

Tạo một trang mới (Add page)
Thêm nhiều Chart block với các biểu đồ khác nhau
Kết hợp với Filter block để lọc dữ liệu chung cho tất cả biểu đồ trên trang
Sắp xếp bố cục bằng kéo thả

Hỗ trợ nhiều Database Dialect

Plugin có query parser riêng cho mỗi loại database:

Database	Parser	Date formatting	Đặc biệt
PostgreSQL	`postgres`	Hỗ trợ đầy đủ	`TO_CHAR`, `DATE_TRUNC`
MySQL	`mysql`	Hỗ trợ đầy đủ	`DATE_FORMAT`
SQLite	`sqlite`	Hạn chế	`strftime`
Oracle	`oracle`	Hỗ trợ đầy đủ	`TO_CHAR`, `TRUNC`

Kiểm tra quyền truy cập

Mỗi truy vấn biểu đồ đều được kiểm tra quyền qua plugin-acl:

User phải đăng nhập (loggedIn)
Quyền đọc trên collection được kiểm tra
Nếu không có quyền, trả về HTTP 403

Lưu ý

Đây là plugin cơ bản. Để có biểu đồ nâng cao (funnel, radar, heatmap, SQL mode), cài thêm plugin-data-visualization-pro
Mỗi biểu đồ kết nối đến một collection duy nhất
Hiệu năng phụ thuộc vào lượng dữ liệu và index trong database
Nên bật cache cho biểu đồ có lượng dữ liệu lớn và không yêu cầu real-time