@goplusvn/core 0.1.59 → 0.1.61

package/templates/starter-app/src/configs/permissions/system.permissions.ts

@@ -0,0 +1,131 @@
+import type { FeaturePermissions } from "./types"
+
+/**
+ * Quản trị hệ thống — nhóm resource đi kèm các trang có sẵn của @goerp/core
+ * (phân quyền, cấu hình, nhật ký, tác vụ nền). Giữ nguyên MÃ resource: chúng
+ * khớp với đường dẫn trang và với chuỗi checkPermission trong route.
+ *
+ * Bộ action khai theo NGHĨA thực: nhật ký thì không có create/update, tác vụ
+ * nền thì không xoá bằng tay…
+ */
+const systemPermissions: FeaturePermissions = {
+  feature: "system",
+  description: "Quản trị hệ thống: phân quyền, cấu hình, nhật ký",
+  customActions: [
+    {
+      code: "cancel",
+      name: "Hủy",
+      description: "Dừng một tác vụ nền đang chạy hoặc đang chờ.",
+    },
+    {
+      code: "view-all-branches",
+      name: "Xem mọi chi nhánh",
+      description:
+        "Bỏ giới hạn phạm vi dữ liệu: thấy chứng từ của mọi chi nhánh, không chỉ chi nhánh được gán (src/lib/branch-scope.ts).",
+    },
+  ],
+  resources: [
+    // ── Phân quyền ───────────────────────────────────────────────────────
+    {
+      code: "role",
+      name: "Vai trò",
+      group: "Phân quyền",
+      icon: "ShieldCheck",
+      order: 10,
+      actions: ["view", "create", "update", "delete", "export"],
+      defaultGrants: { admin: "*" },
+    },
+    {
+      code: "resource",
+      name: "Tài nguyên",
+      group: "Phân quyền",
+      icon: "Database",
+      order: 11,
+      actions: ["view", "create", "update", "delete"],
+      defaultGrants: { admin: "*" },
+    },
+    {
+      code: "action",
+      name: "Hành động",
+      group: "Phân quyền",
+      icon: "Zap",
+      order: 12,
+      actions: ["view", "create", "update", "delete"],
+      defaultGrants: { admin: "*" },
+    },
+    {
+      code: "user",
+      name: "Người dùng",
+      group: "Phân quyền",
+      icon: "Users",
+      order: 13,
+      actions: ["view", "create", "update", "delete", "export"],
+      defaultGrants: { admin: "*" },
+    },
+
+    // ── Cấu hình ─────────────────────────────────────────────────────────
+    {
+      code: "system-setting",
+      name: "Cấu hình chung",
+      group: "Hệ thống",
+      icon: "Settings",
+      order: 20,
+      actions: ["view", "create", "update", "delete", "export"],
+      defaultGrants: { admin: "*" },
+    },
+    {
+      code: "branch",
+      name: "Chi nhánh",
+      group: "Hệ thống",
+      icon: "Building",
+      order: 21,
+      // "view-all-branches" là quyền PHẠM VI DỮ LIỆU, không phải một màn hình:
+      // cấp cho vai trò nào thì vai trò đó thoát bộ lọc chi nhánh ở mọi nơi.
+      actions: ["view", "create", "update", "delete", "view-all-branches"],
+      // Mọi người đều cần đọc danh sách chi nhánh để đổ vào bộ lọc/picker.
+      lookupPolicy: "authenticated",
+      defaultGrants: { admin: "*" },
+    },
+
+    // ── Nhật ký & giám sát ───────────────────────────────────────────────
+    {
+      code: "audit-log",
+      name: "Nhật ký hoạt động",
+      group: "Hệ thống",
+      icon: "Scroll",
+      order: 30,
+      // Nhật ký chỉ đọc/xuất/dọn — không create/update.
+      actions: ["view", "delete", "export"],
+      defaultGrants: { admin: "*" },
+    },
+    {
+      code: "error-log",
+      name: "Nhật ký lỗi",
+      group: "Hệ thống",
+      icon: "Bug",
+      order: 31,
+      actions: ["view", "update", "delete"],
+      defaultGrants: { admin: "*" },
+    },
+    {
+      code: "system-job",
+      name: "Tác vụ định kỳ",
+      group: "Hệ thống",
+      icon: "Cpu",
+      order: 32,
+      actions: ["view", "update"],
+      defaultGrants: { admin: "*" },
+    },
+    {
+      code: "background-task",
+      name: "Tác vụ nền",
+      group: "Hệ thống",
+      icon: "ListChecks",
+      order: 33,
+      actions: ["view", "cancel"],
+      defaultGrants: { admin: "*", staff: ["view"] },
+    },
+  ],
+}
+
+export default systemPermissions

