Cài đặt và sử dụng — Multi Keyword Filter

Tổng quan

Plugin Multi Keyword Filter mở rộng hệ thống filter của Digiforce, cho phép lọc dữ liệu bằng nhiều từ khoá cùng lúc — nhập trực tiếp hoặc import hàng loạt từ file Excel. Plugin thêm hai operator mới: $in (bằng bất kỳ giá trị nào) và $notIn (không bằng bất kỳ giá trị nào).

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

Truy cập Settings → Plugin Manager, tìm plugin-multi-keyword-filter và bật plugin. Khởi động lại server.

Bước 2: Sử dụng trong giao diện

Sau khi kích hoạt, các trường dữ liệu hỗ trợ sẽ có thêm hai tuỳ chọn filter mới:

Operator	Mô tả	Ví dụ
Bằng bất kỳ ($in)	Record có giá trị trùng với một trong các từ khoá	Tìm đơn hàng có mã "ĐH001", "ĐH002", "ĐH003"
Không bằng bất kỳ ($notIn)	Record có giá trị không trùng với bất kỳ từ khoá nào	Loại trừ trạng thái "Huỷ", "Nháp"

Các loại trường hỗ trợ

Plugin đăng ký operator cho các field interface sau:

Field Interface	Kiểu dữ liệu	Ví dụ
input	Chuỗi văn bản	Tên, mã, tiêu đề
phone	Số điện thoại	Số ĐT khách hàng
email	Email	Địa chỉ email
uuid	UUID	ID định danh
sequence	Mã tự sinh	Mã đơn hàng
integer	Số nguyên	Số lượng, tuổi
number	Số thực	Giá, tỷ lệ
percent	Phần trăm	Tỷ lệ hoàn thành
nanoid	NanoID	ID ngắn

Cách nhập từ khoá

Nhập thủ công

Giao diện sử dụng component Select tags mode — nhập từ khoá và nhấn Enter (hoặc xuống dòng) để thêm:

1. Mở filter trên bảng dữ liệu
2. Chọn trường cần lọc
3. Chọn operator "Bằng bất kỳ" hoặc "Không bằng bất kỳ"
4. Nhập từ khoá, nhấn Enter để thêm tag
5. Lặp lại cho mỗi từ khoá

Từ khoá được phân cách bằng ký tự xuống dòng (\n). Mỗi tag hiển thị dạng chip.

Import từ Excel

Plugin hỗ trợ import từ khoá hàng loạt từ file Excel (.xlsx, .xls):

1. Nhấn nút Upload (biểu tượng upload) bên cạnh ô nhập
2. Chọn file Excel
3. Nếu file có 1 cột: Import trực tiếp tất cả giá trị
4. Nếu file có nhiều cột: Hiển thị dialog chọn cột muốn import
5. Giá trị từ các cột đã chọn được gộp (loại trùng) và thêm vào filter

Xử lý URL dài (Server Middleware)

Khi số lượng từ khoá lớn, URL query string có thể vượt quá giới hạn 2000 ký tự. Plugin tự động xử lý:

Client-side (Interceptor)

Nếu URL + query dài hơn 2000 ký tự:

1. Chuyển params vào body dưới dạng __params__
2. Lưu method gốc vào __method__
3. Đổi method thành POST

Server-side (Middleware)

Middleware bodyToQueryMiddleware (chạy sau bodyParser):

1. Kiểm tra body.__params__ có tồn tại không
2. Nếu có: merge __params__ vào ctx.request.query
3. Khôi phục method gốc từ __method__
4. Xoá __params__ và __method__ khỏi body

Cơ chế này trong suốt — các action handler phía sau không cần thay đổi.

Xử lý kiểu dữ liệu

Plugin tự động chuyển đổi từ khoá theo field interface:

Field Interface	Xử lý	Ví dụ
input, phone, email, uuid, sequence, nanoid	Trim khoảng trắng, loại bỏ giá trị rỗng	" abc " → "abc"
integer	Parse parseInt(), loại bỏ NaN	"42" → 42, "abc" → bỏ qua
number	Parse parseInt(), loại bỏ NaN	"3.14" → 3
percent	Parse parseFloat(), loại bỏ NaN	"85.5" → 85.5

Lưu ý khi sử dụng

• Hiệu năng: Với số lượng từ khoá lớn (> 100), query $in có thể chậm trên bảng lớn — cân nhắc tạo index
• Số lượng từ khoá: Không có giới hạn cứng, nhưng khuyến nghị dưới 1000 để đảm bảo hiệu năng
• Case sensitive: Phụ thuộc vào cấu hình database (PostgreSQL mặc định case-sensitive, MySQL thường case-insensitive)
• Excel import: Sử dụng thư viện xlsx (lazy load) — chỉ tải khi người dùng nhấn import