@goplusvn/core 0.1.33 → 0.1.35

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.1.34 — Tab navigation: gom nhóm module, tiêu đề tab chi tiết, nút làm tươi
+
+**PageTabs:**
+
+- **Gom nhóm theo module**: tab sắp theo nhóm (segment đầu pathname) — tab chi
+  tiết đứng ngay sau tab danh sách cùng module, màu gradient hash theo NHÓM
+  (trước đây theo path → mỗi tab chi tiết một màu, không nhận ra nhóm). Tab
+  chi tiết có mũi tên rẽ nhánh (↳) + khe hở nhỏ giữa các nhóm.
+- **Nút làm tươi** trên tab active: `router.refresh()` + phát
+  `CustomEvent(TAB_REFRESH_EVENT)` để trang SWR revalidate (refresh RSC không
+  đụng được cache SWR). Context menu "Reload Tab" dùng chung đường này.
+
+**TabNavigationProvider — API mới cho app:**
+
+- `useTabTitle(title)`: trang chi tiết đặt tiêu đề tab theo dữ liệu nghiệp vụ
+  (vd `useTabTitle(order?.orderNumber)`) — 5 tab chi tiết không còn trùng tên.
+- Fallback tự động cho trang chi tiết CHƯA gắn hook: segment cuối trông như ID
+  (cuid/uuid/số) → tiêu đề `"<Tên module> · <5 ký tự cuối id>"` — mọi tab chi
+  tiết phân biệt được ngay khỏi cần sửa từng trang.
+- `useTabRefreshListener(handler)`: trang client-fetch đăng ký revalidate khi
+  user bấm nút làm tươi trên tab. Kèm export `TAB_REFRESH_EVENT`.
+- Context thêm `setTabTitle(pathname, title)` (action `UPDATE_TAB_TITLE`).
+
 ## 0.1.33 — Tab navigation: giữ bộ lọc + dữ liệu tươi; MainLayout `notificationSlot`
 
 **Tab navigation (PageTabs / TabNavigationProvider):**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goplusvn/core",
   "description": "GoPlusVN Platform Kit - ERP kernel: layout, RBAC, CRUD, multi-tenant, system pages",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/approval/__tests__/approval-engine.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest"
+
+import { planApproval, planRejection, resolveEffectiveSteps } from "../approval-engine"
+import { ApprovalError, type ApprovalFlow } from "../types"
+
+const FLOW: ApprovalFlow = {
+  entityType: "test-doc",
+  steps: [
+    { level: 1, name: "Phê duyệt Lần 1", permission: { resource: "doc", action: "approve_l1" } },
+    { level: 2, name: "Phê duyệt Lần 2", permission: { resource: "doc", action: "approve_l2" } },
+    {
+      level: 3,
+      name: "Phê duyệt Giám đốc",
+      permission: { resource: "doc", action: "approve_l3" },
+      minAmount: 5_000_000,
+    },
+  ],
+}
+
+const allow = () => true
+const denyAll = () => false
+
+describe("approval-engine", () => {
+  it("duyệt tuần tự n cấp: bước kế + isFinal đúng", async () => {
+    const p1 = await planApproval(FLOW, { amount: 10_000_000, completedLevel: 0, terminal: false }, allow)
+    expect(p1.step.level).toBe(1)
+    expect(p1.isFinal).toBe(false)
+
+    const p3 = await planApproval(FLOW, { amount: 10_000_000, completedLevel: 2, terminal: false }, allow)
+    expect(p3.step.level).toBe(3)
+    expect(p3.isFinal).toBe(true)
+  })
+
+  it("điều kiện tiền: dưới ngưỡng bỏ qua cấp có minAmount", async () => {
+    const steps = resolveEffectiveSteps(FLOW, 1_000_000)
+    expect(steps.map((s) => s.level)).toEqual([1, 2])
+
+    const p2 = await planApproval(FLOW, { amount: 1_000_000, completedLevel: 1, terminal: false }, allow)
+    expect(p2.step.level).toBe(2)
+    expect(p2.isFinal).toBe(true) // L2 là bước cuối vì L3 bị lọc
+  })
+
+  it("amount null = áp dụng đủ mọi cấp", () => {
+    expect(resolveEffectiveSteps(FLOW, null)).toHaveLength(3)
+  })
+
+  it("thiếu quyền của ĐÚNG bước hiện tại → 403 kèm tên bước", async () => {
+    const canOnlyL1 = (_r: string, a: string) => a === "approve_l1"
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 1, terminal: false }, canOnlyL1)
+    ).rejects.toThrowError(/Phê duyệt Lần 2/)
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 1, terminal: false }, canOnlyL1)
+    ).rejects.toMatchObject({ status: 403 })
+  })
+
+  it("chứng từ terminal hoặc đã đủ cấp → ApprovalError", async () => {
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 0, terminal: true }, allow)
+    ).rejects.toThrowError(/đã được xử lý/)
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 3, terminal: false }, allow)
+    ).rejects.toThrowError(/đủ cấp/)
+  })
+
+  it("planRejection: chặn terminal + thiếu quyền", async () => {
+    await expect(
+      planRejection(
+        { amount: null, completedLevel: 1, terminal: true },
+        allow,
+        { resource: "doc", action: "reject" },
+        "Bạn không có quyền Từ chối"
+      )
+    ).rejects.toThrowError(/đã được xử lý/)
+    await expect(
+      planRejection(
+        { amount: null, completedLevel: 1, terminal: false },
+        denyAll,
+        { resource: "doc", action: "reject" },
+        "Bạn không có quyền Từ chối"
+      )
+    ).rejects.toThrowError(/không có quyền Từ chối/)
+  })
+})

