Quick Link & Custom Sidebar

Quick Link & Custom Sidebar là cụm tính năng cho phép admin thêm các link tuỳ biến vào sidebar nav ngoài những item built-in của hệ thống.

Tổng quan kiến trúc

Vị trí menu admin

• Cấu hình: trong Cài đặt khác — Thông tin chung, mục Quick link / menu tuỳ chỉnh (/setting/common/tab/general). Phần chỉnh chỉ hiện khi gói dịch vụ cho phép tuỳ biến menu sidebar.
• Hiển thị trên sidebar: sau khi lưu cấu hình, các mục tuỳ chỉnh xuất hiện thêm bên menu chính (nếu danh sách không rỗng và hợp lệ).
• Mở trong khung: khi một mục chọn kiểu iframe, hệ thống dùng trang /quicklink/iframe/url/{base64} để nhúng địa chỉ ngoài trong layout admin.

Setting key

common_quick_link_list - lưu dạng JSON string trong Setting. Field use_extra: true cho phép lưu chuỗi dài.

Cấu trúc JSON:

type QuickLinkItem = {
  uuid: string;
  name: string;
  type: "link" | "group";
  url: string;
  url_target: "self" | "blank" | "iframe";
  svg_icon: string;
  display_order: number;
};

type QuickLinkGroup = QuickLinkItem & {
  type: "group";
  children: QuickLinkItem[];
};

Editor <SettingCommonGeneralQuickLink> (xem Setting Common General > Quick Link)

Drag-drop reorder, add/edit/delete link và group, modal config name/URL/target/svg_icon. Lưu lại JSON string vào common_quick_link_list qua useEffect.

Render sidebar <MainNavigationQuickLink>

Source: components/mainnavigation/MainNavigationQuickLink.tsx. Render dưới dạng <ul> các item:

• Decode JSON từ useSettingStore.getSetting("common_quick_link_list"). Nếu parse fail hoặc rỗng → return null (không render).
• Filter items có name.length > 0 (item không tên bị skip).
• Mỗi link:
  • SVG icon (inline-rendered, tự rewrite <svg> để force width=20 height=20 flex-shrink=0).
  • Tên item.
  • <Link to={url_target === "iframe" ? "/quicklink/iframe/url/" + btoa(url) : url}> với target="_blank" nếu target=blank.
• Group:
  • Click header toggle collapse (qua useQuickLinkStore.toggleGroupCollapse).
  • Khi expand, render children dưới dạng nested list, indent pl-9. Children rỗng group bị skip không render.

Iframe target page /quicklink/iframe/url/{base64}

Component: pages/QuickLinkPage.tsx → render iframe full screen với src = atob(base64).

→ Cho phép embed trang ngoài (tool nội bộ, dashboard, BI...) ngay trong admin layout, không phải mở tab mới.

Ai được xem và chỉnh?

• Cấu hình danh sách quick link: người có quyền Cài đặt công ty / quản trị Cài đặt khác, và công ty đã bật gói cho phép tuỳ chỉnh menu sidebar.
• Thấy các mục trên sidebar: mọi tài khoản đăng nhập đều thấy cùng cấu hình theo công ty.
• Mở trang nhúng iframe (/quicklink/iframe/...): cần đăng nhập admin.

Khi nào dùng

• Doanh nghiệp có dashboard nội bộ (Metabase, Tableau, BI tool) muốn embed vào admin.
• Tool công cụ third-party cần truy cập nhanh từ admin.
• Tổ chức link gom theo group (ví dụ "Báo cáo nhanh", "Tools dev").

Các lối đi từ trang

• Setting Common General - cấu hình.
• Sidebar admin - render khi có config.

Lưu ý - Lỗi thường gặp

• Quick link không hiện sidebar: (1) danh sách cấu hình rỗng hoặc sai định dạng, (2) gói không cho chỉnh menu tuỳ chỉnh (trình sửa có thể ẩn nhưng dữ liệu cũ vẫn có thể hiển thị—tuỳ phiên bản).
• Item không tên không render: cố ý filter name.length > 0. Save tên rỗng = item ẩn.
• Group không có children render rỗng: cố ý filter children.length === 0 ở render.
• Iframe trang trắng: URL trong iframe có X-Frame-Options: DENY hoặc CSP block. Chuyển sang target=blank.
• Base64 URL không decode: kiểm tra encoding - frontend dùng btoa(url), browser-side. Special chars có thể fail; encode URL trước.
• SVG icon broken: SVG sai cấu trúc, có script, hoặc Tabler Icons format khác. Test render bằng paste vào browser viewer trước.

Lưu ý bảo mật iframe

• /quicklink/iframe/url/{base64} render URL sau khi decode từ cấu hình quick link.
• Chỉ cấu hình domain nội bộ hoặc domain bên thứ ba đã được doanh nghiệp tin cậy.
• Nếu trang ngoài bị chặn bởi CSP hoặc X-Frame-Options, đổi target sang blank để mở bằng tab mới.