• Giao diện admin khai báo bản ghi đang được chọn.
• Backend cung cấp bộ tải dữ liệu để hệ thống hiển thị lại tên, biểu tượng và đường dẫn của bản ghi đã gắn thẻ.

Kiến trúc tổng quát

• entityType: định danh loại dữ liệu.
• entityId: ID của bản ghi.
• tagId: ID của thẻ.
• taggedAt: thời điểm gắn thẻ.
• metadata: dữ liệu phụ phục vụ tìm kiếm.

flowchart LR
    A[Trang quản trị plugin] -->|Khai báo bản ghi hiện tại| B[Thanh công cụ gắn thẻ]
    B -->|entityType + entityId + metadata| C[API gắn thẻ]
    C --> D[Kho metadata]
    D --> E[Bộ lập chỉ mục]
    E --> F[Tìm kiếm dữ liệu theo thẻ]

    D --> G[Danh sách dữ liệu đã gắn thẻ]
    G -->|Nhóm ID theo entityType| H[Entity Fetcher]
    H --> I[Tên, mã, biểu tượng và URL]
    I --> B

Điều kiện tích hợp

• Bản ghi có ID kiểu số nguyên.
• Loại dữ liệu có một entityType ổn định và không xung đột với module khác.
• Trang admin có thể xác định bản ghi hiện tại hoặc bản ghi đang được chọn.
• Backend có thể tải một hoặc nhiều bản ghi theo ID.
• Người dùng đang đăng nhập có quyền truy cập chức năng quản lý term/tag.

shop_products
customer_profiles
support_tickets

Khai báo dữ liệu có thể gắn thẻ trên giao diện

ezyadmin.taggableEntity = {
    id: product.id,
    code: product.code,
    displayName: product.name,
    type: 'shop_products'
};

Trang chi tiết

<script th:inline="javascript">
/*<![CDATA[*/
const product = {
    id: /*[[]]*/ 0,
    code: /*[[]]*/ '',
    name: /*[[]]*/ ''
};

ezyadmin.taggableEntity = {
    id: product.id,
    code: product.code,
    displayName: product.name,
    type: 'shop_products'
};
/*]]>*/
</script>

1. Lấy ezyadmin.taggableEntity.
2. Kiểm tra bản ghi đã thuộc thẻ đang chọn hay chưa.
3. Hiển thị nút “Thêm vào thẻ” nếu chưa có.
4. Gửi thông tin bản ghi lên API khi quản trị viên xác nhận.

Trang danh sách

function setTaggableProduct(product) {
    ezyadmin.taggableEntity = {
        id: product.id,
        code: product.code,
        displayName: product.name,
        type: 'shop_products'
    };
}

function clearTaggableProduct() {
    ezyadmin.taggableEntity = null;
}

$('.product-checkbox').on('change', function() {
    if (this.checked) {
        const productId = Number(this.value);
        setTaggableProduct(productById[productId]);
        return;
    }

    const remainingId = $('.product-checkbox:checked')
        .map(function() {
            return Number(this.value);
        })
        .get()
        .pop();

    if (remainingId) {
        setTaggableProduct(productById[remainingId]);
    } else {
        clearTaggableProduct();
    }
});

Đăng ký bộ tải dữ liệu ở backend

@EzySingleton
@AllArgsConstructor
public class AdminProductEntityFetcher
    implements CommonEntityFetcher {

    private final ProductService productService;

    @Override
    public CommonEntityModel getEntityById(long entityId) {
        ProductModel product = productService.getProductById(entityId);

        if (product == null) {
            return CommonEntityModel.defaultEntity(
                entityId,
                getEntityType()
            );
        }

        return toCommonEntity(product);
    }

    @Override
    public Map<Long, CommonEntityModel> getEntityMapByIds(
        Collection<Long> entityIds
    ) {
        return productService.getProductMapByIds(entityIds)
            .entrySet()
            .stream()
            .collect(
                Collectors.toMap(
                    Map.Entry::getKey,
                    entry -> toCommonEntity(entry.getValue())
                )
            );
    }

    @Override
    public String getEntityType() {
        return "shop_products";
    }

    private CommonEntityModel toCommonEntity(
        ProductModel product
    ) {
        return CommonEntityModel.builder()
            .id(product.getId())
            .code(product.getCode())
            .displayName(product.getName())
            .url("/shop/products/" + product.getId())
            .icon("fas fa-box")
            .build();
    }
}

Ý nghĩa của dữ liệu trả về

CommonEntityModel.builder()
    .id(product.getId())
    .code(product.getCode())
    .displayName(product.getName())
    .url("/shop/products/" + product.getId())
    .icon("fas fa-box")
    .build();

