@goplusvn/core 0.1.65 → 0.1.67

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.1.67 — Quyền trong session: dạng map thay cho mảng cặp
+
+`session.user.permissions` là `Permission[]` — mảng các cặp
+`{resourceCode, actionCode}`, lặp lại tên resource ở MỌI cặp. Đo trên một ERP
+thật (user 9 vai trò): **2.428 quyền trải trên 73 resource = 139,7 KB JSON**,
+đi kèm mọi lượt đọc session, kể cả chuyến ra client. Và mỗi lần
+`checkPermission` là một lần quét tuyến tính cả 2.428 phần tử.
+
+**Thêm `ExtendedUser.permissionMap?: PermissionMap`** (`Record<resource,
+action[]>`) — cùng bộ quyền đó còn **~31 KB**, và tra cứu thành "lấy đúng
+resource rồi quét vài chục action" thay vì quét cả mảng.
+
+**KHÔNG breaking.** `permissions` vẫn chạy nguyên vẹn: mọi hàm kiểm quyền đọc
+`permissionMap` trước rồi mới lùi về `permissions`. App chưa chuyển không phải
+sửa gì. (Bản chuyển đổi cho đường cũ được nhớ trong `WeakMap` theo tham chiếu
+mảng, nếu không thì một trang gọi `checkPermission` 20 lần sẽ dựng map 20 lần —
+tệ hơn hẳn phép quét có thoát sớm mà nó thay thế.) Có cả hai thì
+`permissionMap` thắng.
+
+**Thêm `getAccessibleResources(session, actionCode?)`.** Trả `Set` các resource
+user chạm được — bỏ trống `actionCode` là "có bất kỳ action nào" (App Launcher),
+truyền `"view"` là lọc menu. Admin trả `Set(["*"])` khớp quy ước wildcard của
+cây điều hướng. Có ở core vì mọi app đều tự viết lại đúng vòng lặp này, mỗi nơi
+một kiểu.
+
+Kèm `toPermissionMap` / `fromPermissionMap` cho ranh giới với code chưa chuyển.
+
+**Dọn hai bản sao của `Permission`.** `auth/index.ts` khai báo lại y hệt bản
+trong `types/index.ts`, và `rbac/index.ts` còn một `ExtendedUser` thứ ba không
+ai dùng. Nay `Permission`/`PermissionMap` có ĐÚNG một nguồn ở `types`, các nơi
+khác chỉ re-export.
+
+## 0.1.66 — Cache: hết TTL vô hạn, hết nuốt lỗi RBAC
+
+Hai chế độ hỏng âm thầm, cùng một họ: hệ thống *tin* là nó có dữ liệu trong khi
+thực ra không.
+
+**`getUserPermissionsFromDB` NÉM thay vì trả `[]`.** Trước đây `catch → return []`.
+Trong hệ RBAC, "không có quyền nào" và "không hỏi được quyền" hiện ra y hệt nhau
+— menu rỗng, nút biến mất, API 403 — nên người dùng đọc thành "tôi bị thu hồi
+quyền". Tệ hơn: `getCachedUserPermissions` ghi kết quả vào cache 5 phút, nên một
+cú nghẽn DB chớp nhoáng bị ĐÓNG BĂNG thành mảng rỗng suốt 5 phút kể cả khi DB đã
+hồi ngay. Nay lỗi ném ra, `.catch` không ghi cache, lượt sau tự hỏi lại.
+
+⚠️ **BREAKING (hành vi).** App nào đang dựa vào `[]`-khi-lỗi phải tự bắt. Khuyến
+nghị: để lỗi nổi lên `error.tsx` — nhớ đặt boundary ở segment CHA của layout gọi
+nó, vì `error.tsx` không bọc `layout.tsx` cùng segment.
+
+**`SettingsService.getSettings` thêm `revalidate: 60`.** `unstable_cache` không
+khai `revalidate` là cache tới khi process chết. Mọi đường ghi thẳng
+`system_config` không qua `saveSettings` (route CRUD generic, script, migration)
+— hoặc ghi từ tiến trình khác nên không xoá được cache tiến trình này — đều làm
+setting cũ đóng băng VĨNH VIỄN. TTL là lưới an toàn; `saveSettings` vẫn xoá tag
+để đường ghi chuẩn hiện tức thì.
+
+**`revalidateTag` được bọc `try/catch`.** Next 16 throw "Invariant: static
+generation store missing" khi gọi ngoài request scope (cron, task nền). Lời gọi
+luôn nằm SAU lệnh ghi DB, nên không bọc là "lưu xong rồi vẫn báo lỗi". Chỉ an
+toàn nuốt vì cache đã có TTL hữu hạn. Tag xuất khẩu thành
+`SYSTEM_SETTINGS_CACHE_TAG`.
+
+Kèm 8 test ratchet (đã kiểm: cả 8 đỏ khi hoàn nguyên bản vá).
+
 ## 0.1.44 — UnifiedProfileDialog: chi nhánh mặc định + ngày sinh DatePicker + fix Select loại người dùng
 
 **Ngày sinh dùng `DatePicker` (thay `<input type="date">`):** ô ngày sinh cũ khó

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.65",
+  "version": "0.1.67",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/auth/__tests__/permissions.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  checkPermission,
+  fromPermissionMap,
+  getAccessibleResources,
+  getCrudPermissionsFromSession,
+  getUserPermissions,
+  toPermissionMap,
+} from "../index";
+
+/** Session dạng CŨ — app chưa chuyển vẫn gán `permissions`. */
+const legacy = {
+  user: {
+    id: "u1",
+    roles: ["ACCOUNTANT"],
+    permissions: [
+      { resourceCode: "receipt", actionCode: "view" },
+      { resourceCode: "receipt", actionCode: "create" },
+      { resourceCode: "expense", actionCode: "view" },
+    ],
+  },
+};
+
+/** Session dạng GỌN — cùng đúng bộ quyền trên. */
+const compact = {
+  user: {
+    id: "u1",
+    roles: ["ACCOUNTANT"],
+    permissionMap: { receipt: ["view", "create"], expense: ["view"] },
+  },
+};
+
+const both = [
+  ["dạng cũ (permissions)", legacy],
+  ["dạng gọn (permissionMap)", compact],
+] as const;
+
+describe("checkPermission — hai dạng phải cho CÙNG kết quả", () => {
+  for (const [label, session] of both) {
+    it(`${label}: đúng resource + đúng action → true`, () => {
+      expect(checkPermission(session, "receipt", "create")).toBe(true);
+    });
+
+    it(`${label}: đúng resource nhưng SAI action → false`, () => {
+      expect(checkPermission(session, "receipt", "delete")).toBe(false);
+    });
+
+    it(`${label}: action có ở resource KHÁC không được lây sang`, () => {
+      // Bẫy kinh điển của việc gộp khoá: "expense" có "view", "receipt" có
+      // "create" — không được suy ra "expense:create".
+      expect(checkPermission(session, "expense", "create")).toBe(false);
+    });
+
+    it(`${label}: resource lạ → false`, () => {
+      expect(checkPermission(session, "ghost", "view")).toBe(false);
+    });
+  }
+
+  it("SUPER_ADMIN qua cổng kể cả khi không có dòng quyền nào", () => {
+    const admin = { user: { id: "u2", roles: ["SUPER_ADMIN"] } };
+    expect(checkPermission(admin, "bất-kỳ", "bất-kỳ")).toBe(true);
+  });
+
+  it("không có session → false", () => {
+    expect(checkPermission(null, "receipt", "view")).toBe(false);
+  });
+
+  it("permissionMap ĐÈ permissions khi có cả hai", () => {
+    const mixed = {
+      user: {
+        id: "u1",
+        roles: [],
+        permissions: [{ resourceCode: "receipt", actionCode: "delete" }],
+        permissionMap: { receipt: ["view"] },
+      },
+    };
+    expect(checkPermission(mixed, "receipt", "view")).toBe(true);
+    expect(checkPermission(mixed, "receipt", "delete")).toBe(false);
+  });
+});
+
+describe("getCrudPermissionsFromSession", () => {
+  for (const [label, session] of both) {
+    it(`${label}: chỉ bật đúng action đang có`, () => {
+      const p = getCrudPermissionsFromSession(session, "receipt");
+      expect(p).toEqual({
+        view: true,
+        create: true,
+        update: false,
+        delete: false,
+        export: false,
+        import: false,
+        approve: false,
+        reject: false,
+      });
+    });
+  }
+
+  it("entity không có quyền nào → tất cả false", () => {
+    const p = getCrudPermissionsFromSession(compact, "ghost");
+    expect(Object.values(p).every((v) => v === false)).toBe(true);
+  });
+});
+
+describe("getAccessibleResources", () => {
+  for (const [label, session] of both) {
+    it(`${label}: bỏ trống action = có BẤT KỲ action nào`, () => {
+      expect(getAccessibleResources(session)).toEqual(
+        new Set(["receipt", "expense"]),
+      );
+    });
+
+    it(`${label}: lọc theo action cụ thể`, () => {
+      expect(getAccessibleResources(session, "create")).toEqual(
+        new Set(["receipt"]),
+      );
+    });
+  }
+
+  it("admin → wildcard, khớp quy ước cây điều hướng", () => {
+    const admin = { user: { id: "u2", roles: ["admin"] } };
+    expect(getAccessibleResources(admin)).toEqual(new Set(["*"]));
+  });
+
+  it("không có session → rỗng, KHÔNG phải wildcard", () => {
+    expect(getAccessibleResources(null)).toEqual(new Set());
+  });
+});
+
+describe("chuyển đổi hai chiều", () => {
+  it("toPermissionMap gộp trùng", () => {
+    expect(
+      toPermissionMap([
+        { resourceCode: "receipt", actionCode: "view" },
+        { resourceCode: "receipt", actionCode: "view" },
+        { resourceCode: "receipt", actionCode: "create" },
+      ]),
+    ).toEqual({ receipt: ["view", "create"] });
+  });
+
+  it("đi rồi về giữ nguyên tập quyền", () => {
+    const back = fromPermissionMap(toPermissionMap(legacy.user.permissions));
+    expect(new Set(back.map((p) => `${p.resourceCode}:${p.actionCode}`))).toEqual(
+      new Set(
+        legacy.user.permissions.map((p) => `${p.resourceCode}:${p.actionCode}`),
+      ),
+    );
+  });
+
+  it("getUserPermissions bung map ra dạng cũ", () => {
+    expect(new Set(getUserPermissions(compact).map((p) => p.resourceCode))).toEqual(
+      new Set(["receipt", "expense"]),
+    );
+    expect(getUserPermissions(compact)).toHaveLength(3);
+  });
+
+  it("map rỗng ↔ mảng rỗng", () => {
+    expect(toPermissionMap([])).toEqual({});
+    expect(fromPermissionMap({})).toEqual([]);
+  });
+});

