@goplusvn/core 0.1.53 → 0.1.55

package/src/audit/__tests__/prisma-audit-extension.test.ts

@@ -0,0 +1,426 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { withAuditContext } from "../audit-context";
+import { createAuditExtension } from "../prisma-audit-extension";
+
+/**
+ * Extension audit chạy sâu trong Prisma, nơi rất khó quan sát lúc có sự cố —
+ * nên test ở đây bám vào ĐÚNG những gì có thể làm hỏng dữ liệu thật: bỏ sót
+ * bảng cần audit, ghi đè nhầm actor, và (quan trọng nhất) audit làm vỡ nghiệp
+ * vụ khi chính nó lỗi.
+ */
+
+/** Namespace Prisma giả — `defineExtension` chỉ trả lại object để soi. */
+const prismaNamespace = { defineExtension: (ext: any) => ext };
+
+function makeRawClient() {
+  return {
+    auditLog: { create: vi.fn().mockResolvedValue({ id: "audit-1" }) },
+    customer: { findUnique: vi.fn(), findFirst: vi.fn(), findMany: vi.fn() },
+    salesOrder: { findUnique: vi.fn(), findFirst: vi.fn(), findMany: vi.fn() },
+  };
+}
+
+/** Ghi audit là fire-and-forget — nhường 1 vòng event loop rồi mới soi. */
+const settle = () => new Promise((r) => setTimeout(r, 10));
+
+describe("createAuditExtension", () => {
+  let rawClient: ReturnType<typeof makeRawClient>;
+  let handler: any;
+
+  const build = (extra?: Record<string, unknown>) => {
+    const ext = createAuditExtension({
+      prisma: prismaNamespace,
+      rawClient: rawClient as any,
+      ...extra,
+    });
+    return ext.query.$allModels.$allOperations;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    rawClient = makeRawClient();
+    handler = build();
+  });
+
+  it("dựng đúng hình dạng extension Prisma", () => {
+    const ext = createAuditExtension({
+      prisma: prismaNamespace,
+      rawClient: rawClient as any,
+    });
+    expect(ext.name).toBe("audit-log");
+    expect(ext.query.$allModels.$allOperations).toBeInstanceOf(Function);
+  });
+
+  it("bỏ qua thao tác đọc (findMany)", async () => {
+    const query = vi.fn().mockResolvedValue([{ id: "1" }]);
+    const result = await handler({
+      model: "Customer",
+      operation: "findMany",
+      args: {},
+      query,
+    });
+
+    expect(result).toEqual([{ id: "1" }]);
+    expect(rawClient.auditLog.create).not.toHaveBeenCalled();
+  });
+
+  it("KHÔNG audit chính bảng AuditLog (chống đệ quy vô tận)", async () => {
+    const query = vi.fn().mockResolvedValue({ id: "audit-1" });
+    await handler({
+      model: "AuditLog",
+      operation: "create",
+      args: { data: {} },
+      query,
+    });
+    await settle();
+
+    expect(query).toHaveBeenCalled();
+    expect(rawClient.auditLog.create).not.toHaveBeenCalled();
+  });
+
+  it.each(["Session", "Notification", "BackgroundTask", "ErrorLog"])(
+    "bỏ qua bảng hạ tầng %s theo mặc định",
+    async (model) => {
+      const query = vi.fn().mockResolvedValue({ id: "x" });
+      await handler({
+        model,
+        operation: "create",
+        args: { data: {} },
+        query,
+      });
+      await settle();
+
+      expect(rawClient.auditLog.create).not.toHaveBeenCalled();
+    },
+  );
+
+  it("app khai thêm bảng ồn của mình qua skipModels", async () => {
+    const h = build({ skipModels: ["TriAnhZnsMessage"] });
+    const query = vi.fn().mockResolvedValue({ id: "zns-1" });
+
+    await h({
+      model: "TriAnhZnsMessage",
+      operation: "create",
+      args: { data: {} },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).not.toHaveBeenCalled();
+
+    // Bảng nghiệp vụ vẫn audit bình thường.
+    await h({
+      model: "Customer",
+      operation: "create",
+      args: { data: { name: "A" } },
+      query: vi.fn().mockResolvedValue({ id: "c1", name: "A" }),
+    });
+    await settle();
+    expect(rawClient.auditLog.create).toHaveBeenCalledTimes(1);
+  });
+
+  it("audit create kèm id bản ghi vừa tạo", async () => {
+    const query = vi
+      .fn()
+      .mockResolvedValue({ id: "cust-1", name: "Nguyễn Văn A" });
+
+    await handler({
+      model: "Customer",
+      operation: "create",
+      args: { data: { name: "Nguyễn Văn A" } },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        action: "create",
+        resource: "customer",
+        resourceId: "cust-1",
+      }),
+    });
+  });
+
+  it("audit update chộp được dữ liệu CŨ trước khi ghi đè", async () => {
+    rawClient.customer.findUnique.mockResolvedValue({
+      id: "cust-1",
+      name: "Tên cũ",
+    });
+    const query = vi.fn().mockResolvedValue({ id: "cust-1" });
+
+    await handler({
+      model: "Customer",
+      operation: "update",
+      args: { where: { id: "cust-1" }, data: { name: "Tên mới" } },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        action: "update",
+        resourceId: "cust-1",
+        oldData: expect.objectContaining({ name: "Tên cũ" }),
+        newData: expect.objectContaining({ name: "Tên mới" }),
+      }),
+    });
+  });
+
+  it("xoá-theo-điều-kiện (không có id) vẫn để lại dấu vết", async () => {
+    rawClient.customer.findFirst.mockResolvedValue({
+      id: "cust-9",
+      code: "KH009",
+    });
+    const query = vi.fn().mockResolvedValue({ id: "cust-9" });
+
+    await handler({
+      model: "Customer",
+      operation: "delete",
+      args: { where: { code: "KH009" } },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.customer.findFirst).toHaveBeenCalledWith({
+      where: { code: "KH009" },
+    });
+    expect(rawClient.auditLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        action: "delete",
+        resourceId: "cust-9",
+        oldData: expect.objectContaining({ code: "KH009" }),
+      }),
+    });
+  });
+
+  it("PascalCase → kebab-case khớp mã resource RBAC", async () => {
+    const query = vi.fn().mockResolvedValue({ id: "so-1" });
+    await handler({
+      model: "SalesOrder",
+      operation: "create",
+      args: { data: {} },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({ resource: "sales-order" }),
+    });
+  });
+
+  it("lấy actor từ withAuditContext", async () => {
+    const query = vi.fn().mockResolvedValue({ id: "cust-1", name: "Test" });
+
+    await withAuditContext({ userId: "user-1", userName: "Admin" }, () =>
+      handler({
+        model: "Customer",
+        operation: "create",
+        args: { data: { name: "Test" } },
+        query,
+      }),
+    );
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        userId: "user-1",
+        description: expect.stringContaining("[Admin] Tạo mới customer"),
+      }),
+    });
+  });
+
+  it("ngoài context thì rơi về resolveSessionActor (cứu route quên bọc)", async () => {
+    const resolveSessionActor = vi
+      .fn()
+      .mockResolvedValue({ userId: "u-2", userName: "Kế toán" });
+    const h = build({ resolveSessionActor });
+    const query = vi.fn().mockResolvedValue({ id: "cust-2" });
+
+    await h({
+      model: "Customer",
+      operation: "create",
+      args: { data: {} },
+      query,
+    });
+    await settle();
+
+    expect(resolveSessionActor).toHaveBeenCalled();
+    expect(rawClient.auditLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({ userId: "u-2" }),
+    });
+  });
+
+  it("có context rồi thì KHÔNG tra session nữa", async () => {
+    const resolveSessionActor = vi.fn();
+    const h = build({ resolveSessionActor });
+    const query = vi.fn().mockResolvedValue({ id: "cust-3" });
+
+    await withAuditContext({ userId: "u-1", userName: "Admin" }, () =>
+      h({ model: "Customer", operation: "create", args: { data: {} }, query }),
+    );
+    await settle();
+
+    expect(resolveSessionActor).not.toHaveBeenCalled();
+  });
+
+  it("audit ghi hỏng KHÔNG làm vỡ nghiệp vụ", async () => {
+    rawClient.auditLog.create.mockRejectedValue(new Error("DB connect fail"));
+    const onError = vi.fn();
+    const h = build({ onError });
+    const query = vi.fn().mockResolvedValue({ id: "cust-1" });
+
+    const result = await h({
+      model: "Customer",
+      operation: "create",
+      args: { data: { name: "Test" } },
+      query,
+    });
+    await settle();
+
+    expect(result).toEqual({ id: "cust-1" });
+    expect(onError).toHaveBeenCalledWith(
+      "[AuditExtension] Failed to write audit log:",
+      expect.objectContaining({ model: "Customer" }),
+    );
+  });
+
+  it("đọc snapshot cũ hỏng KHÔNG chặn lệnh update", async () => {
+    rawClient.customer.findUnique.mockRejectedValue(new Error("Query failed"));
+    const query = vi.fn().mockResolvedValue({ id: "cust-1" });
+
+    const result = await handler({
+      model: "Customer",
+      operation: "update",
+      args: { where: { id: "cust-1" }, data: { name: "New" } },
+      query,
+    });
+
+    expect(result).toEqual({ id: "cust-1" });
+    expect(query).toHaveBeenCalled();
+  });
+
+  it("đổi Date/Decimal/BigInt sang dạng nhét được vào cột JSON", async () => {
+    const query = vi.fn().mockResolvedValue({
+      id: "cust-1",
+      createdAt: new Date("2026-03-18T10:00:00Z"),
+      amount: { toNumber: () => 1500 },
+      big: 42n,
+    });
+
+    await handler({
+      model: "Customer",
+      operation: "create",
+      args: { data: {} },
+      query,
+    });
+    await settle();
+
+    const newData = rawClient.auditLog.create.mock.calls[0]?.[0]?.data?.newData;
+    expect(newData.createdAt).toBe("2026-03-18T10:00:00.000Z");
+    expect(newData.amount).toBe(1500);
+    expect(newData.big).toBe(42);
+  });
+
+  it("bỏ nhánh quan hệ lồng (connect/create) khỏi diff", async () => {
+    const query = vi.fn().mockResolvedValue({ id: "so-1" });
+    await handler({
+      model: "SalesOrder",
+      operation: "create",
+      args: { data: {} },
+      query,
+    });
+    await settle();
+
+    // newData lấy từ result nên không có nhánh quan hệ; kiểm ở update thì rõ hơn
+    rawClient.salesOrder.findUnique.mockResolvedValue({ id: "so-1" });
+    await handler({
+      model: "SalesOrder",
+      operation: "update",
+      args: {
+        where: { id: "so-1" },
+        data: { status: "done", customer: { connect: { id: "c1" } } },
+      },
+      query: vi.fn().mockResolvedValue({ id: "so-1" }),
+    });
+    await settle();
+
+    const last = rawClient.auditLog.create.mock.calls.at(-1)?.[0];
+    expect(last.data.newData).toEqual({ status: "done" });
+  });
+
+  it("createMany dưới trần: mỗi dòng một hàng audit", async () => {
+    const query = vi.fn().mockResolvedValue({ count: 3 });
+
+    await handler({
+      model: "Customer",
+      operation: "createMany",
+      args: { data: [{ name: "A" }, { name: "B" }, { name: "C" }] },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledTimes(3);
+  });
+
+  it("bulk vượt trần: gom MỘT dòng tóm tắt thay vì N dòng", async () => {
+    const h = build({ maxBulkEntries: 2 });
+    const query = vi.fn().mockResolvedValue({ count: 5 });
+
+    await h({
+      model: "Customer",
+      operation: "createMany",
+      args: { data: [1, 2, 3, 4, 5].map((i) => ({ name: `KH${i}` })) },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledTimes(1);
+    const payload = rawClient.auditLog.create.mock.calls[0]?.[0]?.data;
+    expect(payload.newData).toMatchObject({ bulk: true, count: 5 });
+    expect(payload.description).toContain("hàng loạt");
+  });
+
+  it("updateMany chộp từng dòng cũ để biết đổi những gì", async () => {
+    rawClient.customer.findMany.mockResolvedValue([
+      { id: "c1", status: "active" },
+      { id: "c2", status: "active" },
+    ]);
+    const query = vi.fn().mockResolvedValue({ count: 2 });
+
+    await handler({
+      model: "Customer",
+      operation: "updateMany",
+      args: { where: { status: "active" }, data: { status: "locked" } },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledTimes(2);
+    const first = rawClient.auditLog.create.mock.calls[0]?.[0]?.data;
+    expect(first).toMatchObject({
+      action: "update",
+      resourceId: "c1",
+      oldData: { id: "c1", status: "active" },
+      newData: { status: "locked" },
+    });
+  });
+
+  it("updateMany không khớp dòng nào vẫn ghi 1 dòng tóm tắt", async () => {
+    rawClient.customer.findMany.mockResolvedValue([]);
+    const query = vi.fn().mockResolvedValue({ count: 0 });
+
+    await handler({
+      model: "Customer",
+      operation: "updateMany",
+      args: { where: { status: "ghost" }, data: { status: "x" } },
+      query,
+    });
+    await settle();
+
+    expect(rawClient.auditLog.create).toHaveBeenCalledTimes(1);
+    expect(
+      rawClient.auditLog.create.mock.calls[0]?.[0]?.data?.newData,
+    ).toMatchObject({ bulk: true, count: 0 });
+  });
+});

package/src/audit/audit-actor.ts

@@ -0,0 +1,42 @@
+/**
+ * Xác định ACTOR cho audit từ session — điểm mấu chốt là phiên MẠO DANH
+ * (plugin admin của Better Auth): hàng audit phải quy về ADMIN THẬT
+ * (`userId = impersonatedBy`), `userName` ghi rõ "Admin (mạo danh Nhân viên)".
+ * Không xử lý thì nhật ký gán thao tác của admin cho nhân viên bị mạo danh —
+ * mất giá trị đối chiếu khi tra soát.
+ */
+
+/** Phần session tối thiểu mà audit cần — app truyền session của mình vào. */
+export interface AuditSessionLike {
+  user: { id?: string | null; name?: string | null; email?: string | null };
+  impersonatedBy?: string | null;
+}
+
+/**
+ * @param resolveName cách lấy tên admin từ id (caller tự quyết — tra DB hoặc
+ * bỏ qua). Lỗi lookup KHÔNG được làm vỡ audit.
+ */
+export async function resolveAuditActor(
+  session: AuditSessionLike,
+  resolveName?: (userId: string) => Promise<string | null>,
+): Promise<{ userId?: string; userName?: string }> {
+  const targetName = session.user.name || session.user.email || "?";
+
+  if (!session.impersonatedBy) {
+    return {
+      userId: session.user.id || undefined,
+      userName: targetName === "?" ? undefined : targetName,
+    };
+  }
+
+  let adminName: string | null = null;
+  try {
+    adminName = (await resolveName?.(session.impersonatedBy)) ?? null;
+  } catch {
+    // audit không được vỡ vì lookup tên
+  }
+  return {
+    userId: session.impersonatedBy,
+    userName: `${adminName ?? "Admin"} (mạo danh ${targetName})`,
+  };
+}

package/src/audit/audit-context.ts

@@ -0,0 +1,47 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Ngữ cảnh AUDIT theo request — mang userId/userName xuống tận Prisma extension
+ * mà không phải truyền tay qua từng lớp service.
+ *
+ * Vì sao AsyncLocalStorage: extension audit chạy bên trong Prisma, cách chỗ có
+ * session vài lớp gọi. Nếu bắt mỗi service nhận thêm tham số actor thì hoặc là
+ * sót (ghi user_id NULL), hoặc phải sửa hàng trăm chữ ký hàm.
+ *
+ * Dùng:
+ *   route:      return withAuditContext({ userId, userName, ip }, () => handler())
+ *   extension:  const ctx = getAuditContext()
+ *
+ * BẪY — `fn` phải THỰC SỰ chạy trong ngữ cảnh, không được chỉ trả về một
+ * PrismaPromise. Lệnh Prisma là promise LƯỜI: chỉ chạy khi có ai `await`. Viết
+ *
+ *     withAuditContext(ctx, () => db.x.update(...))   // ❌ ghi user_id NULL
+ *
+ * thì `run()` đã thoát ngữ cảnh trước khi query khởi động → extension không
+ * thấy actor. Phải để `await` nằm BÊN TRONG:
+ *
+ *     withAuditContext(ctx, async () => { await db.x.update(...) })   // ✅
+ *
+ * (Bọc cả một handler `async` thì an toàn sẵn — nó chạy ngay khi được gọi.)
+ */
+
+export interface AuditContext {
+  userId?: string;
+  userName?: string;
+  ip?: string;
+}
+
+const auditStore = new AsyncLocalStorage<AuditContext>();
+
+/** Chạy `fn` trong ngữ cảnh audit — mọi lệnh Prisma bên trong thấy được actor. */
+export function withAuditContext<T>(
+  context: AuditContext,
+  fn: () => T | Promise<T>,
+): T | Promise<T> {
+  return auditStore.run(context, fn);
+}
+
+/** Ngữ cảnh hiện tại, `undefined` nếu đang ở ngoài `withAuditContext`. */
+export function getAuditContext(): AuditContext | undefined {
+  return auditStore.getStore();
+}

package/src/audit/entity-audit.ts

@@ -0,0 +1,71 @@
+/**
+ * Ghi MỘT hàng audit mang NGỮ NGHĨA nghiệp vụ ("Xác nhận thanh toán", "Nhận
+ * hàng") — khác với `createAuditExtension` vốn chỉ chộp create/update/delete
+ * thô trên từng model. Timeline lịch sử của phiếu/đơn đọc chính những hàng này.
+ *
+ * Hai điều đắt giá, đừng bỏ:
+ *  - `client`: truyền TransactionClient của lệnh nghiệp vụ vào thì hàng audit
+ *    nằm chung transaction, rollback cùng nhau. Không truyền thì audit ghi độc
+ *    lập — nghiệp vụ fail vẫn còn lại dòng "đã xảy ra" ma.
+ *  - KHÔNG BAO GIỜ throw: audit hỏng không được chặn nghiệp vụ.
+ */
+
+/** Delegate tối thiểu của bảng audit (`db.auditLog` hoặc `tx.auditLog`). */
+export interface AuditLogWriter {
+  auditLog: { create(args: any): Promise<any> };
+}
+
+export interface LogEntityActionParams {
+  /** Loại đối tượng, kebab-case: "sales-order", "purchase-order"… */
+  resource: string;
+  resourceId: string;
+  /** Mã hành động nghiệp vụ do app định nghĩa ("confirm-payment"…). */
+  action: string;
+  description: string;
+  userId?: string | null;
+  userName?: string | null;
+  oldData?: Record<string, any>;
+  newData?: Record<string, any>;
+  /** Số chứng từ để tra cứu nhanh — gộp vào newData.orderNumber. */
+  referenceNumber?: string | null;
+  /** Client ghi audit; truyền `tx` để hàng audit rollback cùng nghiệp vụ. */
+  client: AuditLogWriter;
+  /** Nơi báo lỗi ghi audit. Mặc định console.error. */
+  onError?: (error: unknown) => void;
+}
+
+export async function logEntityAction({
+  resource,
+  resourceId,
+  action,
+  description,
+  userId,
+  userName,
+  oldData,
+  newData,
+  referenceNumber,
+  client,
+  onError,
+}: LogEntityActionParams): Promise<void> {
+  try {
+    await client.auditLog.create({
+      data: {
+        action,
+        resource,
+        resourceId,
+        userId: userId || undefined,
+        description: userName ? `[${userName}] ${description}` : description,
+        oldData: oldData || undefined,
+        newData: newData
+          ? { ...newData, orderNumber: referenceNumber || undefined }
+          : referenceNumber
+            ? { orderNumber: referenceNumber }
+            : undefined,
+      },
+    });
+  } catch (error) {
+    // Non-blocking — audit hỏng không được làm vỡ nghiệp vụ.
+    if (onError) onError(error);
+    else console.error("[Audit] Failed to log action:", error);
+  }
+}

package/src/audit/index.ts

@@ -1,11 +1,30 @@
+/**
+ * Audit dùng chung mọi app goerp — hai tầng bổ trợ nhau:
+ *
+ *  1. `createAuditExtension` — chộp TỰ ĐỘNG mọi create/update/delete ở tầng
+ *     Prisma. Không sót, nhưng chỉ biết "ai đổi trường nào".
+ *  2. `logEntityAction` — ghi tay bản ghi mang NGỮ NGHĨA ("Xác nhận thanh
+ *     toán"). Đây là thứ timeline lịch sử phiếu/đơn hiển thị.
+ *
+ * Actor chảy xuống cả hai qua `withAuditContext` (AsyncLocalStorage).
+ * Bảng `audit_logs` ship qua `goerp-features sync` (feature `audit-logs`).
+ */
 export {
-  auditManager,
-  AuditManagerImpl,
-  ConsoleAuditLogger,
-} from "./audit-manager";
-export type {
-  AuditLog,
-  AuditLogger,
-  AuditManagerOptions,
-  CreateAuditInput,
-} from "./types";
+  getAuditContext,
+  withAuditContext,
+  type AuditContext,
+} from "./audit-context";
+export { resolveAuditActor, type AuditSessionLike } from "./audit-actor";
+export {
+  logEntityAction,
+  type AuditLogWriter,
+  type LogEntityActionParams,
+} from "./entity-audit";
+export {
+  buildDescription,
+  createAuditExtension,
+  DEFAULT_SKIP_MODELS,
+  type AuditRawClient,
+  type CreateAuditExtensionOptions,
+  type PrismaNamespaceLike,
+} from "./prisma-audit-extension";