npm - @goplusvn/core - Versions diffs - 0.1.100 → 0.1.102 - Mend

@goplusvn/core 0.1.100 → 0.1.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/CHANGELOG.md +82 -1
package/package.json +1 -1
package/src/crud/components/crud-page.tsx +11 -3
package/src/ui/data-display/data-table/data-table.tsx +46 -37
package/src/ui/feedback/index.tsx +22 -14
package/src/ui/forms/multi-select.tsx +1 -2
package/src/ui/primitives/__tests__/dialog-fixed-child.test.tsx +101 -0
package/src/ui/primitives/combobox.tsx +7 -4
package/src/ui/primitives/dialog.tsx +51 -30
package/templates/starter-app/Dockerfile +10 -1
package/templates/starter-app/README.md +33 -0
package/templates/starter-app/eslint.config.mjs +6 -3
package/templates/starter-app/next.config.mjs +3 -1
package/templates/starter-app/package.json +3 -1
package/templates/starter-app/prisma/seed.ts +6 -2
package/templates/starter-app/prisma.config.ts +1 -0
package/templates/starter-app/scripts/backup-db.sh +51 -0
package/templates/starter-app/scripts/migration-new.mjs +13 -7
package/templates/starter-app/scripts/restore-db.sh +147 -0
package/templates/starter-app/src/app/[lang]/(main)/layout.tsx +1 -0
package/templates/starter-app/src/app/[lang]/layout.tsx +1 -2
package/templates/starter-app/src/app/api/branding/logo/route.ts +1 -1
package/templates/starter-app/src/app/layout.tsx +6 -2
package/templates/starter-app/src/app/manifest.ts +1 -1
package/templates/starter-app/src/configs/permissions/index.ts +10 -4
package/templates/starter-app/src/instrumentation.ts +6 -3
package/templates/starter-app/src/lib/auth-client.ts +6 -3
package/templates/starter-app/vitest.config.ts +2 -2

package/CHANGELOG.md CHANGED Viewed