package/templates/starter-app/src/configs/permissions/types.ts

@@ -0,0 +1,63 @@
+/**
+ * PERMISSION REGISTRY — nguồn chân lý DUY NHẤT về quyền của app.
+ *
+ * Mỗi phân hệ có một file `<feature>.permissions.ts` khai đủ resource, action,
+ * nhóm hiển thị và grant mặc định. `scripts/rbac-sync.ts` đọc registry rồi
+ * upsert xuống DB lúc deploy — nhờ vậy không còn cảnh mỗi tính năng mới lại
+ * thêm một script vá RBAC rời rạc, rồi quên chạy trên production.
+ *
+ * RÀNG BUỘC: file trong thư mục này phải là DỮ LIỆU THUẦN — không import
+ * prisma/next/react. Script tsx và test đọc chúng trực tiếp, kéo theo app là
+ * hỏng cả hai.
+ */
+
+/**
+ * Chính sách đọc-để-tra-cứu: cho phép đổ dữ liệu vào combo/picker mà không cần
+ * quyền `view` của trang quản lý. Áp tại GET danh sách, KHÔNG áp cho trang quản lý.
+ *
+ * - "authenticated": ai đăng nhập cũng tra được (danh mục vô hại: kho, đơn vị tính…)
+ * - "view-only":     không có đường tắt, đọc là phải có `<resource>:view`. MẶC ĐỊNH.
+ */
+export type LookupPolicy = "authenticated" | "view-only"
+
+export interface ActionDeclaration {
+  code: string
+  name: string
+  /** Dùng làm gì, ở trang nào — hiện thành tooltip trên trang phân quyền. */
+  description?: string
+}
+
+export interface ResourceDeclaration {
+  /** Mã resource — PHẢI khớp chuỗi dùng trong checkPermission và navigations. */
+  code: string
+  /** Tên hiển thị trên trang phân quyền. */
+  name: string
+  /** Phân hệ — ma trận quyền nhóm theo cột này. */
+  group: string
+  description?: string
+  icon?: string
+  order?: number
+  /**
+   * Action áp dụng cho resource. Action ngoài bộ chuẩn
+   * (view/create/update/delete/export/import) phải khai trong `customActions`
+   * của feature, nếu không rbac-sync sẽ dừng và báo lỗi.
+   */
+  actions: readonly string[]
+  /** Mặc định "view-only". */
+  lookupPolicy?: LookupPolicy
+  /**
+   * Grant mặc định roleCode → action ("*" = mọi action đã khai). CHỈ seed khi
+   * resource xuất hiện LẦN ĐẦU — sync không bao giờ ghi đè chỉnh sửa của admin.
+   */
+  defaultGrants?: Readonly<Record<string, readonly string[] | "*">>
+}
+
+export interface FeaturePermissions {
+  /** Định danh phân hệ, trùng tên file (bỏ đuôi .permissions.ts). */
+  feature: string
+  /** Mô tả ngắn — hiện thành nhãn nguồn gốc trên trang Tài nguyên. */
+  description?: string
+  /** Action riêng của phân hệ (approve, confirm-payment…). */
+  customActions?: readonly ActionDeclaration[]
+  resources: readonly ResourceDeclaration[]
+}

