@goplusvn/core 0.1.87 → 0.1.89

package/src/cron/cron-schedule.ts

@@ -23,7 +23,11 @@ export interface CronFields {
   dowIsWildcard: boolean;
 }
 
-function parseField(field: string, min: number, max: number): Set<number> | null {
+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+)$/);
@@ -79,46 +83,135 @@ export function parseCronExpression(expr: string): CronFields | null {
   };
 }
 
-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;
+/** Các thành phần lịch của một mốc thời gian, ĐỌC THEO MÚI GIỜ chỉ định. */
+export interface ZonedParts {
+  minute: number;
+  hour: number;
+  dayOfMonth: number;
+  month: number;
+  dayOfWeek: number;
+}
+
+const DOW_INDEX: Record<string, number> = {
+  Sun: 0,
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6,
+};
 
-  const domMatch = fields.dayOfMonth.has(date.getDate());
-  const dowMatch = fields.dayOfWeek.has(date.getDay());
+/**
+ * Đọc mốc thời gian theo `timeZone` (bỏ trống = giờ địa phương của tiến trình).
+ *
+ * Vì sao cần: container goerp khai `TZ=Asia/Ho_Chi_Minh`, nhưng CHỈ CẦN một
+ * container cũ còn sống với TZ mặc định UTC là job "30 22 * * *" nổ lúc 05:30
+ * sáng VN — đã xảy ra thật và chốt nhầm "không đi làm" cho cả nhà máy. Khai
+ * `timezone` cho job thì lịch bám múi giờ NGHIỆP VỤ, không bám cấu hình máy.
+ */
+export function zonedParts(date: Date, timeZone?: string): ZonedParts {
+  if (!timeZone) {
+    return {
+      minute: date.getMinutes(),
+      hour: date.getHours(),
+      dayOfMonth: date.getDate(),
+      month: date.getMonth() + 1,
+      dayOfWeek: date.getDay(),
+    };
+  }
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    weekday: "short",
+  }).formatToParts(date);
+  const get = (type: string) =>
+    parts.find((p) => p.type === type)?.value ?? "0";
+  return {
+    minute: Number(get("minute")),
+    hour: Number(get("hour")),
+    dayOfMonth: Number(get("day")),
+    month: Number(get("month")),
+    dayOfWeek: DOW_INDEX[get("weekday")] ?? 0,
+  };
+}
+
+export function cronMatches(
+  fields: CronFields,
+  date: Date,
+  timeZone?: string,
+): boolean {
+  const at = zonedParts(date, timeZone);
+  if (!fields.minute.has(at.minute)) return false;
+  if (!fields.hour.has(at.hour)) return false;
+  if (!fields.month.has(at.month)) return false;
+
+  const domMatch = fields.dayOfMonth.has(at.dayOfMonth);
+  const dowMatch = fields.dayOfWeek.has(at.dayOfWeek);
   // 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;
+  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).
+ * `timeZone` bỏ trống = giờ địa phương của tiến trình (hành vi cũ).
  */