package/src/approval/approval-engine.ts

@@ -0,0 +1,80 @@
+import {
+  ApprovalError,
+  type ApprovalFlow,
+  type ApprovalPlan,
+  type ApprovalState,
+  type ApprovalStep,
+} from "./types"
+
+/**
+ * APPROVAL ENGINE — máy trạng thái duyệt n cấp dùng chung (Phase 6).
+ *
+ * Engine chỉ TÍNH TOÁN: bước nào đến lượt, ai được duyệt, có phải bước cuối
+ * không. Persistence (đổi status, ghi history, side-effect như tạo phiếu chi)
+ * do adapter của từng module thực hiện trong transaction của nó — engine
+ * không import Prisma nên promote lên core không kéo theo schema.
+ */
+
+/** Lọc các bước áp dụng thực tế theo điều kiện số tiền. */
+export function resolveEffectiveSteps(
+  flow: ApprovalFlow,
+  amount: number | null
+): ApprovalStep[] {
+  const steps = [...flow.steps].sort((a, b) => a.level - b.level)
+  if (amount == null) return steps
+  return steps.filter((s) => s.minAmount == null || amount >= s.minAmount)
+}
+
+/**
+ * Xác định bước duyệt kế tiếp + kiểm tra quyền. Ném ApprovalError nếu chứng
+ * từ đã kết thúc, đã duyệt đủ cấp, hoặc người duyệt thiếu quyền của bước.
+ * `can` được phép async (quyền qua ủy quyền phải tra DB).
+ */
+export async function planApproval(
+  flow: ApprovalFlow,
+  state: ApprovalState,
+  can: (resource: string, action: string) => boolean | Promise<boolean>
+): Promise<ApprovalPlan> {
+  if (state.terminal) {
+    throw new ApprovalError(
+      "Chứng từ này đã được xử lý (Đã duyệt hoặc Bị từ chối)"
+    )
+  }
+  const effectiveSteps = resolveEffectiveSteps(flow, state.amount)
+  const step = effectiveSteps[state.completedLevel]
+  if (!step) {
+    throw new ApprovalError("Chứng từ đã duyệt đủ cấp — không còn bước nào")
+  }
+  if (!(await can(step.permission.resource, step.permission.action))) {
+    throw new ApprovalError(
+      step.denyMessage ?? `Bạn không có quyền ${step.name}`,
+      403
+    )
+  }
+  return {
+    step,
+    isFinal: state.completedLevel === effectiveSteps.length - 1,
+    effectiveSteps,
+  }
+}
+
+/**
+ * Kiểm tra điều kiện từ chối: chứng từ chưa kết thúc + có quyền. Trả về
+ * void — từ chối được phép ở BẤT KỲ cấp nào đang chờ (khớp hành vi 2 flow
+ * hiện có).
+ */
+export async function planRejection(
+  state: ApprovalState,
+  can: (resource: string, action: string) => boolean | Promise<boolean>,
+  permission: { resource: string; action: string },
+  denyMessage: string
+): Promise<void> {
+  if (state.terminal) {
+    throw new ApprovalError(
+      "Chứng từ này đã được xử lý (Đã duyệt hoặc Bị từ chối)"
+    )
+  }
+  if (!(await can(permission.resource, permission.action))) {
+    throw new ApprovalError(denyMessage, 403)
+  }
+}