package/templates/starter-app/src/configs/tenant.ts

@@ -0,0 +1,18 @@
+import type { TenantConfig } from "@goerp/core/providers"
+
+/**
+ * Branding + tenant config for this app. Editing this re-skins the whole app —
+ * logo, name and (via `primaryColor`) the brand color, with no globals.css edit.
+ */
+export const tenant: TenantConfig = {
+  id: "starter",
+  name: "GoERP Starter",
+  branding: {
+    // logo: "/logo.png",
+    companyName: "GoERP Starter",
+    tagline: "Powered by @goerp/core",
+    // primaryColor: "262 83% 58%", // HSL triple → reskins --primary at runtime
+    // favicon: "/favicon.ico",
+  },
+  currency: "VND",
+}

package/templates/starter-app/src/data/dictionary.ts

@@ -0,0 +1,8 @@
+import type { DictionaryType } from "@goerp/core/hooks"
+
+/**
+ * i18n dictionary for the shell. The sidebar falls back to the raw nav title
+ * when a key is missing, so an empty object works to start. Grow it into
+ * `{ navigation: { ... }, label: { ... } }` as you localize.
+ */
+export const dictionary: DictionaryType = {}

package/templates/starter-app/src/data/navigations.ts

@@ -0,0 +1,61 @@
+import type { NavigationType } from "@goerp/core/types"
+
+/**
+ * Sidebar navigation. Each top-level entry is a GROUP (title + iconName) with
+ * `items`. `iconName` is a lucide icon name (PascalCase). `resource` ties an
+ * item to an RBAC resource code so it hides when the user lacks permission.
+ *
+ * Entity pages go through the generic route /crud/<key> (see
+ * src/app/[lang]/(main)/crud/[entity]/page.tsx) — the `<key>` must match the
+ * registry key in src/configs/entities and the CRUD model map.
+ */
+export const navigations: NavigationType[] = [
+  {
+    title: "Tổng quan",
+    iconName: "LayoutDashboard",
+    items: [{ title: "Trang chủ", iconName: "House", href: "/" }],
+  },
+  {
+    title: "Quản lý",
+    iconName: "Settings",
+    items: [
+      {
+        title: "Phòng ban",
+        iconName: "Building2",
+        href: "/crud/departments",
+        resource: "department",
+      },
+    ],
+  },
+  {
+    title: "Hệ thống",
+    iconName: "ShieldCheck",
+    items: [
+      { title: "Vai trò", iconName: "ShieldCheck", href: "/roles", resource: "role" },
+      {
+        title: "Cấu hình",
+        iconName: "Settings2",
+        href: "/admin/system/settings",
+        resource: "system-setting",
+      },
+      {
+        title: "Nhật ký hoạt động",
+        iconName: "Scroll",
+        href: "/admin/system/audit",
+        resource: "audit-log",
+      },
+      {
+        title: "Nhật ký lỗi",
+        iconName: "Bug",
+        href: "/admin/system/error-logs",
+        resource: "error-log",
+      },
+      {
+        title: "Tác vụ định kỳ",
+        iconName: "Cpu",
+        href: "/admin/system/jobs",
+        resource: "system-job",
+      },
+    ],
+  },
+]

package/templates/starter-app/src/instrumentation.ts