-export function nextCronDate(fields: CronFields, from = new Date()): Date | null {
+export function nextCronDate(
+  fields: CronFields,
+  from = new Date(),
+  timeZone?: string,
+): 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;
+    if (cronMatches(fields, cursor, timeZone)) 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)) {
+    //
+    // Có `timeZone` thì KHÔNG dùng setMonth/setHours (chúng đặt theo giờ máy,
+    // không phải giờ nghiệp vụ) — nhảy bằng cách CỘNG số phút còn lại tới
+    // biên giờ/ngày ĐỌC THEO múi giờ đó. Sai lệch do DST cùng lắm làm vòng
+    // lặp chạy thêm vài nhịp phút, không làm sai kết quả.
+    const at = zonedParts(cursor, timeZone);
+    const dayOk =
+      !fields.domIsWildcard && !fields.dowIsWildcard
+        ? fields.dayOfMonth.has(at.dayOfMonth) ||
+          fields.dayOfWeek.has(at.dayOfWeek)
+        : fields.dayOfMonth.has(at.dayOfMonth) &&
+          fields.dayOfWeek.has(at.dayOfWeek);
+
+    if (timeZone) {
+      if (!fields.month.has(at.month) || !dayOk) {
+        // Sang đầu ngày kế tiếp theo múi giờ nghiệp vụ.
+        cursor.setMinutes(
+          cursor.getMinutes() + (24 * 60 - (at.hour * 60 + at.minute)),
+        );
+      } else if (!fields.hour.has(at.hour)) {
+        cursor.setMinutes(cursor.getMinutes() + (60 - at.minute));
+      } else {
+        cursor.setMinutes(cursor.getMinutes() + 1);
+      }
+      continue;
+    }
+
+    if (!fields.month.has(at.month)) {
       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()))