package/src/approval/index.ts

@@ -0,0 +1,9 @@
+/**
+ * APPROVAL ENGINE — máy trạng thái duyệt n cấp dùng chung (@goerp/core/approval).
+ *
+ * Thuần logic, Prisma-agnostic: consumer tự cung cấp `can(resource, action)`
+ * (đồng bộ/bất đồng bộ) + flow. Persistence + delegation + DB-config do app lo.
+ * Promote từ vinhhoa (Phase 6, KE_HOACH_ERP_THUC_THU.md).
+ */
+export * from "./types"
+export * from "./approval-engine"

package/src/approval/types.ts

@@ -0,0 +1,60 @@
+/**
+ * APPROVAL ENGINE — kiểu dữ liệu (Phase 6, KE_HOACH_ERP_THUC_THU.md).
+ *
+ * Trừu tượng hóa 2 bản duyệt cài riêng (PO + đề nghị thanh toán) thành một
+ * máy trạng thái n cấp dùng chung. Engine THUẦN LOGIC — không import Prisma,
+ * không side-effect: người gọi (adapter trong module) tự lo persistence
+ * trong transaction của mình. Viết kiểu DI để promote lên @goerp/core (M3).
+ */
+
+export interface ApprovalStep {
+  /** Cấp duyệt, 1-based, tăng dần. */
+  level: number
+  /** Tên hiển thị của cấp ("Kế toán", "Giám đốc", "Phê duyệt Lần 1"...). */
+  name: string
+  /** Quyền RBAC yêu cầu để duyệt cấp này. */
+  permission: { resource: string; action: string }
+  /**
+   * Điều kiện theo số tiền: bước CHỈ áp dụng khi amount >= minAmount.
+   * Bỏ trống = luôn áp dụng. (Ví dụ: dưới 5tr bỏ qua cấp Giám đốc.)
+   */
+  minAmount?: number
+  /** Message khi thiếu quyền — mặc định "Bạn không có quyền <name>". */
+  denyMessage?: string
+}
+
+export interface ApprovalFlow {
+  /** Loại chứng từ ("payment-request", "purchase-order"...). */
+  entityType: string
+  steps: ApprovalStep[]
+}
+
+/** Trạng thái duyệt hiện tại của chứng từ — adapter map từ model riêng. */
+export interface ApprovalState {
+  /** Số tiền chứng từ (null = không có điều kiện tiền). */
+  amount: number | null
+  /** Số CẤP đã duyệt xong (0 = chưa cấp nào; tính theo effective steps). */
+  completedLevel: number
+  /** Đã kết thúc (approved/rejected) — mọi thao tác duyệt tiếp bị chặn. */
+  terminal: boolean
+}
+
+export interface ApprovalPlan {
+  /** Bước cần duyệt bây giờ. */
+  step: ApprovalStep
+  /** true nếu đây là bước cuối → sau bước này chứng từ approved. */
+  isFinal: boolean
+  /** Danh sách bước áp dụng thực tế sau khi lọc điều kiện tiền. */
+  effectiveSteps: ApprovalStep[]
+}
+
+/** Lỗi nghiệp vụ của engine — message hiển thị thẳng cho user (VN). */
+export class ApprovalError extends Error {
+  readonly status: number
+
+  constructor(message: string, status = 400) {
+    super(message)
+    this.name = "ApprovalError"
+    this.status = status
+  }
+}

package/src/ui/layout/page-tabs.tsx

@@ -1,7 +1,14 @@
 "use client";
 
 import { useState } from "react";
-import { X, MoreHorizontal, Loader2, Pin } from "lucide-react";
+import {
+  X,
+  MoreHorizontal,
+  Loader2,
+  Pin,
+  RefreshCw,
+  CornerDownRight,
+} from "lucide-react";
 import { useParams, useRouter } from "next/navigation";
 import type { DictionaryType } from "../../hooks";
 import type { LocaleType } from "../../types";
@@ -19,9 +26,23 @@ import {
   ContextMenuTrigger,
 } from "../primitives/client";
 
-import { useTabNavigation } from "./tab-navigation-provider";
+import {
+  useTabNavigation,
+  TAB_REFRESH_EVENT,
+  type Tab,
+} from "./tab-navigation-provider";
 import { useRouteCache } from "./route-cache";
 
