@goplusvn/core 0.1.66 → 0.1.69

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
 
+## 0.1.69 — Hàng rào kiến trúc thành thư viện: `@goerp/core/guardrails`
+
+Mỗi app dựng từ bộ init trước đây tự chép một file `architecture.test.ts`. Chép
+là đóng băng: bài học rút ra ở app này không bao giờ tới được app kia, và bản
+chép mục dần cho tới lúc không ai dám sửa. Nay luật sống trong core, app chỉ
+khai phần dữ liệu của mình.
+
+**`runCoreGuardrails({...})`** — một lời gọi, sinh ra ~41 thước theo bảy nhóm
+(`auth` `rbac` `layering` `one-door` `structure` `design` `safety` + trần
+`debt`). App khai đúng ba thứ: `allowlists` (nợ cũ, CHỈ được rút bớt),
+`ceilings` (trần theo thư mục, chỉ được hạ và không được dư), `skip` (tắt hẳn,
+bắt buộc kèm lý do). Thêm `doors` / `domain` / `extraRules` cho từ vựng riêng.
+Vinhhoa chuyển sang preset: 1.273 → 547 dòng, số thước chạy TĂNG 57 → 79.
+
+**Thước tự bỏ qua khi không áp dụng** (`NOT_APPLICABLE`): cùng một preset chạy
+được trên app starter trống lẫn app 1.400 file, không phải khai thừa thứ chưa
+có.
+
+**Mỗi thước mang theo `why` là sự cố THẬT** — thông báo lỗi in `[id] why → fix`,
+nên người gặp đỏ đọc được vì sao luật tồn tại thay vì đi tìm cách tắt nó.
+
+**Ratchet hai chiều**: `staleAllowlist` báo entry đã hết vi phạm (suất miễn trừ
+quá hạn chính là chỗ nợ mới chui vào), `debt/*-no-slack` báo trần dư.
+
+**Allowlist theo THƯ MỤC**: entry kết thúc bằng `/` miễn trừ cả cây con. Dùng
+cho `_handlers/` của dispatcher — resource là BIẾN theo loại đơn nên không khai
+được ở cổng, mà số file thì tăng mỗi lần thêm hành động; liệt kê từng file ở đó
+chỉ đẻ ra một danh sách phải sửa cho xanh.
+
+**`rbac/gate-*` đọc đúng chỗ khai quyền.** Bản đầu quét trần `resource: "..."`
+trên cả file và báo nhầm hai thứ rất phổ biến: `orderBy: { _count: { resource:
+"desc" } }` của Prisma, và payload nhật ký `logEntityAction({ resource:
+"stock-movement" })` — ở đó `resource` là tên THỰC THỂ bị ghi vết, không phải mã
+quyền. Nay chỉ đọc các đối số object literal ở TẦNG NGOÀI CÙNG của lời gọi cổng;
+tên cổng khai qua `domain.gateCalls` (mặc định `apiHandler` /
+`requirePermission` / `requireApiPermission`).
+
+**`goerp-guardrails`** — CLI chẩn đoán: liệt kê mọi thước kèm trạng thái, và
+`--write-baseline` sinh sẵn khối `allowlists`/`ceilings` đóng băng hiện trạng
+cho app đang migrate.
+
+**`@goerp/core/eslint`** — lớp chặn thứ hai, lúc gõ code thay vì lúc chạy test.
+Mỗi thông báo kết bằng `[rule/id]` tương ứng để hai lớp nói cùng một ngôn ngữ.
+
+Bộ init: `templates/starter-app` nay đi kèm `architecture.test.ts` mỏng (một lời
+gọi + trần `any` của chính bộ khung), `eslint.config.mjs`, `prettier.config.mjs`
+và mục hàng rào trong `AGENTS.md`.
+
+`vitest` thành peerDependency (optional) — chỉ cần khi app dùng
+`@goerp/core/guardrails`.
+
+## 0.1.68 — Trang Người dùng: bảng chuẩn + phân trang chung hai chế độ xem
+
+Trang `UsersClientPage` lệch chuẩn ở cả hai chế độ: card view KHÔNG phân trang
+(38 user là 38 thẻ đổ hết xuống), còn table view là `BasicUserTable` tự chế —
+`useState` trang cục bộ, nút "Trang trước/sau" tự vẽ, số trang không vào URL và
+không ăn nhập gì với card view.
+
+**`UsersTable` mới** (`user/components/users-table.tsx`): column def tanstack
+trên `DataTable` chuẩn của core — STT tự tính theo trang, sticky header, thanh
+phân trang "Hiển thị x - y trong tổng số n mục" + ô nhập trang + chọn số dòng,
+click dòng mở dialog hồ sơ. `BasicUserTable` xoá hẳn.
+
+**Phân trang CHUNG qua URL (`?page&pageSize`)**: client page cắt trang một chỗ
+cho cả hai chế độ (server vẫn trả toàn bộ danh sách đã lọc). Card view thêm
+footer `ShallowPagination`; đổi trang ghi URL bằng `history.replaceState` —
+không kéo lượt RSC chỉ để lấy dữ liệu client đang cầm. Chuyển qua lại
+bảng ↔ thẻ giữ nguyên trang đang đứng. Đổi bộ lọc/pageSize thì về trang 1;
+trang đang đứng vượt phạm vi (do lọc bớt) thì tự kẹp về trang cuối.
+
+**Thêm `ShallowPagination` vào `@goerp/core/ui`** (port từ vinhhoa, giao diện
+1:1 với `DataTablePagination`/`UrlPagination`) — cho mọi trang mà client làm
+chủ dữ liệu; trang SSR thuần vẫn dùng `UrlPagination`.
+
+**Sửa bug toolbar nuốt query**: effect debounce ô tìm kiếm trong `UserToolbar`
+phụ thuộc identity `onSearchChange`; URL đổi → client page tạo lại callback →
+effect chạy lại → 300ms sau phát `""` → `router.push` XOÁ sạch query (mất
+`?page` vừa bấm). Nay chỉ phát khi giá trị thật sự đổi so với lần phát trước,
+và `applyFilter` phía client page đọc query tại thời điểm gọi
+(`window.location.search`) thay vì phụ thuộc `searchParams`.
+
+Kèm `user-visuals.tsx` dùng chung palette avatar + badge trạng thái/loại user
+cho card view lẫn table (trước lặp 2 bản trong card view và bảng cũ).
+
+## 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 **35,5 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