@@ -0,0 +1,105 @@
+/**
+ * Điểm khởi động phía server của Next.js. Chạy MỘT LẦN mỗi tiến trình, trước
+ * request đầu tiên — chỗ duy nhất hợp lý để bật cron và dọn tác vụ mồ côi.
+ */
+
+export async function register() {
+  // Hook này cũng chạy trên edge runtime, nơi không có Prisma. Chặn sớm.
+  if (process.env.NEXT_RUNTIME !== "nodejs") return
+
+  const { cronManager } = await import("./lib/cron/db-cron-manager")
+  const { logger } = await import("./lib/logger")
+
+  try {
+    await cronManager.init()
+
+    // Tác vụ nền còn "running" là của tiến trình ĐÃ CHẾT (deploy/restart giữa
+    // chừng) — đánh dấu lỗi để user chạy lại, thay vì để quay vòng vĩnh viễn.
+    void import("@/server/tasks")
+      .then(({ reclaimStaleTasks }) => reclaimStaleTasks())
+      .catch((e) => logger.error("Reclaim background tasks failed", e))
+
+    // ── Việc định kỳ ────────────────────────────────────────────────────
+    // Thêm job của bạn ở đây. Lịch chạy lưu trong bảng `system_jobs`, admin
+    // đổi được trên /admin/system/jobs mà không cần deploy lại; `cronTime` bên
+    // dưới chỉ là giá trị mặc định cho lần tạo đầu tiên.
+    //
+    // Job PHẢI idempotent: container restart có thể làm nó chạy lại.
+    cronManager.addJob({
+      name: "system-heartbeat",
+      cronTime: "0 * * * *",
+      start: true,
+      onTick: async () => {
+        logger.debug("heartbeat")
+      },
+    })
+
+    logger.info("System jobs registered")
+  } catch (error) {
+    // Cron hỏng thì app vẫn phải phục vụ được request.
+    logger.error("Failed to register system jobs", error)
+  }
+}
+
+/**
+ * BẪY lịch chạy: bộ hẹn giờ của core quy cron về `setInterval` TỪ LÚC BOOT —
+ * "0 1 * * *" thành "cứ 24 giờ kể từ khi khởi động", không phải "1 giờ sáng".
+ * Container deploy vài lần một ngày thì job hằng ngày gần như không bao giờ
+ * chạy đúng giờ mong muốn.
+ *
+ * Cách chữa: hẹn MỖI GIỜ (`0 * * * *`) rồi tự gác bằng hàm này. Mỗi giờ đồng
+ * hồ chỉ có đúng một tick nên không chạy trùng.
+ *
+ *   cronManager.addJob({
+ *     name: "daily-report",
+ *     cronTime: "0 * * * *",
+ *     start: true,
+ *     onTick: async () => {
+ *       if (!isLocalHour(1)) return
+ *       await sendDailyReport()
+ *     },
+ *   })
+ */
+export function isLocalHour(hour: number, timeZone = "Asia/Ho_Chi_Minh"): boolean {
+  return (
+    Number(
+      new Intl.DateTimeFormat("en-GB", {
+        hour: "numeric",
+        hour12: false,
+        timeZone,
+      }).format(new Date()),
+    ) === hour
+  )
+}
+
+/**
+ * Lưới an toàn cho lỗi KHÔNG được bắt: route handler ném ra ngoài, lỗi render
+ * RSC… Chỗ nào tự bắt rồi trả response thì dùng `serverError()`; hook này lo
+ * phần còn lại để một cú crash vẫn để lại stack trong `error_logs` chứ không
+ * chỉ trôi qua stdout.
+ */
+export async function onRequestError(
+  error: unknown,
+  request: { path?: string; method?: string; headers?: Record<string, string> },
+  context: { routePath?: string; routeType?: string; routerKind?: string },
+) {
+  // logServerError kéo Prisma vào — không có trên edge runtime.
+  if (process.env.NEXT_RUNTIME !== "nodejs") return
+  try {
+    const { logServerError } = await import("./lib/errors/log-server-error")
+    logServerError(error, {
+      url: request?.path,
+      method: request?.method,
+      userAgent: request?.headers?.["user-agent"],
+      severity: "error",
+      extra: {
+        source: "onRequestError",
+        routePath: context?.routePath,
+        routeType: context?.routeType,
+        routerKind: context?.routerKind,
+      },
+    })
+  } catch {
+    // Không bao giờ để việc ghi lỗi tự ném lỗi bên trong hook xử lý lỗi.
+  }
+}

