@digiforce-nc/plugin-data-visualization

Plugin BI charts — truy vấn dữ liệu từ collection, render thành biểu đồ (G2Plot, ECharts) trực tiếp trên trang.

Plugin này làm gì?

Hãy hình dung một bảng điều khiển dashboard trong phòng chỉ huy: dữ liệu thô từ các collection được chuyển thành biểu đồ trực quan — cột, đường, tròn, phễu — giúp ra quyết định nhanh mà không cần mở bảng tính.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Truy vấn dữ liệu	Xây query từ collection với measures, dimensions, filters — hỗ trợ nhiều DB dialect
2	Render biểu đồ	Chuyển kết quả thành chart qua G2Plot hoặc ECharts, tuỳ loại biểu đồ
3	Nhúng vào trang	`ChartBlock` cho phép kéo-thả biểu đồ vào bất kỳ page nào, kết hợp filter block

Kiến trúc

Tổng quan 4 tầng

Tầng	Vai trò	Thành phần
Client UI	Cấu hình chart, render biểu đồ	`ChartBlock`, `ChartBlockDesigner`, renderers
Server API	Xử lý query, trả dữ liệu	`charts` resource, query parsers
Database	Nguồn dữ liệu	Đọc từ các collection hiện có
Cache	Tối ưu hiệu suất	Cache kết quả query

API endpoints

Endpoint	Method	Mô tả
`charts:queryData`	POST	Truy vấn dữ liệu cho biểu đồ

Payload mẫu:

json

{
  "dataSource": "main",
  "collection": "orders",
  "measures": [{ "field": "amount", "aggregation": "sum" }],
  "dimensions": [{ "field": "status" }],
  "filter": { "createdAt": { "$gte": "2024-01-01" } }
}

Query Parsers

Mỗi loại database có parser riêng để chuyển query options thành SQL/query tương ứng:

DB Dialect	Parser	Ghi chú
PostgreSQL	`postgres`	Hỗ trợ đầy đủ aggregation, date functions
MySQL	`mysql`	Hỗ trợ đầy đủ
SQLite	`sqlite`	Hạn chế một số date function
MariaDB	`mariadb`	Tương tự MySQL

Database

Plugin này không tạo bảng riêng — nó đọc dữ liệu từ các collection có sẵn trong hệ thống. Cấu hình chart được lưu trong UI schema.

Thành phần client

Thành phần	Mô tả
`ChartBlock`	Block hiển thị biểu đồ trên page
`ChartBlockDesigner`	Giao diện thiết kế biểu đồ (chọn collection, measures, dimensions)
`G2PlotRenderer`	Render biểu đồ bằng G2Plot (bar, line, pie, area...)
`EChartsRenderer`	Render biểu đồ bằng ECharts (phức tạp hơn, tuỳ biến cao)
`QueryBuilder`	Form xây dựng truy vấn trực quan
`SQLEditor`	Editor SQL thủ công cho truy vấn nâng cao
Filter blocks	Bộ lọc liên kết với chart để lọc dữ liệu động

Dependencies

Package	Vai trò
`@digiforce-nc/cache`	Cache kết quả query (peer)
`@digiforce-nc/database`	Database ORM (peer)
`@digiforce-nc/plugin-data-source-main`	Data source chính
`@digiforce-nc/plugin-ai`	Hỗ trợ tạo chart bằng AI prompt
`@digiforce-nc/client`	Client framework (peer)