@@ -1,9 +1,90 @@
+## 0.1.102 — Template tự sao lưu và phục hồi được; bịt lỗ `.env` lọt vào gói npm
+Ba lỗ trong `templates/starter-app`, cùng một hậu quả: khách nào dựng từ đây cũng thừa hưởng.
+**1. Gói npm nuốt cả `.env` của máy publish.** `files` của package kéo NGUYÊN thư mục `templates/`,
+mà thư mục đó lúc phát triển có `.env` thật, `.next/`, `.turbo/`, `node_modules/` — cả bốn đều không
+được git theo dõi. Publish từ CI (checkout sạch) thì không sao, nên các bản đã lên registry LÀNH: đã
+kiểm 0.1.83 / 0.1.93 / 0.1.101, không bản nào có `.env`. Nhưng publish từ máy lập trình viên thì
+`npm pack` gói hết: đo được **2.112 file / 16,1 MB kèm `.env` chứa `BETTER_AUTH_SECRET`**, so với
+730 file / 4,4 MB của bản trên registry. Thêm `.npmignore` để chặn tại chỗ thay vì dựa vào "CI luôn
+sạch". Sau khi vá, danh sách file `npm pack` tại máy khớp **không sai một file nào** với 0.1.101.
+**2. Image không có `pg_dump` lẫn `psql`.** Khách dựng từ template không có cả binary để lấy dữ liệu
+của mình ra. Thêm `postgresql18-client` + `gzip` vào stage `base` (mọi stage kế thừa, kể cả `runner`).
+Bản 18 vì pg_dump TỪ CHỐI dump server có major mới hơn client — client mới hơn server thì vẫn chạy,
+nên 18 an toàn cả hai chiều. `gzip` cài thật chứ không tin busybox: busybox có `gzip -t` nhưng KHÔNG
+có `gzip -l`, mà kịch bản phục hồi cần cả hai.
+**3. Có đường sao lưu thì phải có đường phục hồi.** Thêm `scripts/backup-db.sh` +
+`scripts/restore-db.sh` (`pnpm db:backup` / `pnpm db:restore`). Cả hai nhận thẳng URI Postgres, KHÔNG
+tách user/pass/host bằng tay — đã diễn tập với mật khẩu `p@ss:word` (có cả `@` lẫn `:`), thứ làm vỡ
+mọi cách tách chuỗi.
+Ba cái bẫy `restore-db.sh` chặn sẵn, mỗi cái đều đã dựng lại và xem nó nổ:
+- `psql` mặc định chạy tiếp qua lỗi rồi thoát 0 ⇒ dump hỏng nửa chừng vẫn báo "thành công".
+  Luôn `-v ON_ERROR_STOP=1 --single-transaction`.
+- `gzip -t` KHÔNG bắt được dump cụt: pg_dump chết giữa chừng vẫn cho ra file nén CRC đúng. Phép kiểm
+  thật là dòng cuối `PostgreSQL database dump complete`.
+- Đích phải khai bằng `--to`; trùng `DATABASE_URL` của app thì phải có `--yes-production`; đích đã có
+  bảng thì phải có `--drop`.
+Diễn tập trọn vòng (Postgres 18, dữ liệu có tiếng Việt có dấu, nháy đơn lồng, `\`, tab, xuống dòng,
+jsonb, mảng text NOT NULL, chuỗi rỗng vs NULL): md5 nội dung bảng ở nguồn và ở bản phục hồi **giống
+hệt**, 8/8 nhánh của script cho đúng kết quả mong đợi.
+**4. Ghim `@goerp/core` trong template.** `^0.1.101` → `0.1.101`. Caret trên gói 0.x nhận MỌI bản
+0.1.*, nên hai khách scaffold cách nhau một tháng chạy hai bản core khác nhau mà không có gì báo.
+Bằng chứng ngay trong repo: lockfile của template ghi `specifier: ...@^0.1.71` và giải ra **0.1.83**
+trong khi package.json nói 0.1.101 — lệch 18 bản, không ai thấy.
+---
+## 0.1.101 — Bỏ transform khỏi DialogContent (điều kiện sống của `portal=false`) & khung chờ bảng không còn dựng 1.000 dòng
+0.1.100 cho Combobox/MultiSelect render inline (`portal=false`) để FocusScope của Dialog không cướp
+focus ô tìm kiếm. Nhưng `DialogContent` khi đó vẫn canh giữa bằng `left-1/2 top-1/2
+translate-x-[-50%] translate-y-[-50%]`, mà `transform` biến phần tử thành CONTAINING BLOCK của mọi
+con `position: fixed` — panel của Radix popper (chạy `strategy: "fixed"`) vừa đổi hệ toạ độ vừa bị
+`overflow-y-auto` của hộp thoại (và `overflow-hidden` mà CrudDialog truyền vào) CẮT SẠCH. Đo Chromium
+với cùng toạ độ hình học: `elementFromPoint` trả về `<body>` khi có transform, trả về đúng panel khi
+không có. Ảnh hưởng nặng nhất là form CRUD trên desktop — hộp thoại ngắn, combo ở field cuối mở
+xuống dưới mép hộp là mất hút. Trên mobile `CrudDialog` cao `h-[100vh]` nên panel thường lọt trong
+hộp, không lộ lỗi.
+**Đổi**
+- `ui/primitives/dialog.tsx` — canh giữa bằng lớp bọc `fixed inset-0 grid place-items-center`
+  (`pointer-events-none`, content `pointer-events-auto`), `DialogContent` không còn `fixed`/`left-1/2`/
+  `top-1/2`/`translate-*`. Animation rút về `fade` + `zoom` (hai class `slide-*-1/2` cũ chỉ có nghĩa
+  khi đi kèm phép canh giữa bằng translate). Call site muốn lệch tâm thì dùng `self-*`/`justify-self-*`
+  của lưới — TUYỆT ĐỐI không dùng `translate-*`, kể cả `translate-y-0` (đã đo: `translate: 0 0` và
+  `will-change: transform` cũng tạo containing block).
+- `ui/primitives/__tests__/dialog-fixed-child.test.tsx` — MỚI. Khoá lại: `DialogContent` và lớp bọc
+  không mang class transform nào ở trạng thái tĩnh.
+- `ui/primitives/combobox.tsx` — cập nhật comment đã lạc hậu từ 0.1.100 (vẫn ghi "panel đi qua Portal").
+- `ui/forms/multi-select.tsx` — `normalizeVietnamese` thêm `.trim()` cho khớp bản trong `combobox.tsx`.
+**Bảng CRUD 1.000 dòng: có báo tải, không đứng hình**
+Chọn "1.000 dòng" thì `DataTable` dựng khung chờ đúng 1.000 hàng skeleton × số cột (hàng vạn node
+`animate-pulse`), vẽ ra rồi vứt đi ngay khi data về, kế đó dựng tiếp 1.000 hàng thật trong MỘT lượt
+render đồng bộ — main thread đứng vài giây, người dùng tưởng app treo.
+- `ui/data-display/data-table/data-table.tsx` — số dòng khung chờ kẹp trần 12 (`SKELETON_MAX_ROWS`)
+  thay vì bám `pageSize`.
+- `crud/components/crud-page.tsx` — `setData` chạy trong `useTransition`: React chia nhỏ lượt dựng
+  bảng lớn nên trang vẫn bấm/cuộn được, và `isRenderPending` giữ khung chờ hiển thị cho tới khi bảng
+  sẵn sàng.
 ## 0.1.100 — Cho phép cấu hình Inline Render (portal=false) cho Combobox & MultiSelect
 Khi Combobox hoặc MultiSelect nằm trong Modal/Dialog/Sheet, Radix Portal ra `document.body` khiến
 panel nằm ngoài DOM tree của Dialog cha, dẫn đến việc Radix Dialog gán `aria-hidden` và cướp focus
 của ô tìm kiếm.
-Bản này bổ sung prop `portal?: boolean` (mặc định `false`) trên `PopoverContent`, `Combobox` và `MultiSelect`,
+Bản này bổ sung prop `portal?: boolean` trên `PopoverContent` (mặc định `true`), `Combobox` và `MultiSelect`
+(mặc định `false`),
 giúp panel render inline cùng DOM tree của Dialog/Sheet, giải quyết triệt để vấn đề mất focus trên cả Desktop và Mobile.
 **Đổi**

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@goplusvn/core",
   "description": "GoPlusVN Platform Kit - ERP kernel: layout, RBAC, CRUD, multi-tenant, system pages",
-  "version": "0.1.100",
+  "version": "0.1.102",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/crud/components/crud-page.tsx CHANGED Viewed

@@ -6,6 +6,7 @@ import {
   useMemo,
   useRef,
   useCallback,
+  useTransition,
 } from "react";
 import { Button } from "../../ui";
 import { globalError } from "../../ui/feedback/error-dialog";
@@ -181,6 +182,13 @@ function CrudPageContent({
   });
   const [loading, setLoading] = useState(true);
   const [tableLoading, setTableLoading] = useState(false); // Separate loading state for table only
+  // Dựng 1.000 hàng bảng là công việc NẶNG (mỗi hàng × mỗi cột một cell
+  // TanStack). Nếu `setData` chạy như cập nhật thường, React dựng cả cây trong
+  // MỘT lượt đồng bộ: trình duyệt không vẽ được frame nào, người dùng thấy app
+  // đứng hình và tưởng là treo. Bọc trong transition thì React chia nhỏ lượt
+  // dựng, trang vẫn cuộn/bấm được, và `isRenderPending` giữ khung chờ hiển thị
+  // cho tới lúc bảng thật sự sẵn sàng — chờ có báo, không phải chết máy.
+  const [isRenderPending, startRenderTransition] = useTransition();
   const [dialogOpen, setDialogOpen] = useState(false);
   const [editingRowId, setEditingRowId] = useState<string | null>(null);
   const [detailOpen, setDetailOpen] = useState(false);
@@ -261,7 +269,7 @@ function CrudPageContent({
         // Only set data if this is still the latest request
         if (requestId === currentRequestRef.current) {
-          setData(response);
+          startRenderTransition(() => setData(response));
         }
       } catch (error) {
         // Ignore abort errors
@@ -849,7 +857,7 @@ function CrudPageContent({
             {viewMode === "table" ? (
               <CrudTable
                 data={data as CrudResponse<Record<string, unknown>>}
-                loading={loading || tableLoading}
+                loading={loading || tableLoading || isRenderPending}
                 onEdit={handleEdit}
                 onDelete={handleDelete}
                 onCustomAction={handleCustomAction}
@@ -868,7 +876,7 @@ function CrudPageContent({
                   config={config}
                   data={data as CrudResponse<Record<string, unknown>>}
                   permissions={permissions}
-                  loading={loading || tableLoading}
+                  loading={loading || tableLoading || isRenderPending}
                   onEdit={handleEdit}
                   onDelete={handleDelete}
                   onCustomAction={handleCustomAction}

package/src/ui/data-display/data-table/data-table.tsx CHANGED Viewed

@@ -153,7 +153,9 @@ export interface DataTableProps<TData> {
   /**
    * Callback when expanded state changes
    */
-  onExpandedChange?: (expanded: ExpandedState | ((old: ExpandedState) => ExpandedState)) => void;
+  onExpandedChange?: (
+    expanded: ExpandedState | ((old: ExpandedState) => ExpandedState),
+  ) => void;
   /**
    * Render custom sub-component (expanded row content)
@@ -194,6 +196,9 @@ export interface DataTableProps<TData> {
 // DataTable Component
 // ============================================================================
+// Trần số dòng khung chờ (xem chỗ dùng bên dưới).
+const SKELETON_MAX_ROWS = 12;
 export function DataTable<TData extends Record<string, unknown>>({
   data,
   columns: userColumns,
@@ -225,8 +230,9 @@ export function DataTable<TData extends Record<string, unknown>>({
 }: DataTableProps<TData>) {
   // Local state for expansion (used when uncontrolled)
   const [internalExpanded, setInternalExpanded] = useState<ExpandedState>({});
-  const expanded = controlledExpanded !== undefined ? controlledExpanded : internalExpanded;
+  const expanded =
+    controlledExpanded !== undefined ? controlledExpanded : internalExpanded;
   const setExpanded = controlledOnExpandedChange || setInternalExpanded;
   // Build final columns with selection and row number if enabled
@@ -491,7 +497,13 @@ export function DataTable<TData extends Record<string, unknown>>({
                 </tr>
                 <DataTableSkeleton
                   columns={userColumns.length}
-                  rows={pagination?.pageSize ?? 10}
+                  // Số dòng KHUNG CHỜ phải kẹp trần, đừng bám pageSize.
+                  // Chọn "1.000 dòng" thì bản cũ dựng 1.000 hàng skeleton ×
+                  // số cột — hàng vạn node `animate-pulse` vẽ ra rồi vứt đi
+                  // ngay khi data về, kế đó lại dựng tiếp 1.000 hàng thật:
+                  // main thread đứng vài giây, người dùng tưởng app treo.
+                  // Khung chờ chỉ cần phủ hết khung nhìn là đủ.
+                  rows={Math.min(pagination?.pageSize ?? 10, SKELETON_MAX_ROWS)}
                   showCheckbox={enableRowSelection}
                   showRowNumber={enableRowNumber}
                 />
@@ -642,44 +654,41 @@ function DataTableRowInner<TData>({
   );
 }
-const MemoizedTableRow = memo(
-  DataTableRowInner,
-  (prevProps, nextProps) => {
-    // Basic checks
+const MemoizedTableRow = memo(DataTableRowInner, (prevProps, nextProps) => {
+  // Basic checks
+  if (
+    prevProps.row.id !== nextProps.row.id ||
+    prevProps.isSelected !== nextProps.isSelected ||
+    prevProps.onRowClick !== nextProps.onRowClick ||
+    prevProps.visibleCellsCount !== nextProps.visibleCellsCount ||
+    prevProps.row.original !== nextProps.row.original ||
+    // cellClassName đổi phải re-render (trước đây bị bỏ sót — đổi class không ăn)
+    prevProps.cellClassName !== nextProps.cellClassName ||
+    // Kiểm tra trạng thái expand (dùng prop thay vì method của row để tránh mutable reference)
+    prevProps.isExpanded !== nextProps.isExpanded ||
+    // Key từ rowMemo(row.original): state ngoài row data mà cell phụ thuộc
+    !Object.is(prevProps.memoKey, nextProps.memoKey)
+  ) {
+    return false;
+  }
+  // Since sizing could change without cells count changing
+  // We check if cell sizes changed
+  const prevCells = prevProps.row.getVisibleCells();
+  const nextCells = nextProps.row.getVisibleCells();
+  for (let i = 0; i < prevCells.length; i++) {
     if (
-      prevProps.row.id !== nextProps.row.id ||
-      prevProps.isSelected !== nextProps.isSelected ||
-      prevProps.onRowClick !== nextProps.onRowClick ||
-      prevProps.visibleCellsCount !== nextProps.visibleCellsCount ||
-      prevProps.row.original !== nextProps.row.original ||
-      // cellClassName đổi phải re-render (trước đây bị bỏ sót — đổi class không ăn)
-      prevProps.cellClassName !== nextProps.cellClassName ||
-      // Kiểm tra trạng thái expand (dùng prop thay vì method của row để tránh mutable reference)
-      prevProps.isExpanded !== nextProps.isExpanded ||
-      // Key từ rowMemo(row.original): state ngoài row data mà cell phụ thuộc
-      !Object.is(prevProps.memoKey, nextProps.memoKey)
+      prevCells[i]?.column.getSize() !== nextCells[i]?.column.getSize() ||
+      prevCells[i]?.id !== nextCells[i]?.id ||
+      prevCells[i]?.column.id !== nextCells[i]?.column.id
     ) {
       return false;
     }
+  }
-    // Since sizing could change without cells count changing
-    // We check if cell sizes changed
-    const prevCells = prevProps.row.getVisibleCells();
-    const nextCells = nextProps.row.getVisibleCells();
-    for (let i = 0; i < prevCells.length; i++) {
-      if (
-        prevCells[i]?.column.getSize() !== nextCells[i]?.column.getSize() ||
-        prevCells[i]?.id !== nextCells[i]?.id ||
-        prevCells[i]?.column.id !== nextCells[i]?.column.id
-      ) {
-        return false;
-      }
-    }
-    return true;
-  },
-) as <TData>(props: MemoizedTableRowProps<TData>) => ReactElement;
+  return true;
+}) as <TData>(props: MemoizedTableRowProps<TData>) => ReactElement;
 // The type cast ensures the component retains the generic type TData
 // Without this, the component type would default to `any` or `unknown`.
 // Adding displayName to a typecast component can cause a ts error, so we cast it as any to add the display name.

package/src/ui/feedback/index.tsx CHANGED Viewed

@@ -86,20 +86,28 @@ export function AlertDialogContent({
   return (
     <AlertDialogPortal>
       <AlertDialogOverlay />
-      <AlertDialogPrimitive.Content
-        data-slot="alert-dialog-content"
-        className={cn(
-          "fixed top-[50%] left-[50%] z-50 w-[calc(100%_-_2rem)] sm:w-full grid bg-background translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 max-w-lg",
-          // KHÔNG để `sm:p-6` / `sm:max-w-lg` làm mặc định: twMerge chỉ khử xung
-          // đột trong cùng variant, nên trang truyền `p-0` / `max-w-sm` sẽ bị
-          // class `sm:` đè ngược ở ≥640px (đúng lỗi 0.1.84 của DialogContent).
-          // Cùng lý do với DialogContent: bị neo giữa màn hình nên phải chặn
-          // chiều cao, không thì mô tả dài sẽ tràn ra ngoài và không cuộn được.
-          "max-h-[calc(100dvh_-_2rem)] overflow-y-auto overscroll-contain",
-          className,
-        )}
-        {...props}
-      />
+      {/*
+        Canh giữa bằng lưới, KHÔNG bằng `translate-*` — cùng lý do với
+        `DialogContent` (xem `ui/primitives/dialog.tsx`): transform biến hộp
+        thoại thành containing block của con `position: fixed`, làm panel
+        Popover/Select bên trong bị `overflow-*` của chính hộp thoại cắt mất.
+      */}
+      <div className="pointer-events-none fixed inset-0 z-50 grid place-items-center">
+        <AlertDialogPrimitive.Content
+          data-slot="alert-dialog-content"
+          className={cn(
+            "pointer-events-auto relative z-50 w-[calc(100%_-_2rem)] sm:w-full grid bg-background gap-4 rounded-lg border p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 max-w-lg",
+            // KHÔNG để `sm:p-6` / `sm:max-w-lg` làm mặc định: twMerge chỉ khử xung
+            // đột trong cùng variant, nên trang truyền `p-0` / `max-w-sm` sẽ bị
+            // class `sm:` đè ngược ở ≥640px (đúng lỗi 0.1.84 của DialogContent).
+            // Cùng lý do với DialogContent: bị neo giữa màn hình nên phải chặn
+            // chiều cao, không thì mô tả dài sẽ tràn ra ngoài và không cuộn được.
+            "max-h-[calc(100dvh_-_2rem)] overflow-y-auto overscroll-contain",
+            className,
+          )}
+          {...props}
+        />
+      </div>
     </AlertDialogPortal>
   );
 }

package/src/ui/forms/multi-select.tsx CHANGED Viewed

@@ -151,6 +151,7 @@ const normalizeVietnamese = (str: string) =>
         .replace(/[\u0300-\u036f]/g, "")
         .replace(/[đĐ]/g, (m) => (m === "đ" ? "d" : "D"))
         .toLowerCase()
+        .trim()
     : "";
 const normalizeVietnameseChar = (char: string) => {
@@ -466,8 +467,6 @@ export const MultiSelect = React.forwardRef<MultiSelectRef, MultiSelectProps>(
       }
     }, [highlightedIndex, isVirtual, open]);
     // Click-ra-ngoài + Escape do DismissableLayer của Radix Popover lo (panel
     // đã đi qua Portal). Không tự nghe document nữa: hai lớp cùng đóng dễ
     // đá nhau, và bộ nghe cũ còn phải chừa ngoại lệ cho dialog.

package/src/ui/primitives/__tests__/dialog-fixed-child.test.tsx ADDED Viewed

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Dialog, DialogContent, DialogTitle } from "../dialog";
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogTitle,
+} from "../../feedback";
+/**
+ * DialogContent KHÔNG được mang transform.
+ *
+ * Panel của Popover/Combobox/MultiSelect/Select chạy `position: fixed`
+ * (Radix popper dùng `strategy: "fixed"`). Một tổ tiên có `transform` /
+ * `translate` / `will-change: transform` sẽ trở thành CONTAINING BLOCK của
+ * con `fixed` đó — kéo theo hai hậu quả: toạ độ đổi hệ quy chiếu, và
+ * `overflow-*` của hộp thoại CẮT panel. Dropdown mở quá mép hộp thoại thì
+ * biến mất sạch (đo Chromium: `elementFromPoint` trả về `<body>`).
+ *
+ * Vì Combobox/MultiSelect render inline (`portal={false}`, để FocusScope của
+ * Dialog không cướp focus ô tìm kiếm), điều kiện "hộp thoại không tạo
+ * containing block" là thứ DUY NHẤT giữ cho panel hiện đủ. Bản cũ canh giữa
+ * bằng `left-1/2 top-1/2 translate-x-[-50%] translate-y-[-50%]` nên vi phạm;
+ * bản mới canh giữa bằng lưới ở lớp bọc.
+ *
+ * Test này khoá lại điều đó — kể cả một class trông vô hại như
+ * `translate-y-0` cũng tạo containing block (đã đo).
+ */
+// Class Tailwind tạo transform. Chỉ soi token KHÔNG có variant prefix
+// (`data-[state=open]:zoom-in-95` chỉ chạy lúc animate nên vô hại).
+const TRANSFORM_UTILITY =
+  /^-?(translate|rotate|scale|skew)-|^transform$|^will-change-transform$/;
+function baseTransformClasses(el: Element): string[] {
+  return el.className
+    .split(/\s+/)
+    .filter((c) => c && !c.includes(":"))
+    .filter((c) => TRANSFORM_UTILITY.test(c));
+}
+describe("DialogContent", () => {
+  it("không mang class transform nào ở trạng thái tĩnh", () => {
+    render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Tiêu đề</DialogTitle>
+        </DialogContent>
+      </Dialog>,
+    );
+    const content = screen.getByRole("dialog");
+    expect(baseTransformClasses(content)).toEqual([]);
+  });
+  it("lớp bọc canh giữa cũng không mang transform", () => {
+    render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Tiêu đề</DialogTitle>
+        </DialogContent>
+      </Dialog>,
+    );
+    const wrapper = screen.getByRole("dialog").parentElement!;
+    expect(wrapper.className).toContain("grid");
+    expect(wrapper.className).toContain("place-items-center");
+    expect(baseTransformClasses(wrapper)).toEqual([]);
+  });
+  it("className của caller không được lén đưa transform vào", () => {
+    // Không chặn được ở runtime, nhưng khoá lại được ĐỊNH DẠNG: mặc định của
+    // core phải sạch để lỗi (nếu có) chỉ tới từ đúng một chỗ — call site.
+    render(
+      <Dialog open>
+        <DialogContent className="max-w-2xl p-0">
+          <DialogTitle>Tiêu đề</DialogTitle>
+        </DialogContent>
+      </Dialog>,
+    );
+    expect(baseTransformClasses(screen.getByRole("dialog"))).toEqual([]);
+  });
+});
+describe("AlertDialogContent", () => {
+  it("không mang class transform nào ở trạng thái tĩnh", () => {
+    render(
+      <AlertDialog open>
+        <AlertDialogContent>
+          <AlertDialogTitle>Xoá?</AlertDialogTitle>
+        </AlertDialogContent>
+      </AlertDialog>,
+    );
+    const content = screen.getByRole("alertdialog");
+    expect(baseTransformClasses(content)).toEqual([]);
+    expect(content.parentElement!.className).toContain("place-items-center");
+  });
+});

package/src/ui/primitives/combobox.tsx CHANGED Viewed

@@ -184,10 +184,13 @@ export function Combobox({
       </PopoverTrigger>
       {/*
-        Panel đi qua Portal của Radix + tự lật lên trên khi thiếu chỗ bên dưới
-        (`avoidCollisions` mặc định). Trước đây panel là `absolute` nằm trong
-        thân dialog (`overflow-y-auto`) nên bị CẮT NGANG ở mép dialog — chọn
-        combo trong CrudDialog chỉ thấy 1-2 dòng đầu.
+        Panel render INLINE (`portal={false}` mặc định): nằm cùng DOM tree với
+        Dialog/Sheet cha nên FocusScope của Radix không cướp focus ô tìm kiếm.
+        Đổi lại, nó CHỈ hiện đủ khi hộp thoại cha không tạo containing block —
+        `DialogContent` của core vì thế đã bỏ sạch transform (xem `dialog.tsx`
+        + `__tests__/dialog-fixed-child.test.tsx`). Panel vẫn là `position:
+        fixed` của Radix popper, tự lật lên trên khi thiếu chỗ bên dưới
+        (`avoidCollisions` mặc định).
         - `--radix-popover-trigger-width`: panel rộng đúng bằng ô trigger.
         - `--radix-popover-content-available-height`: trần chiều cao theo chỗ
           trống thực tế, KHÔNG bao giờ tràn khỏi màn hình.

package/src/ui/primitives/dialog.tsx CHANGED Viewed

@@ -35,36 +35,57 @@ const DialogContent = React.forwardRef<
 >(({ className, children, ...props }, ref) => {
   useReleaseStuckBodyLock();
   return (
-  <DialogPortal>
-    <DialogOverlay />
-    <DialogPrimitive.Content
-      ref={ref}
-      className={cn(
-        "fixed left-[50%] top-[50%] z-50 grid translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] rounded-lg",
-        // Hộp thoại bị neo `top-1/2 -translate-y-1/2`, nên nếu KHÔNG chặn chiều
-        // cao thì nội dung cao hơn màn hình sẽ tràn ra CẢ trên lẫn dưới và
-        // không cuộn được — hỏng trên điện thoại và trên tablet xoay ngang.
-        // Đây là mặc định: trang nào tự khai `max-h-*` / `overflow-*` thì
-        // class của trang đứng sau trong cn() nên vẫn thắng.
-        "max-h-[calc(100dvh_-_2rem)] overflow-y-auto overscroll-contain",
-        // Bề rộng: chừa 1rem mỗi bên trên màn hẹp thay vì dán sát mép.
-        // CẢNH BÁO (đã dính 0.1.84): mọi class mặc định ở đây mà trang có thể
-        // muốn ghi đè PHẢI để dạng KHÔNG prefix. `cn()` = twMerge chỉ khử xung
-        // đột trong CÙNG một variant — `sm:max-w-lg`/`sm:p-6` sẽ SỐNG SÓT khi
-        // trang truyền `max-w-2xl`/`p-0`, rồi thắng ở ≥640px vì nằm trong media
-        // query. Đó chính là lỗi bóp CrudDialog còn 512px + padding kép.
-        "w-[calc(100%_-_2rem)] sm:w-full max-w-lg",
-        className,
-      )}
-      {...props}
-    >
-      {children}
-      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
-        <X className="h-4 w-4" />
-        <span className="sr-only">Close</span>
-      </DialogPrimitive.Close>
-    </DialogPrimitive.Content>
-  </DialogPortal>
+    <DialogPortal>
+      <DialogOverlay />
+      {/*
+      Lớp canh giữa. CỐ Ý không còn `left-1/2 top-1/2 translate-x-[-50%]
+      translate-y-[-50%]` trên chính DialogContent.
+      `transform` biến phần tử thành CONTAINING BLOCK của mọi con
+      `position: fixed`. Panel của Popover/Combobox/Select (Radix popper chạy
+      `strategy: "fixed"`) vì thế vừa đổi hệ toạ độ, vừa BỊ CẮT bởi
+      `overflow-y-auto` ngay bên dưới — và bởi `overflow-hidden` mà CrudDialog
+      truyền vào. Dropdown mở quá mép hộp thoại thì biến mất SẠCH, không phải
+      cắt một nửa: đo Chromium (cùng toạ độ hình học) `elementFromPoint` trả
+      về `<body>` khi có transform, trả về đúng panel khi không có.
+      Grid centering không tạo containing block, nên con `fixed` lại neo theo
+      viewport và thoát khỏi mọi `overflow-*` của hộp thoại. Đây là điều kiện
+      để Combobox/MultiSelect render inline (`portal={false}` — cần thiết để
+      FocusScope của Dialog không cướp focus ô tìm kiếm) mà vẫn hiện đủ.
+      Khoá lại trong `__tests__/dialog-fixed-child.test.tsx`.
+    */}
+      <div className="pointer-events-none fixed inset-0 z-50 grid place-items-center">
+        <DialogPrimitive.Content
+          ref={ref}
+          className={cn(
+            "pointer-events-auto relative z-50 grid gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 rounded-lg",
+            // Hộp thoại canh giữa theo cả hai chiều, nên nếu KHÔNG chặn chiều
+            // cao thì nội dung cao hơn màn hình sẽ tràn ra CẢ trên lẫn dưới và
+            // không cuộn được — hỏng trên điện thoại và trên tablet xoay ngang.
+            // Đây là mặc định: trang nào tự khai `max-h-*` / `overflow-*` thì
+            // class của trang đứng sau trong cn() nên vẫn thắng.
+            "max-h-[calc(100dvh_-_2rem)] overflow-y-auto overscroll-contain",
+            // Bề rộng: chừa 1rem mỗi bên trên màn hẹp thay vì dán sát mép.
+            // CẢNH BÁO (đã dính 0.1.84): mọi class mặc định ở đây mà trang có thể
+            // muốn ghi đè PHẢI để dạng KHÔNG prefix. `cn()` = twMerge chỉ khử xung
+            // đột trong CÙNG một variant — `sm:max-w-lg`/`sm:p-6` sẽ SỐNG SÓT khi
+            // trang truyền `max-w-2xl`/`p-0`, rồi thắng ở ≥640px vì nằm trong media
+            // query. Đó chính là lỗi bóp CrudDialog còn 512px + padding kép.
+            "w-[calc(100%_-_2rem)] sm:w-full max-w-lg",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+          <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+            <X className="h-4 w-4" />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        </DialogPrimitive.Content>
+      </div>
+    </DialogPortal>
   );
 });
 DialogContent.displayName = DialogPrimitive.Content.displayName;

package/templates/starter-app/Dockerfile CHANGED Viewed

@@ -16,7 +16,16 @@ RUN npm install -g pnpm@10.8.1
 # tzdata: cấp /usr/share/zoneinfo để biến TZ ở stage runner có tác dụng. Thiếu
 # nó Alpine đứng nguyên UTC, và mọi phép "hôm nay" tính phía server lệch một
 # ngày trong khung 00:00–07:00 giờ VN.
-RUN apk add --no-cache libc6-compat openssl tzdata
+# postgresql18-client + gzip: để app SAO LƯU VÀ PHỤC HỒI ĐƯỢC CHÍNH NÓ. Thiếu
+# hai gói này thì trong image không có `pg_dump` lẫn `psql` — khách dựng từ
+# template không có cả binary để lấy dữ liệu của mình ra, và không có đường
+# nào bung một bản sao lưu trở lại.
+#   - Bản 18 khớp Postgres 18 đang chạy: pg_dump TỪ CHỐI dump một server có
+#     major MỚI HƠN client. Client mới hơn server thì vẫn chạy được, nên 18 là
+#     mốc an toàn; hạ xuống 17 là hỏng ngay khi khách nâng lên 18.
+#   - `gzip` phải cài THẬT, đừng tin busybox: busybox có `gzip -t` nhưng KHÔNG
+#     có `gzip -l`, mà kịch bản phục hồi cần cả hai.
+RUN apk add --no-cache libc6-compat openssl tzdata postgresql18-client gzip
 # ── Stage 2: deps ────────────────────────────────────────────────────────────
 FROM base AS deps

package/templates/starter-app/README.md CHANGED Viewed

@@ -119,6 +119,8 @@ Feature đã cắm sẵn trong template: `audit-logs`, `background-tasks`,
 | `pnpm prisma:deploy` | Áp migration đang chờ. **Cách duy nhất** đụng vào DB có dữ liệu thật. |
 | `pnpm migration:new <ten>` | Sinh migration mới từ diff schema (shadow DB tự tạo/xoá — Prisma 7 đã bỏ `--shadow-database-url`). |
 | `pnpm seed` | Vai trò + tài khoản admin + dữ liệu mẫu. Chạy TRƯỚC `rbac-sync`. |
+| `pnpm db:backup` | Sao lưu ra `./backups/*.sql.gz` (xem §Sao lưu & phục hồi). |
+| `pnpm db:restore --check-only <file>` | Kiểm một bản sao lưu, không đụng DB nào. |
 ---
@@ -133,6 +135,37 @@ Cần `pnpm-lock.yaml` trong build context (`pnpm install` sinh ra ở lần cà
 ---
+## Sao lưu & phục hồi
+Hai script đối xứng trong `scripts/`. **Đừng dùng cái này mà bỏ cái kia** — một
+bản sao lưu chưa từng thử phục hồi thì không phải bản sao lưu, đó là một lời hứa.
+```bash
+pnpm db:backup                          # → ./backups/<db>_backup_<ts>.sql.gz
+BACKUP_DIR=/opt/backups pnpm db:backup  # cron:  0 2 * * *  cd /app && ./scripts/backup-db.sh
+# rẻ nhất, không đụng database nào — chạy MỖI THÁNG một lần:
+./scripts/restore-db.sh --check-only backups/<bản mới nhất>.sql.gz
+# đầy đủ: dựng lại vào một database nháp
+./scripts/restore-db.sh --drop --to 'postgresql://.../app_thu' backups/<...>.sql.gz
+```
+Cả hai nhận thẳng URI của Postgres (`DATABASE_URL`), không tách user/pass/host
+bằng tay — tách tay là chỗ vỡ kinh điển khi mật khẩu có `@` hoặc `:`.
+Image đã có sẵn `postgresql18-client` + `gzip` cho hai script này.
+### Ba cái bẫy script chặn sẵn
+| Bẫy | Vì sao nó im lặng | Chặn bằng |
+| --- | --- | --- |
+| `psql` chạy tiếp qua lỗi rồi thoát 0 | dump hỏng nửa chừng vẫn báo "phục hồi thành công", DB thiếu bảng mà không ai biết | `-v ON_ERROR_STOP=1 --single-transaction` |
+| `gzip -t` **không** bắt được dump cụt | pg_dump chết giữa chừng vẫn cho ra file nén CRC đúng | kiểm dòng cuối `PostgreSQL database dump complete` |
+| phục hồi đè lên DB đang chạy | — | đích phải khai bằng `--to`; trùng `DATABASE_URL` thì phải có `--yes-production`; đích đã có bảng thì phải có `--drop` |
+---
 ## Bẫy đã gặp
 - Sau khi đổi schema → **restart `next dev`**. Đừng `rm -rf .next` khi dev đang chạy.

package/templates/starter-app/eslint.config.mjs CHANGED Viewed

@@ -4,8 +4,8 @@ import { fileURLToPath } from "node:url"
 import { includeIgnoreFile } from "@eslint/compat"
 import js from "@eslint/js"
-import nextPlugin from "@next/eslint-plugin-next"
 import goerp from "@goerp/core/eslint"
+import nextPlugin from "@next/eslint-plugin-next"
 import tseslint from "@typescript-eslint/eslint-plugin"
 import tsParser from "@typescript-eslint/parser"
 import importPlugin from "eslint-plugin-import"
@@ -15,7 +15,9 @@ import reactHooksPlugin from "eslint-plugin-react-hooks"
 import globals from "globals"
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const gitignorePath = resolve(__dirname, ".gitignore")
+const gitignoreFile = existsSync(resolve(__dirname, ".gitignore"))
+  ? resolve(__dirname, ".gitignore")
+  : resolve(__dirname, "gitignore")
 /**
  * Cấu hình lint của app. Mốc cần giữ: **0 lỗi**.
@@ -30,7 +32,8 @@ const gitignorePath = resolve(__dirname, ".gitignore")
  * và `pnpm guardrails` lo.
  */
 const eslintConfig = [
-  ...(existsSync(gitignorePath) ? [includeIgnoreFile(gitignorePath)] : []),
+  ...(existsSync(gitignoreFile) ? [includeIgnoreFile(gitignoreFile)] : []),
+  { ignores: [".next/**", "node_modules/**", "dist/**"] },
   js.configs.recommended,
   {
     files: ["**/*.{js,jsx,ts,tsx,mjs,cjs}"],

package/templates/starter-app/next.config.mjs CHANGED Viewed

@@ -18,7 +18,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
  */
 const workspaceRoot = (() => {
   try {
-    const real = fs.realpathSync(path.join(__dirname, "node_modules/@goerp/core"))
+    const real = fs.realpathSync(
+      path.join(__dirname, "node_modules/@goerp/core")
+    )
     if (real.startsWith(__dirname + path.sep)) return __dirname
     let dir = path.dirname(__dirname)
     while (dir !== path.dirname(dir)) {

package/templates/starter-app/package.json CHANGED Viewed

@@ -13,6 +13,8 @@
     "prisma:generate": "prisma generate",
     "prisma:deploy": "prisma migrate deploy",
     "prisma:studio": "prisma studio",
+    "db:backup": "./scripts/backup-db.sh",
+    "db:restore": "./scripts/restore-db.sh",
     "seed": "tsx prisma/seed.ts",
     "rbac-sync": "tsx scripts/rbac-sync.ts",
     "goerp-features": "goerp-features",
@@ -22,7 +24,7 @@
     "prepare": "husky || true"
   },
   "dependencies": {
-    "@goerp/core": "npm:@goplusvn/core@^0.1.100",
+    "@goerp/core": "npm:@goplusvn/core@0.1.101",
     "@hookform/resolvers": "3.9.0",
     "@prisma/adapter-pg": "^7.0.0",
     "@prisma/client": "^7.0.0",

package/templates/starter-app/prisma/seed.ts CHANGED Viewed

@@ -16,10 +16,12 @@
 import { PrismaPg } from "@prisma/adapter-pg"
 import { PrismaClient } from "@prisma/client"
 import bcrypt from "bcryptjs"
 import "dotenv/config"
 const connectionString = process.env.DATABASE_URL
-if (!connectionString) throw new Error("DATABASE_URL chưa được set (xem .env.example)")
+if (!connectionString)
+  throw new Error("DATABASE_URL chưa được set (xem .env.example)")
 const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString }) })
 const ADMIN_EMAIL = process.env.SEED_ADMIN_EMAIL ?? "admin@example.com"
@@ -118,7 +120,9 @@ async function main() {
   }
   console.log(`✓ ${departments.length} phòng ban mẫu`)
-  console.log("\nTiếp theo: pnpm rbac-sync   (nạp resource/action/quyền từ registry)")
+  console.log(
+    "\nTiếp theo: pnpm rbac-sync   (nạp resource/action/quyền từ registry)"
+  )
 }
 main()

package/templates/starter-app/prisma.config.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 import path from "node:path"
 import "dotenv/config"
 import { defineConfig } from "prisma/config"
 /**

package/templates/starter-app/scripts/backup-db.sh ADDED Viewed

@@ -0,0 +1,51 @@
+#!/bin/bash
+# ==============================================================================
+# Sao lưu database của app — dùng cùng `DATABASE_URL` mà app đang chạy.
+# ==============================================================================
+#   ./scripts/backup-db.sh                    # dùng DATABASE_URL trong môi trường
+#   BACKUP_DIR=/opt/backups ./scripts/backup-db.sh
+#   cron:  0 2 * * *  cd /app && ./scripts/backup-db.sh >> /var/log/backup.log 2>&1
+#
+# Cặp đôi với `restore-db.sh`. ĐỪNG dùng cái này mà bỏ cái kia: một bản sao lưu
+# chưa từng thử phục hồi thì không phải bản sao lưu, đó là một lời hứa.
+# Mỗi tháng chạy `./scripts/restore-db.sh --check-only <bản mới nhất>` một lần.
+#
+# Image (Dockerfile) đã có sẵn `postgresql18-client` + `gzip` cho hai script này.
+# ==============================================================================
+set -uo pipefail
+DB_URL="${DATABASE_URL:-}"
+if [ -z "$DB_URL" ]; then
+    echo "❌ Thiếu DATABASE_URL." >&2
+    exit 1
+fi
+# pg_dump nhận thẳng URI, nên KHÔNG cần tách user/pass/host bằng tay — tách tay
+# là chỗ hỏng kinh điển khi mật khẩu có ký tự '@' hoặc ':'.
+# Chỉ lấy tên database để đặt tên file: phần sau dấu '/' cuối, bỏ query string.
+DB_NAME=$(printf '%s' "$DB_URL" | sed -e 's|?.*$||' -e 's|.*/||')
+DB_NAME="${DB_NAME:-database}"
+BACKUP_DIR="${BACKUP_DIR:-./backups}"
+KEEP_DAYS="${KEEP_DAYS:-7}"
+mkdir -p "$BACKUP_DIR"
+DATE=$(date +"%Y-%m-%d_%H-%M-%S")
+FILEPATH="$BACKUP_DIR/${DB_NAME}_backup_$DATE.sql.gz"
+echo "[$(date)] Bắt đầu sao lưu '$DB_NAME'..."
+# `pipefail` ở đầu file là thứ bắt được ca pg_dump chết giữa chừng: không có nó,
+# mã thoát của cả pipe là mã của gzip (luôn 0) ⇒ dump hỏng vẫn báo "thành công".
+if pg_dump "$DB_URL" | gzip > "$FILEPATH"; then
+    echo "[$(date)] ✅ Sao lưu xong:"
+    du -h "$FILEPATH"
+    echo "[$(date)] Dọn bản cũ hơn $KEEP_DAYS ngày..."
+    find "$BACKUP_DIR" -name "${DB_NAME}_backup_*.sql.gz" -type f -mtime "+$KEEP_DAYS" -exec rm {} \;
+else
+    echo "[$(date)] ❌ Sao lưu THẤT BẠI." >&2
+    rm -f "$FILEPATH"   # đừng để lại file cụt trông như một bản sao lưu tốt
+    exit 1
+fi

package/templates/starter-app/scripts/migration-new.mjs CHANGED Viewed

@@ -17,6 +17,7 @@ import path from "node:path"
 import process from "node:process"
 import "dotenv/config"
 import pg from "pg"
 const name = process.argv[2]
@@ -34,11 +35,13 @@ if (!dbUrl) {
 const url = new URL(dbUrl)
 const mainDb = url.pathname.slice(1)
 const shadowDb = `${mainDb}_shadow_migrate`
-const shadowUrl = process.env.SHADOW_DATABASE_URL ?? (() => {
-  const u = new URL(dbUrl)
-  u.pathname = `/${shadowDb}`
-  return u.toString()
-})()
+const shadowUrl =
+  process.env.SHADOW_DATABASE_URL ??
+  (() => {
+    const u = new URL(dbUrl)
+    u.pathname = `/${shadowDb}`
+    return u.toString()
+  })()
 const adminUrl = (() => {
   const u = new URL(dbUrl)
@@ -63,7 +66,10 @@ async function withShadow(fn) {
 }
 const run = (cmd, env = {}) =>
-  execSync(cmd, { stdio: ["inherit", "pipe", "inherit"], env: { ...process.env, ...env } })
+  execSync(cmd, {
+    stdio: ["inherit", "pipe", "inherit"],
+    env: { ...process.env, ...env },
+  })
 await withShadow(async () => {
   console.log(`→ deploy migrations hiện có vào shadow (${shadowDb})…`)
@@ -72,7 +78,7 @@ await withShadow(async () => {
   console.log("→ diff shadow ↔ prisma/schema…")
   const sql = run(
     "pnpm exec prisma migrate diff --from-config-datasource --to-schema prisma/schema --script",
-    { DATABASE_URL: shadowUrl },
+    { DATABASE_URL: shadowUrl }
   ).toString()
   if (!sql.trim() || /This is an empty migration/.test(sql)) {

package/templates/starter-app/scripts/restore-db.sh ADDED Viewed

@@ -0,0 +1,147 @@
+#!/bin/bash
+# ==============================================================================
+# Phục hồi database từ bản sao lưu của `backup-db.sh`.
+# ==============================================================================
+#   # rẻ nhất — chỉ kiểm file, KHÔNG đụng database nào (chạy hàng tháng):
+#   ./scripts/restore-db.sh --check-only backups/app_backup_....sql.gz
+#
+#   # dựng lại vào một database NHÁP để kiểm tra:
+#   ./scripts/restore-db.sh --drop \
+#       --to 'postgresql://admin:pass@localhost:5432/app_thu' \
+#       backups/app_backup_....sql.gz
+#
+# Đích lấy từ `--to`, hoặc biến RESTORE_URL. CỐ Ý không mặc định về
+# DATABASE_URL: mặc định tiện tay ở đây nghĩa là một lần gõ nhầm sẽ ghi đè
+# database đang chạy thật.
+#
+# BA CÁI BẪY script này chặn — cả ba đều đã dựng lại và xem nó nổ (30/08/2026):
+#
+#   1. `psql` KHÔNG dừng khi gặp lỗi. Mặc định nó chạy tiếp tới câu cuối rồi
+#      thoát 0 ⇒ bản dump hỏng nửa chừng vẫn "phục hồi thành công", database
+#      thiếu bảng mà không ai biết. Ở đây luôn có `-v ON_ERROR_STOP=1`.
+#   2. `gzip -t` KHÔNG bắt được dump cụt. pg_dump chết giữa chừng vẫn cho ra
+#      file nén hợp lệ, CRC đúng. Phép kiểm thật là dòng cuối
+#      `PostgreSQL database dump complete`.
+#   3. Phục hồi đè lên database đang có dữ liệu, hoặc đè lên chính DATABASE_URL
+#      của app. Cả hai đều bị từ chối trừ khi nói rõ `--drop` / `--yes-production`.
+# ==============================================================================
+set -uo pipefail
+CHECK_ONLY=0
+DROP_FIRST=0
+ALLOW_PROD=0
+TARGET="${RESTORE_URL:-}"
+ARCHIVE=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --check-only)     CHECK_ONLY=1 ;;
+        --drop)           DROP_FIRST=1 ;;
+        --yes-production) ALLOW_PROD=1 ;;
+        --to)             shift; TARGET="${1:-}" ;;
+        -h|--help)        sed -n '3,20p' "$0"; exit 0 ;;
+        -*)               echo "❌ Tham số lạ: $1" >&2; exit 2 ;;
+        *)
+            if [ -n "$ARCHIVE" ]; then echo "❌ Chỉ nhận MỘT file sao lưu." >&2; exit 2; fi
+            ARCHIVE="$1" ;;
+    esac
+    shift
+done
+if [ -z "$ARCHIVE" ] || [ ! -f "$ARCHIVE" ]; then
+    echo "❌ Thiếu hoặc không thấy file sao lưu: ${ARCHIVE:-<trống>}" >&2
+    echo "   Dùng: $0 [--check-only] [--drop] [--to <url>] <*.sql.gz>" >&2
+    exit 2
+fi
+# --- Bước 1: file còn nguyên không -------------------------------------------
+echo "[$(date)] Kiểm tra $ARCHIVE ..."
+if ! gzip -t "$ARCHIVE"; then
+    echo "[$(date)] ❌ File nén HỎNG — không phục hồi được từ file này." >&2
+    exit 1
+fi
+echo "[$(date)] ✅ File nén nguyên vẹn ($(gzip -l "$ARCHIVE" | awk 'NR==2 {print $2}') byte sau giải nén)"
+if ! gunzip -c "$ARCHIVE" | tail -n 20 | grep -q "PostgreSQL database dump complete"; then
+    echo "[$(date)] ❌ Dump CỤT: thiếu dòng kết 'PostgreSQL database dump complete'." >&2
+    echo "    File nén thì nguyên nhưng pg_dump đã chết giữa chừng. Đừng dùng." >&2
+    exit 1
+fi
+echo "[$(date)] ✅ Dump có dòng kết — pg_dump đã chạy trọn."
+TABLES_IN_DUMP=$(gunzip -c "$ARCHIVE" | grep -c "^CREATE TABLE ")
+echo "[$(date)] 📦 Trong bản dump: $TABLES_IN_DUMP bảng"
+if [ "$CHECK_ONLY" -eq 1 ]; then
+    echo "[$(date)] --check-only: dừng ở đây, không đụng vào database nào."
+    exit 0
+fi
+# --- Bước 2: đích ------------------------------------------------------------
+if [ -z "$TARGET" ]; then
+    echo "[$(date)] ❌ Chưa nói phục hồi vào đâu. Thêm --to <url> hoặc đặt RESTORE_URL." >&2
+    exit 2
+fi
+if [ -n "${DATABASE_URL:-}" ] && [ "$TARGET" = "$DATABASE_URL" ] && [ "$ALLOW_PROD" -eq 0 ]; then
+    echo "[$(date)] ❌ Đích trùng DATABASE_URL của app — đây là database đang chạy thật." >&2
+    echo "    Phục hồi vào đó sẽ GHI ĐÈ dữ liệu hiện có." >&2
+    echo "    Nếu đúng là việc bạn muốn (thảm hoạ thật, đã mất DB), thêm --yes-production." >&2
+    exit 1
+fi
+DB_NAME=$(printf '%s' "$TARGET" | sed -e 's|?.*$||' -e 's|.*/||')
+ADMIN_URL=$(printf '%s' "$TARGET" | sed -e "s|/${DB_NAME}\(?.*\)\{0,1\}$|/postgres|")
+if ! psql "$ADMIN_URL" -v ON_ERROR_STOP=1 -tAqc "select 1" >/dev/null 2>&1; then
+    echo "[$(date)] ❌ Không kết nối được tới máy chủ đích (database 'postgres')." >&2
+    exit 1
+fi
+# --- Bước 3: đích phải trống --------------------------------------------------
+EXISTS=$(psql "$ADMIN_URL" -tAqc "select 1 from pg_database where datname = '$DB_NAME'")
+if [ "$EXISTS" = "1" ]; then
+    N=$(psql "$TARGET" -tAqc "select count(*) from information_schema.tables where table_schema='public'")
+    if [ "${N:-0}" -gt 0 ] && [ "$DROP_FIRST" -eq 0 ]; then
+        echo "[$(date)] ❌ Database '$DB_NAME' đã có $N bảng." >&2
+        echo "    Phục hồi đè lên sẽ trộn dữ liệu cũ với dữ liệu trong bản sao lưu." >&2
+        echo "    Chọn database khác, hoặc thêm --drop để XOÁ HẲN '$DB_NAME' rồi dựng lại." >&2
+        exit 1
+    fi
+    if [ "$DROP_FIRST" -eq 1 ]; then
+        echo "[$(date)] ⚠️  --drop: xoá database '$DB_NAME' ($N bảng) rồi tạo lại..."
+        psql "$ADMIN_URL" -v ON_ERROR_STOP=1 -qc "drop database \"$DB_NAME\" with (force)" || exit 1
+        EXISTS=""
+    fi
+fi
+if [ "$EXISTS" != "1" ]; then
+    echo "[$(date)] Tạo database '$DB_NAME'..."
+    psql "$ADMIN_URL" -v ON_ERROR_STOP=1 -qc "create database \"$DB_NAME\"" || exit 1
+fi
+# --- Bước 4: phục hồi ---------------------------------------------------------
+echo "[$(date)] Phục hồi vào '$DB_NAME'..."
+LOG=$(mktemp)
+if gunzip -c "$ARCHIVE" | psql "$TARGET" -v ON_ERROR_STOP=1 --single-transaction -q > "$LOG" 2>&1; then
+    echo "[$(date)] ✅ Phục hồi thành công."
+else
+    echo "[$(date)] ❌ Phục hồi THẤT BẠI. Nhật ký:" >&2
+    tail -n 30 "$LOG" >&2
+    rm -f "$LOG"; exit 1
+fi
+rm -f "$LOG"
+# --- Bước 5: đối chiếu --------------------------------------------------------
+# Restore xong mà không đếm lại thì vẫn chỉ là lời hứa.
+RESTORED=$(psql "$TARGET" -tAqc "select count(*) from information_schema.tables where table_schema='public' and table_type='BASE TABLE'")
+echo "[$(date)] 📊 Bảng trong dump: $TABLES_IN_DUMP — bảng sau phục hồi: $RESTORED"
+if [ "$RESTORED" != "$TABLES_IN_DUMP" ]; then
+    echo "[$(date)] ❌ LỆCH số bảng. Bản phục hồi này KHÔNG dùng được." >&2
+    exit 1
+fi
+echo "[$(date)] 10 bảng nhiều dòng nhất:"
+psql "$TARGET" -c "select relname as bang, n_live_tup as so_dong from pg_stat_user_tables order by n_live_tup desc limit 10"
+echo "[$(date)] 🎉 Hoàn tất. Nhìn bảng trên bằng mắt trước khi tin."

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

@@ -4,6 +4,7 @@ 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"

package/templates/starter-app/src/app/[lang]/layout.tsx CHANGED Viewed

@@ -1,7 +1,6 @@
-import { resolveBranding, tenantWithBranding } from "@goerp/core/branding"
 import { Providers } from "@/providers"
 import { getSystemCompany } from "@/server/services/company-service"
+import { resolveBranding, tenantWithBranding } from "@goerp/core/branding"
 import type { LocaleType } from "@goerp/core/types"
 import type { ReactNode } from "react"

package/templates/starter-app/src/app/api/branding/logo/route.ts CHANGED Viewed

@@ -1,6 +1,6 @@
+import { getSystemCompany } from "@/server/services/company-service"
 import { createBrandingLogoHandler } from "@goerp/core/branding"
-import { getSystemCompany } from "@/server/services/company-service"
 import { getFile } from "@/lib/storage"
 /**

package/templates/starter-app/src/app/layout.tsx CHANGED Viewed

@@ -1,11 +1,15 @@
-import { PwaMetaTags, buildBrandingMetadata, resolveBranding } from "@goerp/core/branding"
+import { getSystemCompany } from "@/server/services/company-service"
+import {
+  PwaMetaTags,
+  buildBrandingMetadata,
+  resolveBranding,
+} from "@goerp/core/branding"
 import type { Metadata } from "next"
 import type { ReactNode } from "react"
 import { i18n } from "@/configs/i18n"
 import { tenant } from "@/configs/tenant"
-import { getSystemCompany } from "@/server/services/company-service"
 import "./globals.css"

package/templates/starter-app/src/app/manifest.ts CHANGED Viewed

@@ -1,10 +1,10 @@
+import { getSystemCompany } from "@/server/services/company-service"
 import { buildAppManifest, resolveBranding } from "@goerp/core/branding"
 import type { MetadataRoute } from "next"
 import { i18n } from "@/configs/i18n"
 import { tenant } from "@/configs/tenant"
-import { getSystemCompany } from "@/server/services/company-service"
 /**
  * Web App Manifest — mức PWA "cài được lên màn hình chính", sinh ĐỘNG theo hồ

package/templates/starter-app/src/configs/permissions/index.ts CHANGED Viewed

@@ -1,8 +1,12 @@
+import type {
+  FeaturePermissions,
+  LookupPolicy,
+  ResourceDeclaration,
+} from "./types"
 import masterDataPermissions from "./master-data.permissions"
 import systemPermissions from "./system.permissions"
-import type { FeaturePermissions, LookupPolicy, ResourceDeclaration } from "./types"
 export type { FeaturePermissions, LookupPolicy, ResourceDeclaration }
 /**
@@ -23,7 +27,7 @@ for (const feature of permissionRegistry) {
       // Trùng mã resource là lỗi cấu hình im lặng nguy hiểm nhất: hai phân hệ
       // tưởng mình sở hữu cùng một quyền. Ném ngay lúc nạp module.
       throw new Error(
-        `Permission registry: resource "${resource.code}" khai trùng ở "${feature.feature}" và "${owner}"`,
+        `Permission registry: resource "${resource.code}" khai trùng ở "${feature.feature}" và "${owner}"`
       )
     }
     resourceByCode.set(resource.code, resource)
@@ -31,7 +35,9 @@ for (const feature of permissionRegistry) {
   }
 }
-export function getRegistryResource(code: string): ResourceDeclaration | undefined {
+export function getRegistryResource(
+  code: string
+): ResourceDeclaration | undefined {
   return resourceByCode.get(code)
 }

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

@@ -49,14 +49,17 @@ export async function register() {
  * Hàm dưới chỉ còn cho ca đặc thù: job muốn gác theo MỘT múi giờ KHÁC múi giờ
  * tiến trình (vd server chạy UTC nhưng nghiệp vụ theo giờ VN).
  */
-export function isLocalHour(hour: number, timeZone = "Asia/Ho_Chi_Minh"): boolean {
+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()),
+      }).format(new Date())
     ) === hour
   )
 }
