@goplusvn/core 0.1.59 → 0.1.60

package/templates/starter-app/scripts/rbac-sync.ts

@@ -0,0 +1,235 @@
+/**
+ * rbac-sync — đồng bộ Permission Registry (src/configs/permissions) xuống DB.
+ * Chạy sau mỗi lần deploy có thêm/sửa resource. KHÔNG cần script vá thủ công.
+ *
+ * Idempotent và AN TOÀN trên production — chạy lại bao nhiêu lần cũng vậy:
+ *   - Action:   tạo nếu thiếu; không bao giờ sửa/xoá action sẵn có.
+ *   - Resource: cập nhật name/group/mô tả/icon/thứ tự theo registry (registry
+ *               sở hữu danh mục quyền); không bao giờ xoá.
+ *   - Grant mặc định: CHỈ seed khi resource được TẠO MỚI ở lần chạy này —
+ *               không bao giờ đè chỉnh sửa của quản trị viên.
+ *   - Drift:    liệt kê resource có trong DB mà chưa khai registry (chỉ cảnh báo).
+ *
+ * Dùng:
+ *   pnpm rbac-sync                 # sync thật
+ *   pnpm rbac-sync --dry-run       # chỉ in kế hoạch
+ *   pnpm rbac-sync --verbose       # in cả danh sách drift
+ *   pnpm rbac-sync --force-grants  # áp lại grant mặc định cho MỌI resource
+ *
+ * `--force-grants` là lối thoát cho trường hợp resource đã tạo trước khi vai trò
+ * tồn tại (chạy rbac-sync trước `pnpm seed`): resource có đủ mà không ai được
+ * quyền gì, và lần chạy sau không còn "tạo mới" nên chẳng grant lại. Cờ này chỉ
+ * THÊM quyền (upsert), không bao giờ thu hồi — nhưng nó cũng dựng lại quyền mà
+ * quản trị viên đã cố tình gỡ, nên đừng đưa vào quy trình deploy.
+ */
+
+import { randomUUID } from "node:crypto"
+
+import { PrismaPg } from "@prisma/adapter-pg"
+import { PrismaClient } from "@prisma/client"
+import "dotenv/config"
+
+import { permissionRegistry } from "../src/configs/permissions"
+
+const DRY_RUN = process.argv.includes("--dry-run")
+const VERBOSE = process.argv.includes("--verbose")
+const FORCE_GRANTS = process.argv.includes("--force-grants")
+
+/** Action ai cũng hiểu — khỏi bắt mỗi app khai lại trong customActions. */
+const STANDARD_ACTIONS: Record<string, string> = {
+  view: "Xem",
+  create: "Thêm",
+  update: "Sửa",
+  delete: "Xóa",
+  export: "Xuất dữ liệu",
+  import: "Nhập dữ liệu",
+}
+
+const connectionString = process.env.DATABASE_URL
+if (!connectionString) throw new Error("DATABASE_URL chưa được set (xem .env.example)")
+const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString }) })
+
+async function main() {
+  const now = new Date()
+  const resourceCount = permissionRegistry.reduce((n, f) => n + f.resources.length, 0)
+  console.log(
+    `→ rbac-sync: ${permissionRegistry.length} phân hệ, ${resourceCount} resource${DRY_RUN ? " [DRY RUN]" : ""}`,
+  )
+
+  // ── 1. Action: tạo nếu thiếu ───────────────────────────────────────────
+  const declaredActions = new Map<string, { name: string; description?: string }>()
+  for (const feature of permissionRegistry) {
+    for (const a of feature.customActions ?? []) {
+      declaredActions.set(a.code, { name: a.name, description: a.description })
+    }
+  }
+  const usedActionCodes = new Set(
+    permissionRegistry.flatMap((f) => f.resources.flatMap((r) => [...r.actions])),
+  )
+
+  const existingActionCodes = new Set(
+    (await prisma.action.findMany({ select: { code: true } })).map((a) => a.code),
+  )
+
+  for (const code of usedActionCodes) {
+    if (existingActionCodes.has(code)) continue
+    const decl = declaredActions.get(code) ?? {
+      name: STANDARD_ACTIONS[code],
+      description: undefined,
+    }
+    if (!decl.name) {
+      // Dừng hẳn thay vì tạo action rác: sai chính tả một action code sẽ khiến
+      // quyền không bao giờ khớp và nút bấm ẩn vĩnh viễn.
+      throw new Error(
+        `Action "${code}" được dùng nhưng không nằm trong bộ chuẩn và chưa khai ở customActions của phân hệ nào.`,
+      )
+    }
+    console.log(`  + action: ${code} (${decl.name})`)
+    if (!DRY_RUN) {
+      await prisma.action.create({
+        data: { code, name: decl.name, description: decl.description ?? "" },
+      })
+    }
+  }
+
+  // ── 2. Resource: upsert metadata + config.actions ──────────────────────
+  // config.actions = danh sách action HIỆN trên ma trận phân quyền của core.
+  // Registry sở hữu khóa `actions`; các khóa khác admin thêm vào được giữ nguyên.
+  const createdResourceCodes = new Set<string>()
+  for (const feature of permissionRegistry) {
+    for (const r of feature.resources) {
+      const existing = await prisma.resource.findUnique({
+        where: { code: r.code },
+        select: { code: true, config: true },
+      })
+
+      let config: Record<string, unknown> = {}
+      if (existing?.config) {
+        try {
+          config = JSON.parse(existing.config)
+        } catch {
+          console.warn(`  ! config của ${r.code} không phải JSON — ghi đè`)
+        }
+      }
+      // Lớp tùy chỉnh của admin (thêm/tắt action trên UI) được BẢO TOÀN:
+      // hiệu lực = registry ∪ customActions − disabledActions
+      const custom = Array.isArray(config.customActions) ? (config.customActions as string[]) : []
+      const disabled = Array.isArray(config.disabledActions)
+        ? (config.disabledActions as string[])
+        : []
+      config.actions = [...new Set([...r.actions, ...custom])].filter(
+        (a) => !disabled.includes(a),
+      )
+
+      if (!existing) {
+        createdResourceCodes.add(r.code)
+        console.log(`  + resource: ${r.code} (${r.name}) [${feature.feature}]`)
+      } else if (VERBOSE) {
+        console.log(`  = resource: ${r.code} — cập nhật metadata`)
+      }
+
+      if (!DRY_RUN) {
+        const data = {
+          name: r.name,
+          group: r.group,
+          description: r.description ?? feature.description ?? null,
+          icon: r.icon ?? null,
+          order: r.order ?? null,
+          config: JSON.stringify(config),
+        }
+        await prisma.resource.upsert({
+          where: { code: r.code },
+          create: { code: r.code, ...data },
+          update: data,
+        })
+      }
+    }
+  }
+
+  // ── 3. Grant mặc định — CHỈ cho resource vừa tạo (trừ khi --force-grants) ──
+  const wantsGrants = (code: string) => FORCE_GRANTS || createdResourceCodes.has(code)
+  let skippedGrants = 0
+
+  const neededRoleCodes = new Set<string>()
+  for (const feature of permissionRegistry) {
+    for (const r of feature.resources) {
+      if (!wantsGrants(r.code)) continue
+      for (const roleCode of Object.keys(r.defaultGrants ?? {})) neededRoleCodes.add(roleCode)
+    }
+  }
+  const presentRoles = new Set(
+    neededRoleCodes.size
+      ? (
+          await prisma.role.findMany({
+            where: { code: { in: [...neededRoleCodes] } },
+            select: { code: true },
+          })
+        ).map((r) => r.code)
+      : [],
+  )
+
+  for (const feature of permissionRegistry) {
+    for (const r of feature.resources) {
+      if (!wantsGrants(r.code)) continue
+      for (const [roleCode, grant] of Object.entries(r.defaultGrants ?? {})) {
+        if (!presentRoles.has(roleCode)) {
+          skippedGrants++
+          console.warn(`  ! vai trò "${roleCode}" chưa tồn tại — bỏ qua grant cho ${r.code}`)
+          continue
+        }
+        for (const actionCode of grant === "*" ? r.actions : grant) {
+          if (VERBOSE || !FORCE_GRANTS) console.log(`  ✓ grant: ${roleCode} → ${r.code}:${actionCode}`)
+          if (!DRY_RUN) {
+            await prisma.rolePermission.upsert({
+              where: {
+                roleCode_resourceCode_actionCode: {
+                  roleCode,
+                  resourceCode: r.code,
+                  actionCode,
+                },
+              },
+              create: { id: randomUUID(), roleCode, resourceCode: r.code, actionCode },
+              update: {},
+            })
+          }
+        }
+      }
+    }
+  }
+
+  // ── 4. Drift (chỉ cảnh báo) ────────────────────────────────────────────
+  const registryCodes = new Set(
+    permissionRegistry.flatMap((f) => f.resources.map((r) => r.code)),
+  )
+  const legacy = (
+    await prisma.resource.findMany({ where: { status: "active" }, select: { code: true } })
+  )
+    .map((r) => r.code)
+    .filter((code) => !registryCodes.has(code))
+    .sort()
+
+  if (legacy.length) {
+    console.log(`→ Drift: ${legacy.length} resource trong DB chưa khai registry`)
+    if (VERBOSE) console.log(`  ${legacy.join(", ")}`)
+  }
+
+  console.log(
+    `→ Xong: ${createdResourceCodes.size} resource mới, ${registryCodes.size - createdResourceCodes.size} resource cập nhật.`,
+  )
+
+  // Bỏ qua grant = resource đã tạo nhưng KHÔNG ai có quyền, và lần chạy sau
+  // resource không còn "mới" nên sẽ im lặng bỏ qua mãi. Nói thẳng cách chữa.
+  if (skippedGrants) {
+    console.warn(
+      `\n⚠ ${skippedGrants} grant bị bỏ vì vai trò chưa tồn tại. Chạy \`pnpm seed\` để tạo vai trò,` +
+        ` rồi \`pnpm rbac-sync --force-grants\` để áp lại — nếu không sẽ không ai vào được màn hình nào.`,
+    )
+  }
+}
+
+main()
+  .catch((e) => {
+    console.error(e)
+    process.exit(1)
+  })
+  .finally(() => prisma.$disconnect())