-      )
-    ) {
+    } else if (!(fields.domIsWildcard && fields.dowIsWildcard) && !dayOk) {
       cursor.setDate(cursor.getDate() + 1);
       cursor.setHours(0, 0, 0, 0);
-    } else if (!fields.hour.has(cursor.getHours())) {
+    } else if (!fields.hour.has(at.hour)) {
       cursor.setHours(cursor.getHours() + 1, 0, 0, 0);
     } else {
       cursor.setMinutes(cursor.getMinutes() + 1);

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

@@ -1,10 +1,6 @@
 import { SimpleCronJob } from "./simple-cron-job";
 
-import type {
-  CronJob,
-  CronJobManager,
-  CronJobOptions,
-} from "./types";
+import type { CronJob, CronJobManager, CronJobOptions } from "./types";
 
 /**
  * Cron CÓ TRẠNG THÁI TRONG DB — engine dùng chung mọi app goerp (bảng
@@ -51,6 +47,12 @@ export interface CronDb {
   systemJob?: {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     count(args?: any): Promise<number>;
+    /**
+     * Optional: có thì bật GIÀNH LƯỢT CHẠY (một tiến trình / một nhịp). Thiếu
+     * thì manager chạy như cũ — app cũ không vỡ.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    updateMany?(args: any): Promise<{ count: number }>;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     findUnique(args: any): Promise<any>;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -110,12 +112,41 @@ export function getJobExecutionContext(): JobExecutionContext | null {
   return currentExecutionContext;
 }
 
+/**
+ * GIÀNH LƯỢT CHẠY — chặn job chạy nhiều lần cùng một nhịp.
+ *
+ * Cron ở đây là timer TRONG TIẾN TRÌNH: mỗi tiến trình boot lên là tự đăng ký
+ * đủ bộ job. Hai container (hoặc `next dev` chạy song song bản deploy, hoặc
+ * một container cũ chưa bị gỡ) ⇒ MỌI job chạy hai lần mỗi nhịp. Đã gây hậu
+ * quả thật trên prod: hai dòng `job_execution_logs` cho mỗi nhịp, và job chốt
+ * ngày chạy lượt thứ hai ghi đè dữ liệu của lượt đầu.
+ *
+ * Cách chốt: trước khi chạy, mỗi tiến trình cố CẬP NHẬT CÓ ĐIỀU KIỆN dòng
+ * `system_jobs` — chỉ ăn khi `lastRun` còn cũ hơn nhịp hiện tại. Postgres bảo
+ * đảm một câu UPDATE có điều kiện là nguyên tử, nên đúng MỘT tiến trình nhận
+ * được `count = 1`; các tiến trình khác thấy 0 và bỏ nhịp. Không cần bảng
+ * khoá riêng, không cần leader election.
+ *
+ * Tắt bằng `GOERP_CRON_SINGLE_RUNNER=off` (chạy nhiều node CỐ Ý, hiếm).
+ *
+ * LƯU Ý: cái này chống trùng theo NHỊP, không sửa được tiến trình chạy SAI
+ * MÚI GIỜ — container UTC nổ job "30 22" vào một nhịp hoàn toàn khác nên vẫn
+ * giành được lượt. Vế đó do `timezone` của job lo (xem cron-schedule.ts).
+ */
+function singleRunnerEnabled(): boolean {
+  return (process.env.GOERP_CRON_SINGLE_RUNNER ?? "").toLowerCase() !== "off";
+}
+
 export class DbCronJobManager implements CronJobManager {
   private jobs = new Map<string, CronJob>();
   /** onTick GỐC của app — giữ để updateJob dựng lại job với cronTime mới. */
   private jobCallbacks = new Map<string, () => void | Promise<void>>();
-  /** onTick ĐÃ BỌC (ghi log) — "chạy ngay" phải dùng bản này để có lịch sử. */
+  /** onTick ĐÃ BỌC (ghi log) — bản cho LỊCH, có giành lượt chạy. */
   private wrappedCallbacks = new Map<string, () => void | Promise<void>>();
+  /** Bản cho nút "Chạy ngay": vẫn ghi log nhưng KHÔNG giành lượt. */
+  private manualCallbacks = new Map<string, () => void | Promise<void>>();
+  /** Múi giờ nghiệp vụ đã khai của từng job — giữ qua updateJob. */
+  private jobTimezones = new Map<string, string | undefined>();
   private isInitialized = false;
 
   async init(): Promise<void> {
@@ -146,12 +177,21 @@ export class DbCronJobManager implements CronJobManager {
   private wrapOnTick(
     name: string,
     onTick: () => void | Promise<void>,
+    /** false cho lượt chạy TAY: người bấm thì phải chạy, không giành lượt. */
+    claimTick = true,
   ): () => Promise<void> {
     return async () => {
       const { db } = requireConfig();
       const startedAt = new Date();
       let logId: string | null = null;
 
+      if (claimTick && !(await this.claimTick(name, startedAt))) {
+        log().info(
+          `Bỏ nhịp job ${name}: tiến trình khác đã nhận lượt này (single-runner)`,
+        );
+        return;
+      }
+
       if (db.jobExecutionLog) {
         try {
           const entry = await db.jobExecutionLog.create({
@@ -202,6 +242,36 @@ export class DbCronJobManager implements CronJobManager {
     };
   }
 
+  /**
+   * Nhận lượt chạy của nhịp hiện tại chưa? Xem docblock `singleRunnerEnabled`.
+   * Trả `true` (cho chạy) ở mọi trường hợp không chắc — cron là hạ tầng nền,
+   * thà chạy trùng còn hơn im lặng không chạy gì.
+   */
+  private async claimTick(name: string, startedAt: Date): Promise<boolean> {
+    if (!singleRunnerEnabled()) return true;
+    const { db } = requireConfig();
+    if (!db.systemJob?.updateMany) return true;
+
+    // Mốc nhịp = đầu phút. Hai tiến trình cùng nổ trong một phút sẽ tính ra
+    // CÙNG một mốc, nên chỉ một câu UPDATE khớp điều kiện.
+    const bucket = new Date(startedAt);
+    bucket.setSeconds(0, 0);
+
+    try {
+      const result = await db.systemJob.updateMany({
+        where: {
+          name,
+          OR: [{ lastRun: null }, { lastRun: { lt: bucket } }],
+        },
+        data: { lastRun: bucket, status: "running" },
+      });
+      return (result?.count ?? 1) > 0;
+    } catch (e) {
+      log().error(`Giành lượt chạy job ${name} lỗi — vẫn cho chạy`, e);
+      return true;
+    }
+  }
+
   private async closeExecutionLog(
     logId: string | null,
     name: string,
@@ -239,6 +309,10 @@ export class DbCronJobManager implements CronJobManager {
     this.jobCallbacks.set(options.name, options.onTick);
 
     const wrappedOnTick = this.wrapOnTick(options.name, options.onTick);
+    this.manualCallbacks.set(
+      options.name,
+      this.wrapOnTick(options.name, options.onTick, false),
+    );
     const wrappedOptions: CronJobOptions = {
       ...options,
       onTick: wrappedOnTick,
@@ -247,6 +321,7 @@ export class DbCronJobManager implements CronJobManager {
     const job = new SimpleCronJob(wrappedOptions);
     this.jobs.set(options.name, job);
     this.wrappedCallbacks.set(options.name, wrappedOnTick);
+    this.jobTimezones.set(options.name, options.timezone);
 
     // Đồng bộ DB bất đồng bộ: DB quyết định job có chạy hay không.
     void this.syncJobWithDb(wrappedOptions, job).catch((e) =>
@@ -340,6 +415,7 @@ export class DbCronJobManager implements CronJobManager {
     this.jobs.delete(name);
     this.jobCallbacks.delete(name);
     this.wrappedCallbacks.delete(name);
+    this.manualCallbacks.delete(name);
   }
 
   getJob(name: string): CronJob | undefined {
@@ -399,7 +475,8 @@ export class DbCronJobManager implements CronJobManager {
 
   /** Chạy tay (fire-and-forget) — vẫn đi qua bản BỌC nên có execution log. */
   async runJobNow(name: string): Promise<boolean> {
-    const callback = this.wrappedCallbacks.get(name);
+    const callback =
+      this.manualCallbacks.get(name) ?? this.wrappedCallbacks.get(name);
     if (!callback) return false;
     void Promise.resolve(callback()).catch((e) =>
       log().error(`Chạy tay job ${name} lỗi`, e),
@@ -442,12 +519,18 @@ export class DbCronJobManager implements CronJobManager {
       cronTime: newCronTime,
       onTick: wrappedOnTick,
       start: finalEnabled ?? false,
+      // Đổi lịch KHÔNG được làm rơi múi giờ nghiệp vụ đã khai lúc đăng ký.
+      timezone: this.jobTimezones.get(name),
     };
 
     const newJob = new SimpleCronJob(newJobOptions);
     this.jobs.set(name, newJob);
     this.jobCallbacks.set(name, originalOnTick);
     this.wrappedCallbacks.set(name, wrappedOnTick);
+    this.manualCallbacks.set(
+      name,
+      this.wrapOnTick(name, originalOnTick, false),
+    );
 
     await this.syncJobWithDb(newJobOptions, newJob, enabled);
     log().info(`Đổi lịch job ${name} → ${newCronTime}`);

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

@@ -32,11 +32,18 @@ class SimpleCronJob implements CronJob {
   /** 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;
+  /**
+   * Múi giờ NGHIỆP VỤ của lịch. Bỏ trống = giờ địa phương tiến trình (hành vi
+   * cũ). Khai ra thì "30 22 * * *" là 22:30 ở múi giờ đó, dù container đang
+   * chạy UTC — chính là cách chặn hẳn lỗi job hằng ngày nổ lệch 7 tiếng.
+   */
+  private timezone?: string;
 
   constructor(options: CronJobOptions) {
     this.name = options.name;
     this.cronTime = options.cronTime;
     this.onTick = options.onTick;
+    this.timezone = options.timezone;
 
     const simpleMatch = options.cronTime.match(/^(\d+)([smhd])$/);
     if (simpleMatch) {
@@ -73,7 +80,7 @@ class SimpleCronJob implements CronJob {
   /** 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);
+    const next = nextCronDate(this.cronFields, new Date(), this.timezone);
     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.`,
@@ -88,10 +95,13 @@ class SimpleCronJob implements CronJob {
       this.timerId = setTimeout(() => this.scheduleNextCron(), MAX_CHUNK);
       return;
     }
-    this.timerId = setTimeout(async () => {
-      await this.fire();
-      this.scheduleNextCron();
-    }, Math.max(0, delay));
+    this.timerId = setTimeout(
+      async () => {
+        await this.fire();
+        this.scheduleNextCron();
+      },
+      Math.max(0, delay),
+    );
   }
 
   start(): void {
@@ -131,7 +141,8 @@ class SimpleCronJob implements CronJob {
 
   nextDate(): Date | null {
     if (!this.running) return null;
-    if (this.cronFields) return nextCronDate(this.cronFields);
+    if (this.cronFields)
+      return nextCronDate(this.cronFields, new Date(), this.timezone);
     return new Date(Date.now() + this.intervalMs!);
   }
 }

package/src/crud/__tests__/status-boolean-display.test.tsx

@@ -0,0 +1,186 @@
+/**
+ * HỒI QUY — Ô "Trạng thái" với dữ liệu boolean.
+ *
+ * Cùng một field khai `type: "switch"` + cặp option chữ
+ * (`Hoạt động` / `Tạm ngưng`), nhưng CỘT trong DB mỗi app một kiểu:
+ *
+ *   - text     → "active" / "inactive"   (spartronics, phần lớn bảng)
+ *   - boolean  → true / false            (`is_active`, `enabled`)
+ *   - smallint → 1 / 0
+ *
+ * Trước bản này chỗ nào cũng so TUYỆT ĐỐI (`optValue === value`) và form thì
+ * so cứng `value === "active"`, nên với cột boolean:
+ *
+ *   - bảng danh sách hiện chữ "true"/"false" trong chip xám;
+ *   - `getStatusMeta(true)` ném TypeError (`true.toLowerCase is not a function`);
+ *   - hộp thoại Sửa hiện công tắc TẮT cho bản ghi đang BẬT.
+ *
+ * Bộ test này khoá cả ba đường: chuẩn hoá giá trị, chip hiển thị, và cặp
+ * bật/tắt mà công tắc form đọc/ghi.
+ */
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+import {
+  normalizeStatusValue,
+  isTruthyStatus,
+  matchesOptionValue,
+} from "../../configs/status";
+import { getStatusMeta } from "../../ui/shared/status-indicator";
+import { StatusBadge } from "../../ui/primitives/status-badge";
+import { coerceFieldValue, resolveSwitchPair } from "../lib/coerce";
+import type { FieldConfig } from "../../types";
+
+const statusField = (over: Partial<FieldConfig> = {}): FieldConfig => ({
+  name: "status",
+  label: "Trạng thái",
+  type: "switch",
+  options: [
+    { label: "Hoạt động", value: "active" },
+    { label: "Tạm ngưng", value: "inactive" },
+  ],
+  ...over,
+});
+
+describe("normalizeStatusValue — mọi biến thể về một key", () => {
+  it("boolean → active/inactive", () => {
+    expect(normalizeStatusValue(true)).toBe("active");
+    expect(normalizeStatusValue(false)).toBe("inactive");
+  });
+
+  it("số 1/0 (cột smallint, BigInt của Prisma) → active/inactive", () => {
+    expect(normalizeStatusValue(1)).toBe("active");
+    expect(normalizeStatusValue(0)).toBe("inactive");
+    expect(normalizeStatusValue(BigInt(1))).toBe("active");
+  });
+
+  it("chuỗi đi qua form/URL → active/inactive", () => {
+    for (const v of ["true", "1", "on", "yes", "ACTIVE", " Active "]) {
+      expect(normalizeStatusValue(v)).toBe("active");
+    }
+    for (const v of ["false", "0", "off", "no", "INACTIVE"]) {
+      expect(normalizeStatusValue(v)).toBe("inactive");
+    }
+  });
+
+  it("trạng thái KHÁC bật/tắt giữ nguyên key để tra bảng màu", () => {
+    expect(normalizeStatusValue("pending")).toBe("pending");
+    expect(normalizeStatusValue("Partially Paid")).toBe("partially_paid");
+  });
+
+  it("rỗng → null (không quy bừa về inactive)", () => {
+    expect(normalizeStatusValue(null)).toBeNull();
+    expect(normalizeStatusValue(undefined)).toBeNull();
+    expect(normalizeStatusValue("")).toBeNull();
+    expect(normalizeStatusValue("   ")).toBeNull();
+  });
+
+  it("isTruthyStatus dùng chung một bảng", () => {
+    expect(isTruthyStatus(true)).toBe(true);
+    expect(isTruthyStatus("active")).toBe(true);
+    expect(isTruthyStatus(0)).toBe(false);
+    expect(isTruthyStatus("pending")).toBe(false);
+  });
+});
+
+describe("matchesOptionValue — giá trị dòng khớp option đã khai", () => {
+  it("boolean khớp option chữ", () => {
+    expect(matchesOptionValue("active", true)).toBe(true);
+    expect(matchesOptionValue("inactive", false)).toBe(true);
+    expect(matchesOptionValue("active", false)).toBe(false);
+  });
+
+  it("số khớp option chuỗi và ngược lại", () => {
+    expect(matchesOptionValue("1", 1)).toBe(true);
+    expect(matchesOptionValue(1, "1")).toBe(true);
+    expect(matchesOptionValue(true, "active")).toBe(true);
+  });
+
+  it("hai giá trị lạ KHÔNG khớp bừa vì cùng chuẩn hoá ra null", () => {
+    expect(matchesOptionValue("", null)).toBe(false);
+    expect(matchesOptionValue(null, undefined)).toBe(false);
+    expect(matchesOptionValue({}, [])).toBe(false);
+  });
+});
+
+describe("getStatusMeta — nhận cả giá trị không phải chuỗi", () => {
+  it("boolean true → Hoạt động, không ném lỗi", () => {
+    expect(() => getStatusMeta(true)).not.toThrow();
+    expect(getStatusMeta(true).label).toBe("Hoạt động");
+    expect(getStatusMeta(true).badgeVariant).toBe("success");
+  });
+
+  it("boolean false → Ngừng hoạt động", () => {
+    expect(getStatusMeta(false).label).toBe("Ngừng hoạt động");
+    expect(getStatusMeta(false).badgeVariant).toBe("danger");
+  });
+
+  it("key lạ báo matched=false để nơi gọi tự quyết nhãn", () => {
+    expect(getStatusMeta("khong_co_trong_bang").matched).toBe(false);
+    expect(getStatusMeta("active").matched).toBe(true);
+  });
+});
+
+describe("StatusBadge — chip trạng thái", () => {
+  it("giá trị boolean KHÔNG được hiện ra chữ true/false", () => {
+    render(<StatusBadge status={true} />);
+    expect(screen.getByText("Hoạt động")).toBeTruthy();
+    expect(screen.queryByText("true")).toBeNull();
+  });
+
+  it("boolean false → nhãn tiếng Việt", () => {
+    render(<StatusBadge status={false} />);
+    expect(screen.getByText("Ngừng hoạt động")).toBeTruthy();
+  });
+
+  it("nhãn do nơi gọi truyền vào vẫn thắng", () => {
+    render(<StatusBadge status={true} label="Đang bật" />);
+    expect(screen.getByText("Đang bật")).toBeTruthy();
+  });
+});
+
+describe("resolveSwitchPair — cặp bật/tắt của công tắc form", () => {
+  it("có cặp option → ghi đúng giá trị cột chữ", () => {
+    expect(resolveSwitchPair(statusField())).toEqual({
+      on: "active",
+      off: "inactive",
+    });
+  });
+
+  it("không khai option → cột Boolean thật", () => {
+    expect(resolveSwitchPair(statusField({ options: undefined }))).toEqual({
+      on: true,
+      off: false,
+    });
+  });
+
+  it("khai valueType boolean → ghi true/false dù option là chữ", () => {
+    expect(resolveSwitchPair(statusField({ valueType: "boolean" }))).toEqual({
+      on: true,
+      off: false,
+    });
+  });
+
+  it("công tắc BẬT cho bản ghi boolean true dù option khai chữ", () => {
+    const { on } = resolveSwitchPair(statusField());
+    expect(matchesOptionValue(on, true)).toBe(true);
+    expect(matchesOptionValue(on, "active")).toBe(true);
+    expect(matchesOptionValue(on, false)).toBe(false);
+  });
+});
+
+describe("coerceFieldValue — lưu xuống đúng kiểu cột", () => {
+  it("valueType boolean: chuỗi 'active' của form → true", () => {
+    const f = statusField({ valueType: "boolean" });
+    expect(coerceFieldValue(f, "active")).toBe(true);
+    expect(coerceFieldValue(f, "inactive")).toBe(false);
+    expect(coerceFieldValue(f, true)).toBe(true);
+  });
+
+  it("cột chữ: boolean lọt vào vẫn ra đúng option, không thành 'true'", () => {
+    const f = statusField();
+    expect(coerceFieldValue(f, true)).toBe("active");
+    expect(coerceFieldValue(f, false)).toBe("inactive");
+    expect(coerceFieldValue(f, "active")).toBe("active");
+  });
+});

package/src/crud/components/crud-detail-dialog.tsx

@@ -31,6 +31,8 @@ import {
   isFieldVisibleInDetail,
   sortFieldsByOrder,
 } from "../lib/crud-utils";
+import { matchesOptionValue } from "../../utils";
+import { humanizeDictKey } from "../lib/translate-config";
 import { formatFieldValue } from "../lib/field-formatter";
 import { dataLoader } from "../lib/data-loader";
 
@@ -111,14 +113,23 @@ function renderFieldValue(
         />
       );
     }
+    // SO LỎNG như ở bảng: `true` phải khớp option `"active"` (cột Boolean),
+    // `1` phải khớp `"1"` (cột smallint).
     const option = field.options?.find((opt) => {
       const optValue = typeof opt === "object" ? opt.value : opt;
-      return optValue === value;
+      return matchesOptionValue(optValue, value);
     });
-    const label =
-      (typeof option === "object" ? option.label : option) ?? String(value);
     if (isEmpty) return <span className="text-muted-foreground">—</span>;
-    return <StatusBadge status={value} label={String(label)} />;
+    const rawLabel = typeof option === "object" ? option.label : option;
+    // Không khớp option nào thì ĐỪNG ép nhãn "true"/"false" — để StatusBadge
+    // tự tra nhãn tiếng Việt theo taxonomy chung.
+    const label =
+      typeof rawLabel === "string" && rawLabel !== ""
+        ? rawLabel.startsWith("crud.")
+          ? humanizeDictKey(rawLabel)
+          : rawLabel
+        : undefined;
+    return <StatusBadge status={value} label={label} />;
   }
 
   if (isEmpty) {
@@ -138,7 +149,11 @@ function renderFieldValue(
       return (
         <div className="flex flex-wrap gap-1">
           {labels.map((l, i) => (
-            <Badge key={`${l}-${i}`} variant="secondary" className="font-normal">
+            <Badge
+              key={`${l}-${i}`}
+              variant="secondary"
+              className="font-normal"
+            >
               {l}
             </Badge>
           ))}
@@ -193,9 +208,7 @@ function renderFieldValue(
       field.type === "json" && typeof value === "object"
         ? JSON.stringify(value, null, 2)
         : formatFieldValue(value, field) || String(value);
-    return (
-      <span className="whitespace-pre-wrap break-words">{text}</span>
-    );
+    return <span className="whitespace-pre-wrap break-words">{text}</span>;
   }
 
   return formatFieldValue(value, field) || String(value);