@goplusvn/core 0.1.50 → 0.1.51

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.50",
+  "version": "0.1.51",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -43,6 +43,8 @@
     "./assets/*": "./src/assets/*",
     "./styles/*": "./src/styles/*",
     "./auth/api-handler": "./src/auth/api-handler.ts",
+    "./tasks": "./src/tasks/index.ts",
+    "./tasks/ui": "./src/tasks/ui/task-list-client.tsx",
     "./auth/proxy-gate": "./src/auth/proxy-gate.ts",
     "./rbac/route-handlers": "./src/rbac/route-handlers.ts",
     "./rbac/permissions-version": "./src/rbac/permissions-version.ts",

package/src/tasks/__tests__/task-runner.test.ts

@@ -0,0 +1,213 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  configureTaskRunner,
+  enqueueTask,
+  readTaskFile,
+  reclaimStaleTasks,
+  registerTaskHandler,
+  saveTaskFile,
+  type TaskDb,
+  type TaskNotifyInput,
+} from "../task-runner";
+
+function makeDb(overrides: Partial<Record<string, unknown>> = {}) {
+  const rows = new Map<string, Record<string, unknown>>();
+  let seq = 0;
+  const db = {
+    backgroundTask: {
+      create: vi.fn(async ({ data }: { data: Record<string, unknown> }) => {
+        const id = `t${++seq}`;
+        const row = { id, status: "pending", ...data };
+        rows.set(id, row);
+        return row;
+      }),
+      update: vi.fn(
+        async ({
+          where,
+          data,
+        }: {
+          where: { id: string };
+          data: Record<string, unknown>;
+        }) => {
+          const row = rows.get(where.id);
+          if (row) Object.assign(row, data);
+          return row;
+        },
+      ),
+      updateMany: vi.fn(
+        async ({
+          where,
+          data,
+        }: {
+          where: Record<string, unknown>;
+          data: Record<string, unknown>;
+        }) => {
+          let count = 0;
+          for (const row of rows.values()) {
+            const statusCond = where.status as
+              | string
+              | { in: string[] }
+              | undefined;
+            const statusOk =
+              statusCond === undefined ||
+              (typeof statusCond === "string"
+                ? row.status === statusCond
+                : (statusCond.in as string[]).includes(row.status as string));
+            const idOk = where.id === undefined || row.id === where.id;
+            if (statusOk && idOk) {
+              Object.assign(row, data);
+              count++;
+            }
+          }
+          return { count };
+        },
+      ),
+      findUnique: vi.fn(async ({ where }: { where: { id: string } }) => {
+        return rows.get(where.id) ?? null;
+      }),
+      ...overrides,
+    },
+    __rows: rows,
+  };
+  return db as unknown as TaskDb & { __rows: Map<string, Record<string, unknown>> };
+}
+
+const flush = () => new Promise((r) => setTimeout(r, 10));
+
+describe("task-runner", () => {
+  let notifications: TaskNotifyInput[];
+
+  beforeEach(() => {
+    notifications = [];
+  });
+
+  it("chưa configure → enqueue throw với hướng dẫn", async () => {
+    // Reset config bằng cách configure với db hợp lệ SAU test này — ở đây
+    // module có thể đã được configure bởi test khác nên chỉ chạy khi chưa có.
+    // (Thứ tự an toàn: test này đứng đầu file, config module-level còn null.)
+    await expect(
+      enqueueTask({ type: "x", title: "x", createdBy: "u1" }),
+    ).rejects.toThrow(/configureTaskRunner/);
+  });
+
+  it("enqueue → handler chạy, success + progress 100 + notify có link tải", async () => {
+    const db = makeDb();
+    configureTaskRunner({
+      db,
+      notify: async (n) => {
+        notifications.push(n);
+      },
+    });
+    registerTaskHandler("demo:ok", async ({ setProgress }) => {
+      await setProgress(50);
+      return { fileKey: "local:a.xlsx", fileName: "a.xlsx", rowCount: 3 };
+    });
+
+    const task = await enqueueTask({
+      type: "demo:ok",
+      title: "Xuất demo",
+      createdBy: "u1",
+    });
+    await flush();
+
+    const row = db.__rows.get(task.id)!;
+    expect(row.status).toBe("success");
+    expect(row.progress).toBe(100);
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].type).toBe("success");
+    expect(notifications[0].url).toBe(`/api/tasks/${task.id}/download`);
+  });
+
+  it("handler throw → status error + notify thất bại", async () => {
+    const db = makeDb();
+    configureTaskRunner({
+      db,
+      notify: async (n) => {
+        notifications.push(n);
+      },
+    });
+    registerTaskHandler("demo:boom", async () => {
+      throw new Error("nổ có chủ đích");
+    });
+
+    const task = await enqueueTask({
+      type: "demo:boom",
+      title: "Nổ",
+      createdBy: "u1",
+    });
+    await flush();
+
+    const row = db.__rows.get(task.id)!;
+    expect(row.status).toBe("error");
+    expect(row.error).toBe("nổ có chủ đích");
+    expect(notifications[0].type).toBe("error");
+  });
+
+  it("kết quả chỉ có errorFileKey (import lỗi) → notify warning + link ?file=error", async () => {
+    const db = makeDb();
+    configureTaskRunner({
+      db,
+      notify: async (n) => {
+        notifications.push(n);
+      },
+    });
+    registerTaskHandler("demo:import-err", async () => ({
+      errorFileKey: "local:loi.xlsx",
+      summary: "3 dòng lỗi",
+    }));
+
+    const task = await enqueueTask({
+      type: "demo:import-err",
+      title: "Nhập demo",
+      createdBy: "u1",
+    });
+    await flush();
+
+    expect(notifications[0].type).toBe("warning");
+    expect(notifications[0].url).toBe(
+      `/api/tasks/${task.id}/download?file=error`,
+    );
+  });
+
+  it("type chưa đăng ký → enqueue throw ngay (không tạo row)", async () => {
+    const db = makeDb();
+    configureTaskRunner({ db });
+    await expect(
+      enqueueTask({ type: "demo:missing", title: "x", createdBy: "u1" }),
+    ).rejects.toThrow(/chưa đăng ký/);
+    expect(db.__rows.size).toBe(0);
+  });
+
+  it("reclaimStaleTasks: pending/running mồ côi → error", async () => {
+    const db = makeDb();
+    configureTaskRunner({ db });
+    db.__rows.set("stale1", { id: "stale1", status: "running" });
+    db.__rows.set("stale2", { id: "stale2", status: "pending" });
+    db.__rows.set("done", { id: "done", status: "success" });
+
+    await reclaimStaleTasks();
+
+    expect(db.__rows.get("stale1")!.status).toBe("error");
+    expect(db.__rows.get("stale2")!.status).toBe("error");
+    expect(db.__rows.get("done")!.status).toBe("success");
+  });
+
+  it("storage seam: có storage thì save/read đi qua storage", async () => {
+    const store = new Map<string, Buffer>();
+    configureTaskRunner({
+      db: makeDb(),
+      storage: {
+        save: async (buf, key) => {
+          store.set(`s3:${key}`, buf);
+          return `s3:${key}`;
+        },
+        read: async (key) => store.get(key)!,
+      },
+    });
+
+    const key = await saveTaskFile(Buffer.from("abc"), "x/y.xlsx", "app/x");
+    expect(key).toBe("s3:x/y.xlsx");
+    expect((await readTaskFile(key)).toString()).toBe("abc");
+  });
+});

