@goplusvn/core 0.1.59 → 0.1.60

package/PLATFORM.md

@@ -10,6 +10,24 @@ implementation of every pattern here.
 > mechanism, or a CAS update into an app, stop — it belongs in core. Promote it
 > and re-export a thin shim from the app so call sites don't change.
 
+## Starting a new app
+
+This package ships the starter app it documents, plus the scaffolder:
+
+```bash
+npx -p @goplusvn/core goerp-init my-app --port 3010
+cd my-app && pnpm install
+# edit DATABASE_URL in the generated .env
+pnpm prisma:deploy && pnpm seed && pnpm rbac-sync && pnpm dev
+```
+
+`goerp-init` fills in the app name, port, branding (`src/configs/tenant.ts`) and
+a random `BETTER_AUTH_SECRET`; it never touches a database. `seed` must run
+**before** `rbac-sync` — see the generated `README.md` for why. What you get is
+a working login, RBAC, CRUD, audit/error logs, notifications, background tasks
+and cron — all from core, not copied code. Do not copy the template directory by
+hand: the rename steps are the whole point of the command.
+
 ## Design system (styles)
 
 One import gives the whole token system; override only your brand.

package/bin/goerp-init.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// Khởi tạo một app mới từ template đi kèm gói này.
+//
+//   npx -p @goplusvn/core goerp-init <ten-app> [--dir <đường-dẫn>] [--port 3010]
+//   pnpm init-app <ten-app> ...                      (từ trong repo goerp-core)
+//
+// Template nằm trong chính gói npm (packages/core/templates/starter-app) nên
+// lệnh này chạy được ở máy trắng, không cần clone goerp-core.
+//
+// App mới là repo ĐỘC LẬP, không phải thành viên workspace của core: nó cài
+// @goerp/core từ npm như mọi app thật, nên lỗi kiểu "chạy được nhờ workspace"
+// không lọt qua được.
+//
+// Script chỉ chép + thay tên/cổng + sinh secret. Không chạy pnpm install,
+// không đụng DB — những việc đó in ra cho người dùng tự chạy.
+
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const templateDir = path.join(packageRoot, "templates", "starter-app");
+
+// Thứ sinh ra lúc build/cài: chép sang chỉ tổ làm app mới hỏng theo cách khó hiểu.
+// `.env` cũng bỏ — nó là bí mật của máy đang chép, app mới sinh secret riêng.
+const SKIP = new Set([
+  "node_modules",
+  ".next",
+  ".turbo",
+  ".git",
+  ".env",
+  "tsconfig.tsbuildinfo",
+  "next-env.d.ts",
+]);
+
+function fail(message) {
+  console.error(`✗ ${message}`);
+  process.exit(1);
+}
+
+// ── Tham số ──────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const name = argv.find((a) => !a.startsWith("-"));
+if (!name) fail("Thiếu tên app. Dùng: goerp-init <ten-app> [--dir <path>] [--port 3010]");
+if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+  fail(`Tên "${name}" không hợp lệ — dùng kebab-case (chữ thường, số, gạch ngang).`);
+}
+
+const flag = (key, fallback) => {
+  const i = argv.indexOf(`--${key}`);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback;
+};
+
+const port = Number(flag("port", "3010"));
+if (!Number.isInteger(port) || port < 1024 || port > 65535) fail(`Cổng không hợp lệ: ${port}`);
+
+const targetDir = path.resolve(flag("dir", path.join(process.cwd(), name)));
+
+if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+  fail(`${targetDir} đã tồn tại và không rỗng — chọn thư mục khác cho chắc.`);
+}
+if (!fs.existsSync(templateDir)) fail(`Không thấy template ở ${templateDir}`);
+
+// ── Chép ─────────────────────────────────────────────────────────────────────
+function copyDir(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
+    const src = path.join(from, entry.name);
+    const dst = path.join(to, entry.name);
+    if (entry.isDirectory()) copyDir(src, dst);
+    else fs.copyFileSync(src, dst);
+  }
+}
+copyDir(templateDir, targetDir);
+
+const read = (p) => fs.readFileSync(path.join(targetDir, p), "utf8");
+const write = (p, content) => fs.writeFileSync(path.join(targetDir, p), content);
+
+// npm/pnpm KHÔNG đóng gói file tên `.gitignore` (nuốt hoặc đổi thành
+// `.npmignore` khi cài). Template ship nó dưới tên `gitignore`, trả lại dấu
+// chấm ở đây — thiếu bước này thì `git add .` đầu tiên của app mới commit luôn
+// `.env` vừa sinh (kèm BETTER_AUTH_SECRET) và cả node_modules.
+fs.renameSync(path.join(targetDir, "gitignore"), path.join(targetDir, ".gitignore"));
+
+// "quan-ly-kho" → "Quan Ly Kho": nhãn hiển thị mặc định, chủ app sửa lại sau.
+const title = name
+  .split("-")
+  .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+  .join(" ");
+
+// ── package.json: tên + cổng ─────────────────────────────────────────────────
+const pkg = JSON.parse(read("package.json"));
+pkg.name = name;
+pkg.version = "0.1.0";
+for (const key of ["dev", "start"]) {
+  if (pkg.scripts?.[key]) pkg.scripts[key] = pkg.scripts[key].replace(/--port \d+/, `--port ${port}`);
+}
+write("package.json", `${JSON.stringify(pkg, null, 2)}\n`);
+
+// ── .env: điền sẵn thứ điền được, để trống thứ chỉ người dùng biết ───────────
+// BETTER_AUTH_SECRET sinh ngay tại đây: bỏ trống thì lần đăng nhập đầu tiên đổ
+// lỗi khó đoán, mà nhét placeholder thì có ngày nó lên production.
+const dbName = name.replace(/-/g, "_");
+const env = read(".env.example")
+  .replace(/^DATABASE_URL=.*$/m, `DATABASE_URL="postgresql://postgres:postgres@localhost:5432/${dbName}"`)
+  .replace(/^BETTER_AUTH_SECRET=.*$/m, `BETTER_AUTH_SECRET="${randomBytes(32).toString("base64")}"`)
+  .replace(/^BETTER_AUTH_URL=.*$/m, `BETTER_AUTH_URL="http://localhost:${port}"`);
+write(".env", env);
+
+// ── Thương hiệu: một chỗ duy nhất đổi tên hiển thị toàn app ──────────────────
+// Bỏ qua bước này thì app mới chạy lên vẫn đề "GoERP Starter" trên sidebar,
+// trang đăng nhập và tiêu đề tab — người dựng app phải đi tìm mới sửa được.
+const tenantPath = "src/configs/tenant.ts";
+write(
+  tenantPath,
+  read(tenantPath)
+    .replace(/(\bid:\s*)"[^"]*"/, `$1"${name}"`)
+    .replace(/(\bname:\s*)"[^"]*"/, `$1"${title}"`)
+    .replace(/(\bcompanyName:\s*)"[^"]*"/, `$1"${title}"`),
+);
+
+// ── Tài liệu: điền tên app ───────────────────────────────────────────────────
+write("AGENTS.md", read("AGENTS.md").replace(/<APP-NAME>/g, name));
+write("README.md", read("README.md").replace(/^# GoERP starter app$/m, `# ${title}`));
+
+// ── Xong ─────────────────────────────────────────────────────────────────────
+const relative = path.relative(process.cwd(), targetDir);
+// Đường dẫn tương đối chỉ dễ đọc khi app nằm gần; xa quá thì in tuyệt đối.
+const rel = relative && relative.length < targetDir.length ? relative : targetDir;
+console.log(`✓ Đã tạo ${name} tại ${targetDir}\n`);
+console.log("Tiếp theo:\n");
+console.log(`  cd ${rel}`);
+console.log("  pnpm install");
+console.log("  # sửa DATABASE_URL trong .env cho trỏ đúng Postgres của bạn");
+console.log("  pnpm prisma:deploy   # dựng bảng (migration _init có sẵn)");
+console.log("  pnpm seed            # vai trò + tài khoản admin");
+console.log("  pnpm rbac-sync       # PHẢI chạy SAU seed, xem README");
+console.log(`  pnpm dev             # http://localhost:${port}`);
+console.log("\n.env đã có sẵn BETTER_AUTH_SECRET sinh ngẫu nhiên — đừng commit file này.");

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.59",
+  "version": "0.1.60",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -12,13 +12,15 @@
   "types": "./src/index.ts",
   "sideEffects": false,
   "bin": {
-    "goerp-features": "./bin/goerp-features.mjs"
+    "goerp-features": "./bin/goerp-features.mjs",
+    "goerp-init": "./bin/goerp-init.mjs"
   },
   "files": [
     "src",
     "bin",
     "scripts",
     "features",
+    "templates",
     "README.md",
     "CHANGELOG.md",
     "PLATFORM.md"
@@ -88,8 +90,6 @@
     "./audit": "./src/audit/index.ts",
     "./rbac/role-service": "./src/rbac/role-service.ts",
     "./rbac/resource-service": "./src/rbac/resource-service.ts",
-    "./infrastructure/cron/cron-manager": "./src/infrastructure/cron/cron-manager.ts",
-    "./infrastructure/cron/types": "./src/infrastructure/cron/types.ts",
     "./crud/pages/entity-crud-page": "./src/crud/pages/entity-crud-page.tsx",
     "./auth/auth-service": "./src/auth/auth-service.ts",
     "./package.json": "./package.json",

package/src/cron/db-cron-manager.ts

@@ -1,15 +1,15 @@
-import { SimpleCronJob } from "../infrastructure/cron/cron-manager";
+import { SimpleCronJob } from "./simple-cron-job";
 
 import type {
   CronJob,
   CronJobManager,
   CronJobOptions,
-} from "../infrastructure/cron/types";
+} from "./types";
 
 /**
  * Cron CÓ TRẠNG THÁI TRONG DB — engine dùng chung mọi app goerp (bảng
  * `system_jobs` + `job_execution_logs` ship qua `goerp-features sync`, feature
- * system-jobs). Bản `infrastructure/cron` chỉ hẹn giờ trong RAM: restart là
+ * system-jobs). Bản `SimpleCronJob` cạnh đây chỉ hẹn giờ trong RAM: restart là
  * mất bật/tắt, không có lịch sử chạy, admin không nhìn thấy gì.
  *
  * Vai trò từng lớp:

package/src/cron/index.ts

@@ -16,9 +16,9 @@ export {
   cronJobManager,
   CronJobManagerImpl,
   SimpleCronJob,
-} from "../infrastructure/cron/cron-manager";
+} from "./simple-cron-job";
 export type {
   CronJob,
   CronJobManager,
   CronJobOptions,
-} from "../infrastructure/cron/types";
+} from "./types";

package/src/{infrastructure/cron/cron-manager.ts → cron/simple-cron-job.ts}

@@ -3,7 +3,7 @@ import type {
   CronJobManager as ICronJobManager,
   CronJobOptions,
 } from "./types";
-import { createLogger } from "../logger";
+import { createLogger } from "../infrastructure/logger";
 
 const logger = createLogger("CronJobManager");
 

package/src/infrastructure/__tests__/architecture-verification.spec.ts

@@ -1,103 +1,19 @@
-import { describe, it, expect, vi } from "vitest";
-import { LockManager } from "../lock/lock-manager";
-import { WithLock } from "../lock/decorators";
-import type { CacheOptions, Cache } from "../cache/types";
-import { CacheNamespace } from "../cache/types";
-
-// Mock Cache Implementation for Testing
-class MockCache implements Cache {
-  private store = new Map<string, any>();
-  async get<T>(key: string): Promise<T | undefined> {
-    return this.store.get(key);
-  }
-  async set<T>(key: string, value: T): Promise<void> {
-    this.store.set(key, value);
-  }
-  async del(key: string): Promise<void> {
-    this.store.delete(key);
-  }
-  async has(key: string): Promise<boolean> {
-    return this.store.has(key);
-  }
-  async reset(): Promise<void> {
-    this.store.clear();
-  }
-  async keys(): Promise<string[]> {
-    return Array.from(this.store.keys());
-  }
-}
-
-describe("Architecture Verification: Phase 2 Enhancements", () => {
-  describe("2.2 Concurrency Control (LockManager)", () => {
-    it("should acquire and release lock successfully", async () => {
-      const cache = new MockCache();
-      const lockManager = new LockManager(cache);
-      const resourceId = "order-123";
-
-      const acquired = await lockManager.acquire(resourceId, { ttl: 1000 });
-      expect(acquired).toBe(true);
-
-      const isLocked = await cache.has(resourceId);
-      expect(isLocked).toBe(true);
-
-      await lockManager.release(resourceId);
-      const isLockedAfterRelease = await cache.has(resourceId);
-      expect(isLockedAfterRelease).toBe(false);
-    });
-
-    it("should fail to acquire lock if already locked", async () => {
-      const cache = new MockCache();
-      const lockManager = new LockManager(cache);
-      const resourceId = "order-456";
-
-      await lockManager.acquire(resourceId, { ttl: 5000 }); // Lock 1
-      const acquiredAgain = await lockManager.acquire(resourceId, {
-        ttl: 1000,
-      }); // Lock 2
+import { describe, it, expect } from "vitest";
 
-      expect(acquiredAgain).toBe(false);
-    });
-  });
-
-  describe("2.2 Decorator Usage (@WithLock)", () => {
-    it("should execute method with lock", async () => {
-      const cache = new MockCache();
-      const lockManager = new LockManager(cache);
-
-      class OrderService {
-        lockManager = lockManager;
-        executionCount = 0;
-
-        @WithLock("{0}")
-        async processOrder(orderId: string) {
-          this.executionCount++;
-          return `Processed ${orderId}`;
-        }
-      }
-
-      const service = new OrderService();
-      const result = await service.processOrder("100");
+import type { CacheOptions } from "../cache/types";
+import { CacheNamespace } from "../cache/types";
 
-      expect(result).toBe("Processed 100");
-      expect(service.executionCount).toBe(1);
-      // Lock should be released after execution
-      expect(await cache.has("lock:order-100")).toBe(false);
-    });
+describe("Cache: chiến lược namespace", () => {
+  it("CacheNamespace khai đúng giá trị", () => {
+    expect(CacheNamespace.Auth).toBe("auth");
+    expect(CacheNamespace.TenantConfig).toBe("tenant-config");
   });
 
-  describe("2.3 Namespace Caching Strategy", () => {
-    it("should define CacheNamespace enum correctly", () => {
-      expect(CacheNamespace.Auth).toBe("auth");
-      expect(CacheNamespace.TenantConfig).toBe("tenant-config");
-    });
-
-    it("should allow configuring cache with namespace (Simulation)", () => {
-      // This tests the TYPE definition and intent, as actual implementation depends on the Factory we haven't fully refactored yet.
-      const options: CacheOptions = {
-        name: "redis",
-        prefix: CacheNamespace.Auth,
-      };
-      expect(options.prefix).toBe("auth");
-    });
+  it("prefix nhận namespace", () => {
+    const options: CacheOptions = {
+      name: "redis",
+      prefix: CacheNamespace.Auth,
+    };
+    expect(options.prefix).toBe("auth");
   });
 });

package/src/infrastructure/index.ts

@@ -14,13 +14,10 @@ export type {
   CacheManagerOptions,
 } from "./cache";
 
-// EventBus
-export { eventBus, EventBusImpl } from "./event-bus";
-export type { EventBus, EventHandler, EventSubscription } from "./event-bus";
-
-// CronJob
-export { cronJobManager, CronJobManagerImpl, SimpleCronJob } from "./cron";
-export type { CronJob, CronJobOptions, CronJobManager } from "./cron";
+// Lịch chạy nền KHÔNG ở đây: dùng `@goerp/core/cron` (DbCronManager, đọc bảng
+// system_jobs). Bản in-memory cũ đã bỏ — mất hết job khi process restart.
+// Event-bus và lock in-memory cũng đã bỏ: chỉ đúng trong 1 tiến trình, mà app
+// thật chạy nhiều instance — khoá thì dùng advisory lock của Postgres.
 
 // API Service Layer (Inspired by Plane's Abstract APIService pattern)
 export { APIService, defaultClientOptions, isAPIError } from "./api-service";

package/src/ui/management/index.ts

@@ -1,3 +1,4 @@
-export * from "./job-management";
-export * from "./audit-log-page";
+// Trang quản trị bộ nhớ đệm. Nhật ký hoạt động nằm ở
+// `@goerp/core/system/pages/system-audit-page` (SystemAuditPage) — bản
+// AuditLogPage cũ đọc RAM trong client component nên luôn rỗng, đã bỏ.
 export * from "./cache-management";

package/templates/starter-app/.dockerignore

@@ -0,0 +1,41 @@
+# Git & IDE
+.git
+.gitignore
+**/.DS_Store
+**/.idea
+**/.vscode
+
+# Kết quả build — dựng lại bên trong Docker
+**/.next
+**/dist
+**/build
+**/.turbo
+
+# Cài lại bằng pnpm trong image; giữ context nhỏ
+node_modules
+**/node_modules
+
+# Test
+**/__tests__
+**/*.test.ts
+**/*.test.tsx
+**/coverage
+
+# Log
+*.log
+**/logs
+
+# Env — tuyệt đối không đưa secret vào image
+.env
+**/.env.local
+**/.env.*.local
+
+# Tài liệu
+**/docs
+**/*.md
+!**/README.md
+
+# ⚠️ Đừng thêm glob trần kiểu **/check-*.ts hay **/seed*.ts: chúng khớp CẢ mã
+# nguồn app (một route handler tên check-*.ts chẳng hạn) → build local xanh
+# (local không đọc .dockerignore) nhưng production 500 "Module not found".
+# Muốn loại script dev thì neo theo thư mục: **/scripts/seed*.ts

package/templates/starter-app/.env.example

@@ -0,0 +1,25 @@
+# ============================================================
+# Sao chép thành .env rồi điền. Ba biến đầu là BẮT BUỘC.
+# ============================================================
+
+# Postgres. Prisma 7 đọc qua prisma.config.ts (driver adapter), app đọc trong
+# src/lib/prisma.ts. Cùng một biến, không tách hai.
+DATABASE_URL="postgresql://user:password@localhost:5432/starter_app"
+
+# Better Auth. SECRET ký cookie phiên — đổi giá trị này là mọi người bị đăng
+# xuất. Sinh bằng: openssl rand -base64 32
+BETTER_AUTH_SECRET="generate-with: openssl rand -base64 32"
+# URL gốc THẬT của app. Better Auth dùng nó để kiểm Origin của các POST
+# (chống CSRF) — sai giá trị thì đăng nhập trả 403 dù mật khẩu đúng.
+BETTER_AUTH_URL="http://localhost:3010"
+
+# Trang chủ sau khi đăng nhập = "/vi" (src/proxy.ts: homePath). Muốn đổi thì
+# sửa thẳng ở đó — đường dẫn PHẢI có locale, để "/" thì proxy localize lại và
+# tạo vòng lặp chuyển hướng.
+
+# ---- Tùy chọn ----
+
+# Chỉ DEV: dựng vỏ app mà KHÔNG cần đăng nhập (phiên admin giả). Tiện lúc mới
+# clone; bỏ đi khi đã seed tài khoản thật. Đặt trên production cũng vô hiệu —
+# cả app lẫn core đều chặn cứng khi NODE_ENV=production.
+# BYPASS_AUTH=1

package/templates/starter-app/AGENTS.md

@@ -0,0 +1,52 @@
+# <APP-NAME> — Quy tắc cho AI
+
+> **Đọc trước:** `goerp-core/AGENTS.md` (nếu goerp-core là repo sibling) — quy tắc
+> nền cho mọi app dựng trên `@goerp/core`. File này chỉ nói phần riêng của app.
+
+## App này (điền khi khởi tạo)
+
+- **Nghiệp vụ:** <mô tả domain>.
+- **DB:** `DATABASE_URL` trong `.env`. Nếu đi qua SSH tunnel thì kiểm bằng
+  `nc -z localhost <port>` TRƯỚC khi chạy bất cứ lệnh Prisma nào.
+- **Cổng dev:** 3010 (đổi trong `package.json`).
+
+## Luật cứng
+
+**1. Tái dùng core, đừng chế lại.** Trước khi viết một màn hình/lớp hạ tầng, tìm
+trong `@goerp/core` xem đã có chưa: trang RBAC, trang cấu hình/nhật ký/tác vụ,
+CRUD engine, export, print, task runner, notification, cron. Cần thêm chức năng
+generic → **bổ sung vào core** (additive) rồi dùng, đừng fork vào app.
+
+**2. Không route nào tự gác.** Mọi handler đi qua `apiHandler` ở
+`src/lib/api-handler.ts`; mọi trang cần quyền gọi `requirePageAccess`. Không tự
+viết chuỗi `getSession → 401 → checkPermission → 403`.
+
+**3. Quyền phải khai trước khi dùng.** Chuỗi `resource` trong route/menu phải tồn
+tại trong `src/configs/permissions/`. Khai xong chạy `pnpm rbac-sync`. Gõ sai một
+ký tự = nút biến mất vĩnh viễn, không có thông báo. `pnpm test` bắt lỗi này.
+
+**4. DB có dữ liệu thật thì chỉ `migrate deploy`.** `prisma migrate dev`,
+`db push`, `migrate reset` (và các tool MCP tương ứng) chỉ dành cho DB trống lúc
+khởi tạo. Với DB đang chạy: viết SQL tay vào `prisma/migrations/<ts>_<tên>/` rồi
+`pnpm prisma:deploy`.
+
+**5. Mỗi lần sửa xong: `pnpm type-check` + `pnpm test`.** Không dồn kiểm tra về
+cuối. Ratchet trong `src/__tests__/architecture.test.ts` chỉ được siết chặt thêm,
+không được nới ra.
+
+**6. Lỗi phải đi vào `error_logs`.** Route dùng `serverError(error, req)` trong
+catch; đừng nuốt lỗi bằng `console.log` rồi trả 200.
+
+## Bẫy đã trả giá
+
+- Đổi schema xong phải **restart `next dev`**. KHÔNG `rm -rf .next` khi dev chạy.
+- Cron của core = `setInterval` tính từ lúc boot, không phải lịch theo giờ. Muốn
+  chạy đúng giờ: hẹn mỗi giờ + chặn bằng `isLocalHour()` (`src/instrumentation.ts`).
+- Handler tác vụ nền phải được import qua `src/server/tasks/index.ts` (side-effect
+  đăng ký) trước khi có ai enqueue, nếu không tác vụ nằm mãi ở `pending`.
+- Mọi đường ghi cấu hình phải `revalidateTag("system-settings", "max")`.
+- Ma trận quyền của core đọc chuỗi `"action:resource"` — đảo thứ tự thì không ô
+  nào tick và cũng chẳng có lỗi nào hiện ra.
+- Refactor lớn: chạy `pnpm build` thật trước khi deploy, và soi lại
+  `.dockerignore` — glob trần kiểu `**/check-*.ts` khớp cả mã nguồn app, làm build
+  local xanh nhưng production 500 "Module not found".

package/templates/starter-app/Dockerfile

@@ -0,0 +1,74 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# App độc lập trên @goerp/core — một app Next.js, không monorepo/turbo.
+# Output `standalone` (khai trong next.config.mjs) nên image chỉ chứa server.js
+# + đúng những node_modules đã được trace, không phải cả cây phụ thuộc.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Stage 1: base ────────────────────────────────────────────────────────────
+# Node ≥24.15 BẮT BUỘC: vá race TransformStream (nodejs/node#62040) — khách hủy
+# request giữa lúc SSR streaming làm nổ "transformAlgorithm is not a function"
+# trên node:22, và lỗi đó rơi thẳng vào error_logs.
+FROM node:24-alpine AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN npm install -g pnpm@10.8.1
+# libc6-compat + openssl: engine Prisma cần trên Alpine.
+# 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
+
+# ── Stage 2: deps ────────────────────────────────────────────────────────────
+FROM base AS deps
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+# ── Stage 3: builder ─────────────────────────────────────────────────────────
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# `prisma generate` đòi DATABASE_URL lúc build. Giá trị giả là đủ để sinh
+# client; URL thật tiêm lúc chạy.
+ARG DATABASE_URL
+ENV DATABASE_URL=${DATABASE_URL:-"postgresql://dummy:dummy@localhost:5432/dummy"}
+
+ENV NODE_OPTIONS="--max-old-space-size=4096"
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN pnpm run build
+
+# ── Stage 4: runner ──────────────────────────────────────────────────────────
+FROM base AS runner
+WORKDIR /app
+
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+# Đồng hồ container theo giờ VN để `new Date()` và các phép cắt ngày phía server
+# khớp GMT+7. Dữ liệu đã lưu (created_at) không đổi.
+ENV TZ=Asia/Ho_Chi_Minh
+
+# standalone: server.js + node_modules đã trace nằm ngay gốc.
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+
+# File tác vụ nền ghi vào <cwd>/storage khi chưa cấu hình S3/MinIO. Tạo sẵn +
+# cấp quyền, nếu không tác vụ xuất đầu tiên chết vì EACCES. Muốn file sống qua
+# lần deploy sau thì mount volume vào đúng đường dẫn này.
+RUN mkdir -p /app/storage && chown -R nextjs:nodejs /app/storage
+
+USER nextjs
+EXPOSE 3000
+
+# Di trú KHÔNG chạy ở đây: image standalone không có Prisma CLI. Chạy
+# `pnpm prisma migrate deploy` từ CI (hoặc một container one-shot dựng từ stage
+# `builder`) TRƯỚC khi đổi sang bản mới — như vậy migration hỏng thì dừng ở đó,
+# chứ không làm container khởi động lại vô hạn.
+CMD ["node", "server.js"]