@goplusvn/core 0.1.70 → 0.1.72

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.1.71 — Bịt gap từ pilot init spartronics: cron giờ thật, đăng nhập username, proxy publicPrefixes, template hết vấp
+
+Nguồn: docs/INIT-PILOT-SPARTRONICS-GAPS.md (dựng app thật từ goerp-init 0.1.70
+trên DB thật, port domain máy chấm công — 19 gap ghi nhận, đợt này bịt nhóm
+gây vấp khi init; realtime/device-gate/provisionUsers/trang users/PWA/
+translations để các batch sau).
+
+**Core:**
+- **Cron chạy ĐÚNG GIỜ** (`cron-schedule.ts`): biểu thức 5 trường nay hẹn
+  setTimeout tới lần khớp kế tiếp theo giờ địa phương — "0 1 * * *" là 1 giờ
+  sáng thật, hết cảnh "cứ 24h kể từ boot" khiến job hằng ngày trôi giờ và app
+  phải tự chế isLocalHour(). Khoảng đơn giản ("5m", "1h") giữ ngữ nghĩa cũ.
+  `nextDate()`/next_run trong DB nay là giờ thật. 9 test mới.
+- **Logo hết 400**: bỏ default ma `/images/logos/goeat_logo.png` (di sản
+  goeat) — không cấu hình logo thì render monogram chữ cái đầu, không trỏ vào
+  file không tồn tại.
+- **`SignInForm` nhận `identifier`** ("email" | "username" | "both") +
+  `identifierLabel`/`identifierPlaceholder` — app đăng nhập bằng mã nhân viên
+  (Better Auth username plugin) không phải fork form nữa. Mật khẩu ở form đăng
+  nhập chỉ đòi khác rỗng (luật độ phức tạp là chuyện lúc ĐẶT mật khẩu — siết ở
+  đây chặn nhầm mật khẩu cũ import từ hệ khác).
+- **`createAuthProxy` thêm `publicPrefixes`** — tên chính danh cho prefix
+  công khai NGOÀI /api (route thiết bị /pub, /iclock, webhook); `publicApiPrefixes`
+  giữ nguyên làm alias. JSDoc nói rõ giới hạn cookie-presence ở Edge.
+- **Guardrail mới `auth/route-outside-api-declared`**: route.ts ngoài app/api
+  (điểm mù cũ của api-route-gated) phải khai tiền tố trong danh sách công khai
+  của proxy hoặc tự gác.
+- **GuardrailOptions nhận `readonly`** registry/navigations, NavigationGroupLike
+  bỏ index signature — app mới init hết fail type-check ngay từ đầu.
+- `goerp-init` pin `@goerp/core` theo đúng version CLI đang chạy.
+
+**Template starter-app:**
+- Trang home tự `getSession()` → redirect sign-in (proxy chỉ kiểm tra SỰ TỒN
+  TẠI cookie — cookie rác/cookie app khác cùng localhost từng xem được dashboard).
+- `advanced.cookiePrefix = tenant.id` + `getSessionCookie(req, { cookiePrefix })`
+  — mỗi app một tên cookie, hết va chạm khi dev nhiều app GoERP trên localhost.
+- `pnpm.onlyBuiltDependencies` (pnpm 10 chặn build scripts của prisma/esbuild/sharp).
+- `pnpm migration:new <ten>` — sinh migration qua shadow DB tự tạo/xoá
+  (Prisma 7.9 đã bỏ `--shadow-database-url`).
+- Favicon mặc định `src/app/icon.svg`; sửa doc drift (README goerp-features
+  status|sync thay list|add; header seed.ts hết tự mâu thuẫn thứ tự seed→rbac-sync;
+  comment bootstrap.ts ma trong lib/prisma.ts); tsconfig paths ưu tiên source
+  core trong repo (co-dev) rồi mới node_modules.
+
+
 ## 0.1.70 — In A5 ngang: khai kích thước tường minh thay từ khóa `landscape`
 
 `PrintStyles` khổ `A5-Landscape` đổi `@page size: A5 landscape` →

package/bin/goerp-init.mjs

@@ -83,6 +83,13 @@ const write = (p, content) => fs.writeFileSync(path.join(targetDir, p), content)
 // 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"));