package/src/tasks/index.ts

@@ -0,0 +1,19 @@
+// Trung tâm tác vụ nền — engine dùng chung. Bảng đi kèm ship qua
+// `goerp-features sync` (feature background-tasks). App wiring mẫu: vinhhoa
+// src/server/tasks (configureTaskRunner + handlers + routes /api/tasks).
+export {
+  configureTaskRunner,
+  enqueueTask,
+  readTaskFile,
+  reclaimStaleTasks,
+  registerTaskHandler,
+  saveTaskFile,
+  type EnqueueInput,
+  type TaskContext,
+  type TaskDb,
+  type TaskFileResult,
+  type TaskHandler,
+  type TaskNotifyInput,
+  type TaskRecord,
+  type TaskStorage,
+} from "./task-runner";

package/src/tasks/task-runner.ts

@@ -0,0 +1,307 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+
+/**
+ * Trung tâm tác vụ nền — engine dùng chung cho mọi app goerp (bảng
+ * `background_tasks` ship qua `goerp-features sync`, feature background-tasks).
+ *
+ * Hàng đợi trong DB, worker IN-PROCESS: enqueue xong là `void runTask(id)`
+ * ngay trong container đang phục vụ request (deploy 1 container — không cần
+ * queue ngoài). Vòng đời: pending → running (CAS updateMany, chống chạy đôi)
+ * → success | error. Server restart giữa chừng → `reclaimStaleTasks()` (gọi
+ * từ instrumentation) đánh dấu error để user chạy lại.
+ *
+ * App cắm phụ thuộc qua `configureTaskRunner` (cùng khuôn
+ * `configureSettingsService`): db (Prisma client có model BackgroundTask),
+ * notify (chuông/push — tuỳ chọn), storage (S3/MinIO — tuỳ chọn, mặc định
+ * thư mục local PRIVATE, KHÔNG để trong public/).
+ */
+
+export interface TaskFileResult {
+  fileKey?: string;
+  fileName?: string;
+  contentType?: string;
+  rowCount?: number;
+  errorFileKey?: string;
+  errorFileName?: string;
+  summary?: string;
+}
+
+export interface TaskContext {
+  taskId: string;
+  params: unknown;
+  /** Cập nhật % tiến độ (0–100) — throttle sẵn, gọi thoải mái theo chunk. */
+  setProgress: (percent: number) => Promise<void>;
+}
+
+export type TaskHandler = (ctx: TaskContext) => Promise<TaskFileResult>;
+
+export interface TaskRecord {
+  id: string;
+  type: string;
+  title: string;
+  status: string;
+  params: unknown;
+  createdBy: string;
+}
+
+/**
+ * Delegate Prisma tối thiểu — structural, args nới thành `any` CÓ CHỦ ĐÍCH:
+ * client Prisma sinh ra của app có kiểu args HẸP hơn (contravariance) nên
+ * khai chặt ở đây sẽ không assignable (cùng bài học SettingsDb).
+ */
+export interface TaskDb {
+  backgroundTask: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    create(args: any): Promise<TaskRecord>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    update(args: any): Promise<unknown>;
+    // 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<TaskRecord | null>;
+  };
+}
+
+export interface TaskNotifyInput {
+  userIds: string[];
+  type: "success" | "error" | "warning" | "info";
+  category: string;
+  title: string;
+  content: string;
+  url?: string;
+  resourceType?: string;
+  resourceId?: string;
+}
+
+export interface TaskStorage {
+  /** Trả key đã lưu, hoặc `null` = "để core fallback local" (vd S3 đang tắt). */
+  save(buffer: Buffer, key: string, contentType: string): Promise<string | null>;
+  /** Chỉ được gọi cho key KHÔNG phải `local:` — key local core tự đọc. */
+  read(fileKey: string): Promise<Buffer>;
+}
+
+interface TaskRunnerConfig {
+  db: TaskDb;
+  /** Báo chuông/push khi task xong-lỗi — bỏ trống thì im lặng. */
+  notify?: (input: TaskNotifyInput) => Promise<unknown>;
+  /** Kho file kết quả — bỏ trống dùng thư mục local `localDir`. */
+  storage?: TaskStorage;
+  /** Thư mục fallback local (mặc định <cwd>/storage/task-files). */
+  localDir?: string;
+}
+
+let config: TaskRunnerConfig | null = null;
+
+export function configureTaskRunner(next: TaskRunnerConfig): void {
+  config = next;
+}
+
+function requireConfig(): TaskRunnerConfig {
+  if (!config) {
+    throw new Error(
+      "[tasks] chưa configureTaskRunner({ db, notify?, storage? }) — gọi 1 lần lúc khởi tạo app (cạnh configureSettingsService).",
+    );
+  }
+  return config;
+}
+
+const registry = new Map<string, TaskHandler>();
+
+export function registerTaskHandler(type: string, handler: TaskHandler): void {
+  registry.set(type, handler);
+}
+
+export interface EnqueueInput {
+  type: string;
+  title: string;
+  params?: unknown;
+  createdBy: string;
+  branchId?: string | null;
+}
+
+/**
+ * Tạo task + chạy ngay trong process (fire-and-forget). AUTHORIZE TRƯỚC KHI
+ * GỌI: worker chạy ngoài request nên không còn session — mọi giới hạn quyền
+ * (scope chi nhánh, quyền xem giá vốn…) phải được snapshot vào `params`.
+ */
+export async function enqueueTask(input: EnqueueInput): Promise<TaskRecord> {
+  const { db } = requireConfig();
+  if (!registry.has(input.type)) {
+    throw new Error(`[tasks] type "${input.type}" chưa đăng ký handler`);
+  }
+  const task = await db.backgroundTask.create({
+    data: {
+      type: input.type,
+      title: input.title,
+      params: input.params ?? undefined,
+      createdBy: input.createdBy,
+      branchId: input.branchId ?? null,
+    },
+  });
+  void runTask(task.id);
+  return task;
+}
+
+async function runTask(id: string): Promise<void> {
+  const { db } = requireConfig();
+  // CAS pending→running: chỉ một luồng thắng (chống double-run khi retry).
+  const claimed = await db.backgroundTask.updateMany({
+    where: { id, status: "pending" },
+    data: { status: "running", startedAt: new Date() },
+  });
+  if (claimed.count === 0) return;
+
+  const task = await db.backgroundTask.findUnique({ where: { id } });
+  if (!task) return;
+  const handler = registry.get(task.type);
+
+  try {
+    if (!handler) {
+      throw new Error(`[tasks] type "${task.type}" chưa đăng ký handler`);
+    }
+
+    let lastWrite = 0;
+    const setProgress = async (percent: number) => {
+      const now = Date.now();
+      if (now - lastWrite < 500) return; // throttle ghi DB
+      lastWrite = now;
+      await db.backgroundTask.update({
+        where: { id },
+        data: { progress: Math.max(0, Math.min(99, Math.round(percent))) },
+      });
+    };
+
+    const result = await handler({
+      taskId: id,
+      params: task.params,
+      setProgress,
+    });
+
+    await db.backgroundTask.update({
+      where: { id },
+      data: {
+        status: "success",
+        progress: 100,
+        result: result as unknown as Record<string, unknown>,
+        finishedAt: new Date(),
+      },
+    });
+    await notifyTaskDone(task.createdBy, id, task.title, result);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[tasks] ${task.type} (${id}) lỗi:`, error);
+    await db.backgroundTask
+      .update({
+        where: { id },
+        data: {
+          status: "error",
+          error: message || "Tác vụ thất bại",
+          finishedAt: new Date(),
+        },
+      })
+      .catch(() => {});
+    await notifyTaskFailed(task.createdBy, task.title, message);
+  }
+}
+
+/**
+ * Gọi 1 lần khi server boot (instrumentation): task còn "running"/"pending"
+ * là mồ côi của process trước (restart giữa chừng) → error để user chạy lại.
+ */
+export async function reclaimStaleTasks(): Promise<void> {
+  const { db } = requireConfig();
+  const { count } = await db.backgroundTask.updateMany({
+    where: { status: { in: ["pending", "running"] } },
+    data: {
+      status: "error",
+      error: "Server khởi động lại giữa chừng — vui lòng chạy lại tác vụ.",
+      finishedAt: new Date(),
+    },
+  });
+  if (count > 0) {
+    console.warn(`[tasks] reclaim ${count} task mồ côi sau restart`);
+  }
+}
+
+// ─── Thông báo khi xong (qua seam notify — app cắm chuông/push) ───
+
+async function notifyTaskDone(
+  userId: string,
+  taskId: string,
+  title: string,
+  result: TaskFileResult,
+): Promise<void> {
+  const { notify } = requireConfig();
+  if (!notify) return;
+  // Task chạy XONG nhưng nghiệp vụ fail từng dòng (import) → warning + link
+  // tải file lỗi để sửa-rồi-nạp-lại.
+  const hasErrorFile = !result.fileKey && !!result.errorFileKey;
+  await notify({
+    userIds: [userId],
+    type: hasErrorFile ? "warning" : "success",
+    category: "task",
+    title: hasErrorFile ? `Cần sửa file: ${title}` : `Hoàn tất: ${title}`,
+    content: result.fileKey
+      ? `${result.summary ?? `${result.rowCount ?? ""} dòng`} — bấm để tải file.`.trim()
+      : hasErrorFile
+        ? `${result.summary ?? "Có dòng lỗi."} Bấm để tải file lỗi từng dòng.`
+        : (result.summary ?? "Tác vụ đã chạy xong."),
+    url: result.fileKey
+      ? `/api/tasks/${taskId}/download`
+      : hasErrorFile
+        ? `/api/tasks/${taskId}/download?file=error`
+        : undefined,
+    resourceType: "background_task",
+    resourceId: taskId,
+  });
+}
+
+async function notifyTaskFailed(
+  userId: string,
+  title: string,
+  message?: string,
+): Promise<void> {
+  const { notify } = requireConfig();
+  if (!notify) return;
+  await notify({
+    userIds: [userId],
+    type: "error",
+    category: "task",
+    title: `Thất bại: ${title}`,
+    content: message || "Tác vụ nền gặp lỗi — thử chạy lại.",
+  });
+}
+
+// ─── Lưu/đọc file kết quả (storage seam; fallback thư mục PRIVATE local) ───
+
+function localDir(): string {
+  return requireConfig().localDir ?? join(process.cwd(), "storage", "task-files");
+}
+
+export async function saveTaskFile(
+  buffer: Buffer,
+  key: string,
+  contentType: string,
+): Promise<string> {
+  const { storage } = requireConfig();
+  if (storage) {
+    const saved = await storage.save(buffer, key, contentType);
+    if (saved) return saved;
+  }
+  const filepath = join(localDir(), key);
+  await mkdir(dirname(filepath), { recursive: true });
+  await writeFile(filepath, buffer);
+  return `local:${key}`;
+}
+
+export async function readTaskFile(fileKey: string): Promise<Buffer> {
+  const { storage } = requireConfig();
+  if (fileKey.startsWith("local:")) {
+    return readFile(join(localDir(), fileKey.slice("local:".length)));
+  }
+  if (!storage) {
+    throw new Error(`[tasks] fileKey "${fileKey}" cần storage seam (S3/MinIO) nhưng chưa cấu hình.`);
+  }
+  return storage.read(fileKey);
+}

package/src/tasks/ui/task-list-client.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { format } from "date-fns";
+import { Download, FileWarning, ListChecks } from "lucide-react";
+import useSWR from "swr";
+
+import { getStatusMeta } from "../../ui/shared/status-indicator";
+
+/**
+ * Trang "Tác vụ nền" của CHÍNH user — dùng chung mọi app goerp: list 50 task,
+ * poll 3s khi còn task chạy, progress bar, nút tải file kết quả / file lỗi.
+ * App chỉ cần page server-shell (gate session) render component này; API
+ * chuẩn: GET /api/tasks + GET /api/tasks/[id]/download (xem app mẫu vinhhoa).
+ */
+
+interface TaskRow {
+  id: string;
+  type: string;
+  title: string;
+  status: "pending" | "running" | "success" | "error";
+  progress: number;
+  result?: {
+    fileKey?: string;
+    fileName?: string;
+    errorFileKey?: string;
+    errorFileName?: string;
+    summary?: string;
+  } | null;
+  error?: string | null;
+  createdAt: string;
+  finishedAt?: string | null;
+}
+
+const fetcher = (url: string) => fetch(url).then((r) => r.json());
+
+const STATUS_LABEL: Record<TaskRow["status"], string> = {
+  pending: "Chờ chạy",
+  running: "Đang chạy",
+  success: "Hoàn tất",
+  error: "Lỗi",
+};
+
+export function TaskListClient({ apiUrl = "/api/tasks" }: { apiUrl?: string }) {
+  const { data } = useSWR<{ tasks: TaskRow[] }>(`${apiUrl}?take=50`, fetcher, {
+    // Còn task đang chạy → poll nhanh để progress nhảy; yên ắng thì thôi.
+    refreshInterval: (latest) =>
+      latest?.tasks?.some(
+        (t) => t.status === "running" || t.status === "pending",
+      )
+        ? 3000
+        : 0,
+  });
+  const tasks = data?.tasks ?? [];
+
+  return (
+    <div className="mx-auto max-w-3xl space-y-3 p-4">
+      <div className="flex items-center gap-2">
+        <ListChecks className="h-5 w-5 text-muted-foreground" />
+        <h1 className="text-base font-bold text-foreground">Tác vụ nền</h1>
+        <span className="text-xs text-muted-foreground">
+          export/import lớn chạy nền — xong sẽ báo qua chuông thông báo
+        </span>
+      </div>
+
+      {tasks.length === 0 ? (
+        <p className="rounded-xl border border-border bg-card px-4 py-10 text-center text-sm text-muted-foreground">
+          Chưa có tác vụ nào. Xuất/Nhập Excel dữ liệu lớn sẽ hiện ở đây.
+        </p>
+      ) : (
+        <div className="divide-y divide-border overflow-hidden rounded-xl border border-border bg-card">
+          {tasks.map((task) => {
+            const meta = getStatusMeta(
+              task.status === "success"
+                ? "completed"
+                : task.status === "error"
+                  ? "cancelled"
+                  : "pending",
+              STATUS_LABEL[task.status],
+            );
+            return (
+              <div key={task.id} className="flex items-center gap-3 px-4 py-3">
+                <span
+                  className={`h-2 w-2 shrink-0 rounded-full ${meta.dotClass}`}
+                />
+                <div className="min-w-0 flex-1">
+                  <p className="truncate text-sm font-medium text-foreground">
+                    {task.title}
+                  </p>
+                  <p className="mt-0.5 truncate text-xs text-muted-foreground">
+                    {format(new Date(task.createdAt), "dd/MM HH:mm")} ·{" "}
+                    {task.status === "error"
+                      ? task.error || "Tác vụ thất bại"
+                      : (task.result?.summary ?? meta.label)}
+                  </p>
+                  {(task.status === "running" ||
+                    task.status === "pending") && (
+                    <div className="mt-1.5 h-1.5 w-full overflow-hidden rounded-full bg-muted">
+                      <div
+                        className="h-full rounded-full bg-primary transition-all"
+                        style={{ width: `${Math.max(task.progress, 4)}%` }}
+                      />
+                    </div>
+                  )}
+                </div>
+                {task.status === "success" && task.result?.fileKey && (
+                  <a
+                    href={`${apiUrl}/${task.id}/download`}
+                    className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border bg-card px-2.5 py-1.5 text-xs font-medium text-foreground hover:bg-muted"
+                  >
+                    <Download className="h-3.5 w-3.5" /> Tải file
+                  </a>
+                )}
+                {task.status === "success" && task.result?.errorFileKey && (
+                  <a
+                    href={`${apiUrl}/${task.id}/download?file=error`}
+                    className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-amber-200 bg-amber-50 px-2.5 py-1.5 text-xs font-medium text-amber-700 hover:bg-amber-100 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-300"
+                  >
+                    <FileWarning className="h-3.5 w-3.5" /> File lỗi
+                  </a>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}