package/bin/goerp-guardrails.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// CLI `goerp-guardrails` — chạy hàng rào kiến trúc của @goerp/core lên app hiện
+// tại và báo cáo (không làm đỏ CI).
+//
+//   pnpm guardrails                    # bảng trạng thái từng thước
+//   pnpm guardrails --verbose          # in đủ mọi chỗ chưa đạt
+//   pnpm guardrails --write-baseline   # in khối allowlist/ceilings/skip để dán
+//
+// Engine viết bằng TypeScript và import không kèm đuôi file, nên bộ strip-types
+// sẵn có của Node không nạp được — chạy qua `tsx` (đã nằm trong devDependencies
+// của bộ khung; app cũ chưa có thì `pnpm add -D tsx`).
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const doctor = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "doctor.ts");
+const appRoot = process.cwd();
+
+/** tsx của app trước, rồi tới tsx cài kèm core. */
+function findTsx() {
+  for (const from of [join(appRoot, "package.json"), import.meta.url]) {
+    try {
+      return createRequire(from).resolve("tsx/cli");
+    } catch {
+      /* thử chỗ kế tiếp */
+    }
+  }
+  return null;
+}
+
+const tsx = findTsx();
+if (!tsx) {
+  console.error("Không tìm thấy `tsx`. Cài bằng: pnpm add -D tsx");
+  process.exit(1);
+}
+
+// Không truyền appRoot làm tham số vị trí: doctor mặc định lấy cwd, và người
+// dùng vẫn có thể chỉ định thư mục khác.
+const { status } = spawnSync(process.execPath, [tsx, doctor, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: appRoot,
+});
+process.exit(status ?? 1);