@@ -70,7 +73,7 @@ export function isLocalHour(hour: number, timeZone = "Asia/Ho_Chi_Minh"): boolea
 export async function onRequestError(
   error: unknown,
   request: { path?: string; method?: string; headers?: Record<string, string> },
-  context: { routePath?: string; routeType?: string; routerKind?: 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

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

@@ -3,8 +3,8 @@
 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"
+import type { AuthBridgeClient } from "@goerp/core/ui"
 /**
  * Client Better Auth + cầu nối sang `AuthBridgeClient` của core.
@@ -22,7 +22,9 @@ export const authBridgeClient: AuthBridgeClient = {
   useSession: () => {
     const s = authClient.useSession()
     return {
-      data: s.data ? { user: s.data.user, expires: s.data.session?.expiresAt } : null,
+      data: s.data
+        ? { user: s.data.user, expires: s.data.session?.expiresAt }
+        : null,
       status: s.isPending
         ? "loading"
         : s.data
@@ -39,7 +41,8 @@ export const authBridgeClient: AuthBridgeClient = {
     // 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.",
+        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" }

package/templates/starter-app/vitest.config.ts CHANGED Viewed

@@ -21,11 +21,11 @@ export default defineConfig({
       "@": path.resolve(__dirname, "./src"),
       "@goerp/core/user/client-page": path.resolve(
         __dirname,
-        "../../src/user/pages/users-client-page.tsx",
+        "../../src/user/pages/users-client-page.tsx"
       ),
       "@goerp/core/tasks/ui": path.resolve(
         __dirname,
-        "../../src/tasks/ui/task-list-client.tsx",
+        "../../src/tasks/ui/task-list-client.tsx"
       ),
       "@goerp/core": path.resolve(__dirname, "../../src"),
     },