+/** Nhóm tab theo module — segment đầu của pathname đã bỏ locale. */
+function groupKeyOf(tab: Tab): string {
+  return tab.id.split("/").filter(Boolean)[0] ?? "home";
+}
+
+/** Độ sâu path: 1 = trang danh sách, >1 = trang chi tiết (tab con). */
+function depthOf(tab: Tab): number {
+  return tab.id.split("/").filter(Boolean).length;
+}
+
 interface PageTabsProps {
   dictionary?: DictionaryType;
   className?: string;
@@ -47,6 +68,7 @@ export function PageTabs({
   const router = useRouter();
   const locale = params?.lang as LocaleType | undefined;
   const [contextMenuTabId, setContextMenuTabId] = useState<string | null>(null);
+  const [refreshingTabId, setRefreshingTabId] = useState<string | null>(null);
 
   // Don't render if no tabs
   if (tabs.length === 0) {
@@ -57,9 +79,16 @@ export function PageTabs({
     setActiveTab(tabId);
   };
 
-  const handleReloadTab = (path: string) => {
-    reloadTab(path);
+  // Làm tươi tab: refresh RSC payload + báo cho trang SWR revalidate
+  // (router.refresh không đụng được cache SWR nên cần event kèm theo).
+  const handleReloadTab = (tab: Tab) => {
+    reloadTab(tab.path);
     router.refresh();
+    window.dispatchEvent(
+      new CustomEvent(TAB_REFRESH_EVENT, { detail: { path: tab.path } }),
+    );
+    setRefreshingTabId(tab.id);
+    setTimeout(() => setRefreshingTabId(null), 800);
   };
 
   const handleCloseTab = (e: React.MouseEvent, tabId: string) => {
@@ -71,10 +100,23 @@ export function PageTabs({
     setContextMenuTabId(tabId);
   };
 
-  // Sort tabs: pinned first, then by creation time
+  // Gom nhóm theo module: tab chi tiết đứng ngay sau tab danh sách cùng module.
+  // Thứ tự nhóm theo tab xuất hiện sớm nhất; trong nhóm: trang danh sách
+  // (path nông hơn) trước, rồi theo thời gian mở.
+  const groupOrder = new Map<string, number>();
+  for (const tab of [...tabs].sort((a, b) => a.createdAt - b.createdAt)) {
+    const key = groupKeyOf(tab);
+    if (!groupOrder.has(key)) groupOrder.set(key, groupOrder.size);
+  }
+
   const sortedTabs = [...tabs].sort((a, b) => {
-    if (a.isPinned && !b.isPinned) return -1;
-    if (!a.isPinned && b.isPinned) return 1;
+    if (a.isPinned !== b.isPinned) return a.isPinned ? -1 : 1;
+    const groupDiff =
+      (groupOrder.get(groupKeyOf(a)) ?? 0) -
+      (groupOrder.get(groupKeyOf(b)) ?? 0);
+    if (groupDiff !== 0) return groupDiff;
+    const depthDiff = depthOf(a) - depthOf(b);
+    if (depthDiff !== 0) return depthDiff;
     return a.createdAt - b.createdAt;
   });
 
@@ -86,13 +128,13 @@ export function PageTabs({
   const hasOtherTabs = sortedTabs.length > 1;
 
   // Nền tab: active = mặt phẳng trang (trắng); inactive = 1 gradient tối theo hash
-  // của path (bộ 21 màu cố định) — bám thiết kế golden vinhhoa (icon/chữ trắng đọc
-  // rõ trên nền tối). KHÔNG dùng --primary để mỗi tab có màu riêng, dễ phân biệt.
-  const getTabBackgroundColor = (path: string, isActive: boolean) => {
+  // của NHÓM module (bộ 21 màu cố định) — mọi tab cùng module (danh sách + các
+  // trang chi tiết) chung một màu để nhận ra nhóm ngay. KHÔNG dùng --primary
+  // để mỗi nhóm có màu riêng, dễ phân biệt.
+  const getTabBackgroundColor = (groupKey: string, isActive: boolean) => {
     if (isActive) return "bg-background";
 
-    const normalizedPath = path.replace(/^\/[a-z]{2}(\/|$)/, "/");
-    const hash = normalizedPath.split("").reduce((acc, char) => {
+    const hash = groupKey.split("").reduce((acc, char) => {
       return (acc << 5) - acc + char.charCodeAt(0);
     }, 0);
 
@@ -135,6 +177,10 @@ export function PageTabs({
           {sortedTabs.map((tab, index) => {
             const isActive = tab.id === activeTabId;
             const isLast = index === sortedTabs.length - 1;
+            const isChild = depthOf(tab) > 1;
+            const isNewGroup =
+              index > 0 &&
+              groupKeyOf(sortedTabs[index - 1]) !== groupKeyOf(tab);
             return (
               <ContextMenu
                 key={tab.id}
@@ -160,7 +206,9 @@ export function PageTabs({
                       "border border-transparent",
                       "cursor-pointer",
                       "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
-                      getTabBackgroundColor(tab.path, isActive),
+                      getTabBackgroundColor(groupKeyOf(tab), isActive),
+                      // Khe hở nhỏ giữa các nhóm module cho dễ quét mắt
+                      isNewGroup && "ml-1.5",
                       variant === "default" &&
                         (isActive
                           ? "bg-background text-foreground border-b-2 border-primary shadow-sm shadow-primary/10 border-t border-x border-b-0 rounded-t-md -mb-px z-10"
@@ -207,6 +255,16 @@ export function PageTabs({
                         />
                       ) : null}
                     </div>
+                    {/* Tab con (trang chi tiết): mũi tên rẽ nhánh để phân biệt
+                        với tab danh sách của cùng module */}
+                    {isChild && (
+                      <CornerDownRight
+                        className={cn(
+                          "h-3 w-3 shrink-0",
+                          isActive ? "text-muted-foreground" : "text-white/60",
+                        )}
+                      />
+                    )}
                     <span
                       className={cn(
                         "truncate max-w-[150px]",
@@ -229,6 +287,30 @@ export function PageTabs({
                           : tab.badge}
                       </Badge>
                     )}
+                    {/* Nút làm tươi: chỉ hiện trên tab đang active — refresh
+                        RSC + phát event cho trang SWR revalidate */}
+                    {isActive && (
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        className={cn(
+                          "h-4 w-4 ml-0.5 shrink-0",
+                          "hover:bg-primary/10 hover:text-primary",
+                        )}
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          handleReloadTab(tab);
+                        }}
+                        aria-label={`Reload ${tab.title}`}
+                      >
+                        <RefreshCw
+                          className={cn(
+                            "h-2.5 w-2.5",
+                            refreshingTabId === tab.id && "animate-spin",
+                          )}
+                        />
+                      </Button>
+                    )}
                     <Button
                       variant="ghost"
                       size="icon"
@@ -245,7 +327,7 @@ export function PageTabs({
                   </div>
                 </ContextMenuTrigger>
                 <ContextMenuContent>
-                  <ContextMenuItem onClick={() => handleReloadTab(tab.path)}>
+                  <ContextMenuItem onClick={() => handleReloadTab(tab)}>
                     Reload Tab
                   </ContextMenuItem>
                   <ContextMenuItem onClick={() => handleTabClick(tab.id)}>

package/src/ui/layout/tab-navigation-provider.tsx

@@ -46,6 +46,7 @@ type TabNavigationAction =
   | { type: "REMOVE_TAB"; payload: { id: string } }
   | { type: "SET_ACTIVE_TAB"; payload: { id: string } }
   | { type: "UPDATE_TAB_PATH"; payload: { id: string; path: string } }
+  | { type: "UPDATE_TAB_TITLE"; payload: { id: string; title: string } }
   | { type: "LOAD_STATE"; payload: TabNavigationState }
   | { type: "CLEAR_TABS" }
   | { type: "REMOVE_OTHER_TABS"; payload: { id: string } }
@@ -137,6 +138,17 @@ function tabNavigationReducer(
       };
     }
 
+    case "UPDATE_TAB_TITLE": {
+      const { id, title } = action.payload;
+      const tab = state.tabs.find((t) => t.id === id);
+      if (!tab || !title || tab.title === title) return state;
+
+      return {
+        ...state,
+        tabs: state.tabs.map((t) => (t.id === id ? { ...t, title } : t)),
+      };
+    }
+
     case "LOAD_STATE": {
       return action.payload;
     }
@@ -199,6 +211,7 @@ interface TabNavigationContextValue {
   addTab: (path: string, title?: string) => void;
   removeTab: (id: string) => void;
   setActiveTab: (id: string) => void;
+  setTabTitle: (pathname: string, title: string) => void;
   clearTabs: () => void;
   removeOtherTabs: (id: string) => void;
   removeTabsToRight: (id: string) => void;
@@ -281,10 +294,22 @@ export function TabNavigationProvider({
     }
 
     // Get title and icon from navigation data or use pathname
-    const title = findRouteTitle(pathname, navigations) || "Page";
+    const baseTitle = findRouteTitle(pathname, navigations) || "Page";
     const iconName = findRouteIcon(pathname, navigations) || undefined;
     const normalizedPath = normalizePathname(pathname);
 
+    // Trang chi tiết (segment cuối là ID) lấy tên module từ navigation nên
+    // mở 5 chi tiết là 5 tab trùng tên — đính đuôi ID ngắn để phân biệt ngay.
+    // Trang nào gắn useTabTitle sẽ thay bằng mã nghiệp vụ thật sau khi mount.
+    const lastSegment = normalizedPath.split("/").filter(Boolean).pop() ?? "";
+    const looksLikeId =
+      /^(c[a-z0-9]{20,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\d{4,})$/i.test(
+        lastSegment,
+      );
+    const title = looksLikeId
+      ? `${baseTitle} · ${lastSegment.slice(-5)}`
+      : baseTitle;
+
     // Full URL incl. query string — window.location is already updated by
     // effect time, and reading it here keeps pathname-triggered and
     // searchSignal-triggered runs consistent with each other.
@@ -364,6 +389,13 @@ export function TabNavigationProvider({
     [state.tabs, router],
   );
 
+  const setTabTitle = useCallback((tabPathname: string, title: string) => {
+    dispatch({
+      type: "UPDATE_TAB_TITLE",
+      payload: { id: normalizePathname(tabPathname), title },
+    });
+  }, []);
+
   const clearTabs = useCallback(() => {
     dispatch({ type: "CLEAR_TABS" });
   }, []);
@@ -540,6 +572,7 @@ export function TabNavigationProvider({
         addTab,
         removeTab,
         setActiveTab,
+        setTabTitle,
         clearTabs,
         removeOtherTabs,
         removeTabsToRight,
@@ -563,6 +596,7 @@ const noopTabNavigation = {
   addTab: () => {},
   removeTab: () => {},
   setActiveTab: () => {},
+  setTabTitle: () => {},
   clearTabs: () => {},
   removeOtherTabs: () => {},
   removeTabsToRight: () => {},
@@ -576,3 +610,48 @@ export function useTabNavigation() {
   const context = useContext(TabNavigationContext);
   return context ?? noopTabNavigation;
 }
+
+/**
+ * Đặt tiêu đề tab của trang hiện tại theo dữ liệu nghiệp vụ — dùng ở trang
+ * chi tiết để 5 tab chi tiết không hiện cùng một tên chung chung.
+ * Truyền null/undefined khi dữ liệu chưa sẵn sàng (giữ tiêu đề mặc định).
+ *
+ * @example useTabTitle(order?.orderNumber)
+ */
+export function useTabTitle(title: string | null | undefined) {
+  const { setTabTitle, tabs } = useTabNavigation();
+  const pathname = usePathname();
+
+  // Effect con chạy TRƯỚC effect ADD_TAB của provider (React chạy effect từ
+  // dưới lên) — nên phải dep theo "tab đã tồn tại chưa" để set lại tiêu đề
+  // ngay sau khi provider thêm tab, thay vì dispatch vào khoảng không.
+  const tabExists =
+    !!pathname && tabs.some((t) => t.id === normalizePathname(pathname));
+
+  useEffect(() => {
+    if (title && pathname && tabExists) {
+      setTabTitle(pathname, title);
+    }
+  }, [title, pathname, tabExists, setTabTitle]);
+}
+
+/** Tên event nút "làm tươi" trên tab phát ra (detail = { path }). */
+export const TAB_REFRESH_EVENT = "goerp:tab-refresh";
+
+/**
+ * Lắng nghe nút làm tươi trên tab đang active. Trang client-fetch (SWR) dùng
+ * hook này để revalidate dữ liệu của mình — router.refresh() chỉ làm mới RSC
+ * payload, không đụng được cache SWR.
+ *
+ * @example useTabRefreshListener(() => mutateList())
+ */
+export function useTabRefreshListener(handler: () => void) {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const listener = () => handlerRef.current();
+    window.addEventListener(TAB_REFRESH_EVENT, listener);
+    return () => window.removeEventListener(TAB_REFRESH_EVENT, listener);
+  }, []);
+}