@goplusvn/core 0.1.77 → 0.1.78

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.77",
+  "version": "0.1.78",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -54,6 +54,7 @@
     "./import": "./src/import/index.ts",
     "./auth/proxy-gate": "./src/auth/proxy-gate.ts",
     "./rbac/route-handlers": "./src/rbac/route-handlers.ts",
+    "./rbac/landing-path": "./src/rbac/landing-path.ts",
     "./workspace/route-handlers": "./src/workspace/route-handlers.ts",
     "./rbac/permissions-version": "./src/rbac/permissions-version.ts",
     "./ui/shared/table-styles": "./src/ui/shared/table-styles.ts",

package/src/guardrails/__tests__/guardrails.test.ts

@@ -343,6 +343,88 @@ describe("rule bắt được vi phạm thật", () => {
     ]);
   });
 
+  /**
+   * Ca lỗi thật: tanloc-spartronics khởi tạo mà không chép
+   * `services/navigation-service.ts`, nên layout truyền thẳng cây menu xuống —
+   * vai `staff` thấy đủ mục, bấm vào mới bị cổng gác đá về (2026-08-15).
+   */
+  const NAV_RULE = "rbac/nav-filtered-by-permission";
+
+  it(`${NAV_RULE} — layout cấp menu thô cho vỏ ứng dụng thì đỏ`, () => {
+    const results = run(
+      fixture({
+        "app/[lang]/(main)/layout.tsx": [
+          'import { navigations } from "@/data/navigations"',
+          "export default function L() {",
+          "  return <MainLayout navigation={navigations} />",
+          "}",
+        ].join("\n"),
+      }),
+    );
+    expect(resultOf(results, NAV_RULE).violations).toEqual([
+      "app/[lang]/(main)/layout.tsx — cấp menu cho vỏ ứng dụng mà không lọc",
+    ]);
+  });
+
+  it(`${NAV_RULE} — lọc bằng mốc rộng hơn cổng gác trang thì đỏ`, () => {
+    const results = run(
+      fixture({
+        "app/[lang]/(main)/layout.tsx": [
+          'import { getAccessibleResources } from "@goerp/core/auth"',
+          'import { filterNavigationTree } from "@goerp/core/navigation"',
+          'import { navigations } from "@/data/navigations"',
+          "export default async function L() {",
+          // Thiếu `"view"` = "có BẤT KỲ action nào" → menu rộng hơn trang mở được.
+          "  const nav = filterNavigationTree(navigations, getAccessibleResources(session))",
+          "  return <MainLayout navigation={nav} />",
+          "}",
+        ].join("\n"),
+      }),
+    );
+    expect(resultOf(results, NAV_RULE).violations).toEqual([
+      'app/[lang]/(main)/layout.tsx — lọc menu không theo action "view"',
+    ]);
+  });
+
+  it(`${NAV_RULE} — truy sang service mà layout gọi, không dừng ở layout`, () => {
+    const results = run(
+      fixture({
+        "app/[lang]/(main)/layout.tsx": [
+          'import { getNavigationForUser } from "@/services/navigation-service"',
+          "export default async function L() {",
+          "  const nav = await getNavigationForUser()",
+          "  return <MainLayout navigation={nav} />",
+          "}",
+        ].join("\n"),
+        "services/navigation-service.ts": [
+          'import { navigationsData } from "@/data/navigations"',
+          "export async function getNavigationForUser() { return navigationsData }",
+        ].join("\n"),
+      }),
+    );
+    expect(resultOf(results, NAV_RULE).violations).toEqual([
+      "services/navigation-service.ts (qua app/[lang]/(main)/layout.tsx) — cấp menu cho vỏ ứng dụng mà không lọc",
+    ]);
+  });
+
+  it(`${NAV_RULE} — file đọc menu cho việc KHÁC không bị bắt oan`, () => {
+    // Ba ca có thật trong vinhhoa/thingtodo/spartronics: sinh registry TỪ menu,
+    // seed RBAC từ menu, và provider tra tiêu đề tab. Không chỗ nào vẽ menu.
+    const results = run(
+      fixture({
+        "configs/permissions/menu-tree.ts":
+          'import { navigations } from "@/data/navigations"\nexport const MENU_TREE = navigations',
+        "app/api/resources/sync/route.ts":
+          'import { navigationsData } from "@/data/navigations"\nexport const POST = () => sync(navigationsData)',
+        "providers/index.tsx":
+          'import { navigations } from "@/data/navigations"\nexport const P = () => <TabNavigationProvider navigations={navigations} />',
+        "app/[lang]/layout.tsx":
+          'import { P } from "@/providers"\nexport default function Root() { return <P /> }',
+      }),
+    );
+    expect(resultOf(results, NAV_RULE).violations).toEqual([]);
+  });
+
   it("rbac/* tự bỏ qua khi app không truyền registry", () => {
     const results = run(fixture({ "lib/a.ts": "export const a = 1" }));
     expect(resultOf(results, "rbac/known-actions").status).toBe(

package/src/guardrails/rules/rbac.ts

@@ -18,6 +18,41 @@ const declaredResources = (ctx: GuardrailContext) =>
     (registryOf(ctx) ?? []).flatMap((f) => f.resources.map((r) => r.code)),
   );
 
+/** Cây menu thô. Mọi app đều để ở `data/navigations` — cũng là `options.navigations`. */
+const READS_RAW_NAV = /from\s+["'][^"']*data\/navigations["']/;
+
+/** Hai lối ra hợp lệ cho việc lọc menu. */
+const FILTERS_NAV = /(buildNavigationForSession|filterNavigationTree)\s*\(/;
+
+/**
+ * Các file nguồn (rel `srcDir`) mà `code` import từ TRONG app — cả `@/x` lẫn
+ * `./x`. Trả về mọi ứng viên phần mở rộng; chỗ gọi dùng `readCodeRel` nên file
+ * không tồn tại chỉ ra chuỗi rỗng, không cần kiểm tra trước.
+ */
+function localImportsOf(code: string, fromDir: string): string[] {
+  const out: string[] = [];
+  for (const m of code.matchAll(/from\s+["'](@\/|\.\.?\/)([^"']+)["']/g)) {
+    const base =
+      m[1] === "@/"
+        ? m[2]
+        : // `./a/b` và `../a/b` — gộp về đường dẫn tương đối srcDir rồi rút gọn.
+          `${fromDir}/${m[1]}${m[2]}`
+            .split("/")
+            .reduce<string[]>((acc, seg) => {
+              if (seg === "." || seg === "") return acc;
+              if (seg === "..") {
+                acc.pop();
+                return acc;
+              }
+              acc.push(seg);
+              return acc;
+            }, [])
+            .join("/");
+    out.push(`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`);
+  }
+  return out;
+}
+
 const isApiFile = (rel: string) =>
   (rel.startsWith("app/api/") && rel.endsWith("/route.ts")) ||
   /^modules\/[a-z-]+\/api\//.test(rel);
@@ -202,6 +237,91 @@ export const rbacRules: GuardrailRule[] = [
     },
   },
 
+  {
+    id: "rbac/nav-filtered-by-permission",
+    title: "file nào đọc cây menu thô cũng phải lọc theo quyền",
+    why:
+      "Cây menu là bản đồ TOÀN BỘ hệ thống. Truyền thẳng nó xuống layout thì " +
+      "mọi người đăng nhập đều thấy đủ mục — vai `staff` không có một quyền " +
+      "nào trên `role`/`user` vẫn thấy Vai trò, Người dùng; bấm vào thì cổng " +
+      "gác đá về trang chủ, menu hứa một đằng trang trả lời một nẻo, và người " +
+      "dùng chỉ đọc được là 'hệ thống lỗi'. Đúng lỗi này sống trong " +
+      "tanloc-spartronics tới 2026-08-15 vì app đó khởi tạo mà không chép " +
+      "`services/navigation-service.ts` — `filterNavigationTree` có trong core " +
+      "nhưng KHÔNG một chỗ nào gọi. Ẩn ở client không cứu được: layout render " +
+      "ra HTML nên mục ẩn bằng CSS vẫn nằm nguyên trong payload gửi xuống.",
+    fix:
+      "Dùng `buildNavigationForSession(navigations, session)` của " +
+      "`@goerp/core/navigation` (fail-closed, mốc `view` sẵn), hoặc tự gọi " +
+      "`filterNavigationTree`. File chỉ đọc menu cho việc khác (breadcrumb, " +
+      "sitemap) thì khai vào `allowlists[\"rbac/nav-filtered-by-permission\"]`.",
+    run(ctx) {
+      const allowed = new Set(
+        ctx.options.allowlists["rbac/nav-filtered-by-permission"] ?? [],
+      );
+
+      const problems: string[] = [];
+      const seen = new Set<string>();
+
+      const check = (rel: string, code: string, via?: string) => {
+        if (!code || seen.has(rel) || allowed.has(rel)) return;
+        seen.add(rel);
+        const label = via ? `${rel} (qua ${via})` : rel;
+        if (!FILTERS_NAV.test(code)) {
+          problems.push(`${label} — cấp menu cho vỏ ứng dụng mà không lọc`);
+          return;
+        }
+        // Mốc lọc phải TRÙNG mốc cổng gác trang. `getAccessibleResources` bỏ
+        // trống action = "có BẤT KỲ action nào" → menu rộng hơn trang mở được.
+        // `buildNavigationForSession` đã chốt `"view"` bên trong nên không soi.
+        if (
+          /getAccessibleResources\s*\(/.test(code) &&
+          !/getAccessibleResources\s*\([^)]*["']view["']/.test(code)
+        ) {
+          problems.push(`${label} — lọc menu không theo action "view"`);
+        }
+      };
+
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        const code = ctx.readCode(file);
+        // Chỉ soi chỗ menu đi VÀO GIAO DIỆN: prop `navigation` của vỏ ứng dụng
+        // (`MainLayout` của core), hoặc file layout. Quét mọi file đọc cây menu
+        // là báo oan hàng loạt — `configs/permissions/menu-tree.ts` sinh registry
+        // TỪ menu, `api/resources/sync` seed RBAC từ menu, trang audit tra nhãn
+        // resource: không chỗ nào trong số đó vẽ menu ra cả.
+        const feedsShell = /\bnavigation=\{/.test(code);
+        const isLayout = /(^|\/)layout\.tsx$/.test(rel);
+        if (!feedsShell && !isLayout) continue;
+
+        if (READS_RAW_NAV.test(code)) {
+          check(rel, code);
+          continue;
+        }
+        // Layout thường không tự đọc cây menu mà gọi một service
+        // (`getNavigationForUser`). Truy sang file đó: chính nó mới là chỗ
+        // quên lọc được, và không ai soi nó cả.
+        //
+        // CHỈ truy từ layout đang thật sự cấp `navigation=` cho vỏ. Truy từ mọi
+        // layout thì layout GỐC kéo theo `providers/index.tsx` — file này đọc
+        // cây menu để `TabNavigationProvider` tra tiêu đề tab, không vẽ menu, và
+        // bắt nó ở đây là báo oan ở cả ba app đang chạy.
+        if (!feedsShell) continue;
+        const dir = rel.split("/").slice(0, -1).join("/");
+        for (const dep of localImportsOf(code, dir)) {
+          const depCode = ctx.readCodeRel(dep);
+          if (depCode && READS_RAW_NAV.test(depCode)) check(dep, depCode, rel);
+        }
+      }
+      return problems;
+    },
+    staleAllowlist(ctx) {
+      return (
+        ctx.options.allowlists["rbac/nav-filtered-by-permission"] ?? []
+      ).filter((rel) => !ctx.existsInSrc(rel));
+    },
+  },
+
   {
     id: "rbac/gate-resource-declared",
     title: "resource mà cổng gác đều đã khai trong registry",

package/src/navigation/index.ts

@@ -2,10 +2,13 @@
 // Core navigation utilities for GoERP platform
 // Consolidated from packages/shared/navigation
 
+import { getAccessibleResources } from "../auth";
+
 import type {
   NavigationType,
   NavigationRootItem,
   NavigationNestedItem,
+  Session,
 } from "../types";
 
 /**
@@ -89,3 +92,49 @@ export function filterNavigationTree(
 
   return filteredNavigation;
 }
+
+/**
+ * Menu của MỘT session — bản ráp sẵn, đúng-mặc-định.
+ *
+ * `filterNavigationTree` ở trên là nguyên liệu, và trong hai năm nó là thứ DUY
+ * NHẤT core cung cấp: mỗi app tự viết lấy phần ráp trong
+ * `src/services/navigation-service.ts`. Bốn app, bốn bản chép tay, và mỗi bản
+ * lệch một kiểu — tanloc-spartronics thì không có file đó luôn, nên menu không
+ * hề được lọc: mọi người đăng nhập đều thấy đủ mục, bấm vào mới bị
+ * `requirePageAccess` đá về trang chủ (2026-08-15). Hàm này tồn tại để câu trả
+ * lời đúng có đúng MỘT chỗ.
+ *
+ * Ba mặc định ở đây đều là bài học đã trả giá, đừng đảo:
+ *
+ *  1. **Chưa đăng nhập ⇒ menu RỖNG.** Fail-closed. Cây menu là bản đồ toàn bộ
+ *     hệ thống; trả đầy đủ rồi tính sau là lộ cấu trúc màn hình cho người lạ.
+ *  2. **Mốc lọc mặc định là `"view"`**, TRÙNG mặc định của cổng gác trang
+ *     (`requirePageAccess(lang, resource)`). `getAccessibleResources` bỏ trống
+ *     action nghĩa là "có bất kỳ action nào" — lấy mốc đó thì menu rộng hơn
+ *     trang, tức là lại hứa một đằng trả lời một nẻo, chỉ lệch ít hơn.
+ *  3. **KHÔNG bắt lỗi.** Hai bản chép tay cũ `catch → return []`, biến sự cố DB
+ *     thành sidebar trắng trơn không lời giải thích — chế độ hỏng tệ nhất của
+ *     app RBAC: người dùng tưởng bị thu hồi quyền và đi báo lỗi sai chỗ. Cứ để
+ *     lỗi nổi lên error boundary.
+ *
+ * Core KHÔNG tự đọc session: app dùng better-auth, app dùng next-auth, và cách
+ * lấy session là thứ duy nhất khác nhau thật giữa chúng. App truyền session vào
+ * và tự bọc `cache()` của React nếu muốn gọi nhiều lần trong một request.
+ *
+ * ```ts
+ * // app/[lang]/(main)/layout.tsx
+ * const navigation = buildNavigationForSession(navigations, await getSession())
+ * ```
+ */
+export function buildNavigationForSession(
+  navigation: NavigationType[],
+  session: Session | null,
+  options: { action?: string } = {},
+): NavigationType[] {
+  if (!session?.user) return [];
+
+  return filterNavigationTree(
+    navigation,
+    getAccessibleResources(session, options.action ?? "view"),
+  );
+}

package/src/rbac/__tests__/landing-path.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createLandingPathResolver } from "../landing-path";
+import type { NavigationType } from "../../types";
+
+/**
+ * Ba thứ dễ hỏng ở đây, và hỏng thì người dùng KHÔNG vào được hệ thống:
+ *  - `landingPath` trỏ tới trang vai trò không còn quyền → phải bỏ qua, nếu
+ *    không sẽ là vòng chuyển hướng vô hạn.
+ *  - App chưa migrate cột → phải im lặng bỏ qua bước 1, không được ném.
+ *  - Người kiêm nhiều vai → theo vai MẠNH nhất (rank nhỏ nhất), tức theo đúng
+ *    thứ tự DB trả về.
+ */
+
+const NAV: NavigationType[] = [
+  {
+    title: "Tổng quan",
+    items: [
+      { title: "Trang chủ", href: "/", iconName: "House", resource: "dashboard" },
+      { title: "Hồ sơ", href: "/profile", iconName: "User" },
+    ],
+  },
+  {
+    title: "Bếp",
+    iconName: "Utensils",
+    items: [
+      {
+        title: "Đặt món",
+        href: "/ordering",
+        iconName: "Utensils",
+        resource: "ordering",
+      },
+      {
+        title: "Nhận món",
+        href: "/pickup",
+        iconName: "Hand",
+        resource: "pickup",
+      },
+    ],
+  },
+];
+
+/** Phiên có đúng bộ quyền được liệt kê, không phải admin. */
+function session(roles: string[], perms: Record<string, string[]>) {
+  return {
+    user: {
+      id: "u1",
+      roles,
+      permissionMap: perms,
+    },
+  } as any;
+}
+
+function fakePrisma(
+  rows: Array<{ landingPath: string | null }>,
+  opts?: { withColumn?: boolean; withRank?: boolean },
+) {
+  const findMany = vi.fn().mockResolvedValue(rows);
+  const role: any = { findMany };
+  if (opts?.withColumn !== false) {
+    role.fields = { landingPath: {} };
+    if (opts?.withRank !== false) role.fields.rank = {};
+  }
+  return { prisma: { role } as any, findMany };
+}
+
+describe("createLandingPathResolver", () => {
+  it("dùng landingPath của vai trò khi quyền còn hợp lệ", async () => {
+    const { prisma } = fakePrisma([{ landingPath: "/pickup" }]);
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(
+      resolve(session(["kitchen"], { pickup: ["view"] }), "vi"),
+    ).resolves.toBe("/vi/pickup");
+  });
+
+  it("bỏ qua landingPath đã mất quyền, rơi về mục menu đầu tiên mở được", async () => {
+    const { prisma } = fakePrisma([{ landingPath: "/pickup" }]);
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(
+      resolve(session(["staff"], { ordering: ["view"] }), "vi"),
+    ).resolves.toBe("/vi/profile");
+  });
+
+  it("bỏ qua landingPath không có trên menu (trang đã bị gỡ)", async () => {
+    const { prisma } = fakePrisma([{ landingPath: "/da-xoa" }]);
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(
+      resolve(session(["staff"], { ordering: ["view"] }), "vi"),
+    ).resolves.toBe("/vi/profile");
+  });
+
+  it("người kiêm nhiều vai đi theo dòng đầu tiên DB trả về (rank asc)", async () => {
+    const { prisma, findMany } = fakePrisma([
+      { landingPath: "/" },
+      { landingPath: "/pickup" },
+    ]);
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(
+      resolve(
+        session(["admin", "kitchen"], { dashboard: ["view"], pickup: ["view"] }),
+        "vi",
+      ),
+    ).resolves.toBe("/vi");
+    expect(findMany.mock.calls[0][0].orderBy).toEqual({ rank: "asc" });
+  });
+
+  it("app không có cột `rank` (vinhhoa) thì không sắp xếp, vẫn chạy", async () => {
+    const { prisma, findMany } = fakePrisma([{ landingPath: "/pickup" }], {
+      withRank: false,
+    });
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(
+      resolve(session(["kitchen"], { pickup: ["view"] }), "vi"),
+    ).resolves.toBe("/vi/pickup");
+    expect(findMany.mock.calls[0][0].orderBy).toBeUndefined();
+  });
+
+  it("app chưa migrate cột thì không hỏi DB, vẫn trả mục menu đầu tiên", async () => {
+    const { prisma, findMany } = fakePrisma([], { withColumn: false });
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(
+      resolve(session(["kitchen"], { pickup: ["view"] }), "vi"),
+    ).resolves.toBe("/vi/profile");
+    expect(findMany).not.toHaveBeenCalled();
+  });
+
+  it("mục không khai resource là trang ai đăng nhập cũng mở được", async () => {
+    const { prisma } = fakePrisma([{ landingPath: null }]);
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(resolve(session(["nobody"], {}), "vi")).resolves.toBe(
+      "/vi/profile",
+    );
+  });
+
+  it("chưa đăng nhập thì về trang đăng nhập", async () => {
+    const { prisma } = fakePrisma([]);
+    const resolve = createLandingPathResolver({ prisma, navigations: NAV });
+
+    await expect(resolve(null, "vi")).resolves.toBe("/vi/sign-in");
+  });
+});

package/src/rbac/__tests__/route-handlers.test.ts

@@ -0,0 +1,147 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// `Role.landingPath` là cột BỔ SUNG: chỉ app nào đã migrate mới có. Hai app
+// đang chạy thật dùng chung core này, nên handler phải tự dò và im lặng bỏ qua
+// — ghi bừa một cột không tồn tại là 500 ở mọi lần lưu vai trò.
+//
+// Đây cũng là chỗ chặn đường dẫn ra ngoài: `landingPath` là nơi người dùng bị
+// đưa tới ngay sau khi đăng nhập, để lọt "//host" là mở đường phishing.
+
+import { describe, expect, it } from "vitest";
+
+import {
+  createRoleItemHandlers,
+  createRolesCollectionHandlers,
+} from "../route-handlers";
+
+function fakeDb(opts: { withLandingPath: boolean }) {
+  const existing = {
+    id: "r1",
+    code: "staff",
+    name: "Nhân viên",
+    description: "",
+    status: "active",
+    landingPath: null as string | null,
+    rolePermissions: [],
+  };
+  const created: any[] = [];
+  const updated: any[] = [];
+
+  const tx = {
+    role: {
+      create: async ({ data }: any) => {
+        created.push(data);
+        return { ...existing, ...data };
+      },
+      update: async ({ data }: any) => {
+        updated.push(data);
+        return { ...existing, ...data };
+      },
+    },
+    rolePermission: {
+      deleteMany: async () => undefined,
+      createMany: async () => undefined,
+    },
+  };
+
+  const role: any = { findUnique: async () => existing };
+  // Prisma sinh sẵn `model.fields` — chỉ có khi schema thật khai cột đó.
+  if (opts.withLandingPath) role.fields = { landingPath: { name: "landingPath" } };
+
+  const prisma: any = {
+    role,
+    systemConfig: { upsert: async () => undefined },
+    $transaction: async (fn: any) => fn(tx),
+  };
+
+  const deps = {
+    prisma,
+    getSession: async () => ({ user: { id: "u1" } }),
+    getCrudPermissions: async () => ({
+      read: true,
+      create: true,
+      update: true,
+      delete: true,
+    }),
+  };
+
+  return { deps, created, updated };
+}
+
+const post = (body: unknown) =>
+  new Request("http://app.test/api/roles", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+
+const put = (body: unknown) =>
+  new Request("http://app.test/api/roles/r1", {
+    method: "PUT",
+    body: JSON.stringify(body),
+  });
+
+const ctx = { params: Promise.resolve({ id: "r1" }) };
+
+describe("roles route handlers — landingPath", () => {
+  it("ghi landingPath khi app ĐÃ có cột", async () => {
+    const { deps, created } = fakeDb({ withLandingPath: true });
+    const res = await createRolesCollectionHandlers(deps as any).POST(
+      post({ code: "staff", name: "Nhân viên", landingPath: "/ordering" })
+    );
+
+    expect(res.status).toBe(201);
+    expect(created[0].landingPath).toBe("/ordering");
+  });
+
+  it("app CHƯA migrate: không đưa landingPath vào data (không làm 500)", async () => {
+    const { deps, created } = fakeDb({ withLandingPath: false });
+    const res = await createRolesCollectionHandlers(deps as any).POST(
+      post({ code: "staff", name: "Nhân viên", landingPath: "/ordering" })
+    );
+
+    expect(res.status).toBe(201);
+    expect(created[0]).not.toHaveProperty("landingPath");
+  });
+
+  it("không gửi khóa landingPath thì KHÔNG đụng giá trị đang có", async () => {
+    const { deps, updated } = fakeDb({ withLandingPath: true });
+    await createRoleItemHandlers(deps as any).PUT(
+      put({ name: "Nhân viên" }),
+      ctx as any
+    );
+
+    expect(updated[0]).not.toHaveProperty("landingPath");
+  });
+
+  it("chuỗi rỗng = trả về 'tự suy ra' (null)", async () => {
+    const { deps, updated } = fakeDb({ withLandingPath: true });
+    await createRoleItemHandlers(deps as any).PUT(
+      put({ name: "Nhân viên", landingPath: "" }),
+      ctx as any
+    );
+
+    expect(updated[0].landingPath).toBeNull();
+  });
+
+  it.each(["//evil.example/x", "https://evil.example", "javascript:alert(1)", "ordering"])(
+    "chặn đường dẫn ra ngoài app: %s",
+    async (value) => {
+      const { deps, updated } = fakeDb({ withLandingPath: true });
+      await createRoleItemHandlers(deps as any).PUT(
+        put({ name: "Nhân viên", landingPath: value }),
+        ctx as any
+      );
+
+      expect(updated[0].landingPath).toBeNull();
+    }
+  );
+
+  it("GET trả landingPath để form sửa prefill được", async () => {
+    const { deps } = fakeDb({ withLandingPath: true });
+    const res = await createRoleItemHandlers(deps as any).GET(
+      new Request("http://app.test/api/roles/r1"),
+      ctx as any
+    );
+
+    expect(await res.json()).toMatchObject({ landingPath: null });
+  });
+});

package/src/rbac/landing-path.ts

@@ -0,0 +1,140 @@
+import { cache } from "react";
+
+import type { NavigationType } from "../types";
+import type { Session } from "../auth";
+import { checkPermission } from "../auth";
+
+/**
+ * TRANG MỞ ĐẦU của một người — nơi đưa họ tới sau khi đăng nhập, và nơi đá về
+ * khi họ mở một trang không có quyền.
+ *
+ * Mặc định của mọi app là cắm cứng "/" cho tất cả. Hệ quả: người chỉ có một
+ * phần việc (đặt cơm, nhận món, chấm công) vẫn bị ném vào bảng số liệu tổng —
+ * và khi trang chủ có quyền riêng thì "/" còn là ngõ cụt thật sự với họ.
+ *
+ * Thứ tự quyết định, dừng ở cái đầu tiên hợp lệ:
+ *
+ *  1. `landingPath` của vai trò, ưu tiên vai trò MẠNH nhất (`rank` nhỏ nhất) —
+ *     người kiêm nhiều vai vào trang của vai cao nhất.
+ *  2. Mục ĐẦU TIÊN trên menu mà họ mở được, theo đúng thứ tự sidebar.
+ *  3. "/" — chịu thua, để trang chủ tự nói là chưa có quyền.
+ *
+ * Bước 1 LUÔN kiểm tra lại quyền thật. Cấu hình nhập một lần rồi quyền đổi sau
+ * đó; một `landingPath` trỏ tới trang người ta không mở được sẽ thành vòng
+ * chuyển hướng vô hạn — người dùng chỉ thấy trình duyệt quay mãi.
+ */
+
+/** Chỉ cần đúng một câu hỏi trên bảng `roles` — app truyền client nào cũng được. */
+export interface LandingPrismaClient {
+  role: {
+    findMany: (args: any) => Promise<Array<{ landingPath?: string | null }>>;
+    // `fields` của Prisma là object sinh sẵn theo model, không có index
+    // signature — khai lỏng để client thật của app nào cũng khớp.
+    fields?: object;
+  };
+}
+
+export interface LandingPathDeps {
+  prisma: LandingPrismaClient;
+  /** Cây menu GỐC của app (chưa lọc quyền) — thứ tự ở đây là thứ tự ưu tiên. */
+  navigations: readonly NavigationType[];
+}
+
+/**
+ * Chuẩn hoá giá trị người dùng nhập/chọn trước khi ghi DB. Chỉ nhận đường dẫn
+ * NỘI BỘ; rỗng hoặc bậy = "tự suy ra" (null).
+ *
+ * "//host" là URL giao thức tương đối — chặn, nếu không cấu hình vai trò thành
+ * chỗ đá người dùng sang tên miền lạ ngay sau khi đăng nhập.
+ */
+export function normalizeLandingPath(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const path = value.trim();
+  if (!path.startsWith("/") || path.startsWith("//")) return null;
+  return path;
+}
+
+interface Leaf {
+  href: string;
+  resource?: string;
+  action?: string;
+}
+
+/** Mọi mục có `href`, phẳng ra theo đúng thứ tự hiển thị trên sidebar. */
+function menuLeaves(navigations: readonly NavigationType[]): Leaf[] {
+  const out: Leaf[] = [];
+  const walk = (items: readonly unknown[]) => {
+    for (const raw of items) {
+      const item = raw as {
+        href?: string;
+        resource?: string;
+        action?: string;
+        items?: readonly unknown[];
+      };
+      if (item.items?.length) {
+        walk(item.items);
+        continue;
+      }
+      if (item.href) {
+        out.push({
+          href: item.href,
+          resource: item.resource,
+          action: item.action,
+        });
+      }
+    }
+  };
+  for (const group of navigations) walk(group.items ?? []);
+  return out;
+}
+
+/** Mục không khai `resource` là trang công khai với người đã đăng nhập. */
+function canOpen(session: Session, leaf: Leaf): boolean {
+  if (!leaf.resource) return true;
+  return checkPermission(session, leaf.resource, leaf.action ?? "view");
+}
+
+const withLocale = (locale: string, href: string) =>
+  href === "/" ? `/${locale}` : `/${locale}${href}`;
+
+/**
+ * App nào CHƯA migrate cột `landing_path` thì bỏ qua bước 1, vẫn chạy bình
+ * thường bằng mục menu đầu tiên — hỏi cột không tồn tại là Prisma ném thẳng.
+ */
+const hasField = (prisma: LandingPrismaClient, field: string) =>
+  Boolean((prisma as any)?.role?.fields?.[field]);
+
+const hasLandingPath = (prisma: LandingPrismaClient) =>
+  hasField(prisma, "landingPath");
+
+export function createLandingPathResolver({
+  prisma,
+  navigations,
+}: LandingPathDeps) {
+  return cache(
+    async (session: Session | null, locale: string): Promise<string> => {
+      if (!session?.user) return `/${locale}/sign-in`;
+
+      const leaves = menuLeaves(navigations);
+      const roleCodes = ((session.user as any).roles ?? []) as string[];
+
+      if (roleCodes.length > 0 && hasLandingPath(prisma)) {
+        const configured = await prisma.role.findMany({
+          where: { code: { in: roleCodes }, landingPath: { not: null } },
+          select: { landingPath: true },
+          // `rank` nhỏ = quyền lực cao. App nào chưa có cột `rank` (vinhhoa) thì
+          // bỏ orderBy — sắp theo cột không tồn tại là Prisma ném.
+          ...(hasField(prisma, "rank") ? { orderBy: { rank: "asc" } } : {}),
+        });
+        for (const role of configured) {
+          const leaf = leaves.find((l) => l.href === role.landingPath);
+          if (leaf && canOpen(session, leaf))
+            return withLocale(locale, leaf.href);
+        }
+      }
+
+      const first = leaves.find((l) => canOpen(session, l));
+      return withLocale(locale, first?.href ?? "/");
+    },
+  );
+}

package/src/rbac/pages/role-form-page.tsx

@@ -42,6 +42,7 @@ import {
   ChevronDown,
   ChevronRight,
   Copy,
+  House,
   Info,
   LayoutTemplate,
   Save,
@@ -76,6 +77,9 @@ const DEFAULT_ACTION_LABELS: Record<string, ActionLabelConfig> = {
 // Thứ tự hiển thị action trong một trang: CRUD chuẩn trước, nghiệp vụ sau.
 const STANDARD_ORDER = ["create", "update", "delete", "export", "import"]
 
+/** Radix Select không nhận value rỗng — dùng mã riêng cho "tự suy ra". */
+const LANDING_AUTO = "__auto__"
+
 /** Bộ quyền mẫu áp khi TẠO vai trò mới (consumer định nghĩa). */
 export interface RoleTemplate {
   code: string
@@ -136,6 +140,8 @@ export interface RoleFormPageProps {
     description: string | undefined
     status: string
     permissions: string[]
+    /** Trang mở đầu của vai trò. Null/undefined = tự suy ra. */
+    landingPath?: string | null
   }
   actionLabels?: Record<string, ActionLabelConfig>
   roleTemplates?: RoleTemplate[]
@@ -189,6 +195,8 @@ export function RoleFormPage({
     description: initialData?.description || "",
     status: (initialData?.status || "active") as "active" | "inactive",
     permissions: initialData?.permissions || ([] as string[]),
+    // "" = tự suy ra (mục đầu tiên trên menu mà vai trò này mở được).
+    landingPath: initialData?.landingPath || "",
   })
 
   const getLocalizedName = React.useCallback(
@@ -436,6 +444,30 @@ export function RoleFormPage({
     })
   }
 
+  // ── Trang mở đầu của vai trò ──────────────────────────────────────────
+  // Chỉ cho chọn trang mà vai trò này THẬT SỰ mở được: đặt trang chưa cấp
+  // quyền làm nơi hạ cánh là đá người ta vào tường ngay sau khi đăng nhập.
+  const landingOptions = React.useMemo(() => {
+    const byHref = new Map<string, { href: string; label: string }>()
+    tree.forEach((section) =>
+      section.items.forEach((i) => {
+        if (!i.href || i.note || !has(i.resource, "view")) return
+        // Hai mục cùng href (vd trang chi tiết gắn 2 chỗ) — giữ mục đầu.
+        if (!byHref.has(i.href))
+          byHref.set(i.href, {
+            href: i.href,
+            label: `${section.title} · ${i.title}`,
+          })
+      })
+    )
+    return Array.from(byHref.values())
+  }, [tree, has])
+
+  /** Đã cấu hình nhưng quyền bị gỡ sau đó — vẫn hiện để admin thấy mà sửa. */
+  const landingStale =
+    formData.landingPath !== "" &&
+    !landingOptions.some((o) => o.href === formData.landingPath)
+
   const applyTemplate = (templateCode: string) => {
     const tpl = roleTemplates?.find((t) => t.code === templateCode)
     if (!tpl) return
@@ -854,6 +886,73 @@ export function RoleFormPage({
             </div>
           )}
 
+          {/* Trang mở đầu — nơi vai trò này hạ cánh sau khi đăng nhập */}
+          <div className="flex items-center gap-1.5">
+            <House className="h-3.5 w-3.5 text-muted-foreground" />
+            <span className="text-xs text-muted-foreground">
+              Trang mở đầu:
+            </span>
+            <Select
+              value={formData.landingPath || LANDING_AUTO}
+              onValueChange={(v) =>
+                setFormData({
+                  ...formData,
+                  landingPath: v === LANDING_AUTO ? "" : v,
+                })
+              }
+            >
+              <SelectTrigger
+                className={cn(
+                  "h-8 w-52 rounded-md border border-border bg-card text-sm",
+                  landingStale && "border-amber-500 text-amber-700 dark:text-amber-400"
+                )}
+              >
+                <SelectValue>
+                  {!formData.landingPath
+                    ? "Tự động"
+                    : landingStale
+                      ? `${formData.landingPath} · chưa cấp quyền`
+                      : landingOptions.find(
+                          (o) => o.href === formData.landingPath
+                        )?.label}
+                </SelectValue>
+              </SelectTrigger>
+              <SelectContent className="rounded-lg">
+                <SelectItem value={LANDING_AUTO}>
+                  <span className="flex flex-col">
+                    <span>Tự động</span>
+                    <span className="text-[11px] text-muted-foreground">
+                      Menu đầu tiên vai trò này mở được
+                    </span>
+                  </span>
+                </SelectItem>
+                {/* Cấu hình cũ trỏ tới trang vừa bị gỡ quyền — giữ lại trong
+                    danh sách, nếu không nó biến mất im lặng và admin tưởng
+                    mình chưa từng đặt. */}
+                {landingStale && (
+                  <SelectItem value={formData.landingPath}>
+                    <span className="flex flex-col">
+                      <span>{formData.landingPath}</span>
+                      <span className="text-[11px] text-amber-600 dark:text-amber-400">
+                        Chưa cấp quyền vào trang này
+                      </span>
+                    </span>
+                  </SelectItem>
+                )}
+                {landingOptions.map((o) => (
+                  <SelectItem key={o.href} value={o.href}>
+                    <span className="flex flex-col">
+                      <span>{o.label}</span>
+                      <span className="text-[11px] text-muted-foreground">
+                        {o.href}
+                      </span>
+                    </span>
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
           <p className="ml-auto whitespace-nowrap text-xs text-muted-foreground">
             <span className="font-semibold tabular-nums text-foreground">
               {formData.permissions.length}

package/src/rbac/route-handlers.ts

@@ -14,6 +14,7 @@
 //   });
 
 import { getRolesData, type RoleServiceSchema } from "./role-service";
+import { normalizeLandingPath } from "./landing-path";
 import {
   bumpPermissionsVersion,
   getPermissionsVersion,
@@ -46,6 +47,18 @@ async function writePermissions(tx: any, roleCode: string, permissions: string[]
   if (rows.length) await tx.rolePermission.createMany({ data: rows, skipDuplicates: true });
 }
 
+// ── Trang mở đầu theo vai trò (`Role.landingPath`) ─────────────────────────
+// Cột BỔ SUNG: app nào chưa migrate thì handler phải im lặng bỏ qua, không ném
+// — hai app đang chạy thật vẫn dùng core này. Dò bằng `prisma.role.fields`
+// (Prisma sinh sẵn), rẻ và đúng với schema THẬT của app chứ không đoán.
+const hasLandingPath = (prisma: any) => Boolean(prisma?.role?.fields?.landingPath);
+
+/** Mảnh `data` để ghép vào create/update — rỗng khi app chưa có cột. */
+function landingPathData(prisma: any, body: any) {
+  if (!hasLandingPath(prisma) || !("landingPath" in (body ?? {}))) return {};
+  return { landingPath: normalizeLandingPath(body.landingPath) };
+}
+
 // GET (list, schema-tolerant) + POST (create + permissions) for /api/roles.
 export function createRolesCollectionHandlers(deps: RbacHandlerDeps) {
   const { prisma, getSession, getCrudPermissions, schema, onError } = deps;
@@ -87,7 +100,13 @@ export function createRolesCollectionHandlers(deps: RbacHandlerDeps) {
       const permissions: string[] = Array.isArray(body.permissions) ? body.permissions : [];
       const role = await prisma.$transaction(async (tx: any) => {
         const created = await tx.role.create({
-          data: { code, name, description: body.description ?? null, status: body.status ?? "active" },
+          data: {
+            code,
+            name,
+            description: body.description ?? null,
+            status: body.status ?? "active",
+            ...landingPathData(prisma, body),
+          },
         });
         await writePermissions(tx, created.code, permissions);
         return created;
@@ -126,6 +145,7 @@ export function createRoleItemHandlers(deps: RbacHandlerDeps) {
         name: role.name,
         description: role.description ?? "",
         status: role.status,
+        landingPath: role.landingPath ?? null,
         permissions: role.rolePermissions.map((p: any) => `${p.actionCode}:${p.resourceCode}`),
       });
     } catch (e) {
@@ -151,6 +171,7 @@ export function createRoleItemHandlers(deps: RbacHandlerDeps) {
             name: (body.name ?? existing.name).trim(),
             description: body.description ?? existing.description,
             status: body.status ?? existing.status,
+            ...landingPathData(prisma, body),
           },
         });
         await writePermissions(tx, updated.code, permissions);

package/src/schemas/role.schema.ts

@@ -6,6 +6,12 @@ export const roleSchema = z.object({
   description: z.string().optional(),
   status: z.enum(["active", "inactive"]).default("active"),
   permissions: z.array(z.string()).optional(),
+  /**
+   * Trang mở đầu của vai trò (`Role.landingPath`). Rỗng = "tự suy ra".
+   * Route phải lọc lại bằng `normalizeLandingPath` (@goerp/core/rbac/landing-path)
+   * trước khi ghi — schema chỉ nhận kiểu, không phán đường dẫn có an toàn không.
+   */
+  landingPath: z.string().optional().nullable(),
 });
 
 export type RoleFormData = z.infer<typeof roleSchema>;

package/src/ui/auth/sign-in-form.tsx

@@ -47,6 +47,18 @@ export interface SignInFormProps {
   /** Ghi đè nhãn ô định danh (vd "Email hoặc mã nhân viên"). */
   identifierLabel?: string;
   identifierPlaceholder?: string;
+  /**
+   * Endpoint trả `{ path }` — TRANG MỞ ĐẦU của chính người vừa đăng nhập.
+   *
+   * Chỉ hỏi được SAU khi đăng nhập xong (trước đó server chưa biết là ai), nên
+   * không thể gói vào `?redirectTo=`. Không khai prop này thì mọi thứ y như cũ:
+   * về `?redirectTo=` / NEXT_PUBLIC_HOME_PATHNAME / "/".
+   *
+   * Hỏng mạng hay trả bậy đều bỏ qua, vẫn về đường mặc định — chặn đăng nhập
+   * thành công rồi kẹt ở màn hình trắng là cái giá quá đắt cho một gợi ý điều
+   * hướng.
+   */
+  landingEndpoint?: string;
 }
 
 const IDENTIFIER_PRESETS = {
@@ -80,6 +92,7 @@ export function SignInForm({
   identifier = "email",
   identifierLabel,
   identifierPlaceholder,
+  landingEndpoint,
 }: SignInFormProps = {}) {
   const preset = IDENTIFIER_PRESETS[identifier];
   const schema = React.useMemo(
@@ -98,10 +111,9 @@ export function SignInForm({
   const { clearAllCache } = useTabContentCache();
   const { clearTabs } = useTabNavigation();
 
+  const explicitRedirect = searchParams.get("redirectTo");
   const redirectPathname =
-    searchParams.get("redirectTo") ||
-    process.env.NEXT_PUBLIC_HOME_PATHNAME ||
-    "/";
+    explicitRedirect || process.env.NEXT_PUBLIC_HOME_PATHNAME || "/";
 
   const form = useForm<SignInFormType>({
     resolver: zodResolver(schema),
@@ -145,7 +157,27 @@ export function SignInForm({
         // Best-effort only
       }
 
-      router.push(redirectPathname);
+      // `?redirectTo=` là chỗ người dùng đang muốn tới trước khi bị đòi đăng
+      // nhập — luôn thắng trang mở đầu của vai trò.
+      let target = redirectPathname;
+      if (landingEndpoint && !explicitRedirect) {
+        try {
+          const res = await fetch(landingEndpoint);
+          const data = await res.json();
+          // Chỉ nhận đường dẫn nội bộ ("//host" là URL giao thức tương đối).
+          if (
+            typeof data?.path === "string" &&
+            data.path.startsWith("/") &&
+            !data.path.startsWith("//")
+          ) {
+            target = data.path;
+          }
+        } catch {
+          // Giữ đường mặc định — đăng nhập đã thành công rồi.
+        }
+      }
+
+      router.push(target);
     } catch (error) {
       const rawMessage =
         error instanceof Error ? error.message : "Đăng nhập thất bại";

package/templates/starter-app/src/app/[lang]/(main)/layout.tsx

@@ -1,13 +1,25 @@
+import { buildNavigationForSession } from "@goerp/core/navigation"
+
 import type { ReactNode } from "react"
 
 import { dictionary } from "@/data/dictionary"
 import { navigations } from "@/data/navigations"
+import { getSession } from "@/lib/auth"
 
 import { MainLayoutWrapper } from "@/components/layout/main-layout-wrapper"
 
-export default function MainAreaLayout({ children }: { children: ReactNode }) {
+export default async function MainAreaLayout({
+  children,
+}: {
+  children: ReactNode
+}) {
+  // Cây menu thô là bản đồ TOÀN BỘ hệ thống — truyền thẳng xuống layout thì ai
+  // đăng nhập cũng thấy đủ mục rồi bấm vào bị cổng gác đá về. Lọc theo quyền
+  // ngay ở server: mục không có quyền không nằm trong payload gửi xuống.
+  const navigation = buildNavigationForSession(navigations, await getSession())
+
   return (
-    <MainLayoutWrapper dictionary={dictionary} navigation={navigations}>
+    <MainLayoutWrapper dictionary={dictionary} navigation={navigation}>
       {children}
     </MainLayoutWrapper>
   )