package/templates/starter-app/src/lib/api-handler.ts

@@ -0,0 +1,157 @@
+/**
+ * CỔNG của tầng API. Mọi route handler đi qua đây thay vì tự viết chuỗi
+ * `getSession → 401 → checkPermission → 403 → try/catch`.
+ *
+ *   export const GET  = apiHandler(handler)                                  // chỉ cần đăng nhập
+ *   export const POST = apiHandler(handler, { resource: "department", action: "create" })
+ *   export const GET  = apiHandler(handler, { public: true })                // không gác
+ *
+ * Khung ở @goerp/core/auth/api-handler; file này cắm phần thuộc về app:
+ *  - nguồn session + luật quyền,
+ *  - kiểm resource có trong Permission Registry (bắt lỗi gõ sai ngay lúc load),
+ *  - audit-context (ai đang thao tác — extension Prisma đọc để ghi audit_logs),
+ *  - ghi lỗi vào error_logs.
+ */
+import { NextResponse } from "next/server"
+import { withAuditContext } from "@goerp/core/audit"
+import { checkPermission as coreCheckPermission } from "@goerp/core/auth"
+import {
+  createApiHandler,
+  type ApiHandlerMiddleware,
+} from "@goerp/core/auth/api-handler"
+
+import type { NextRequest } from "next/server"
+import type { Session } from "@/types/session"
+
+import { getRegistryResource } from "@/configs/permissions"
+import { getSession } from "@/lib/auth"
+import { getBranchScope, runWithBranchScope } from "@/lib/branch-scope"
+import { logServerError } from "@/lib/errors/log-server-error"
+
+/**
+ * `TParams` mở ra cho route catch-all: `/api/files/[...key]` nhận
+ * `{ key: string[] }` chứ không phải `Record<string, string>`, khai cứng thì
+ * validator sinh tự động của Next báo lỗi kiểu ở mọi route dạng đó.
+ */
+interface HandlerContext<TParams = Record<string, string>> {
+  session: Session
+  params: Promise<TParams>
+}
+
+type Handler<TParams = Record<string, string>> = (
+  req: NextRequest,
+  ctx: HandlerContext<TParams>,
+) => Promise<Response>
+
+interface ApiHandlerOptions {
+  resource?: string
+  action?: string
+  /** true → endpoint public, bỏ qua cả xác thực. */
+  public?: boolean
+}
+
+/**
+ * Resource phải tồn tại trong Permission Registry. Gõ sai một ký tự sẽ khiến
+ * quyền KHÔNG BAO GIỜ khớp — nút biến mất, API trả 403, mà không có thông báo
+ * nào. Chạy lúc đăng ký handler (module load), không phải mỗi request: dev/test
+ * ném lỗi ngay, production chỉ cảnh báo để drift không làm sập app đang chạy.
+ */
+function assertResourceDeclared(resource: string) {
+  if (getRegistryResource(resource)) return
+  const message =
+    `[api-handler] resource "${resource}" chưa khai trong Permission Registry ` +
+    `(src/configs/permissions) — thêm vào <feature>.permissions.ts rồi chạy pnpm rbac-sync.`
+  if (process.env.NODE_ENV === "production") console.warn(message)
+  else throw new Error(message)
+}
+
+/**
+ * Gắn "ai đang thao tác" vào AsyncLocalStorage cho cả request. Extension audit
+ * trong lib/prisma.ts đọc context này; thiếu nó thì mọi dòng audit_logs đều
+ * ghi tác nhân rỗng.
+ */
+const auditContext: ApiHandlerMiddleware<Session> = async (next, { req, session }) => {
+  if (!session) return next()
+  const ip =
+    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+    req.headers.get("x-real-ip") ||
+    undefined
+  return (await withAuditContext(
+    { userId: session.user.id, userName: session.user.name, ip },
+    () => next(),
+  )) as Response
+}
+
+/**
+ * Mở context phạm vi chi nhánh cho cả request để branch-guard (lib/prisma.ts)
+ * biết user được xem chi nhánh nào. Phạm vi được tính LƯỜI — request không đụng
+ * model nào bị guard thì `resolve` không bao giờ chạy.
+ */
+const branchScope: ApiHandlerMiddleware<Session> = async (next, { session }) => {
+  if (!session) return next()
+  return (await runWithBranchScope(
+    { resolve: () => getBranchScope(session) },
+    () => next(),
+  )) as Response
+}
+
+/** Lỗi chưa bắt của route: in ra terminal + lưu error_logs + 500. */
+async function onApiError(error: unknown, req: Request): Promise<Response> {
+  console.error(`[API] ${req.method} ${req.url} error:`, error)
+
+  const session = await getSession().catch(() => null)
+  // Fire-and-forget — việc ghi log không được làm chậm phản hồi lỗi.
+  logServerError(error, {
+    url: req.url,
+    method: req.method,
+    userId: session?.user?.id,
+    userAgent: req.headers.get("user-agent") || undefined,
+  })
+
+  const message = error instanceof Error ? error.message : "Internal Server Error"
+  return NextResponse.json(
+    {
+      error: message,
+      // Ở dev trả kèm stack để showError() phía client hiện đúng thứ terminal
+      // đang in — production thì tuyệt đối không lộ.
+      ...(process.env.NODE_ENV === "production"
+        ? {}
+        : { debug: { message, stack: error instanceof Error ? error.stack : undefined } }),
+    },
+    { status: 500 },
+  )
+}
+
+const coreApiHandler = createApiHandler<Session>({
+  // Session có nhưng thiếu user thì coi như chưa đăng nhập.
+  getSession: async () => {
+    const session = await getSession()
+    return session?.user ? session : null
+  },
+  checkPermission: (session, resource, action) =>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    coreCheckPermission(session as any, resource, action),
+  assertResource: assertResourceDeclared,
+  wrap: [auditContext, branchScope],
+  onError: onApiError,
+})
+
+export function apiHandler<TParams = Record<string, string>>(
+  handler: Handler<TParams>,
+  options?: ApiHandlerOptions,
+) {
+  const route = coreApiHandler(
+    (req, ctx) =>
+      handler(req as NextRequest, {
+        // Đường public không có session; handler public không được đọc user.
+        session: ctx.session ?? ({} as Session),
+        params: ctx.params as Promise<TParams>,
+      }),
+    options,
+  )
+  return async (
+    req: NextRequest,
+    // Route tĩnh (không có segment động) được Next gọi mà không kèm ctx.
+    routeCtx?: { params: Promise<TParams> },
+  ): Promise<Response> => route(req, routeCtx as never)
+}