• id: phải bằng ID đã dùng khi gắn thẻ.
• code: mã nghiệp vụ hoặc slug.
• displayName: tên hiển thị chính.
• url: đường dẫn trong khu vực admin.
• icon: class biểu tượng, chẳng hạn Font Awesome.
• properties: có thể chứa dữ liệu mở rộng nếu ứng dụng cần sử dụng sau này.

Tối ưu truy vấn theo lô

getEntityMapByIds(Collection<Long> entityIds)

SELECT *
FROM shop_products
WHERE id IN (...);

Map<Long, CommonEntityModel>

Luồng gắn thẻ

sequenceDiagram
    actor Admin as Quản trị viên
    participant Page as Trang plugin
    participant Toolbar as Thanh công cụ tag
    participant API as API quản trị
    participant Meta as Kho metadata
    participant Index as Chỉ mục tìm kiếm

    Page->>Toolbar: Cung cấp taggableEntity
    Admin->>Toolbar: Chọn một thẻ
    Toolbar->>API: Kiểm tra entity đã thuộc thẻ chưa
    API->>Meta: Tìm entityType + entityId + tagId
    Meta-->>API: Có hoặc không
    API-->>Toolbar: contains

    Admin->>Toolbar: Chọn “Thêm vào thẻ”
    Toolbar->>API: tagId, entityType, entityId, metadata
    API->>Meta: Lưu quan hệ
    Meta-->>Index: Bản ghi chờ lập chỉ mục
    Index->>Index: Tách từ khóa từ type, ID và metadata

{
  "entityType": "shop_products",
  "entityId": 1205,
  "metadata": {
    "code": "SKU-1205",
    "displayName": "Bàn phím cơ"
  }
}

Hiển thị dữ liệu đã gắn thẻ

1. Truy vấn các quan hệ có tagId tương ứng.
2. Phân trang kết quả.
3. Nhóm các ID theo entityType.
4. Tìm fetcher đã đăng ký cho từng loại.
5. Tải dữ liệu theo lô.
6. Ghép thông tin hiển thị vào kết quả.
7. Trả danh sách cho giao diện.

Tìm kiếm dữ liệu trong thẻ

• entityType;
• entityId;
• ID thẻ;
• tên các trường metadata;
• giá trị của các trường metadata.

{
  "entityType": "shop_products",
  "entityId": 1205,
  "metadata": {
    "code": "SKU-1205",
    "displayName": "Bàn phím cơ"
  }
}

shop_products
1205
SKU-1205
Bàn phím cơ

Bảo mật

• Yêu cầu người dùng đã đăng nhập.
• Được bảo vệ bởi feature quản lý term/tag.
• Chỉ nên được gọi từ khu vực admin.
• Không xác thực sự tồn tại của bản ghi nghiệp vụ trước khi lưu quan hệ; plugin tích hợp phải cung cấp entityId hợp lệ.
• Không thay thế cơ chế phân quyền của module dữ liệu nguồn.

Các điểm cần lưu ý

• entityType phía JavaScript và getEntityType() phía backend phải giống nhau tuyệt đối.
• Một trang chỉ có một ezyadmin.taggableEntity tại một thời điểm.
• Metadata dùng để tìm kiếm, không phải bản sao của dữ liệu nghiệp vụ.
• Thay đổi tên bản ghi trong hệ thống nguồn không tự động cập nhật metadata đã lưu. Tuy nhiên tên hiển thị trong danh sách vẫn có thể lấy mới từ fetcher.
• Xóa bản ghi nguồn không tự động xóa quan hệ tag.
• Thao tác xóa hiện tại được xác định bằng entityType và entityId; nó có thể xóa toàn bộ quan hệ system tag của bản ghi, không chỉ quan hệ với thẻ đang được chọn. Plugin không nên tự gọi API xóa nếu chưa hiểu rõ hành vi này.
• Fetcher phải hỗ trợ tải theo lô để tránh truy vấn N+1.
• ID hiện được thiết kế theo kiểu long; dữ liệu dùng UUID hoặc khóa chuỗi cần có một ID số ánh xạ ổn định.

Checklist tích hợp

• [ ] Chọn entityType duy nhất và ổn định.
• [ ] Khai báo ezyadmin.taggableEntity trên trang chi tiết hoặc khi chọn dòng.
• [ ] Xóa taggableEntity khi không còn bản ghi nào được chọn.
• [ ] Đăng ký một CommonEntityFetcher ở admin backend.
• [ ] Trả về đúng id, displayName, url và icon.
• [ ] Cài đặt truy vấn nhiều ID trong getEntityMapByIds.
• [ ] Không đưa dữ liệu nhạy cảm vào metadata.
• [ ] Kiểm tra quyền truy cập trang chi tiết tại URL do fetcher trả về.
• [ ] Xử lý trường hợp dữ liệu nguồn đã bị xóa.
• [ ] Xác nhận hành vi xóa toàn bộ tag của một entity là phù hợp với nghiệp vụ.