@goplusvn/core 0.1.58 → 0.1.60

package/src/branch-scope/guard.ts

@@ -0,0 +1,100 @@
+import { resolveAmbientBranchScope } from "./context";
+import { scopedBranchWhere } from "./scope";
+
+import type { BranchScope } from "./types";
+
+/**
+ * LỚP 2 — lưới an toàn ở tầng ORM (mô hình Odoo/NocoBase): route mới quên lọc
+ * chi nhánh thì vẫn không lộ dữ liệu.
+ *
+ * Chỉ chạm thao tác ĐỌC, chỉ trên model được khai, và chỉ khi có
+ * BranchScopeContext — ngoài context (RSC page, cron, webhook, script) extension
+ * bất động, nên tác vụ nền không bị cắt dữ liệu bất ngờ.
+ *
+ *   db.$extends(createBranchGuardExtension({
+ *     models: ["Receipt", "Expense", "CashCount"],
+ *     // model không có cột branchId thì khai đường đi riêng:
+ *     buildWhere: (model, scope) =>
+ *       model === "GoodsReceipt" ? scopedBranchWhere(scope, "warehouse") : null,
+ *   }))
+ *
+ * CẢNH BÁO: model đưa vào `models` PHẢI có cột branchId, hoặc phải có nhánh
+ * riêng trong `buildWhere`. Chèn điều kiện lên cột không tồn tại là Prisma ném
+ * validation error cho MỌI thao tác đọc của user bị scope — nghĩa là hỏng cả
+ * nghiệp vụ, không chỉ hỏng bộ lọc.
+ */
+
+export interface BranchGuardOptions {
+  /** Tên model Prisma (đúng chữ hoa/thường như trong schema). */
+  models: string[];
+  /**
+   * Điều kiện guard riêng theo model; trả `null` để dùng mặc định (cột
+   * branchId trực tiếp + cho phép null = dùng chung).
+   */
+  buildWhere?: (
+    model: string,
+    scope: BranchScope,
+  ) => Record<string, unknown> | null;
+  /** Mặc định: các thao tác đọc nhiều dòng. */
+  operations?: string[];
+}
+
+/**
+ * findUnique* cố ý không guard: `where` của nó chỉ nhận unique field, chèn thêm
+ * điều kiện là Prisma từ chối. Trang chi tiết guard bằng `canAccessBranch`.
+ * Mutation cũng không guard — create ghi vào chi nhánh của user, update/delete
+ * đi qua kiểm tra quyền riêng.
+ */
+const DEFAULT_OPERATIONS = [
+  "findMany",
+  "findFirst",
+  "findFirstOrThrow",
+  "count",
+  "aggregate",
+  "groupBy",
+];
+
+export function createBranchGuardExtension(options: BranchGuardOptions) {
+  const models = new Set(options.models);
+  const operations = new Set(options.operations ?? DEFAULT_OPERATIONS);
+  const buildWhere = options.buildWhere;
+
+  return {
+    name: "branch-guard",
+    query: {
+      $allModels: {
+        // Chữ ký thật do Prisma sinh theo schema của từng app; khai chặt ở core
+        // sẽ không assignable ở phía app (kiểu hẹp hơn, contravariance).
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        async $allOperations({
+          model,
+          operation,
+          args,
+          query,
+        }: {
+          model?: string;
+          operation: string;
+          args: any;
+          query: (args: any) => Promise<any>;
+        }): Promise<any> {
+          if (!model || !models.has(model)) return query(args);
+          if (!operations.has(operation)) return query(args);
+
+          const scopePromise = resolveAmbientBranchScope();
+          if (!scopePromise) return query(args);
+
+          const scope = await scopePromise;
+          if (scope.canViewAll) return query(args);
+
+          const guard = buildWhere?.(model, scope) ?? scopedBranchWhere(scope);
+          const prevWhere = args?.where;
+          return query({
+            ...args,
+            where: prevWhere ? { AND: [prevWhere, guard] } : guard,
+          });
+        },
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+      },
+    },
+  };
+}

