@goplusvn/core 0.1.53 → 0.1.54

package/features/README.md

@@ -34,8 +34,12 @@ GENERATED — đừng sửa tay) và tạo thư mục migration
 - `notifications` — bảng `notifications` + `push_subscriptions` cho thông báo
   in-app NHÂN VIÊN. Runtime: `@goerp/core/notification`
   (`configureNotificationService`, seam `afterNotify` để app cắm web push/email)
-  + UI `@goerp/core/notification/ui` (chuông + hộp thư). YÊU CẦU model `User`
+  và UI `@goerp/core/notification/ui` (chuông + hộp thư). YÊU CẦU model `User`
   của app khai back-relation — xem `features/notifications/README.md`.
+- `system-jobs` — bảng `system_jobs` + `job_execution_logs` cho cron có trạng
+  thái DB. Runtime: `@goerp/core/cron` (`configureCronManager`) + trang admin
+  `system/pages/system-jobs-page` (app cung cấp API, mẫu vinhhoa
+  /api/admin/system/jobs).
 - `error-logs` — bảng `error_logs` cho hệ ghi lỗi server
   (`createErrorLogger`/`buildServerError` ở `errors/server-error`) + trang
   admin `system/pages/error-logs-page` (app cung cấp API, mẫu vinhhoa

package/features/system-jobs/README.md

@@ -0,0 +1,40 @@
+# Feature: system-jobs
+
+Bảng `system_jobs` + `job_execution_logs` cho engine `@goerp/core/cron`
+(`configureCronManager`) và trang admin
+`@goerp/core/system/pages/system-jobs-page`.
+
+Không phụ thuộc model nào của app (không FK sang `users`) — sync xong là dùng
+được ngay.
+
+## Cắm vào app
+
+```ts
+// src/lib/cron.ts (hoặc nơi khởi tạo)
+import { configureCronManager, cronManager } from "@goerp/core/cron"
+import { db } from "@/lib/prisma"
+
+configureCronManager({ db })
+export { cronManager }
+
+// instrumentation.ts — đăng ký job
+cronManager.addJob({ name: "sync-gold-price", cronTime: "5m", onTick: syncGoldPrice })
+```
+
+Trong job, ghi diễn biến để trang admin xem lại được:
+
+```ts
+import { getJobExecutionContext } from "@goerp/core/cron"
+getJobExecutionContext()?.log("Đã đồng bộ", `${n} bản ghi`)
+```
+
+## API app phải cung cấp (trang admin gọi)
+
+- `GET  <apiUrl>` → `{ data: SystemJob[] }` (gộp `cronManager.getJobsInfo()`
+  với row DB, thêm cờ `inMemory`)
+- `POST <apiUrl>` `{ name, action: "toggle" | "run" | "remove" }`
+- `GET  <apiUrl>/<name>/history?skip&take` → `{ data, meta.total }`
+
+Mẫu chuẩn: vinhhoa `src/app/api/admin/system/jobs/`. Quyền do app gác
+(`apiHandler(..., { resource, action })`) — Permission Registry của app là
+nguồn sự thật.

package/features/system-jobs/migrations/0001_init.sql

@@ -0,0 +1,47 @@
+-- goerp feature: system-jobs — bước 0001 (idempotent). 2 bảng cho engine cron
+-- có trạng thái DB (@goerp/core/cron, configureCronManager) + trang admin
+-- SystemJobsPage: cấu hình job (bật/tắt, lịch) và lịch sử từng lần chạy.
+-- Tên index/constraint giữ đúng bản Prisma sinh ra để app đã có bảng (vinhhoa)
+-- chạy lại là no-op, không đẻ index trùng.
+CREATE TABLE IF NOT EXISTS "system_jobs" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "cron_time" TEXT NOT NULL,
+    "enabled" BOOLEAN NOT NULL DEFAULT true,
+    "last_run" TIMESTAMP(3),
+    "next_run" TIMESTAMP(3),
+    "status" TEXT NOT NULL DEFAULT 'idle',
+    "error" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    "metadata" JSONB,
+
+    CONSTRAINT "system_jobs_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "system_jobs_name_key" ON "system_jobs"("name");
+
+CREATE TABLE IF NOT EXISTS "job_execution_logs" (
+    "id" TEXT NOT NULL,
+    "job_name" TEXT NOT NULL,
+    "started_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "finished_at" TIMESTAMP(3),
+    "duration_ms" INTEGER,
+    "status" TEXT NOT NULL DEFAULT 'running',
+    "error" TEXT,
+    "actions" JSONB,
+    "summary" TEXT,
+
+    CONSTRAINT "job_execution_logs_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "job_execution_logs_job_name_idx" ON "job_execution_logs"("job_name");
+CREATE INDEX IF NOT EXISTS "job_execution_logs_started_at_idx" ON "job_execution_logs"("started_at");
+
+-- FK: PG không có ADD CONSTRAINT IF NOT EXISTS → DO-block kiểm tra pg_constraint.
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'job_execution_logs_job_name_fkey') THEN
+    ALTER TABLE "job_execution_logs" ADD CONSTRAINT "job_execution_logs_job_name_fkey"
+      FOREIGN KEY ("job_name") REFERENCES "system_jobs"("name") ON DELETE CASCADE ON UPDATE CASCADE;
+  END IF;
+END $$;

package/features/system-jobs/schema.prisma

@@ -0,0 +1,42 @@
+/// Job định kỳ có TRẠNG THÁI TRONG DB (engine `@goerp/core/cron`). DB là nguồn
+/// sự thật của cờ enabled + lịch chạy: admin tắt job thì deploy mới không tự
+/// bật lại, và restart tiến trình không mất cấu hình. `name` trùng tên đăng ký
+/// trong code (`cronManager.addJob({ name })`) nên là khoá tự nhiên.
+model SystemJob {
+  id            String            @id @default(cuid()) @map("id")
+  name          String            @unique @map("name")
+  cronTime      String            @map("cron_time") // "5m" | "1h" | "0 * * * *"
+  enabled       Boolean           @default(true) @map("enabled")
+  lastRun       DateTime?         @map("last_run")
+  nextRun       DateTime?         @map("next_run")
+  status        String            @default("idle") @map("status") // idle | running | failed
+  error         String?           @map("error") // lỗi lần chạy gần nhất (xoá khi chạy lại được)
+  createdAt     DateTime          @default(now()) @map("created_at")
+  updatedAt     DateTime          @updatedAt @map("updated_at")
+  metadata      Json?             @map("metadata")
+  executionLogs JobExecutionLog[]
+
+  @@map("system_jobs")
+}
+
+/// Một LẦN chạy của job: mở row lúc bắt đầu (status=running) và đóng lúc kết
+/// thúc. `actions` là nhật ký diễn biến do chính job ghi qua
+/// `getJobExecutionContext().log()` — thứ giúp admin biết job "chạy rồi" đã
+/// làm được gì, không chỉ thành công/thất bại.
+model JobExecutionLog {
+  id         String    @id @default(cuid()) @map("id")
+  jobName    String    @map("job_name")
+  startedAt  DateTime  @default(now()) @map("started_at")
+  finishedAt DateTime? @map("finished_at")
+  durationMs Int?      @map("duration_ms")
+  status     String    @default("running") @map("status") // running | success | failed
+  error      String?   @map("error")
+  actions    Json?     @map("actions") // [{ time, action, details? }]
+  summary    String?   @map("summary")
+
+  job SystemJob @relation(fields: [jobName], references: [name], onDelete: Cascade)
+
+  @@index([jobName])
+  @@index([startedAt])
+  @@map("job_execution_logs")
+}

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.53",
+  "version": "0.1.54",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -80,6 +80,8 @@
     "./system/pages/system-settings-page": "./src/system/pages/system-settings-page.tsx",
     "./system/pages/system-category-page": "./src/system/pages/system-category-page.tsx",
     "./system/pages/error-logs-page": "./src/system/pages/error-logs-page.tsx",
+    "./system/pages/system-jobs-page": "./src/system/pages/system-jobs-page.tsx",
+    "./cron": "./src/cron/index.ts",
     "./rbac/role-service": "./src/rbac/role-service.ts",
     "./rbac/resource-service": "./src/rbac/resource-service.ts",
     "./infrastructure/cron/cron-manager": "./src/infrastructure/cron/cron-manager.ts",

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

@@ -0,0 +1,316 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  configureCronManager,
+  DbCronJobManager,
+  getJobExecutionContext,
+} from "../db-cron-manager";
+import type { CronDb } from "../db-cron-manager";
+
+interface JobRow {
+  name: string;
+  cronTime: string;
+  enabled: boolean;
+  status?: string;
+  lastRun?: Date | null;
+  nextRun?: Date | null;
+  error?: string | null;
+}
+
+interface LogRow {
+  id: string;
+  jobName: string;
+  status: string;
+  actions?: unknown;
+  durationMs?: number | null;
+  error?: string | null;
+  summary?: string | null;
+}
+
+/** Fake Prisma tối thiểu — đủ để quan sát side-effect DB của manager. */
+function makeDb(seed: JobRow[] = []) {
+  const jobs = new Map(seed.map((j) => [j.name, { ...j }]));
+  const logs: LogRow[] = [];
+  let seq = 0;
+
+  const db = {
+    systemJob: {
+      count: vi.fn(async () => jobs.size),
+      findUnique: vi.fn(
+        async ({ where }: { where: { name: string } }) =>
+          jobs.get(where.name) ?? null,
+      ),
+      create: vi.fn(async ({ data }: { data: JobRow }) => {
+        jobs.set(data.name, { ...data });
+        return jobs.get(data.name);
+      }),
+      update: vi.fn(
+        async ({
+          where,
+          data,
+        }: {
+          where: { name: string };
+          data: Partial<JobRow>;
+        }) => {
+          const row = jobs.get(where.name);
+          if (!row) throw new Error(`no job ${where.name}`);
+          Object.assign(row, data);
+          return row;
+        },
+      ),
+    },
+    jobExecutionLog: {
+      create: vi.fn(async ({ data }: { data: Omit<LogRow, "id"> }) => {
+        const row = { id: `log${++seq}`, ...data };
+        logs.push(row);
+        return row;
+      }),
+      update: vi.fn(
+        async ({
+          where,
+          data,
+        }: {
+          where: { id: string };
+          data: Partial<LogRow>;
+        }) => {
+          const row = logs.find((l) => l.id === where.id);
+          if (!row) throw new Error(`no log ${where.id}`);
+          Object.assign(row, data);
+          return row;
+        },
+      ),
+    },
+  };
+
+  return { db: db as unknown as CronDb, jobs, logs };
+}
+
+const silentLogger = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+/** Chờ các promise nền (syncJobWithDb chạy fire-and-forget trong addJob). */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+describe("DbCronJobManager — đăng ký job", () => {
+  let manager: DbCronJobManager;
+
+  beforeEach(() => {
+    manager = new DbCronJobManager();
+  });
+  afterEach(() => manager.stopAll());
+
+  it("chưa có row DB → tạo mới và chạy theo cờ start", async () => {
+    const { db, jobs } = makeDb();
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({
+      name: "sync",
+      cronTime: "5m",
+      onTick: vi.fn(),
+      start: true,
+    });
+    await flush();
+
+    expect(jobs.get("sync")).toMatchObject({ cronTime: "5m", enabled: true });
+    expect(manager.getJob("sync")?.isRunning()).toBe(true);
+  });
+
+  it("DB enabled=false THẮNG start:true — admin tắt thì deploy mới không tự bật", async () => {
+    const { db } = makeDb([{ name: "sync", cronTime: "5m", enabled: false }]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({
+      name: "sync",
+      cronTime: "5m",
+      onTick: vi.fn(),
+      start: true,
+    });
+    await flush();
+
+    expect(manager.getJob("sync")?.isRunning()).toBe(false);
+  });
+
+  it("lịch trong CODE đổi → ghi ngược lại DB", async () => {
+    const { db, jobs } = makeDb([
+      { name: "sync", cronTime: "1h", enabled: false },
+    ]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({ name: "sync", cronTime: "15m", onTick: vi.fn() });
+    await flush();
+
+    expect(jobs.get("sync")?.cronTime).toBe("15m");
+  });
+
+  it("app chưa sync feature (thiếu model) → memory-only, KHÔNG nổ", async () => {
+    configureCronManager({ db: {} as CronDb, logger: silentLogger });
+
+    manager.addJob({
+      name: "sync",
+      cronTime: "5m",
+      onTick: vi.fn(),
+      start: true,
+    });
+    await manager.init();
+    await flush();
+
+    expect(manager.getJob("sync")?.isRunning()).toBe(true);
+  });
+});
+
+describe("DbCronJobManager — lịch sử thực thi", () => {
+  let manager: DbCronJobManager;
+
+  beforeEach(() => {
+    manager = new DbCronJobManager();
+  });
+  afterEach(() => manager.stopAll());
+
+  it("chạy thành công: log running → success kèm actions của job", async () => {
+    const { db, jobs, logs } = makeDb([
+      { name: "sync", cronTime: "5m", enabled: true },
+    ]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({
+      name: "sync",
+      cronTime: "5m",
+      onTick: async () => {
+        getJobExecutionContext()?.log("Đã tải giá", "12 mã");
+      },
+    });
+    await flush();
+    await manager.runJobNow("sync");
+    await flush();
+
+    expect(logs).toHaveLength(1);
+    expect(logs[0]).toMatchObject({ jobName: "sync", status: "success" });
+    expect(logs[0].actions).toEqual([
+      expect.objectContaining({ action: "Đã tải giá", details: "12 mã" }),
+    ]);
+    expect(jobs.get("sync")).toMatchObject({ status: "idle", error: null });
+  });
+
+  it("chạy lỗi: log failed + job.status failed + giữ nguyên message", async () => {
+    const { db, jobs, logs } = makeDb([
+      { name: "sync", cronTime: "5m", enabled: true },
+    ]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({
+      name: "sync",
+      cronTime: "5m",
+      onTick: async () => {
+        throw new Error("upstream 503");
+      },
+    });
+    await flush();
+    await manager.runJobNow("sync"); // fire-and-forget: lỗi được nuốt ở đây
+    await flush();
+
+    expect(logs[0]).toMatchObject({ status: "failed" });
+    expect(String(logs[0].error)).toContain("upstream 503");
+    expect(jobs.get("sync")?.status).toBe("failed");
+    expect(String(jobs.get("sync")?.error)).toContain("upstream 503");
+  });
+
+  it("ngữ cảnh được dọn sau khi chạy — không rò sang lần sau", async () => {
+    const { db } = makeDb([{ name: "sync", cronTime: "5m", enabled: true }]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({ name: "sync", cronTime: "5m", onTick: vi.fn() });
+    await flush();
+    await manager.runJobNow("sync");
+    await flush();
+
+    expect(getJobExecutionContext()).toBeNull();
+  });
+
+  it("đổi lịch xong VẪN ghi lịch sử (bản cũ mất log sau updateJob)", async () => {
+    const { db, jobs, logs } = makeDb([
+      { name: "sync", cronTime: "5m", enabled: true },
+    ]);
+    configureCronManager({ db, logger: silentLogger });
+
+    const onTick = vi.fn();
+    manager.addJob({ name: "sync", cronTime: "5m", onTick });
+    await flush();
+
+    expect(await manager.updateJob("sync", "30m", false)).toBe(true);
+    expect(jobs.get("sync")?.cronTime).toBe("30m");
+    expect(manager.getJob("sync")?.isRunning()).toBe(false);
+
+    await manager.runJobNow("sync");
+    await flush();
+
+    expect(onTick).toHaveBeenCalledTimes(1);
+    expect(logs).toHaveLength(1);
+    expect(logs[0].status).toBe("success");
+  });
+
+  it("updateJob job lạ → false, không đụng DB", async () => {
+    const { db } = makeDb();
+    configureCronManager({ db, logger: silentLogger });
+    expect(await manager.updateJob("khong-co", "5m")).toBe(false);
+  });
+});
+
+describe("DbCronJobManager — điều khiển", () => {
+  let manager: DbCronJobManager;
+
+  beforeEach(() => {
+    manager = new DbCronJobManager();
+  });
+  afterEach(() => manager.stopAll());
+
+  it("toggleJob ghi cờ enabled xuống DB", async () => {
+    const { db, jobs } = makeDb([
+      { name: "sync", cronTime: "5m", enabled: true },
+    ]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({ name: "sync", cronTime: "5m", onTick: vi.fn() });
+    await flush();
+    expect(manager.getJob("sync")?.isRunning()).toBe(true);
+
+    await manager.toggleJob("sync");
+    expect(manager.getJob("sync")?.isRunning()).toBe(false);
+    expect(jobs.get("sync")?.enabled).toBe(false);
+  });
+
+  it("runJobNow/toggleJob với job chưa đăng ký → false", async () => {
+    const { db } = makeDb();
+    configureCronManager({ db, logger: silentLogger });
+    expect(await manager.runJobNow("khong-co")).toBe(false);
+    expect(await manager.toggleJob("khong-co")).toBe(false);
+  });
+
+  it("removeJob dừng timer và quên callback", async () => {
+    const { db } = makeDb([{ name: "sync", cronTime: "5m", enabled: true }]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({ name: "sync", cronTime: "5m", onTick: vi.fn() });
+    await flush();
+    manager.removeJob("sync");
+
+    expect(manager.getJob("sync")).toBeUndefined();
+    expect(manager.getAllJobs()).toHaveLength(0);
+    expect(await manager.runJobNow("sync")).toBe(false);
+  });
+
+  it("getJobsInfo trả trạng thái runtime cho trang admin", async () => {
+    const { db } = makeDb([{ name: "sync", cronTime: "5m", enabled: true }]);
+    configureCronManager({ db, logger: silentLogger });
+
+    manager.addJob({ name: "sync", cronTime: "5m", onTick: vi.fn() });
+    await flush();
+
+    const info = manager.getJobsInfo();
+    expect(info).toHaveLength(1);
+    expect(info[0]).toMatchObject({
+      name: "sync",
+      cronTime: "5m",
+      isRunning: true,
+    });
+    expect(info[0].nextDate).toBeInstanceOf(Date);
+  });
+});