@goplusvn/core 0.1.53 → 0.1.54

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

@@ -0,0 +1,459 @@
+import { SimpleCronJob } from "../infrastructure/cron/cron-manager";
+
+import type {
+  CronJob,
+  CronJobManager,
+  CronJobOptions,
+} from "../infrastructure/cron/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à
+ * 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:
+ *  - `SimpleCronJob` (infrastructure): bấm giờ setInterval thuần.
+ *  - lớp này: DB là NGUỒN SỰ THẬT của cờ enabled + cronTime, bọc mỗi lần chạy
+ *    thành 1 row `job_execution_logs` (running → success|failed, kèm actions
+ *    do job tự ghi qua `getJobExecutionContext().log()`).
+ *
+ * App cắm qua `configureCronManager({ db, logger? })` (cùng khuôn
+ * configureTaskRunner/configureNotificationService), rồi đăng ký job trong
+ * `instrumentation.ts`.
+ *
+ * BỀN VỚI APP CHƯA SYNC FEATURE: thiếu model systemJob/jobExecutionLog thì
+ * chạy chế độ memory-only thay vì nổ — cron là hạ tầng nền, không được làm
+ * chết boot.
+ */
+
+export interface ActionLog {
+  time: string;
+  action: string;
+  details?: string;
+}
+
+/** Ngữ cảnh của LẦN CHẠY hiện tại — job dùng để ghi diễn biến vào log. */
+export interface JobExecutionContext {
+  logId: string;
+  jobName: string;
+  startedAt: Date;
+  actions: ActionLog[];
+  log: (action: string, details?: string) => void;
+}
+
+/**
+ * Delegate Prisma tối thiểu — structural, args `any` CÓ CHỦ ĐÍCH (client
+ * Prisma sinh ra hẹp hơn structural type — bài học SettingsDb/TaskDb).
+ * Cả 2 model đều optional: app chưa `goerp-features sync` vẫn chạy được.
+ */
+export interface CronDb {
+  systemJob?: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    count(args?: any): Promise<number>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findUnique(args: any): Promise<any>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    create(args: any): Promise<any>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    update(args: any): Promise<any>;
+  };
+  jobExecutionLog?: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    create(args: any): Promise<any>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    update(args: any): Promise<any>;
+  };
+}
+
+export interface CronLogger {
+  info(message: string, meta?: unknown): void;
+  warn(message: string, meta?: unknown): void;
+  error(message: string, meta?: unknown): void;
+}
+
+interface CronConfig {
+  db: CronDb;
+  /** Bỏ trống thì dùng console (prefix [cron]). */
+  logger?: CronLogger;
+}
+
+const consoleLogger: CronLogger = {
+  info: (m, meta) => console.info(`[cron] ${m}`, meta ?? ""),
+  warn: (m, meta) => console.warn(`[cron] ${m}`, meta ?? ""),
+  error: (m, meta) => console.error(`[cron] ${m}`, meta ?? ""),
+};
+
+let config: CronConfig | null = null;
+
+export function configureCronManager(next: CronConfig): void {
+  config = next;
+}
+
+function requireConfig(): CronConfig {
+  if (!config) {
+    throw new Error(
+      "[cron] chưa configureCronManager({ db, logger? }) — gọi 1 lần lúc khởi tạo app (instrumentation).",
+    );
+  }
+  return config;
+}
+
+function log(): CronLogger {
+  return config?.logger ?? consoleLogger;
+}
+
+let currentExecutionContext: JobExecutionContext | null = null;
+
+/** Job đang chạy gọi để ghi diễn biến vào `job_execution_logs.actions`. */
+export function getJobExecutionContext(): JobExecutionContext | null {
+  return currentExecutionContext;
+}
+
+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ử. */
+  private wrappedCallbacks = new Map<string, () => void | Promise<void>>();
+  private isInitialized = false;
+
+  async init(): Promise<void> {
+    if (this.isInitialized) return;
+    try {
+      const { db } = requireConfig();
+      if (db.systemJob) {
+        const jobsCount = await db.systemJob.count();
+        log().info("DbCronJobManager initialized", { jobsCount });
+      } else {
+        log().warn(
+          "Thiếu model SystemJob (app chưa goerp-features sync system-jobs) — cron chạy memory-only",
+        );
+      }
+    } catch (error) {
+      log().error("Khởi tạo DbCronJobManager lỗi", error);
+    } finally {
+      // Đánh dấu đã init kể cả khi lỗi — tránh vòng lặp thử lại mỗi request.
+      this.isInitialized = true;
+    }
+  }
+
+  /**
+   * Bọc onTick: mở row execution log → chạy → đóng row (success/failed) và
+   * cập nhật trạng thái job. Dùng CHUNG cho addJob/updateJob/chạy-tay để
+   * mọi đường chạy đều để lại lịch sử.
+   */
+  private wrapOnTick(
+    name: string,
+    onTick: () => void | Promise<void>,
+  ): () => Promise<void> {
+    return async () => {
+      const { db } = requireConfig();
+      const startedAt = new Date();
+      let logId: string | null = null;
+
+      if (db.jobExecutionLog) {
+        try {
+          const entry = await db.jobExecutionLog.create({
+            data: { jobName: name, startedAt, status: "running", actions: [] },
+          });
+          logId = entry.id;
+        } catch (e) {
+          log().error(`Tạo execution log cho ${name} lỗi`, e);
+        }
+      }
+
+      const actions: ActionLog[] = [];
+      currentExecutionContext = {
+        logId: logId ?? "",
+        jobName: name,
+        startedAt,
+        actions,
+        log: (action, details) =>
+          actions.push({ time: new Date().toISOString(), action, details }),
+      };
+
+      await this.recordJobRun(name, "running");
+
+      try {
+        await onTick();
+        const finishedAt = new Date();
+        await this.closeExecutionLog(logId, name, {
+          finishedAt,
+          durationMs: finishedAt.getTime() - startedAt.getTime(),
+          status: "success",
+          actions,
+        });
+        await this.recordJobRun(name, "idle", finishedAt);
+      } catch (error) {
+        const finishedAt = new Date();
+        await this.closeExecutionLog(logId, name, {
+          finishedAt,
+          durationMs: finishedAt.getTime() - startedAt.getTime(),
+          status: "failed",
+          actions,
+          error: String(error),
+        });
+        await this.recordJobRun(name, "failed", undefined, String(error));
+        throw error;
+      } finally {
+        currentExecutionContext = null;
+      }
+    };
+  }
+
+  private async closeExecutionLog(
+    logId: string | null,
+    name: string,
+    result: {
+      finishedAt: Date;
+      durationMs: number;
+      status: "success" | "failed";
+      actions: ActionLog[];
+      error?: string;
+    },
+  ): Promise<void> {
+    const { db } = requireConfig();
+    if (!logId || !db.jobExecutionLog) return;
+    try {
+      await db.jobExecutionLog.update({
+        where: { id: logId },
+        data: {
+          finishedAt: result.finishedAt,
+          durationMs: result.durationMs,
+          status: result.status,
+          actions: result.actions,
+          error: result.error,
+          summary:
+            result.status === "success"
+              ? `Completed in ${result.durationMs}ms with ${result.actions.length} actions`
+              : `Failed after ${result.durationMs}ms: ${result.error}`,
+        },
+      });
+    } catch (e) {
+      log().error(`Cập nhật execution log cho ${name} lỗi`, e);
+    }
+  }
+
+  addJob(options: CronJobOptions): CronJob {
+    this.jobCallbacks.set(options.name, options.onTick);
+
+    const wrappedOnTick = this.wrapOnTick(options.name, options.onTick);
+    const wrappedOptions: CronJobOptions = {
+      ...options,
+      onTick: wrappedOnTick,
+    };
+
+    const job = new SimpleCronJob(wrappedOptions);
+    this.jobs.set(options.name, job);
+    this.wrappedCallbacks.set(options.name, wrappedOnTick);
+
+    // Đồ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) =>
+      log().error(`Đồng bộ job ${options.name} lỗi`, e),
+    );
+
+    return job;
+  }
+
+  private async syncJobWithDb(
+    options: CronJobOptions,
+    job: CronJob,
+    /** Ý chí ADMIN (updateJob truyền vào) — ghi đè cờ enabled đang có trong DB. */
+    enabledOverride?: boolean,
+  ): Promise<void> {
+    const { db } = requireConfig();
+    if (!db.systemJob) {
+      if ((enabledOverride ?? options.start ?? true) !== false) job.start();
+      return;
+    }
+
+    try {
+      let dbJob = await db.systemJob.findUnique({
+        where: { name: options.name },
+      });
+
+      if (!dbJob) {
+        dbJob = await db.systemJob.create({
+          data: {
+            name: options.name,
+            cronTime: options.cronTime,
+            enabled: enabledOverride ?? options.start ?? true,
+            status: "idle",
+          },
+        });
+      } else if (
+        enabledOverride !== undefined &&
+        dbJob.enabled !== enabledOverride
+      ) {
+        // Không ghi xuống DB thì vòng dưới sẽ đọc lại cờ cũ và bật lại job.
+        await db.systemJob.update({
+          where: { name: options.name },
+          data: { enabled: enabledOverride },
+        });
+        dbJob.enabled = enabledOverride;
+      }
+
+      // DB là nguồn sự thật: admin tắt job thì deploy mới không tự bật lại.
+      if (dbJob.enabled && !job.isRunning()) job.start();
+      else if (!dbJob.enabled && job.isRunning()) job.stop();
+
+      // Lịch trong CODE thắng khi lập trình viên đổi — ghi ngược lại DB.
+      if (dbJob.cronTime !== options.cronTime) {
+        await db.systemJob.update({
+          where: { name: options.name },
+          data: { cronTime: options.cronTime },
+        });
+      }
+    } catch (e) {
+      log().error(`Đồng bộ job ${options.name} với DB lỗi`, e);
+    }
+  }
+
+  private async recordJobRun(
+    name: string,
+    status: string,
+    lastRun?: Date,
+    error?: string,
+  ): Promise<void> {
+    const { db } = requireConfig();
+    if (!db.systemJob) return;
+    try {
+      await db.systemJob.update({
+        where: { name },
+        data: {
+          status,
+          lastRun,
+          error: error ?? null, // chạy được thì xoá lỗi cũ
+          nextRun: this.getJob(name)?.nextDate(),
+        },
+      });
+    } catch (e) {
+      log().error(`Cập nhật trạng thái job ${name} lỗi`, e);
+    }
+  }
+
+  removeJob(name: string): void {
+    const job = this.jobs.get(name);
+    if (!job) return;
+    job.stop();
+    this.jobs.delete(name);
+    this.jobCallbacks.delete(name);
+    this.wrappedCallbacks.delete(name);
+  }
+
+  getJob(name: string): CronJob | undefined {
+    return this.jobs.get(name);
+  }
+
+  getAllJobs(): CronJob[] {
+    return Array.from(this.jobs.values());
+  }
+
+  startAll(): void {
+    this.jobs.forEach((job) => {
+      if (!job.isRunning()) job.start();
+    });
+  }
+
+  stopAll(): void {
+    this.jobs.forEach((job) => job.stop());
+  }
+
+  /** Trạng thái runtime cho trang admin. */
+  getJobsInfo(): Array<{
+    name: string;
+    cronTime: string;
+    isRunning: boolean;
+    nextDate: Date | null;
+  }> {
+    return Array.from(this.jobs.values()).map((job) => ({
+      name: job.name,
+      cronTime: job.cronTime,
+      isRunning: job.isRunning(),
+      nextDate: job.nextDate(),
+    }));
+  }
+
+  async toggleJob(name: string): Promise<boolean> {
+    const job = this.jobs.get(name);
+    if (!job) return false;
+
+    const newState = !job.isRunning();
+    if (newState) job.start();
+    else job.stop();
+
+    const { db } = requireConfig();
+    if (db.systemJob) {
+      try {
+        await db.systemJob.update({
+          where: { name },
+          data: { enabled: newState },
+        });
+      } catch (e) {
+        log().error(`Ghi cờ enabled của job ${name} lỗi`, e);
+      }
+    }
+    return true;
+  }
+
+  /** 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);
+    if (!callback) return false;
+    void Promise.resolve(callback()).catch((e) =>
+      log().error(`Chạy tay job ${name} lỗi`, e),
+    );
+    return true;
+  }
+
+  /** Đổi lịch: dựng lại job từ onTick GỐC, giữ nguyên đường ghi log. */
+  async updateJob(
+    name: string,
+    newCronTime: string,
+    enabled?: boolean,
+  ): Promise<boolean> {
+    const existingJob = this.jobs.get(name);
+    const originalOnTick = this.jobCallbacks.get(name);
+    if (!existingJob || !originalOnTick) {
+      log().warn(`Job ${name} không tồn tại — bỏ qua updateJob`);
+      return false;
+    }
+
+    const wasRunning = existingJob.isRunning();
+    existingJob.stop();
+    this.jobs.delete(name);
+
+    const { db } = requireConfig();
+    let finalEnabled = enabled;
+    if (finalEnabled === undefined && db.systemJob) {
+      try {
+        const dbJob = await db.systemJob.findUnique({ where: { name } });
+        finalEnabled = dbJob?.enabled ?? wasRunning;
+      } catch (e) {
+        log().error(`Đọc trạng thái job ${name} từ DB lỗi`, e);
+        finalEnabled = wasRunning;
+      }
+    }
+
+    const wrappedOnTick = this.wrapOnTick(name, originalOnTick);
+    const newJobOptions: CronJobOptions = {
+      name,
+      cronTime: newCronTime,
+      onTick: wrappedOnTick,
+      start: finalEnabled ?? false,
+    };
+
+    const newJob = new SimpleCronJob(newJobOptions);
+    this.jobs.set(name, newJob);
+    this.jobCallbacks.set(name, originalOnTick);
+    this.wrappedCallbacks.set(name, wrappedOnTick);
+
+    await this.syncJobWithDb(newJobOptions, newJob, enabled);
+    log().info(`Đổi lịch job ${name} → ${newCronTime}`);
+    return true;
+  }
+}
+
+/** Singleton dùng chung app (đăng ký job ở instrumentation). */
+export const cronManager = new DbCronJobManager();