package/src/branch-scope/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Phạm vi dữ liệu theo chi nhánh — hai lớp:
+ *
+ *   Lớp 1 (tường minh): `getBranchScope(session)` + `scopedBranchWhere(scope)`
+ *   trong page/route/service. Đây mới là lớp làm việc chính.
+ *
+ *   Lớp 2 (lưới an toàn): `createBranchGuardExtension` cắm vào Prisma, tự AND
+ *   điều kiện chi nhánh cho thao tác đọc trên model được khai — cứu chỗ quên.
+ *
+ * App cấu hình một lần ở composition root và import phạm vi qua đúng file đó
+ * (`src/lib/branch-scope.ts`), giống kho tập tin: engine là singleton, import
+ * thẳng từ core sẽ lấy được hàm nhưng bỏ lỡ lời gọi cấu hình.
+ */
+export {
+  configureBranchScope,
+  canViewAllBranches,
+  getBranchScope,
+  canAccessBranch,
+  scopedBranchWhere,
+  clampBranchFilter,
+  clampIdFilter,
+} from "./scope";
+
+export {
+  runWithBranchScope,
+  getBranchScopeContext,
+  resolveAmbientBranchScope,
+  runWithoutBranchScope,
+  type BranchScopeContext,
+} from "./context";
+
+export {
+  createBranchGuardExtension,
+  type BranchGuardOptions,
+} from "./guard";
+
+export {
+  NO_BRANCH_ACCESS,
+  type BranchScope,
+  type BranchScopeConfig,
+  type BranchScopeDb,
+} from "./types";

package/src/branch-scope/scope.ts

@@ -0,0 +1,149 @@
+import {
+  NO_BRANCH_ACCESS,
+  type BranchScope,
+  type BranchScopeConfig,
+} from "./types";
+
+/**
+ * LỚP 1 — lọc tường minh. Page/route/service gọi `getBranchScope(session)` rồi
+ * nhét `scopedBranchWhere(scope)` vào `where`. Lớp 2 (branch-guard extension)
+ * là lưới an toàn cho chỗ quên, KHÔNG phải thay thế lớp này: guard chỉ chạm các
+ * model được khai và chỉ trong request đi qua apiHandler.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let configured: BranchScopeConfig<any> | null = null;
+
+export function configureBranchScope<TSession>(
+  config: BranchScopeConfig<TSession>,
+): void {
+  configured = config;
+}
+
+function requireConfigured() {
+  if (!configured) {
+    throw new Error(
+      "[branch-scope] chưa configureBranchScope(...) — gọi một lần ở composition root (src/lib/branch-scope.ts) rồi import phạm vi qua đúng file đó.",
+    );
+  }
+  return configured;
+}
+
+export function canViewAllBranches<TSession>(session: TSession): boolean {
+  return requireConfigured().canViewAll(session);
+}
+
+/**
+ * Phạm vi chi nhánh của user. Chưa được gán chi nhánh nào → sentinel, tức thấy
+ * 0 dòng — KHÔNG phải "thấy tất": mặc định an toàn là không thấy gì.
+ */
+export async function getBranchScope<TSession>(
+  session: TSession,
+): Promise<BranchScope> {
+  const config = requireConfigured();
+  if (config.canViewAll(session)) return { canViewAll: true };
+
+  const branchIds = await readAllowedBranchIds(config, session);
+
+  return {
+    canViewAll: false,
+    allowedBranchIds: branchIds.length > 0 ? branchIds : [NO_BRANCH_ACCESS],
+  };
+}
+
+async function readAllowedBranchIds<TSession>(
+  config: BranchScopeConfig<TSession>,
+  session: TSession,
+): Promise<string[]> {
+  if (config.getAllowedBranchIds) {
+    const ids = await config.getAllowedBranchIds(session);
+    return (ids ?? []).filter((id): id is string => Boolean(id));
+  }
+
+  const userId = config.getUserId(session);
+  if (!userId) return [];
+
+  if (!config.db) {
+    throw new Error(
+      "[branch-scope] configureBranchScope cần `db` (hoặc `getAllowedBranchIds`) để biết user thuộc chi nhánh nào.",
+    );
+  }
+  const rows = await config.db.userBranch.findMany({
+    where: { userId },
+    select: { branchId: true },
+  });
+  return rows
+    .map((row) => (row as { branchId?: string | null }).branchId)
+    .filter((id): id is string => Boolean(id));
+}
+
+/**
+ * Guard trang chi tiết: user có được xem bản ghi thuộc chi nhánh này không?
+ * Bản ghi không gắn chi nhánh (null — dữ liệu cũ hoặc dùng chung) thì ai vào
+ * được trang đều xem được.
+ */
+export function canAccessBranch(
+  scope: BranchScope,
+  branchId: string | null | undefined,
+): boolean {
+  if (scope.canViewAll) return true;
+  if (!branchId) return true;
+  return scope.allowedBranchIds!.includes(branchId);
+}
+
+/**
+ * Fragment `where` cho model có cột branchId: thuộc CN được phép HOẶC chưa gắn
+ * CN. `{}` khi xem được tất — nhét thẳng vào where là xong, không cần rẽ nhánh.
+ *
+ * `field` cho model scope qua quan hệ, ví dụ kho: `scopedBranchWhere(scope,
+ * "warehouse")` → `{ OR: [{ warehouse: { branchId: { in } } }, { warehouse: {
+ * branchId: null } }] }`.
+ */
+export function scopedBranchWhere(
+  scope: BranchScope,
+  relation?: string,
+): Record<string, unknown> {
+  if (scope.canViewAll) return {};
+  const ids = scope.allowedBranchIds!;
+  const inClause = { branchId: { in: ids } };
+  const nullClause = { branchId: null };
+  return relation
+    ? { OR: [{ [relation]: inClause }, { [relation]: nullClause }] }
+    : { OR: [inClause, nullClause] };
+}
+
+/**
+ * Kẹp bộ lọc chi nhánh client gửi lên vào trong phạm vi được phép. `undefined`
+ * = client không lọc gì (phạm vi đã do allowedBranchIds lo). Chọn toàn CN ngoài
+ * phạm vi → sentinel: thấy 0 dòng, chứ KHÔNG rơi về "không lọc".
+ */
+export function clampBranchFilter(
+  requested: string[] | string | null | undefined,
+  scope: BranchScope,
+): string[] | undefined {
+  const ids = normalizeIds(requested);
+  if (ids.length === 0) return undefined;
+  if (scope.canViewAll) return ids;
+  const valid = ids.filter((id) => scope.allowedBranchIds!.includes(id));
+  return valid.length > 0 ? valid : [NO_BRANCH_ACCESS];
+}
+
+/**
+ * Kẹp danh sách id client chọn vào danh sách được phép — dùng cho thực thể đi
+ * theo chi nhánh (kho, quầy, điểm bán). Ngoài danh sách → sentinel.
+ */
+export function clampIdFilter(
+  requested: string[] | string | null | undefined,
+  allowedIds: string[],
+): string[] {
+  const valid = normalizeIds(requested).filter((id) => allowedIds.includes(id));
+  return valid.length > 0 ? valid : [NO_BRANCH_ACCESS];
+}
+
+function normalizeIds(
+  requested: string[] | string | null | undefined,
+): string[] {
+  return (Array.isArray(requested) ? requested : [requested]).filter(
+    (id): id is string => Boolean(id && id.trim()),
+  );
+}