package/eslint/index.mjs

@@ -0,0 +1,120 @@
+/**
+ * Tầng lint của hàng rào GoERP — `@goerp/core/eslint`.
+ *
+ * Cùng bài học với `@goerp/core/guardrails`, khác thời điểm bắt:
+ *
+ *   - guardrails chạy lúc `pnpm test`, quét được quan hệ giữa NHIỀU file
+ *     (ranh giới module, đếm nợ theo thư mục, route nào chưa gác);
+ *   - lint chạy ngay trong editor, chỉ thấy MỘT file — nhưng thấy lúc người ta
+ *     còn đang gõ, tức là trước khi cái sai kịp lan ra.
+ *
+ * Nên ở đây chỉ có những luật quyết định được trong phạm vi một file, và mỗi
+ * thông báo đều dẫn về id của thước tương ứng để hai tầng không trôi khỏi nhau.
+ *
+ * Cách dùng trong eslint.config.mjs của app:
+ *
+ *   import goerp from "@goerp/core/eslint"
+ *   export default [ ...(cấu hình sẵn có), ...goerp() ]
+ *
+ * Cố ý KHÔNG phụ thuộc plugin nào: chỉ dùng luật lõi của ESLint, nên khối này
+ * ghép được vào mọi cấu hình mà không kéo thêm dependency hay đụng phiên bản.
+ */
+
+/** @type {import("eslint").Linter.RuleEntry} */
+const NO_RESTRICTED_IMPORTS = [
+  "error",
+  {
+    paths: [
+      {
+        name: "next-auth",
+        message:
+          "next-auth đã gỡ — dùng Better Auth (@/lib/auth). [auth/no-next-auth]",
+      },
+      {
+        name: "@goerp/core/storage",
+        message:
+          "Kho tập tin đi qua đúng một cửa: import @/lib/storage. Cửa đó là nơi " +
+          "gọi configureStorage — import thẳng core thì chạy vào engine chưa cấu " +
+          "hình. [one-door/storage]",
+      },
+      {
+        name: "@goerp/core/branch-scope",
+        message:
+          "Phạm vi chi nhánh đi qua cửa hạ tầng của app (@/lib/rbac/branch-scope " +
+          "hoặc composition root), đừng import thẳng core. [one-door/branch-scope]",
+      },
+    ],
+    patterns: [
+      {
+        group: ["@/modules/*/services/*", "@/modules/*/repositories/*", "@/modules/*/lib/*"],
+        message:
+          "Deep-import xuyên ranh giới module. Dùng public API `@/modules/<domain>`. " +
+          "(Ngoại lệ đã được thước kiểm tra tự nhận: stub app/api và file server " +
+          "action.) [layering/module-public-api]",
+      },
+    ],
+  },
+];
+
+/** @type {import("eslint").Linter.RuleEntry} */
+const NO_RESTRICTED_SYNTAX = [
+  "error",
+  {
+    selector: "NewExpression[callee.name='PrismaClient']",
+    message:
+      "Chỉ composition root (src/lib/prisma.ts) được tạo PrismaClient. Client thứ " +
+      "hai mở thêm một pool và không có extension audit/branch-guard. " +
+      "[one-door/single-prisma-client]",
+  },
+  {
+    selector:
+      "CallExpression[callee.object.name='window'][callee.property.name='open'] > " +
+      "Literal.arguments[value=/\\/export/]",
+    message:
+      "Tải file qua hook useExport (giữ header xác thực + báo lỗi). window.open " +
+      "tới endpoint export bỏ qua cả hai. [one-door/export-no-window-open]",
+  },
+  {
+    selector: "TSAsExpression > TSAnyKeyword",
+    message:
+      "`as any` tắt kiểm tra kiểu ngay chỗ dễ sai nhất. Nếu buộc phải dùng thì " +
+      "eslint-disable kèm lý do — số lượng còn bị đếm bởi thước [debt/any].",
+  },
+];
+
+/**
+ * @param {{ srcDir?: string }} [options]
+ * @returns {import("eslint").Linter.Config[]}
+ */
+export default function goerpEslintConfig(options = {}) {
+  const src = options.srcDir ?? "src";
+  return [
+    {
+      files: [`${src}/**/*.{ts,tsx}`],
+      rules: {
+        "no-restricted-imports": NO_RESTRICTED_IMPORTS,
+        "no-restricted-syntax": NO_RESTRICTED_SYNTAX,
+      },
+    },
+    {
+      // Composition root là nơi DUY NHẤT được làm những việc trên — nó chính là
+      // cái cửa mà các luật kia bắt mọi người đi qua.
+      files: [
+        `${src}/lib/prisma.ts`,
+        `${src}/lib/storage.ts`,
+        `${src}/lib/rbac/branch-scope.ts`,
+        `${src}/lib/branch-scope.ts`,
+        `${src}/server/bootstrap.ts`,
+      ],
+      rules: {
+        "no-restricted-imports": "off",
+        "no-restricted-syntax": "off",
+      },
+    },
+    {
+      // Script vận hành chạy độc lập ngoài Next: nó tự mở client của mình.
+      files: [`${src}/../scripts/**/*.{ts,mts}`, "scripts/**/*.{ts,mts}", "prisma/**/*.ts"],
+      rules: { "no-restricted-syntax": "off" },
+    },
+  ];
+}

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.66",
+  "version": "0.1.69",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -13,11 +13,13 @@
   "sideEffects": false,
   "bin": {
     "goerp-features": "./bin/goerp-features.mjs",
+    "goerp-guardrails": "./bin/goerp-guardrails.mjs",
     "goerp-init": "./bin/goerp-init.mjs"
   },
   "files": [
     "src",
     "bin",
+    "eslint",
     "scripts",
     "features",
     "templates",
@@ -95,7 +97,8 @@
     "./package.json": "./package.json",
     "./providers/brand-theme": "./src/providers/brand-theme.ts",
     "./storage": "./src/storage/index.ts",
-    "./storage/s3": "./src/storage/s3/index.ts"
+    "./storage/s3": "./src/storage/s3/index.ts",
+    "./eslint": "./eslint/index.mjs"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.0.0",
@@ -103,7 +106,8 @@
     "@smithy/node-http-handler": "^4.0.0",
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "vitest": ">=2"
   },
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.1101.0",
@@ -215,6 +219,9 @@
     },
     "@smithy/node-http-handler": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "scripts": {

package/scripts/doctor.ts

@@ -0,0 +1,99 @@
+/**
+ * `goerp doctor` — chạy toàn bộ hàng rào kiến trúc lên app hiện tại và BÁO CÁO,
+ * không làm đỏ CI.
+ *
+ * Nó tồn tại vì một app đã chạy nhiều tháng (thingtodo, tanloc, wu) không thể
+ * bật hết luật trong một lần: bật lên là vài trăm chỗ đỏ cùng lúc, và phản ứng
+ * tự nhiên khi thấy vậy là tắt luôn cả bộ luật. Nên có hai bước:
+ *
+ *   pnpm guardrails                    # xem mình đang ở đâu
+ *   pnpm guardrails --write-baseline   # in ra khối allowlist/ceilings/skip
+ *
+ * Dán khối đó vào `runCoreGuardrails({...})` là hiện trạng được ĐÓNG BĂNG: nợ
+ * cũ không chặn ai, nhưng từ đó trở đi không ai thêm nợ mới được nữa. Trả nợ
+ * tới đâu thì xoá entry / hạ trần tới đó — thước sẽ tự báo entry nào đã thừa.
+ */
+import { evaluateGuardrails } from "../src/guardrails/preset";
+import type { GuardrailResult } from "../src/guardrails/types";
+
+const args = process.argv.slice(2);
+const writeBaseline = args.includes("--write-baseline");
+const verbose = args.includes("--verbose") || args.includes("-v");
+const root = args.find((a) => !a.startsWith("-")) ?? process.cwd();
+
+const results = evaluateGuardrails({ root });
+
+const failed = results.filter((r) => r.status === "fail");
+const passed = results.filter((r) => r.status === "pass");
+const skipped = results.filter((r) => r.status === "skipped");
+const na = results.filter((r) => r.status === "not-applicable");
+
+const ICON: Record<GuardrailResult["status"], string> = {
+  pass: "✔",
+  fail: "✘",
+  skipped: "○",
+  "not-applicable": "–",
+};
+
+console.log(`\nHàng rào kiến trúc @goerp/core — ${root}\n`);
+for (const r of results) {
+  const count = r.violations.length ? ` (${r.violations.length})` : "";
+  console.log(`  ${ICON[r.status]} ${r.rule.id}${count}`);
+  if (r.status === "fail") {
+    const show = verbose ? r.violations : r.violations.slice(0, 3);
+    for (const v of show) console.log(`      - ${v}`);
+    if (!verbose && r.violations.length > 3) {
+      console.log(`      … còn ${r.violations.length - 3} chỗ (thêm --verbose)`);
+    }
+  }
+}
+
+console.log(
+  `\n${passed.length} đạt · ${failed.length} chưa đạt · ` +
+    `${skipped.length} đang tắt · ${na.length} không áp dụng\n`,
+);
+
+if (failed.length > 0 && !writeBaseline) {
+  console.log("Chạy lại với --write-baseline để lấy khối đóng băng hiện trạng.\n");
+}
+
+if (!writeBaseline) process.exit(0);
+
+/** Vi phạm của thước đếm-theo-thư-mục có dạng `app: 671 > trần 0`. */
+const CEILING_LINE = /^(\S+):\s+(\d+)\s+>/;
+
+const allowlists: Record<string, string[]> = {};
+const ceilings: Record<string, Record<string, number>> = {};
+const skip: Record<string, string> = {};
+
+for (const r of failed) {
+  const ceilingEntries = r.violations
+    .map((v) => CEILING_LINE.exec(v))
+    .filter((m): m is RegExpExecArray => m !== null);
+
+  if (ceilingEntries.length === r.violations.length && ceilingEntries.length > 0) {
+    ceilings[r.rule.id] = Object.fromEntries(
+      ceilingEntries.map((m) => [m[1], Number(m[2])]),
+    );
+    continue;
+  }
+
+  if (r.rule.staleAllowlist) {
+    // Vi phạm có thể kèm giải thích sau ` — `; allowlist chỉ nhận đường dẫn.
+    allowlists[r.rule.id] = r.violations.map((v) => v.split(" — ")[0].trim()).sort();
+    continue;
+  }
+
+  // Không có allowlist thì chỉ còn cách tắt hẳn — và phải ghi lý do.
+  skip[r.rule.id] = `TODO: ${r.violations.length} chỗ chưa đạt, chưa hẹn ngày trả`;
+}
+
+const block = { allowlists, ceilings, skip };
+console.log("// Dán vào runCoreGuardrails({ ... }) — sửa mọi dòng TODO thành lý do thật:");
+console.log(
+  JSON.stringify(block, null, 2)
+    .split("\n")
+    .filter((line) => !/^\s*"(allowlists|ceilings|skip)": \{\},?$/.test(line))
+    .join("\n"),
+);
+console.log();

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([]);
+  });
+});