@goplusvn/core 0.1.101 → 0.1.102

package/CHANGELOG.md

@@ -1,3 +1,46 @@
+## 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

package/package.json

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

package/templates/starter-app/Dockerfile

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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"),
     },