package/src/branch-scope/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Phạm vi dữ liệu theo chi nhánh — hợp đồng chung.
+ *
+ * Bài toán: app nhiều chi nhánh thì "danh sách phiếu thu" của kế toán CN A phải
+ * KHÁC của CN B, còn giám đốc thì thấy tất. Lọc bằng tay ở từng route là cách
+ * chắc chắn sẽ rò: chỉ cần một route mới quên `where branchId`.
+ */
+
+/**
+ * Sentinel cho "user chưa được gán chi nhánh nào" và "client lọc toàn chi nhánh
+ * ngoài phạm vi". Là một chuỗi KHÔNG BAO GIỜ khớp branchId thật, nên
+ * `branchId: { in: [NO_BRANCH_ACCESS] }` trả 0 dòng. Không dùng mảng rỗng: Prisma
+ * hiểu `in: []` là "không có gì khớp" ở vài chỗ nhưng `undefined`/bỏ mệnh đề ở
+ * chỗ khác — nhầm một lần là lộ toàn bộ dữ liệu.
+ */
+export const NO_BRANCH_ACCESS = "__NO_ACCESS__";
+
+export interface BranchScope {
+  canViewAll: boolean;
+  /** undefined khi canViewAll — ngược lại LUÔN ≥1 phần tử (sentinel nếu user chưa gán CN). */
+  allowedBranchIds?: string[];
+}
+
+/** Chỉ cần đúng phần delegate `user_branches` mà scope dùng tới. */
+export interface BranchScopeDb {
+  userBranch: {
+    findMany: (args: {
+      where: { userId: string };
+      select: { branchId: true };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }) => Promise<any[]>;
+  };
+}
+
+export interface BranchScopeConfig<TSession = unknown> {
+  /**
+   * Nguồn mặc định của phạm vi: bảng `user_branches`. Bỏ trống được NẾU đã khai
+   * `getAllowedBranchIds`.
+   */
+  db?: BranchScopeDb;
+  /**
+   * Session đã mang sẵn danh sách chi nhánh (app nhồi vào lúc đăng nhập) thì
+   * khai ở đây — khỏi phải truy vấn user_branches mỗi lần cần phạm vi. Trả mảng
+   * rỗng/null = user chưa được gán chi nhánh nào (→ sentinel, thấy 0 dòng).
+   */
+  getAllowedBranchIds?: (
+    session: TSession,
+  ) => string[] | null | undefined | Promise<string[] | null | undefined>;
+  /** Lấy id user từ session của app. */
+  getUserId: (session: TSession) => string | null | undefined;
+  /**
+   * "Xem mọi chi nhánh" — app tự quyết: vai trò quản trị, hoặc quyền
+   * `view-all-branches` trên resource nào đó. Trả true thì scope bỏ qua luôn
+   * truy vấn user_branches.
+   */
+  canViewAll: (session: TSession) => boolean;
+}

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