package/src/auth/index.ts

@@ -1,25 +1,30 @@
 // @goerp/core/auth
 // Authentication and RBAC utilities for GoERP
 
-import type { Session } from "../types";
+import type { Permission, PermissionMap, Session } from "../types";
 
 export * from "./auth-service";
 
+// `Permission` từng được KHAI BÁO LẠI ở đây, y hệt bản trong ../types — hai
+// nguồn sự thật cho cùng một shape. Giờ chỉ còn re-export.
+export type { Permission, PermissionMap };
+
 // ============================================================================
 // Types
 // ============================================================================
 
-export interface Permission {
-  resourceCode: string;
-  actionCode: string;
-}
-
 export interface ExtendedUser {
   id: string;
   name?: string | null;
   email?: string | null;
   image?: string | null;
   roles?: string[];
+  /**
+   * Dạng GỌN, nên dùng: resource → các action. Xem `PermissionMap`.
+   * Có `permissionMap` thì `permissions` bị BỎ QUA hoàn toàn.
+   */
+  permissionMap?: PermissionMap;
+  /** Dạng cũ. Vẫn chạy nguyên vẹn, chỉ tốn ~4,5 lần payload. */
   permissions?: Permission[];
 }
 
@@ -72,17 +77,105 @@ export function getActionCode(action: string): string {
 // Permission Functions
 // ============================================================================
 
+// ============================================================================
+// Permission Map — chuyển đổi + tra cứu
+// ============================================================================
+
+/** `Permission[]` → dạng gọn. Tự gộp trùng. */
+export function toPermissionMap(permissions: Permission[]): PermissionMap {
+  const map: PermissionMap = {};
+  for (const p of permissions) {
+    const actions = (map[p.resourceCode] ??= []);
+    if (!actions.includes(p.actionCode)) actions.push(p.actionCode);
+  }
+  return map;
+}
+
+/** Dạng gọn → `Permission[]`. Chỉ dùng ở ranh giới với code chưa chuyển. */
+export function fromPermissionMap(map: PermissionMap): Permission[] {
+  const out: Permission[] = [];
+  for (const resourceCode of Object.keys(map)) {
+    for (const actionCode of map[resourceCode]) {
+      out.push({ resourceCode, actionCode });
+    }
+  }
+  return out;
+}
+
+/**
+ * Nhớ bản đã chuyển đổi theo CHÍNH mảng `permissions` của session cũ.
+ *
+ * Không có nó, mỗi lần `checkPermission` của app chưa chuyển sẽ dựng lại map
+ * từ đầu — một trang gọi 20 lần là 20 lần dựng, tệ hơn hẳn phép quét tuyến
+ * tính có thoát sớm mà nó thay thế. WeakMap khoá theo tham chiếu mảng nên
+ * session hết hạn là bản nhớ tự rụng, không cần dọn.
+ */
+const legacyMapCache = new WeakMap<Permission[], PermissionMap>();
+
+/**
+ * Đọc quyền của session về dạng gọn, bất kể app gán kiểu nào.
+ * Trả `undefined` khi session không có user (khác hẳn "user không có quyền
+ * nào", vốn là `{}`) để chỗ gọi tự quyết cách xử lý.
+ */
+function readPermissionMap(session: Session | null): PermissionMap | undefined {
+  if (!session?.user) return undefined;
+  const user = session.user as ExtendedUser;
+  if (user.permissionMap) return user.permissionMap;
+  if (!user.permissions) return {};
+
+  let cached = legacyMapCache.get(user.permissions);
+  if (!cached) {
+    cached = toPermissionMap(user.permissions);
+    legacyMapCache.set(user.permissions, cached);
+  }
+  return cached;
+}
+
+function isAdminUser(user: ExtendedUser): boolean {
+  return Boolean(
+    user.roles?.includes(ADMIN_ROLE_CODE) || user.roles?.includes("SUPER_ADMIN"),
+  );
+}
+
+/**
+ * Các resource user chạm được — dùng để lọc menu và App Launcher.
+ *
+ * `actionCode` bỏ trống = "có BẤT KỲ action nào" (thấy tile là vào được trang);
+ * truyền `"view"` = đúng nghĩa xem được. Admin trả `Set(["*"])`, khớp quy ước
+ * wildcard mà cây điều hướng đang dùng.
+ *
+ * Có sẵn ở core vì mọi app đều tự viết lại đúng vòng lặp này, mỗi nơi một kiểu.
+ */
+export function getAccessibleResources(
+  session: Session | null,
+  actionCode?: string,
+): Set<string> {
+  if (!session?.user) return new Set();
+  if (isAdminUser(session.user as ExtendedUser)) return new Set(["*"]);
+
+  const map = readPermissionMap(session) ?? {};
+  const out = new Set<string>();
+  for (const resourceCode of Object.keys(map)) {
+    if (!actionCode || map[resourceCode].includes(actionCode)) {
+      out.add(resourceCode);
+    }
+  }
+  return out;
+}
+
 /**
  * Get all permissions from session
+ *
+ * Trả về dạng CŨ (`Permission[]`) nên phải bung map ra — mỗi lần gọi là một
+ * lần dựng lại vài nghìn object. Cần lọc theo resource thì dùng
+ * `getAccessibleResources`; cần kiểm một quyền thì dùng `checkPermission`.
  */
 export function getUserPermissions(session: Session | null): Permission[] {
   if (!session?.user) return [];
   const user = session.user as ExtendedUser;
 
-  if (!user.permissions) {
-    return [];
-  }
-  return user.permissions;
+  if (user.permissionMap) return fromPermissionMap(user.permissionMap);
+  return user.permissions ?? [];
 }
 
 /**
@@ -135,10 +228,7 @@ export function getCrudPermissionsFromSession(
   }
 
   // Check admin role first (fastest check)
-  const isAdmin =
-    user.roles?.includes(ADMIN_ROLE_CODE) ||
-    user.roles?.includes("SUPER_ADMIN");
-  if (isAdmin) {
+  if (isAdminUser(user)) {
     return {
       create: true,
       view: true,
@@ -151,16 +241,12 @@ export function getCrudPermissionsFromSession(
     };
   }
 
-  // Pre-compute permission keys for fast lookup
-  const permissions = user.permissions || [];
-  const permissionKeys = new Set(
-    permissions.map((p) => `${p.resourceCode}:${p.actionCode}`),
-  );
+  // Chỉ lấy danh sách action CỦA RIÊNG entity này. Bản cũ dựng một Set
+  // "resource:action" cho TOÀN BỘ quyền của user (vài nghìn chuỗi) rồi hỏi
+  // đúng 8 lần — dựng lại ở mỗi lần gọi hàm.
+  const actions = readPermissionMap(session)?.[entity] ?? [];
 
-  const hasPermission = (action: string) => {
-    const key = `${entity}:${action}`;
-    return permissionKeys.has(key);
-  };
+  const hasPermission = (action: string) => actions.includes(action);
 
   return {
     create: hasPermission(getActionCode("create")),
@@ -191,20 +277,13 @@ export function checkPermission(
 
   // Admin role bypass — checked BEFORE the empty-permissions guard so an admin
   // who relies on their role (no explicit permission rows) is not locked out.
-  if (
-    user.roles?.includes(ADMIN_ROLE_CODE) ||
-    user.roles?.includes("SUPER_ADMIN")
-  ) {
+  if (isAdminUser(user)) {
     return true;
   }
 
-  if (!user.permissions || user.permissions.length === 0) {
-    return false;
-  }
-
-  return user.permissions.some(
-    (p) => p.resourceCode === resourceCode && p.actionCode === actionCode,
-  );
+  // Tra thẳng theo resource rồi quét danh sách action của riêng nó (vài chục
+  // phần tử), thay vì quét tuyến tính CẢ mảng quyền như bản `Permission[]`.
+  return readPermissionMap(session)?.[resourceCode]?.includes(actionCode) ?? false;
 }
 
 /**

package/src/rbac/__tests__/permission-service.test.ts

@@ -0,0 +1,113 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { clearAllPermissionsCache } from "../index";
+import {
+  getCachedUserPermissions,
+  getUserPermissionsFromDB,
+} from "../permission-service";
+
+import type { RBACPrismaClient } from "../permission-service";
+
+/** DB giả: mỗi lượt gọi lấy kịch bản kế tiếp trong hàng đợi. */
+function makeDb(outcomes: Array<{ rows?: unknown[]; fail?: Error }>): {
+  db: RBACPrismaClient;
+  calls: () => number;
+} {
+  let calls = 0;
+  const db = {
+    userRole: {
+      findMany: async () => {
+        const outcome = outcomes[Math.min(calls, outcomes.length - 1)];
+        calls += 1;
+        if (outcome.fail) throw outcome.fail;
+        return outcome.rows as never;
+      },
+    },
+  } as unknown as RBACPrismaClient;
+  return { db, calls: () => calls };
+}
+
+const ROW_WITH_VIEW = {
+  roleCode: "accountant",
+  role: { rolePermissions: [{ resourceCode: "receipt", actionCode: "view" }] },
+};
+
+describe("getUserPermissionsFromDB", () => {
+  beforeEach(async () => {
+    await clearAllPermissionsCache();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  it("dedupe quyền trùng giữa các vai trò", async () => {
+    const { db } = makeDb([
+      {
+        rows: [
+          ROW_WITH_VIEW,
+          {
+            roleCode: "cashier",
+            role: {
+              rolePermissions: [
+                { resourceCode: "receipt", actionCode: "view" },
+                { resourceCode: "receipt", actionCode: "create" },
+              ],
+            },
+          },
+        ],
+      },
+    ]);
+
+    expect(await getUserPermissionsFromDB(db, "u1")).toEqual([
+      { resourceCode: "receipt", actionCode: "view" },
+      { resourceCode: "receipt", actionCode: "create" },
+    ]);
+  });
+
+  it("user KHÔNG có vai trò nào → mảng rỗng (đây là câu trả lời hợp lệ)", async () => {
+    const { db } = makeDb([{ rows: [] }]);
+    expect(await getUserPermissionsFromDB(db, "u1")).toEqual([]);
+  });
+
+  it("query hỏng → NÉM, không được nuốt thành mảng rỗng", async () => {
+    const { db } = makeDb([{ fail: new Error("P1017 ConnectionClosed") }]);
+
+    // Trả `[]` ở đây là biến sự cố hạ tầng thành "user không có quyền nào" —
+    // menu rỗng, nút biến mất, mà không ai biết là DB hỏng.
+    await expect(getUserPermissionsFromDB(db, "u1")).rejects.toThrow(
+      "P1017 ConnectionClosed",
+    );
+  });
+});
+
+describe("getCachedUserPermissions", () => {
+  beforeEach(async () => {
+    await clearAllPermissionsCache();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  it("lỗi DB KHÔNG bị đóng băng vào cache 5 phút", async () => {
+    // Lượt 1 hỏng, lượt 2 trở đi thành công.
+    const { db } = makeDb([
+      { fail: new Error("nghẽn DB") },
+      { rows: [ROW_WITH_VIEW] },
+    ]);
+
+    await expect(getCachedUserPermissions(db, "u1")).rejects.toThrow(
+      "nghẽn DB",
+    );
+
+    // Nếu lỗi bị nuốt thành `[]`, `[]` đã được setToCache và user mất sạch
+    // quyền suốt 5 phút kể cả khi DB hồi ngay lập tức.
+    expect(await getCachedUserPermissions(db, "u1")).toEqual([
+      { resourceCode: "receipt", actionCode: "view" },
+    ]);
+  });
+
+  it("lượt thành công thì có cache — không hỏi DB lần hai", async () => {
+    const { db, calls } = makeDb([{ rows: [ROW_WITH_VIEW] }]);
+
+    await getCachedUserPermissions(db, "u1");
+    await getCachedUserPermissions(db, "u1");
+
+    expect(calls()).toBe(1);
+  });
+});

package/src/rbac/index.ts

@@ -106,22 +106,19 @@ export { getFromCache, setToCache, pendingQueries };
 // Permissions
 // ============================================================================
 
-interface ExtendedUser {
-  id: string;
-  name?: string | null;
-  email?: string | null;
-  image?: string | null;
-  roles?: string[];
-  permissions?: Permission[];
-}
-
 // Permission checks now live in a single hardened source: @goerp/core/auth
 // (bypass is dev-only; the admin role is honored BEFORE the empty-permissions
 // guard). Re-exported here so existing @goerp/core/rbac consumers are unchanged
 // and can never diverge from auth again.
+//
+// (Ở đây từng có thêm một `interface ExtendedUser` thứ ba, không ai dùng — bản
+// thật nằm ở ../auth.)
 export {
   getUserPermissions,
   getCrudPermissionsFromSession,
+  getAccessibleResources,
+  toPermissionMap,
+  fromPermissionMap,
   checkPermission,
   hasPermission,
   requirePermission,

package/src/rbac/permission-service.ts

@@ -41,6 +41,20 @@ export interface RBACPrismaClient {
  * Fetch user permissions from database based on roles.
  * Deduplicates permissions by resourceCode:actionCode.
  *
+ * NÉM LỖI khi query hỏng — KHÔNG trả `[]`.
+ *
+ * Trước 2026-08 hàm này `catch → logger.error → return []`. Trong một hệ RBAC,
+ * "không có quyền nào" và "không hỏi được quyền" là hai chuyện khác hẳn nhau,
+ * nhưng cả hai đều hiện ra y như nhau: menu rỗng, nút biến mất, API trả 403.
+ * Người dùng đọc thành "tôi bị thu hồi quyền" và đi báo sai chỗ.
+ *
+ * Tệ hơn: `getCachedUserPermissions` bên dưới ghi kết quả vào cache 5 phút.
+ * Một cú nghẽn DB chớp nhoáng vì thế bị ĐÓNG BĂNG thành mảng rỗng suốt 5 phút
+ * kể cả khi DB đã hồi ngay sau đó. Ném lỗi thì `.catch` ở đó không ghi cache,
+ * lượt sau tự hỏi lại DB.
+ *
+ * Nơi gọi phải tự quyết: hiện error boundary, hay hạ cấp có chủ đích.
+ *
  * @param db - The tenant-specific Prisma Client instance
  * @param userId - The user ID to fetch permissions for
  */
@@ -94,7 +108,7 @@ export async function getUserPermissionsFromDB(
     return uniquePermissions;
   } catch (error) {
     logger.error("Error fetching user permissions from DB", error);
-    return [];
+    throw error;
   }
 }
 

package/src/system/services/__tests__/settings-service.test.ts

@@ -0,0 +1,85 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const unstableCacheMock = vi.fn(
+  (
+    fn: (...args: unknown[]) => unknown,
+    _keyParts?: string[],
+    _options?: unknown,
+  ) =>
+    (...args: unknown[]) =>
+      fn(...args),
+);
+const revalidateTagMock = vi.fn();
+
+vi.mock("next/cache", () => ({
+  unstable_cache: (
+    fn: (...args: unknown[]) => unknown,
+    keyParts?: string[],
+    options?: unknown,
+  ) => unstableCacheMock(fn, keyParts, options),
+  revalidateTag: (...args: unknown[]) => revalidateTagMock(...args),
+}));
+
+const { SettingsService, configureSettingsService, SYSTEM_SETTINGS_CACHE_TAG } =
+  await import("../settings-service");
+
+function fakeDb(value: string | null) {
+  return {
+    systemConfig: {
+      findUnique: vi.fn(async () => (value === null ? null : { value })),
+      upsert: vi.fn(async () => ({})),
+    },
+  };
+}
+
+describe("SettingsService cache options", () => {
+  beforeEach(() => {
+    unstableCacheMock.mockClear();
+    revalidateTagMock.mockClear();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  it("LUÔN khai `revalidate` hữu hạn — thiếu nó là cache vĩnh viễn", async () => {
+    configureSettingsService(fakeDb(JSON.stringify({ a: 1 })));
+
+    await SettingsService.getSettings("demo", { a: 0 });
+
+    const options = unstableCacheMock.mock.calls[0][2] as {
+      tags: string[];
+      revalidate?: number;
+    };
+    // Bỏ `revalidate` là entry sống tới khi process chết: mọi đường ghi thẳng
+    // `system_config` mà quên xoá tag sẽ đóng băng setting cũ VĨNH VIỄN.
+    expect(options.revalidate).toBeTypeOf("number");
+    expect(options.revalidate).toBeGreaterThan(0);
+    expect(options.tags).toContain(SYSTEM_SETTINGS_CACHE_TAG);
+  });
+
+  it("saveSettings xoá tag sau khi ghi", async () => {
+    const db = fakeDb(null);
+    configureSettingsService(db);
+
+    await SettingsService.saveSettings("demo", { a: 1 });
+
+    expect(db.systemConfig.upsert).toHaveBeenCalledOnce();
+    expect(revalidateTagMock).toHaveBeenCalledWith(
+      SYSTEM_SETTINGS_CACHE_TAG,
+      "max",
+    );
+  });
+
+  it("revalidateTag ném ngoài request scope KHÔNG được kéo đổ lệnh ghi", async () => {
+    const db = fakeDb(null);
+    configureSettingsService(db);
+    revalidateTagMock.mockImplementation(() => {
+      throw new Error("Invariant: static generation store missing");
+    });
+
+    // Cron/task nền chạy ngoài request scope. Lời gọi nằm SAU lệnh ghi DB nên
+    // để lỗi thoát ra là "lưu xong rồi vẫn báo lỗi" cho người dùng.
+    await expect(
+      SettingsService.saveSettings("demo", { a: 1 }),
+    ).resolves.toBeUndefined();
+    expect(db.systemConfig.upsert).toHaveBeenCalledOnce();
+  });
+});

package/src/system/services/settings-service.ts

@@ -1,6 +1,45 @@
-import { cache } from "react";
 import { revalidateTag, unstable_cache } from "next/cache";
 
+import { logger } from "../../utils";
+
+/** Tag dùng chung cho mọi entry cache của SettingsService. */
+export const SYSTEM_SETTINGS_CACHE_TAG = "system-settings";
+
+/**
+ * TTL của cache setting — LƯỚI AN TOÀN, không phải cơ chế chính.
+ *
+ * `saveSettings` xoá tag ngay nên đường ghi chuẩn vẫn hiện tức thì. TTL này
+ * chặn kịch bản kẹt vĩnh viễn: `unstable_cache` KHÔNG khai `revalidate` là
+ * cache tới khi process chết. Mọi đường ghi thẳng bảng `system_config` không
+ * qua `saveSettings` (route CRUD generic của app, script, migration) — hoặc ghi
+ * từ tiến trình khác nên không xoá được cache của tiến trình này — đều làm
+ * setting cũ đóng băng luôn.
+ *
+ * 60s: đủ ngắn để sai sót tự lành, đủ dài để không thành một vòng DB mỗi lượt
+ * đọc setting.
+ */
+const SETTINGS_TTL_SECONDS = 60;
+
+/**
+ * `revalidateTag` NÉM khi không có request scope — Next 16 throw
+ * "Invariant: static generation store missing" nếu `workAsyncStorage` rỗng.
+ * Cron và task nền là chạy ngoài scope, mà lời gọi luôn nằm SAU lệnh ghi DB:
+ * không bọc thì dữ liệu đã lưu xong vẫn báo lỗi ngược cho người gọi.
+ *
+ * Nuốt lỗi ở đây CÓ CHỦ ĐÍCH và chỉ an toàn vì cache đã có TTL hữu hạn — tệ
+ * nhất là chậm đúng một nhịp TTL. Vẫn log để lộ chỗ gọi sai ngữ cảnh.
+ */
+function safeRevalidateSettingsTag(): void {
+  try {
+    revalidateTag(SYSTEM_SETTINGS_CACHE_TAG, "max");
+  } catch (error) {
+    logger.warn(
+      `revalidateTag("${SYSTEM_SETTINGS_CACHE_TAG}") bỏ qua — gọi ngoài request scope`,
+      { error: error instanceof Error ? error.message : String(error) },
+    );
+  }
+}
+
 /**
  * DB được INJECT từ app (core không import prisma client cụ thể). Trước
  * 2026-07 chỗ này là `const db: any = {...} // Mocked for build` — mọi
@@ -115,7 +154,10 @@ export class SettingsService {
         }
       },
       [`system-settings-${key}`],
-      { tags: ["system-settings"] },
+      {
+        tags: [SYSTEM_SETTINGS_CACHE_TAG],
+        revalidate: SETTINGS_TTL_SECONDS,
+      },
     )();
   }
 
@@ -155,7 +197,7 @@ export class SettingsService {
       },
     });
 
-    revalidateTag("system-settings", "max");
+    safeRevalidateSettingsTag();
   }
 
   static async saveAuditSettings(settings: AuditSettings): Promise<void> {

package/src/types/index.ts

@@ -164,6 +164,23 @@ export interface Permission {
 
 export type PermissionType = Permission;
 
+/**
+ * Bản GỌN của `Permission[]` để nhét vào session: resource → các action.
+ *
+ * Vì sao cần: một user nhiều vai trò có thể có hàng nghìn cặp
+ * resource/action, mà `Permission[]` lặp lại tên resource ở MỌI cặp. Đo trên
+ * ERP thật (2.428 quyền / 73 resource): `Permission[]` là 139,7 KB JSON, bản
+ * map là ~31 KB — mà payload đó đi kèm mọi lượt đọc session, kể cả về client.
+ *
+ * Tra cứu cũng đổi chất: `Permission[]` bắt quét tuyến tính cả mảng cho MỖI
+ * lần `checkPermission`, map thì tra thẳng theo resource rồi chỉ quét danh
+ * sách action của riêng nó (vài chục phần tử).
+ *
+ * `ExtendedUser` nhận CẢ HAI: app chưa chuyển vẫn gán `permissions`, mọi hàm
+ * kiểm quyền của core đọc `permissionMap` trước rồi mới lùi về `permissions`.
+ */
+export type PermissionMap = Record<string, string[]>;
+
 export type PermissionMatrix = Record<string, Record<string, boolean>>;
 
 // ============================================================================