+// Cùng bẫy đóng gói: npm pack nuốt cả thư mục `.husky` (đã kiểm chứng bằng
+// npm pack --dry-run) — ship `husky/`, trả lại dấu chấm ở đây. Hook chỉ sống
+// khi app `git init` (prepare: "husky || true" bỏ qua êm khi chưa có .git).
+const huskySrc = path.join(targetDir, "husky");
+if (fs.existsSync(huskySrc)) {
+  fs.renameSync(huskySrc, path.join(targetDir, ".husky"));
+}
 
 // "quan-ly-kho" → "Quan Ly Kho": nhãn hiển thị mặc định, chủ app sửa lại sau.
 const title = name
@@ -94,6 +101,14 @@ const title = name
 const pkg = JSON.parse(read("package.json"));
 pkg.name = name;
 pkg.version = "0.1.0";
+// Pin @goerp/core theo ĐÚNG bản CLI đang chạy — template trong repo có thể
+// ghi version cũ hơn (từng ship ^0.1.59 khi core đã 0.1.70).
+const coreVersion = JSON.parse(
+  fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"),
+).version;
+if (pkg.dependencies?.["@goerp/core"]) {
+  pkg.dependencies["@goerp/core"] = `npm:@goplusvn/core@^${coreVersion}`;
+}
 for (const key of ["dev", "start"]) {
   if (pkg.scripts?.[key]) pkg.scripts[key] = pkg.scripts[key].replace(/--port \d+/, `--port ${port}`);
 }

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.70",
+  "version": "0.1.72",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -93,6 +93,7 @@
     "./rbac/role-service": "./src/rbac/role-service.ts",
     "./rbac/resource-service": "./src/rbac/resource-service.ts",
     "./crud/pages/entity-crud-page": "./src/crud/pages/entity-crud-page.tsx",
+    "./crud/server": "./src/crud/server.ts",
     "./auth/auth-service": "./src/auth/auth-service.ts",
     "./package.json": "./package.json",
     "./providers/brand-theme": "./src/providers/brand-theme.ts",

package/src/auth/index.ts

@@ -7,7 +7,11 @@ export * from "./auth-service";
 
 // `Permission` từng được KHAI BÁO LẠI ở đây, y hệt bản trong ../types — hai
 // nguồn sự thật cho cùng một shape. Giờ chỉ còn re-export.
-export type { Permission, PermissionMap };
+// `Session` PHẢI export từ đây: đây là kiểu tham số của checkPermission/hasRole,
+// không export thì mọi app phải viết `session as Parameters<typeof
+// checkPermission>[0]` — Session của app ({ user: SessionUser }) vốn gán thẳng
+// được vào `{ user?: unknown }`, không cần cast nào cả.
+export type { Permission, PermissionMap, Session };
 
 // ============================================================================
 // Types

package/src/auth/proxy-gate.ts