package/templates/starter-app/src/__tests__/architecture.test.ts

@@ -0,0 +1,151 @@
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { join, relative } from "node:path"
+
+import { describe, expect, it } from "vitest"
+
+import { permissionRegistry } from "@/configs/permissions"
+import { navigations } from "@/data/navigations"
+
+/**
+ * RATCHET — hàng rào kiến trúc. Mỗi kiểm tra ở đây tương ứng một lỗi im lặng
+ * đã từng làm mất thời gian trong app thật: quyền khai sai thì nút biến mất
+ * không báo lỗi, route quên gác thì thành lỗ hổng, hai Prisma client thì rò
+ * connection pool. Thêm quy tắc mới khi bạn gặp lỗi loại đó; đừng nới lỏng.
+ */
+
+const SRC = join(__dirname, "..")
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue
+      walk(full, out)
+    } else if (/\.(ts|tsx)$/.test(entry)) {
+      out.push(full)
+    }
+  }
+  return out
+}
+
+const allFiles = walk(SRC)
+const read = (f: string) => readFileSync(f, "utf8")
+const rel = (f: string) => relative(SRC, f)
+
+/** Bộ action ai cũng hiểu — trùng danh sách trong scripts/rbac-sync.ts. */
+const STANDARD_ACTIONS = ["view", "create", "update", "delete", "export", "import"]
+
+describe("permission registry", () => {
+  const declaredCustom = new Set(
+    permissionRegistry.flatMap((f) => (f.customActions ?? []).map((a) => a.code)),
+  )
+
+  it("mọi action được dùng đều là action chuẩn hoặc đã khai customActions", () => {
+    const unknown: string[] = []
+    for (const feature of permissionRegistry) {
+      for (const r of feature.resources) {
+        for (const a of r.actions) {
+          if (!STANDARD_ACTIONS.includes(a) && !declaredCustom.has(a)) {
+            unknown.push(`${r.code}:${a}`)
+          }
+        }
+      }
+    }
+    // rbac-sync ném lỗi khi gặp trường hợp này — bắt sớm ở test rẻ hơn nhiều
+    // so với phát hiện lúc deploy.
+    expect(unknown).toEqual([])
+  })
+
+  it("defaultGrants chỉ trỏ tới action đã khai trên chính resource đó", () => {
+    const bad: string[] = []
+    for (const feature of permissionRegistry) {
+      for (const r of feature.resources) {
+        for (const [roleCode, grant] of Object.entries(r.defaultGrants ?? {})) {
+          if (grant === "*") continue
+          for (const a of grant) {
+            if (!r.actions.includes(a)) bad.push(`${roleCode} → ${r.code}:${a}`)
+          }
+        }
+      }
+    }
+    expect(bad).toEqual([])
+  })
+
+  it("mã resource dùng kebab-case (khớp chuỗi trong checkPermission và URL)", () => {
+    const bad = permissionRegistry
+      .flatMap((f) => f.resources.map((r) => r.code))
+      .filter((code) => !/^[a-z][a-z0-9-]*$/.test(code))
+    expect(bad).toEqual([])
+  })
+
+  it("mọi mục navigation có `resource` đều đã khai trong registry", () => {
+    const declared = new Set(
+      permissionRegistry.flatMap((f) => f.resources.map((r) => r.code)),
+    )
+    const missing: string[] = []
+    for (const group of navigations) {
+      for (const item of group.items ?? []) {
+        const resource = (item as { resource?: string }).resource
+        if (resource && !declared.has(resource)) missing.push(resource)
+      }
+    }
+    // Mục nav trỏ tới resource chưa khai sẽ ẨN VĨNH VIỄN với mọi người dùng
+    // (kể cả admin) mà không có thông báo nào.
+    expect(missing).toEqual([])
+  })
+})
+
+describe("ranh giới kiến trúc", () => {
+  it("không còn dấu vết NextAuth (app đã sang Better Auth)", () => {
+    const offenders = allFiles.filter((f) => /from ["']next-auth/.test(read(f)))
+    expect(offenders.map(rel)).toEqual([])
+  })
+
+  it("chỉ src/lib/prisma.ts được tạo PrismaClient", () => {
+    const offenders = allFiles.filter(
+      (f) => /new PrismaClient\(/.test(read(f)) && rel(f) !== "lib/prisma.ts",
+    )
+    // Client thứ hai = pool kết nối thứ hai + bỏ qua audit extension.
+    expect(offenders.map(rel)).toEqual([])
+  })
+
+  it("route API đều đi qua getSession hoặc handler có gác quyền của core", () => {
+    const routes = allFiles.filter((f) => /app\/api\/.*route\.ts$/.test(rel(f)))
+    expect(routes.length).toBeGreaterThan(0)
+
+    // better-auth tự lo xác thực cho chính nó (đăng nhập thì làm gì có phiên).
+    const exempt = ["app/api/better-auth"]
+    const offenders = routes.filter((f) => {
+      if (exempt.some((p) => rel(f).startsWith(p))) return false
+      const src = read(f)
+      // apiHandler( = cổng của app — chấp cả dạng có generic
+      // `apiHandler<{ key: string[] }>(` ở route catch-all; create*Handlers( =
+      // factory sẵn của core (rbac/crud) vốn đã tự gác session + quyền bên trong.
+      return !/apiHandler[<(]|create\w*Handlers\(|getSession/.test(src)
+    })
+    expect(offenders.map(rel)).toEqual([])
+  })
+
+  it("resource mà route gác đều đã khai trong registry", () => {
+    const declared = new Set(
+      permissionRegistry.flatMap((f) => f.resources.map((r) => r.code)),
+    )
+    const missing: string[] = []
+    for (const file of allFiles.filter((f) => /app\/api\/.*route\.ts$/.test(rel(f)))) {
+      for (const [, code] of read(file).matchAll(/resource:\s*["']([^"']+)["']/g)) {
+        if (!declared.has(code)) missing.push(`${rel(file)} → ${code}`)
+      }
+    }
+    // assertResourceDeclared cũng bắt lỗi này, nhưng chỉ khi route được load.
+    // Test quét tĩnh nên thấy cả route chưa ai gọi tới.
+    expect(missing).toEqual([])
+  })
+
+  it("cấu hình quyền là dữ liệu thuần — không kéo prisma/next/react vào", () => {
+    const offenders = allFiles
+      .filter((f) => rel(f).startsWith("configs/permissions"))
+      .filter((f) => /from ["'](@\/lib\/prisma|next|react|@prisma)/.test(read(f)))
+    // scripts/rbac-sync.ts và test đọc thẳng các file này qua tsx.
+    expect(offenders.map(rel)).toEqual([])
+  })
+})

package/templates/starter-app/src/app/[lang]/(main)/admin/system/audit/page.tsx

@@ -0,0 +1,24 @@
+import { SystemAuditPage } from "@goerp/core/system/pages/system-audit-page"
+
+import type { Metadata } from "next"
+
+import { requirePageAccess } from "@/lib/page-guard"
+
+export const metadata: Metadata = { title: "Nhật ký hoạt động" }
+
+export default async function AuditRoute({
+  params,
+}: {
+  params: Promise<{ lang: string }>
+}) {
+  const { lang } = await params
+  await requirePageAccess(lang, "audit-log")
+
+  // Bảng nhật ký tự cuộn bên trong — cho nó chiều cao cố định thay vì để cả
+  // trang dài ra theo số dòng.
+  return (
+    <div className="h-[calc(100vh-120px)]">
+      <SystemAuditPage />
+    </div>
+  )
+}

package/templates/starter-app/src/app/[lang]/(main)/admin/system/error-logs/page.tsx

@@ -0,0 +1,21 @@
+import { ErrorLogsPage } from "@goerp/core/system/pages/error-logs-page"
+
+import type { Metadata } from "next"
+
+import { requirePageAccess } from "@/lib/page-guard"
+
+export const metadata: Metadata = { title: "Nhật ký lỗi" }
+
+/** `?search=<errorId>` để deep-link thẳng tới một lỗi từ thông báo/dashboard. */
+export default async function ErrorLogsRoute({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ lang: string }>
+  searchParams: Promise<{ search?: string }>
+}) {
+  const [{ lang }, sp] = await Promise.all([params, searchParams])
+  await requirePageAccess(lang, "error-log")
+
+  return <ErrorLogsPage initialSearch={sp.search} />
+}

package/templates/starter-app/src/app/[lang]/(main)/admin/system/jobs/page.tsx

@@ -0,0 +1,18 @@
+import { SystemJobsPage } from "@goerp/core/system/pages/system-jobs-page"
+
+import type { Metadata } from "next"
+
+import { requirePageAccess } from "@/lib/page-guard"
+
+export const metadata: Metadata = { title: "Tác vụ định kỳ" }
+
+export default async function JobsRoute({
+  params,
+}: {
+  params: Promise<{ lang: string }>
+}) {
+  const { lang } = await params
+  await requirePageAccess(lang, "system-job")
+
+  return <SystemJobsPage />
+}

package/templates/starter-app/src/app/[lang]/(main)/admin/system/settings/page.tsx

@@ -0,0 +1,22 @@
+import { SystemSettingsPage } from "@goerp/core/system/pages/system-settings-page"
+
+import type { Metadata } from "next"
+
+import { requirePageAccess } from "@/lib/page-guard"
+
+export const metadata: Metadata = { title: "Cấu hình hệ thống" }
+
+/**
+ * Trang cài đặt = màn hình sẵn của core + các route dưới
+ * /api/admin/system/settings/* mà app cung cấp. Không có mã giao diện riêng.
+ */
+export default async function SettingsPage({
+  params,
+}: {
+  params: Promise<{ lang: string }>
+}) {
+  const { lang } = await params
+  await requirePageAccess(lang, "system-setting")
+
+  return <SystemSettingsPage lang={lang} />
+}

package/templates/starter-app/src/app/[lang]/(main)/crud/[entity]/page.tsx

@@ -0,0 +1,41 @@
+import { EntityCrudPage } from "@goerp/core/crud"
+
+import type { LocaleType } from "@goerp/core/types"
+
+import { getEntityConfig } from "@/configs/entities"
+import { dictionary } from "@/data/dictionary"
+import { getSession } from "@/lib/auth"
+
+export const dynamic = "force-dynamic"
+
+// Generic CRUD page — one file serves EVERY entity in the registry. The core
+// engine renders table + form + filters + import/export from the EntityConfig.
+// Add an entity: register it in src/configs/entities and link /crud/<key> in nav.
+export default async function CrudEntityPage({
+  params,
+}: {
+  params: Promise<{ lang: string; entity: string }>
+}) {
+  const { lang, entity } = await params
+  const config = getEntityConfig(entity)
+
+  if (!config) {
+    return (
+      <div className="p-6 text-sm text-muted-foreground">
+        Không tìm thấy entity: <code className="rounded bg-muted px-1">{entity}</code>
+      </div>
+    )
+  }
+
+  const session = await getSession()
+
+  return (
+    <EntityCrudPage
+      entity={entity}
+      lang={lang as LocaleType}
+      config={config}
+      session={session!}
+      dictionary={dictionary}
+    />
+  )
+}

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

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react"
+
+import { MainLayoutWrapper } from "@/components/layout/main-layout-wrapper"
+import { dictionary } from "@/data/dictionary"
+import { navigations } from "@/data/navigations"
+
+export default function MainAreaLayout({ children }: { children: ReactNode }) {
+  return (
+    <MainLayoutWrapper dictionary={dictionary} navigation={navigations}>
+      {children}
+    </MainLayoutWrapper>
+  )
+}

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

@@ -0,0 +1,13 @@
+import { NotificationsInbox } from "@goerp/core/notification/ui"
+
+import type { Metadata } from "next"
+
+export const metadata: Metadata = { title: "Thông báo" }
+
+/**
+ * Hộp thư của CHÍNH người đang đăng nhập — không cần quyền RBAC, API đã tự
+ * lọc theo `session.user.id`. Chuông trên thanh tiêu đề trỏ về trang này.
+ */
+export default function NotificationsPage() {
+  return <NotificationsInbox />
+}

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

@@ -0,0 +1,130 @@
+import { StatBar } from "@goerp/core/ui"
+import { ArrowRight, Building2, ShieldCheck, Sparkles } from "lucide-react"
+import Link from "next/link"
+
+import { db } from "@/lib/prisma"
+
+export const dynamic = "force-dynamic"
+
+// Sample ERP dashboard. Server component: query counts, hand StatBar plain data.
+// Replace the KPIs + quick actions with your domain's once you add entities.
+export default async function HomePage() {
+  const [departmentCount, activeDepartments, userCount] = await Promise.all([
+    db.department.count(),
+    db.department.count({ where: { status: "active" } }),
+    db.user.count(),
+  ])
+
+  return (
+    <div className="flex h-full flex-col gap-4 p-4 md:p-6">
+      <div className="space-y-1">
+        <h1 className="text-2xl font-bold tracking-tight text-foreground">
+          Bảng điều khiển
+        </h1>
+        <p className="text-sm text-muted-foreground">
+          App mẫu chạy trên{" "}
+          <code className="rounded bg-muted px-1">@goerp/core</code> — auth, RBAC,
+          CRUD engine và design system đều từ core.
+        </p>
+      </div>
+
+      <StatBar
+        items={[
+          {
+            id: "departments",
+            label: "Phòng ban",
+            value: departmentCount,
+            iconName: "Building2",
+            colorTheme: "dark",
+            isHighlighted: true,
+          },
+          {
+            id: "active",
+            label: "Đang hoạt động",
+            value: activeDepartments,
+            iconName: "CheckCircle2",
+            colorTheme: "emerald",
+          },
+          {
+            id: "users",
+            label: "Người dùng",
+            value: userCount,
+            iconName: "Users",
+            colorTheme: "blue",
+          },
+        ]}
+      />
+
+      <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+        <QuickCard
+          href="/crud/departments"
+          icon={<Building2 className="size-5" />}
+          title="Phòng ban"
+          desc="Xem, thêm, sửa cơ cấu tổ chức — bảng/biểu mẫu/lọc/nhập-xuất tự sinh từ EntityConfig."
+        />
+        <InfoCard
+          icon={<Sparkles className="size-5" />}
+          title="Thêm entity mới"
+          desc="Khai báo EntityConfig, đăng ký trong src/configs/entities, thêm 1 dòng nav /crud/<key>. Không viết engine."
+        />
+        <InfoCard
+          icon={<ShieldCheck className="size-5" />}
+          title="Phân quyền"
+          desc="Đăng nhập thật qua bảng User (admin/admin123). Role 'admin' = full quyền; RBAC chi tiết thêm bảng RolePermission."
+        />
+      </div>
+    </div>
+  )
+}
+
+function QuickCard({
+  href,
+  icon,
+  title,
+  desc,
+}: {
+  href: string
+  icon: React.ReactNode
+  title: string
+  desc: string
+}) {
+  return (
+    <Link
+      href={href}
+      className="group flex flex-col gap-3 rounded-lg border border-border bg-card p-5 transition-colors hover:border-primary/40 hover:bg-accent"
+    >
+      <div className="flex items-center justify-between">
+        <span className="flex size-10 items-center justify-center rounded-lg bg-primary/10 text-primary">
+          {icon}
+        </span>
+        <ArrowRight className="size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5 group-hover:text-primary" />
+      </div>
+      <div>
+        <div className="font-semibold text-foreground">{title}</div>
+        <p className="mt-1 text-sm text-muted-foreground">{desc}</p>
+      </div>
+    </Link>
+  )
+}
+
+function InfoCard({
+  icon,
+  title,
+  desc,
+}: {
+  icon: React.ReactNode
+  title: string
+  desc: string
+}) {
+  return (
+    <div className="flex flex-col gap-3 rounded-lg border border-border bg-card p-5">
+      <span className="flex size-10 items-center justify-center rounded-lg bg-muted text-muted-foreground">
+        {icon}
+      </span>
+      <div>
+        <div className="font-semibold text-foreground">{title}</div>
+        <p className="mt-1 text-sm text-muted-foreground">{desc}</p>
+      </div>
+    </div>
+  )
+}