package/templates/starter-app/src/lib/auth-client.ts

@@ -0,0 +1,57 @@
+"use client"
+
+import { customSessionClient } from "better-auth/client/plugins"
+import { createAuthClient } from "better-auth/react"
+
+import type { AuthBridgeClient } from "@goerp/core/ui"
+import type { getAuth } from "@/lib/better-auth"
+
+/**
+ * Client Better Auth + cầu nối sang `AuthBridgeClient` của core.
+ *
+ * Core cố tình KHÔNG phụ thuộc thư viện auth nào: nó chỉ gọi qua bridge này,
+ * được mount ở src/providers/index.tsx. Object bridge phải là hằng số suốt
+ * vòng đời app (nó chứa một hook) — đừng tạo mới trong component.
+ */
+export const authClient = createAuthClient({
+  basePath: "/api/better-auth",
+  plugins: [customSessionClient<ReturnType<typeof getAuth>>()],
+})
+
+export const authBridgeClient: AuthBridgeClient = {
+  useSession: () => {
+    const s = authClient.useSession()
+    return {
+      data: s.data ? { user: s.data.user, expires: s.data.session?.expiresAt } : null,
+      status: s.isPending
+        ? "loading"
+        : s.data
+          ? "authenticated"
+          : "unauthenticated",
+      update: async () => {
+        await s.refetch()
+      },
+    }
+  },
+  signInWithCredentials: async ({ email, password }) => {
+    const { error } = await authClient.signIn.email({ email, password })
+    if (!error) return { error: null }
+    // Rate-limit của Better Auth trả 429 với message tiếng Anh — dịch cho người dùng.
+    if (error.status === 429) {
+      return {
+        error: "Bạn đã thử đăng nhập quá nhiều lần. Vui lòng đợi khoảng 1 phút rồi thử lại.",
+      }
+    }
+    return { error: error.message ?? "Đăng nhập thất bại" }
+  },
+  signOut: async (options) => {
+    await authClient.signOut()
+    if (typeof window !== "undefined") {
+      // Tab (URL + bộ lọc) sống trong sessionStorage qua cả hard reload — dọn
+      // khi đăng xuất để người đăng nhập sau không thấy tab của người trước.
+      sessionStorage.removeItem("tab-navigation-state")
+      sessionStorage.removeItem("tab-content-cache")
+      if (options?.callbackUrl) window.location.href = options.callbackUrl
+    }
+  },
+}