@@ -14,7 +14,15 @@ import { NextResponse } from "next/server";
 import type { NextRequest } from "next/server";
 
 export interface AuthProxyOptions {
-  /** API prefixes served without a session (auth handler + public). Default: /api/auth, /api/public. */
+  /**
+   * Prefixes served WITHOUT a session — API public, webhook, và cả endpoint
+   * NGOÀI /api (thiết bị/máy móc không có cookie: /pub, /iclock…). Mỗi entry
+   * phải TỰ XÁC THỰC (allowlist serial, HMAC, token…). Được gộp với
+   * `publicApiPrefixes` (tên cũ, giữ để tương thích — nó luôn hoạt động với
+   * mọi prefix chứ không riêng /api).
+   */
+  publicPrefixes?: string[];
+  /** Tên cũ của `publicPrefixes`. Default khi cả hai vắng: /api/auth, /api/public. */
   publicApiPrefixes?: string[];
   /** Pages reachable while logged out. Default: /sign-in. */
   publicPages?: string[];
@@ -27,6 +35,13 @@ export interface AuthProxyOptions {
    * (Better Auth: `getSessionCookie` from "better-auth/cookies"; NextAuth:
    * `getToken` from "next-auth/jwt"). Default: presence of a known session
    * cookie, see SESSION_COOKIE_NAMES.
+   *
+   * ⚠ GIỚI HẠN: middleware chạy ở Edge nên đây là kiểm tra SỰ TỒN TẠI cookie,
+   * KHÔNG xác minh chữ ký/hạn — ai tự đặt cookie rác vẫn qua được lớp này.
+   * Vì vậy: (1) page server-query dữ liệu PHẢI tự gọi getSession() (xem trang
+   * home của starter-app); (2) dev nhiều app trên cùng localhost nên đặt
+   * `advanced.cookiePrefix` riêng cho từng app (Better Auth) kẻo cookie app
+   * này mở khoá proxy app kia — cookie theo HOST, không phân biệt port.
    */
   getToken?: (req: NextRequest) => Promise<unknown | null>;
 }
@@ -52,7 +67,11 @@ const SESSION_COOKIE_NAMES = [
 ];
 
 export function createAuthProxy(options: AuthProxyOptions = {}) {
-  const publicApiPrefixes = options.publicApiPrefixes ?? ["/api/auth", "/api/public"];
+  const publicApiPrefixes = [
+    ...(options.publicPrefixes ?? []),
+    ...(options.publicApiPrefixes ??
+      (options.publicPrefixes ? [] : ["/api/auth", "/api/public"])),
+  ];
   const publicPages = options.publicPages ?? ["/sign-in"];
   const signInPath = options.signInPath ?? "/sign-in";
   const homePath = options.homePath ?? "/";

package/src/configs/entities/departments.config.ts

@@ -17,6 +17,7 @@ export const departmentsConfig: EntityConfig = {
   icon: Building2,
   description: "Quản lý cơ cấu tổ chức phòng ban",
   apiEndpoint: "/api/departments",
+  modelName: "department",
   idField: "id",
   displayField: "name",
 

package/src/configs/entities/material-categories.config.ts

@@ -11,6 +11,7 @@ export const materialCategoriesConfig: EntityConfig = {
   icon: FolderTree,
   description: "Quản lý danh mục nguyên vật liệu",
   apiEndpoint: "/api/material-categories",
+  modelName: "materialCategory",
   idField: "id",
   displayField: "name",
 

package/src/cron/__tests__/cron-schedule.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  cronMatches,
+  nextCronDate,
+  parseCronExpression,
+} from "../cron-schedule";
+
+// Giờ ĐỊA PHƯƠNG của tiến trình test — dựng Date bằng constructor local cho khớp
+// ngữ nghĩa của engine (container prod set TZ=Asia/Ho_Chi_Minh).
+const at = (y: number, mo: number, d: number, h: number, mi: number) =>
+  new Date(y, mo - 1, d, h, mi, 0, 0);
+
+describe("parseCronExpression", () => {
+  it("nhận đủ *, số, danh sách, khoảng, bước", () => {
+    expect(parseCronExpression("* * * * *")).toBeTruthy();
+    expect(parseCronExpression("0 1 * * *")).toBeTruthy();
+    expect(parseCronExpression("*/15 8-17 * * 1-5")).toBeTruthy();
+    expect(parseCronExpression("0,30 6,18 1 1,7 0")).toBeTruthy();
+  });
+
+  it("từ chối biểu thức hỏng", () => {
+    expect(parseCronExpression("khong phai cron")).toBeNull();
+    expect(parseCronExpression("* * * *")).toBeNull(); // 4 trường
+    expect(parseCronExpression("60 * * * *")).toBeNull(); // phút 60
+    expect(parseCronExpression("* 24 * * *")).toBeNull(); // giờ 24
+  });
+
+  it("dow 7 = Chủ nhật (chuẩn hoá về 0)", () => {
+    const f = parseCronExpression("0 0 * * 7")!;
+    // 2026-08-09 là Chủ nhật
+    expect(cronMatches(f, at(2026, 8, 9, 0, 0))).toBe(true);
+    expect(cronMatches(f, at(2026, 8, 10, 0, 0))).toBe(false);
+  });
+});
+
+describe("nextCronDate — CHỐT gap #8: giờ thật chứ không phải interval-từ-boot", () => {
+  it('"0 1 * * *" ra ĐÚNG 01:00 hôm sau, bất kể đang là mấy giờ', () => {
+    const f = parseCronExpression("0 1 * * *")!;
+    const next = nextCronDate(f, at(2026, 8, 7, 16, 33))!;
+    expect([next.getHours(), next.getMinutes()]).toEqual([1, 0]);
+    expect(next.getDate()).toBe(8);
+  });
+
+  it('"0 * * * *" ra đầu giờ kế tiếp, không phải "60 phút nữa"', () => {
+    const f = parseCronExpression("0 * * * *")!;
+    const next = nextCronDate(f, at(2026, 8, 7, 16, 33))!;
+    expect([next.getHours(), next.getMinutes()]).toEqual([17, 0]);
+  });
+
+  it('"* * * * *" ra phút kế tiếp', () => {
+    const f = parseCronExpression("* * * * *")!;
+    const next = nextCronDate(f, at(2026, 8, 7, 16, 33))!;
+    expect([next.getHours(), next.getMinutes()]).toEqual([16, 34]);
+  });
+
+  it("khoảng giờ + step + ngày-trong-tuần", () => {
+    // 16:33 thứ Sáu → lần khớp kế của */15 trong 8-17 T2-T6 là 16:45 thứ Sáu
+    const f = parseCronExpression("*/15 8-17 * * 1-5")!;
+    expect(nextCronDate(f, at(2026, 8, 7, 16, 33))).toEqual(at(2026, 8, 7, 16, 45));
+    // 17:50 thứ Sáu → nhảy sang 08:00 thứ Hai
+    expect(nextCronDate(f, at(2026, 8, 7, 17, 50))).toEqual(at(2026, 8, 10, 8, 0));
+  });
+
+  it("POSIX dom|dow: cả hai bị giới hạn thì khớp MỘT trong hai", () => {
+    // ngày 15 HOẶC Chủ nhật
+    const f = parseCronExpression("0 0 15 * 0")!;
+    expect(nextCronDate(f, at(2026, 8, 7, 12, 0))).toEqual(at(2026, 8, 9, 0, 0)); // CN 9/8 tới trước ngày 15
+    expect(nextCronDate(f, at(2026, 8, 13, 12, 0))).toEqual(at(2026, 8, 15, 0, 0));
+  });
+
+  it("biểu thức bất khả thi (30/2) trả null thay vì treo", () => {
+    const f = parseCronExpression("0 0 30 2 *")!;
+    expect(nextCronDate(f, at(2026, 1, 1, 0, 0))).toBeNull();
+  });
+});

package/src/cron/cron-schedule.ts

@@ -0,0 +1,128 @@
+/**
+ * Bộ phân giải biểu thức cron 5 trường (phút giờ ngày tháng thứ) — KHÔNG phụ
+ * thuộc ngoài, tính theo GIỜ ĐỊA PHƯƠNG của tiến trình (container goerp set
+ * `TZ=Asia/Ho_Chi_Minh` trong Dockerfile nên "0 1 * * *" là 1 giờ sáng VN).
+ *
+ * Ra đời để thay lối cũ "quy cron về setInterval-từ-lúc-boot": job hằng ngày
+ * trên container deploy vài lần/ngày gần như không bao giờ chạy đúng giờ, mọi
+ * app phải tự chế isLocalHour() để vá. Xem SimpleCronJob.
+ *
+ * Hỗ trợ mỗi trường: `*`, số, danh sách `a,b,c`, khoảng `a-b`, bước `*\/n` và
+ * `a-b/n`. Thứ (dow): 0 hoặc 7 đều là Chủ nhật. Không hỗ trợ tên (JAN/MON).
+ * Ngữ nghĩa dom/dow theo POSIX: cả hai cùng bị giới hạn thì khớp MỘT TRONG HAI.
+ */
+
+export interface CronFields {
+  minute: Set<number>;
+  hour: Set<number>;
+  dayOfMonth: Set<number>;
+  month: Set<number>;
+  dayOfWeek: Set<number>;
+  /** Trường viết `*` (khác `*` kèm step) — cần cho ngữ nghĩa dom/dow POSIX. */
+  domIsWildcard: boolean;
+  dowIsWildcard: boolean;
+}
+
+function parseField(field: string, min: number, max: number): Set<number> | null {
+  const values = new Set<number>();
+  for (const part of field.split(",")) {
+    const stepMatch = part.match(/^(.+)\/(\d+)$/);
+    const step = stepMatch ? parseInt(stepMatch[2], 10) : 1;
+    const range = stepMatch ? stepMatch[1] : part;
+    if (step < 1) return null;
+
+    let lo: number;
+    let hi: number;
+    if (range === "*") {
+      lo = min;
+      hi = max;
+    } else if (/^\d+$/.test(range)) {
+      lo = hi = parseInt(range, 10);
+      // "5/15" nghĩa là 5,20,35,50 (bắt đầu từ 5 tới max) — chỉ khi có step.
+      if (stepMatch) hi = max;
+    } else {
+      const m = range.match(/^(\d+)-(\d+)$/);
+      if (!m) return null;
+      lo = parseInt(m[1], 10);
+      hi = parseInt(m[2], 10);
+    }
+    if (lo < min || hi > max || lo > hi) return null;
+    for (let v = lo; v <= hi; v += step) values.add(v);
+  }
+  return values.size ? values : null;
+}
+
+/** Trả null nếu không phải biểu thức cron 5 trường hợp lệ. */
+export function parseCronExpression(expr: string): CronFields | null {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return null;
+
+  const minute = parseField(parts[0], 0, 59);
+  const hour = parseField(parts[1], 0, 23);
+  const dayOfMonth = parseField(parts[2], 1, 31);
+  const month = parseField(parts[3], 1, 12);
+  // 7 = Chủ nhật (chuẩn hoá về 0 bên dưới).
+  const dayOfWeekRaw = parseField(parts[4], 0, 7);
+  if (!minute || !hour || !dayOfMonth || !month || !dayOfWeekRaw) return null;
+
+  const dayOfWeek = new Set<number>();
+  for (const d of dayOfWeekRaw) dayOfWeek.add(d === 7 ? 0 : d);
+
+  return {
+    minute,
+    hour,
+    dayOfMonth,
+    month,
+    dayOfWeek,
+    domIsWildcard: parts[2] === "*",
+    dowIsWildcard: parts[4] === "*",
+  };
+}
+
+export function cronMatches(fields: CronFields, date: Date): boolean {
+  if (!fields.minute.has(date.getMinutes())) return false;
+  if (!fields.hour.has(date.getHours())) return false;
+  if (!fields.month.has(date.getMonth() + 1)) return false;
+
+  const domMatch = fields.dayOfMonth.has(date.getDate());
+  const dowMatch = fields.dayOfWeek.has(date.getDay());
+  // POSIX: cả dom lẫn dow bị giới hạn → OR; ngược lại → AND (vế wildcard luôn đúng).
+  if (!fields.domIsWildcard && !fields.dowIsWildcard) return domMatch || dowMatch;
+  return domMatch && dowMatch;
+}
+
+/**
+ * Lần khớp KẾ TIẾP sau `from` (đầu phút, không tính chính `from`).
+ * Trả null nếu không có trong 2 năm tới (biểu thức bất khả thi, vd 30/2).
+ */
+export function nextCronDate(fields: CronFields, from = new Date()): Date | null {
+  const cursor = new Date(from.getTime());
+  cursor.setSeconds(0, 0);
+  cursor.setMinutes(cursor.getMinutes() + 1);
+
+  const LIMIT = 2 * 366 * 24 * 60; // phút
+  for (let i = 0; i < LIMIT; i++) {
+    if (cronMatches(fields, cursor)) return cursor;
+    // Nhảy nhanh: sai tháng → đầu tháng sau; sai ngày → đầu ngày sau; sai giờ
+    // → đầu giờ sau. Giảm vòng lặp từ hàng trăm nghìn xuống vài trăm.
+    if (!fields.month.has(cursor.getMonth() + 1)) {
+      cursor.setMonth(cursor.getMonth() + 1, 1);
+      cursor.setHours(0, 0, 0, 0);
+    } else if (
+      !(fields.domIsWildcard && fields.dowIsWildcard) &&
+      !(
+        (!fields.domIsWildcard && !fields.dowIsWildcard
+          ? fields.dayOfMonth.has(cursor.getDate()) || fields.dayOfWeek.has(cursor.getDay())
+          : fields.dayOfMonth.has(cursor.getDate()) && fields.dayOfWeek.has(cursor.getDay()))
+      )
+    ) {
+      cursor.setDate(cursor.getDate() + 1);
+      cursor.setHours(0, 0, 0, 0);
+    } else if (!fields.hour.has(cursor.getHours())) {
+      cursor.setHours(cursor.getHours() + 1, 0, 0, 0);
+    } else {
+      cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+  }
+  return null;
+}

package/src/cron/simple-cron-job.ts

@@ -4,111 +4,124 @@ import type {
   CronJobOptions,
 } from "./types";
 import { createLogger } from "../infrastructure/logger";
+import { nextCronDate, parseCronExpression } from "./cron-schedule";
+import type { CronFields } from "./cron-schedule";
 
 const logger = createLogger("CronJobManager");
 
 /**
- * Simple interval-based cron job (no external dependencies)
- * Supports basic cron expressions: minute, hour, day, month, weekday
+ * Hẹn giờ cron KHÔNG phụ thuộc ngoài, hai chế độ:
+ *
+ *  - Biểu thức cron 5 trường ("0 1 * * *"): hẹn `setTimeout` tới đúng lần khớp
+ *    kế tiếp theo GIỜ ĐỊA PHƯƠNG (cron-schedule.ts) — "0 1 * * *" là 1 giờ
+ *    sáng THẬT, không phải "cứ 24h kể từ lúc boot" như bản cũ. Hết một lần
+ *    chạy tự hẹn lần kế tiếp; deploy lại giữa chừng cũng không trôi giờ.
+ *  - Khoảng đơn giản ("30s", "5m", "1h", "1d"): giữ nguyên ngữ nghĩa cũ —
+ *    lặp đều tính từ lúc start.
+ *
+ * Lý do bản cũ phải thay: nó quy MỌI biểu thức cron về setInterval-từ-boot,
+ * job hằng ngày trên container deploy vài lần/ngày gần như không bao giờ chạy
+ * đúng giờ, mọi app phải tự chế isLocalHour() để vá.
  */
 class SimpleCronJob implements CronJob {
   name: string;
   cronTime: string;
   private onTick: () => void | Promise<void>;
-  private intervalId: NodeJS.Timeout | null = null;
+  private timerId: NodeJS.Timeout | null = null;
   private running = false;
-  private intervalMs: number;
+  /** Chế độ khoảng đơn giản ("5m"…); null nghĩa là chạy theo cron thật. */
+  private intervalMs: number | null = null;
+  private cronFields: CronFields | null = null;
 
   constructor(options: CronJobOptions) {
     this.name = options.name;
     this.cronTime = options.cronTime;
     this.onTick = options.onTick;
-    this.intervalMs = this.parseInterval(options.cronTime);
-
-    if (options.start) {
-      this.start();
-    }
-  }
 
-  /**
-   * Parse simple cron expressions to interval
-   * Supports:
-   * - '* * * * *' - every minute
-   * - '0 * * * *' - every hour
-   * - '0 0 * * *' - every day at midnight
-   * - Also supports simple intervals: '5m', '1h', '1d'
-   */
-  private parseInterval(cronTime: string): number {
-    // Simple interval format: 5m, 1h, 1d
-    const simpleMatch = cronTime.match(/^(\d+)([smhd])$/);
+    const simpleMatch = options.cronTime.match(/^(\d+)([smhd])$/);
     if (simpleMatch) {
       const value = parseInt(simpleMatch[1], 10);
-      const unit = simpleMatch[2];
-      switch (unit) {
-        case "s":
-          return value * 1000;
-        case "m":
-          return value * 60 * 1000;
-        case "h":
-          return value * 60 * 60 * 1000;
-        case "d":
-          return value * 24 * 60 * 60 * 1000;
+      const unitMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[
+        simpleMatch[2] as "s" | "m" | "h" | "d"
+      ];
+      this.intervalMs = value * unitMs;
+    } else {
+      this.cronFields = parseCronExpression(options.cronTime);
+      if (!this.cronFields) {
+        logger.warn(
+          `Could not parse cron expression "${options.cronTime}", defaulting to every minute`,
+        );
+        this.intervalMs = 60_000;
       }
     }
 
-    // Parse cron expression
-    const parts = cronTime.split(" ");
-    if (parts.length >= 5) {
-      const [minute, hour, dayOfMonth, ,] = parts;
-
-      // Every minute
-      if (minute === "*" && hour === "*") {
-        return 60 * 1000; // 1 minute
-      }
-
-      // Every hour (minute = 0)
-      if (minute !== "*" && hour === "*") {
-        return 60 * 60 * 1000; // 1 hour
-      }
+    if (options.start) {
+      this.start();
+    }
+  }
 
-      // Every day (minute and hour specified)
-      if (minute !== "*" && hour !== "*" && dayOfMonth === "*") {
-        return 24 * 60 * 60 * 1000; // 1 day
-      }
+  private async fire(): Promise<void> {
+    try {
+      await this.onTick();
+    } catch (error) {
+      logger.error(`Cron job "${this.name}" failed`, {
+        error: String(error),
+      });
     }
+  }
 
-    // Default: every minute
-    logger.warn(
-      `Could not parse cron expression "${cronTime}", defaulting to every minute`,
-    );
-    return 60 * 1000;
+  /** Hẹn giờ tới lần khớp cron kế tiếp; chạy xong tự hẹn tiếp. */
+  private scheduleNextCron(): void {
+    if (!this.running || !this.cronFields) return;
+    const next = nextCronDate(this.cronFields);
+    if (!next) {
+      logger.warn(
+        `Cron job "${this.name}": biểu thức "${this.cronTime}" không có lần chạy nào trong 2 năm tới — dừng.`,
+      );
+      this.running = false;
+      return;
+    }
+    // setTimeout trần ~24.8 ngày (int32 ms) — chia chặng nếu xa hơn.
+    const delay = next.getTime() - Date.now();
+    const MAX_CHUNK = 2_000_000_000;
+    if (delay > MAX_CHUNK) {
+      this.timerId = setTimeout(() => this.scheduleNextCron(), MAX_CHUNK);
+      return;
+    }
+    this.timerId = setTimeout(async () => {
+      await this.fire();
+      this.scheduleNextCron();
+    }, Math.max(0, delay));
   }
 
   start(): void {
     if (this.running) return;
+    this.running = true;
+
+    if (this.cronFields) {
+      logger.info(`Starting cron job: ${this.name}`, {
+        cronTime: this.cronTime,
+        nextRun: this.nextDate()?.toISOString(),
+      });
+      this.scheduleNextCron();
+      return;
+    }
 
     logger.info(`Starting cron job: ${this.name}`, {
       interval: `${this.intervalMs}ms`,
     });
-
-    this.running = true;
-    this.intervalId = setInterval(async () => {
-      try {
-        await this.onTick();
-      } catch (error) {
-        logger.error(`Cron job "${this.name}" failed`, {
-          error: String(error),
-        });
-      }
-    }, this.intervalMs);
+    this.timerId = setInterval(() => void this.fire(), this.intervalMs!);
   }
 
   stop(): void {
-    if (!this.running || !this.intervalId) return;
+    if (!this.running) return;
 
     logger.info(`Stopping cron job: ${this.name}`);
-    clearInterval(this.intervalId);
-    this.intervalId = null;
+    if (this.timerId) {
+      // clearTimeout/clearInterval dùng lẫn được — cùng pool timer của Node.
+      clearTimeout(this.timerId);
+      this.timerId = null;
+    }
     this.running = false;
   }
 
@@ -118,7 +131,8 @@ class SimpleCronJob implements CronJob {
 
   nextDate(): Date | null {
     if (!this.running) return null;
-    return new Date(Date.now() + this.intervalMs);
+    if (this.cronFields) return nextCronDate(this.cronFields);
+    return new Date(Date.now() + this.intervalMs!);
   }
 }
 

package/src/crud/components/crud-export-button.tsx

@@ -53,8 +53,9 @@ export function CrudExportButton({
         search: activeSearch,
       });
 
-      // Always force format to xlsx
-      const url = `${endpoint}?${queryParams}&format=xlsx`;
+      // Always force format to xlsx. Endpoint từ getEntityEndpoints có thể đã
+      // mang sẵn query params — nối bằng "&" thay vì "?" thứ hai.
+      const url = `${endpoint}${endpoint.includes("?") ? "&" : "?"}${queryParams}&format=xlsx`;
 
       const response = await fetch(url);
       if (!response.ok) {