@digiforce-nc/plugin-block-tree

Plugin hiển thị dữ liệu phân cấp dưới dạng cây (Tree) - phù hợp cho danh mục phòng ban, thư mục, phân loại sản phẩm, hoặc bất kỳ cấu trúc cha-con nào.

Plugin này làm gì?

Nhiều loại dữ liệu có cấu trúc phân cấp: phòng ban trong công ty, danh mục sản phẩm, thư mục tài liệu. Tree block hiển thị dữ liệu này dưới dạng cây có thể mở rộng/thu gọn, và đặc biệt hữu ích khi kết hợp làm filter block - click vào node trên cây để lọc dữ liệu trên block khác.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Hiển thị cây phân cấp	Render tree view với expand/collapse cho dữ liệu cha-con
2	Filter block	Click node trên cây → lọc dữ liệu block liên kết
3	Phát hiện tree collection	Tự động detect collection có tree template (parentId)

Kiến trúc

Tổng quan

Plugin hoạt động hoàn toàn ở client - đọc dữ liệu phân cấp từ collection API và render bằng Ant Design Tree component.

Tree template collection

Plugin hoạt động tốt nhất với collection sử dụng tree template - collection có field parentId tạo quan hệ cha-con. Plugin tự động detect các collection này khi hiển thị danh sách "Add block".

Thuộc tính	Mô tả
`parentId`	Field trỏ đến record cha (self-referencing FK)
`children`	Association HasMany đến chính collection
`tree template`	Template đánh dấu collection là dạng cây

Cơ chế filter

Khi tree block được sử dụng làm filter block:

Tính năng

Tính năng	Mô tả
Tree view	Hiển thị phân cấp với expand/collapse animation
Search	Tìm kiếm nhanh trong cây, highlight kết quả
Expand all	Nút mở rộng/thu gọn tất cả node
Title field	Cấu hình field nào hiển thị làm tiêu đề node
Record count	Hiển thị số lượng bản ghi con trên mỗi node
Filter block	Kết nối với block khác để lọc dữ liệu
Auto-detect	Tự phát hiện collection có tree template
Async loading	Lazy load children khi expand node (cây lớn)

Luồng sử dụng

Thành phần client

Thành phần	Mô tả
`TreeBlockWidget`	Widget chính đăng ký Tree block vào hệ thống
`Tree`	Component React bọc Ant Design Tree với search và expand
`TreeBlockInitializer`	Đăng ký vào menu "Add block", lọc tree collection
`TreeDesigner`	Designer: cấu hình title field, filter connection
`TreeSearch`	Component tìm kiếm với highlight matching nodes
`TreeNodeTitle`	Custom render title node (count badge, icon)

Cấu hình block

Setting	Mô tả	Mặc định
Title field	Field hiển thị làm tiêu đề node	`title` hoặc field đầu tiên
Show count	Hiển thị số record con	`false`
Default expand	Mức expand mặc định	1 (chỉ root)
Search	Hiển thị ô tìm kiếm	`true`
Connect	Block liên kết để filter	Không có

Dependencies

Package	Vai trò
`@digiforce-nc/client`	Client framework, widget system (peer)
`@digiforce-nc/server`	Server framework - chỉ dùng khi build (peer)
`antd`	Ant Design - Tree, Input.Search components (peer)