package/templates/starter-app/src/lib/auth.ts

@@ -0,0 +1,62 @@
+import { cache } from "react"
+import { headers } from "next/headers"
+
+import type { Session } from "@/types/session"
+
+/**
+ * ⚠️ CHỈ DEV: bỏ qua đăng nhập để dựng vỏ app trước khi có tài khoản thật.
+ * Guard `NODE_ENV !== "production"` khiến biến này vô hiệu trên bản build
+ * production dù có set env — đừng gỡ guard đó.
+ */
+const BYPASS_AUTH =
+  process.env.NODE_ENV !== "production" &&
+  (process.env.BYPASS_AUTH === "true" || process.env.BYPASS_AUTH === "1")
+
+/**
+ * getSession — nguồn session DUY NHẤT phía server. Mọi route/page gọi hàm này,
+ * đừng gọi thẳng `getAuth().api.getSession` chỗ khác.
+ *
+ * `cache()` của React gom mọi lần gọi trong CÙNG một request về một truy vấn.
+ */
+export const getSession = cache(async (): Promise<Session | null> => {
+  if (BYPASS_AUTH) {
+    return {
+      user: {
+        id: "dev-user",
+        email: "dev@example.com",
+        name: "Dev User",
+        avatar: null,
+        status: "active",
+        roles: ["admin"], // vai trò admin ⇒ core mở toàn quyền, khỏi cần seed
+        branchId: null,
+        branches: [],
+        permissions: [],
+      },
+      expires: new Date(Date.now() + 30 * 864e5).toISOString(),
+    }
+  }
+
+  // Import ĐỘNG có chủ đích — đừng đổi thành static. Turbopack dev có race lúc
+  // cold compile: hai request đầu ép module này compile song song và binding
+  // tĩnh tới better-auth có thể đóng băng ở undefined ("getAuth is not a
+  // function" ở mọi API route, chỉ hết khi sửa chạm file). Import động phân
+  // giải lúc runtime nên miễn nhiễm; bản production đã nạp sẵn module nên
+  // await gần như bằng 0.
+  const { getAuth } = await import("@/lib/better-auth")
+  const result = await getAuth().api.getSession({ headers: await headers() })
+  if (!result?.user) return null
+
+  const expiresAt = result.session?.expiresAt
+  return {
+    user: result.user,
+    expires:
+      expiresAt instanceof Date ? expiresAt.toISOString() : String(expiresAt ?? ""),
+  } as unknown as Session
+})
+
+/** Dùng trong API route/server action khi bắt buộc phải có người dùng. */
+export async function requireUser() {
+  const session = await getSession()
+  if (!session?.user?.id) throw new Error("Unauthorized")
+  return session.user
+}