@goplusvn/core 0.1.59 → 0.1.61

package/src/crud/server-service.ts

@@ -15,7 +15,8 @@
 //     getModelName: (e) => getModelName(e, MODEL_MAP),
 //   });
 
-import { compileFilterTree } from "./lib/filter-tree";
+import { buildListQuery } from "./lib/query-builder";
+import { prepareMutationData } from "./lib/mutation-builder";
 import type { CrudQueryParams, CrudResponse, EntityConfig } from "../types";
 import { serializeDecimalFields } from "../utils/serialize";
 
@@ -136,163 +137,27 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
     return m;
   };
 
-  const filterValidFields = (data: any, config: EntityConfig) => {
-    const valid = new Set(config.fields.filter((f) => !(f as any).isDisplayOnly).map((f) => f.name));
-    for (const f of systemFields) valid.add(f);
-    const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(data)) {
-      if (valid.has(k)) out[k] = v;
-      else log.warn(`Filtering out invalid field "${k}" for entity "${config.name}"`);
-    }
-    return out;
-  };
 
-  const castFieldValues = (data: any, config: EntityConfig) => {
-    const out = { ...data };
-    for (const field of config.fields) {
-      const value = out[field.name];
-      if (value === undefined || value === null) continue;
-      if (field.type === "boolean" || field.type === "switch") {
-        let isTrue: boolean;
-        if (typeof value === "string") {
-          const lv = value.toLowerCase();
-          isTrue = lv === "true" || lv === "active" || value === "1" || value === "on";
-        } else isTrue = Boolean(value);
-        if (field.type === "switch" && field.options && field.options.length >= 2) {
-          out[field.name] = isTrue ? (field.options[0] as any).value : (field.options[1] as any).value;
-        } else out[field.name] = isTrue;
-      } else if (field.type === "number" || (field.type as string) === "integer") {
-        if (typeof value === "string") {
-          if (value.trim() === "") out[field.name] = null;
-          else {
-            const num = Number(value);
-            if (!isNaN(num)) out[field.name] = num;
-          }
-        }
-      }
-    }
-    return out;
-  };
-
-  const transformRelationFields = (data: any, mode: "create" | "update") => {
-    const out = { ...data };
-    // citizenId/targetId là legacy-default từ consumer đầu tiên — app mới khai
-    // cột scalar *Id của mình qua deps.relationFieldSkip thay vì sửa core.
-    const skip = new Set([
-      "id",
-      "createdBy",
-      "updatedBy",
-      "citizenId",
-      "targetId",
-      ...(deps.relationFieldSkip ?? []),
-    ]);
-    for (const key of Object.keys(out)) {
-      if (skip.has(key)) continue;
-      if (key.endsWith("Id") && key.length > 2) {
-        const rel = key.slice(0, -2);
-        const value = out[key];
-        if (value && typeof value === "string" && value.trim() !== "") {
-          out[rel] = { connect: { id: value } };
-          delete out[key];
-        } else if (value === null || value === undefined || value === "") {
-          if (mode === "update") out[rel] = { disconnect: true };
-          delete out[key];
-        }
-      }
-    }
-    return out;
-  };
 
   return {
     async list(entity, config, params) {
       const prismaModel = model(entity);
-      const { page = 1, pageSize = 10, search, sort, filters } = params;
-      const safePage = Math.max(1, Number(page) || 1);
-      const safePageSize = Math.min(Math.max(1, Number(pageSize) || 10), MAX_PAGE_SIZE);
-      const skip = (safePage - 1) * safePageSize;
-      const take = safePageSize;
-
-      const allowedFields = new Set<string>([
-        ...config.fields.map((f) => f.name),
-        "id", "createdAt", "updatedAt", "createdBy", "updatedBy", config.idField || "id",
-      ]);
-      const allowedRelations = new Set<string>(config.include || []);
-      const isAllowed = (name: string) => {
-        if (!name) return false;
-        if (name.includes(".")) return allowedRelations.has(name.split(".")[0]);
-        return allowedFields.has(name);
-      };
-
-      const where: any = { ...(deps.scopeWhere?.(entity, config) ?? {}) };
-      if (search && search.trim()) {
-        const term = search.trim();
-        const searchFields = config.fields.filter((f) => f.filterable && f.type === "text").map((f) => f.name);
-        if (searchFields.length) where.OR = searchFields.map((f) => ({ [f]: { contains: term, mode: "insensitive" } }));
-      }
-      if (filters && filters.length) {
-        for (const filter of filters) {
-          const { name, value, operator } = filter as any;
-          if (value === undefined || value === null || (Array.isArray(value) && value.length === 0)) continue;
-          if (!isAllowed(name)) {
-            log.warn(`Ignoring filter on disallowed field "${name}" for entity "${entity}"`);
-            continue;
-          }
-          let target = where;
-          let key = name;
-          if (name.includes(".")) {
-            const parts = name.split(".");
-            key = parts.pop()!;
-            for (const p of parts) { if (!target[p]) target[p] = {}; target = target[p]; }
-          }
-          const op = operator as string;
-          if (op === "contains") target[key] = { contains: value, mode: "insensitive" };
-          else if (op === "in") target[key] = { in: value };
-          else if (op === "notIn") target[key] = { notIn: value };
-          else if (op === "eq") target[key] = value;
-          else if (op === "ne") target[key] = { not: value };
-          else if (op === "gt") target[key] = { gt: value };
-          else if (op === "gte") target[key] = { gte: value };
-          else if (op === "lt") target[key] = { lt: value };
-          else if (op === "lte") target[key] = { lte: value };
-          else if (op === "startsWith") target[key] = { startsWith: value, mode: "insensitive" };
-          else if (op === "endsWith") target[key] = { endsWith: value, mode: "insensitive" };
-          else if (op === "isNull") target[key] = null;
-          else if (op === "isNotNull") target[key] = { not: null };
-          else target[key] = value;
-        }
-      }
-      // Bộ lọc nâng cao dạng cây ($and/$or, nhiều điều kiện cùng field) —
-      // cùng guard isAllowed với filter phẳng; AND vào where (search dùng OR
-      // nên không đụng nhau). Cây sai cấu trúc → throw (route trả lỗi 4xx).
-      if (params.filterTree) {
-        const compiled = compileFilterTree(params.filterTree, {
-          isAllowed,
-          onDisallowed: (field) =>
-            log.warn(`Ignoring filterTree condition on disallowed field "${field}" for entity "${entity}"`),
-        });
-        if (compiled) {
-          where.AND = [...(Array.isArray(where.AND) ? where.AND : where.AND ? [where.AND] : []), compiled];
-        }
-      }
-
-      const orderBy: any = {};
-      const applySort = (field: string, direction: any) => {
-        if (field.includes(".")) {
-          const parts = field.split(".");
-          const leaf = parts.pop()!;
-          let t = orderBy;
-          for (const p of parts) { t[p] = t[p] || {}; t = t[p]; }
-          t[leaf] = direction;
-        } else orderBy[field] = direction;
-      };
-      if (sort && isAllowed(sort.field)) applySort(sort.field, sort.direction);
-      else if (config.defaultSort) applySort(config.defaultSort.field, config.defaultSort.direction);
-      else if (config.fields.some((f) => f.name === "createdAt")) orderBy.createdAt = "desc";
-      else orderBy[config.idField || "id"] = "desc";
-
-      const include: any = {};
-      if (config.include?.length) config.include.forEach((inc) => (include[inc] = true));
-      const includeOption = Object.keys(include).length ? { include } : {};
+      
+      const {
+        where,
+        orderBy,
+        includeOption,
+        skip,
+        take,
+        safePage,
+        safePageSize,
+      } = buildListQuery({
+        entity,
+        config,
+        params,
+        scopeWhere: deps.scopeWhere?.(entity, config) as Record<string, unknown> | undefined,
+        onDisallowedFilter: (field) => log.warn(`Ignoring filter on disallowed field "${field}" for entity "${entity}"`),
+      });
 
       try {
         const [total, data] = await Promise.all([
@@ -324,13 +189,15 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
     async create(entity, data, config, tx) {
       const prismaModel = model(entity, tx ?? prisma);
       try {
-        let filtered = config ? filterValidFields(data, config) : data;
-        if (config) filtered = castFieldValues(filtered, config);
-        if (!filtered.id) filtered.id = crypto.randomUUID();
-        if (deps.touchUpdatedAtOnCreate && !filtered.updatedAt) {
-          filtered.updatedAt = new Date();
-        }
-        const prismaData = transformRelationFields(filtered, "create");
+        const prismaData = prepareMutationData({
+          data,
+          config,
+          mode: "create",
+          systemFields,
+          relationFieldSkip: deps.relationFieldSkip,
+          logger: log,
+          touchUpdatedAtOnCreate: deps.touchUpdatedAtOnCreate,
+        });
         return serializeDecimalFields(await prismaModel.create({ data: prismaData }));
       } catch (error) {
         log.error(`Error creating ${entity}:`, error);
@@ -341,9 +208,14 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
     async update(entity, id, data, config, tx) {
       const prismaModel = model(entity, tx ?? prisma);
       try {
-        let filtered = config ? filterValidFields(data, config) : data;
-        if (config) filtered = castFieldValues(filtered, config);
-        const prismaData = transformRelationFields(filtered, "update");
+        const prismaData = prepareMutationData({
+          data,
+          config,
+          mode: "update",
+          systemFields,
+          relationFieldSkip: deps.relationFieldSkip,
+          logger: log,
+        });
         return serializeDecimalFields(await prismaModel.update({ where: { id }, data: prismaData }));
       } catch (error) {
         log.error(`Error updating ${entity}:`, error);

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"]