package/src/cron/index.ts

@@ -0,0 +1,24 @@
+export {
+  configureCronManager,
+  cronManager,
+  DbCronJobManager,
+  getJobExecutionContext,
+} from "./db-cron-manager";
+export type {
+  ActionLog,
+  CronDb,
+  CronLogger,
+  JobExecutionContext,
+} from "./db-cron-manager";
+
+// Lớp hẹn giờ thuần RAM — dùng lại khi app không cần trạng thái DB.
+export {
+  cronJobManager,
+  CronJobManagerImpl,
+  SimpleCronJob,
+} from "../infrastructure/cron/cron-manager";
+export type {
+  CronJob,
+  CronJobManager,
+  CronJobOptions,
+} from "../infrastructure/cron/types";

package/src/system/pages/__tests__/system-jobs-page.test.tsx

@@ -0,0 +1,92 @@
+/**
+ * Smoke render trang "Tác vụ định kỳ": mount thật (jsdom) với fetch giả — bắt
+ * lỗi import/hook trước khi app tiêu thụ. Trang này chỉ mở được sau đăng nhập
+ * (quyền admin) nên không kiểm được bằng cách gọi HTTP ẩn danh.
+ */
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { SystemJobsPage } from "../system-jobs-page";
+
+const JOB = {
+  name: "zns-dispatch",
+  cronTime: "* * * * *",
+  isRunning: true,
+  nextDate: null,
+  enabled: true,
+  status: "idle" as const,
+  lastRun: "2026-08-01T06:00:00.000Z",
+  nextRun: "2026-08-01T06:01:00.000Z",
+  error: null,
+  inMemory: true,
+};
+
+const LOG = {
+  id: "log1",
+  jobName: "zns-dispatch",
+  startedAt: "2026-08-01T06:00:00.000Z",
+  finishedAt: "2026-08-01T06:00:02.000Z",
+  durationMs: 2000,
+  status: "success" as const,
+  error: null,
+  summary: null,
+  actions: [{ time: "2026-08-01T06:00:01.000Z", action: "Gửi 3 tin ZNS" }],
+};
+
+function mockFetch(jobs = [JOB]) {
+  const calls: string[] = [];
+  global.fetch = vi.fn(async (input: RequestInfo | URL) => {
+    const url = String(input);
+    calls.push(url);
+    const body = url.includes("/history")
+      ? { data: [LOG], meta: { total: 1 } }
+      : { data: jobs };
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as unknown as typeof fetch;
+  return calls;
+}
+
+describe("SystemJobsPage", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("render job từ API kèm lịch chạy", async () => {
+    mockFetch();
+    render(<SystemJobsPage />);
+
+    await waitFor(() => expect(screen.getByText("zns-dispatch")).toBeDefined());
+    expect(screen.getByText("* * * * *")).toBeDefined();
+    expect(screen.getByText("Chờ")).toBeDefined();
+  });
+
+  it("bung dòng → gọi endpoint lịch sử và hiện actions của lần chạy", async () => {
+    const calls = mockFetch();
+    render(<SystemJobsPage apiUrl="/api/jobs" />);
+
+    await waitFor(() => expect(screen.getByText("zns-dispatch")).toBeDefined());
+    fireEvent.click(screen.getByText("zns-dispatch"));
+
+    await waitFor(() => expect(screen.getByText("Thành công")).toBeDefined());
+    expect(
+      calls.some((u) => u.startsWith("/api/jobs/zns-dispatch/history?")),
+    ).toBe(true);
+
+    // Bung tiếp một lần chạy mới thấy nhật ký actions.
+    fireEvent.click(screen.getByText("Thành công"));
+    expect(screen.getByText("Gửi 3 tin ZNS")).toBeDefined();
+  });
+
+  it("job chỉ-còn-trong-DB: khoá nút chạy/tạm dừng", async () => {
+    mockFetch([{ ...JOB, inMemory: false }]);
+    render(<SystemJobsPage />);
+
+    await waitFor(() => expect(screen.getByText("Chỉ lịch sử")).toBeDefined());
+    const actionButtons = screen
+      .getAllByRole("button")
+      .filter((b) => b.getAttribute("title")?.includes("Không khả dụng"));
+    expect(actionButtons).toHaveLength(2);
+    actionButtons.forEach((b) => expect(b.hasAttribute("disabled")).toBe(true));
+  });
+});