@goplusvn/core 0.1.53 → 0.1.55

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

@@ -0,0 +1,572 @@
+import { getAuditContext } from "./audit-context";
+import type { AuditContext } from "./audit-context";
+
+/**
+ * Prisma extension ghi TỰ ĐỘNG mọi create/update/delete vào bảng `audit_logs`
+ * (feature `audit-logs`). Engine dùng chung mọi app goerp.
+ *
+ * Nguyên tắc bất di:
+ *  - Blacklist chứ không whitelist: mặc định audit HẾT, chỉ chừa bảng kỹ thuật.
+ *    App mới quên khai model là vẫn có nhật ký — an toàn hơn quên bật.
+ *  - Ghi bằng `rawClient` (client CHƯA gắn extension) → không đệ quy vô tận.
+ *  - Non-blocking tuyệt đối: mọi lỗi audit đều nuốt, nghiệp vụ chạy tiếp.
+ *  - Bulk có TRẦN: một `updateMany` của job đồng bộ đụng hàng trăm dòng không
+ *    được đẻ hàng trăm hàng audit — quá `maxBulkEntries` thì gom 1 dòng tóm tắt.
+ *
+ * App cắm qua `createAuditExtension({ prisma, rawClient, ... })` — `prisma` là
+ * NAMESPACE Prisma của client app tự generate (core không phụ thuộc @prisma/client
+ * nào cụ thể, mỗi app một client riêng).
+ */
+
+/** Namespace Prisma của app — chỉ cần `defineExtension`. */
+export interface PrismaNamespaceLike {
+  defineExtension(extension: any): any;
+}
+
+/** Client gốc (chưa gắn extension) dùng để ĐỌC snapshot + GHI audit. */
+export interface AuditRawClient {
+  auditLog: { create(args: any): Promise<any> };
+  [model: string]: any;
+}
+
+export interface CreateAuditExtensionOptions {
+  prisma: PrismaNamespaceLike;
+  rawClient: AuditRawClient;
+  /**
+   * Khôi phục actor khi lệnh ghi nằm NGOÀI `withAuditContext` (route chưa bọc
+   * apiHandler, server action…). Trả undefined nếu không có phiên. App cắm hàm
+   * đọc session của mình — core không biết auth stack nào.
+   */
+  resolveSessionActor?: () => Promise<AuditContext | undefined>;
+  /** Model bỏ qua NGOÀI danh sách mặc định (bảng ồn đặc thù của app). */
+  skipModels?: Iterable<string>;
+  /** Thay hẳn danh sách mặc định (hiếm dùng — cân nhắc `skipModels` trước). */
+  skipModelsOverride?: Iterable<string>;
+  /** Trần số hàng audit sinh ra từ một lệnh bulk. Mặc định 100. */
+  maxBulkEntries?: number;
+  onError?: (message: string, error: unknown) => void;
+}
+
+/**
+ * Bảng KHÔNG audit theo mặc định: nhật ký của chính nó (chống đệ quy), bảng
+ * auth đổi liên tục, và bảng hạ tầng do core sở hữu (task nền/thông báo/cron)
+ * — audit chúng chỉ tạo nhiễu che mất thao tác nghiệp vụ thật.
+ */
+export const DEFAULT_SKIP_MODELS: readonly string[] = [
+  // Audit của chính nó — chống đệ quy vô tận.
+  "AuditLog",
+  // Auth/session: đổi mỗi request, không phải dấu vết nghiệp vụ.
+  "Account",
+  "Session",
+  "RefreshToken",
+  "VerificationToken",
+  "Verification",
+  // Bảng log sẵn có — audit thêm là ghi hai lần.
+  "SystemLog",
+  "SystemJob",
+  "JobExecutionLog",
+  "ErrorLog",
+  // Hạ tầng core: hàng đợi/tiến độ, ghi rất dày.
+  "BackgroundTask",
+  "Notification",
+  "PushSubscription",
+];
+
+const AUDITED_OPERATIONS = new Set([
+  "create",
+  "update",
+  "delete",
+  "createMany",
+  "updateMany",
+  "deleteMany",
+]);
+
+const BULK_OPERATIONS = new Set(["createMany", "updateMany", "deleteMany"]);
+
+function toAuditAction(operation: string): string {
+  if (operation.startsWith("create")) return "create";
+  if (operation.startsWith("update")) return "update";
+  if (operation.startsWith("delete")) return "delete";
+  return operation;
+}
+
+/** "SalesOrder" → "sales-order" (khớp mã resource của RBAC). */
+function toResourceName(modelName: string): string {
+  return modelName
+    .replace(/([A-Z])/g, "-$1")
+    .toLowerCase()
+    .replace(/^-/, "");
+}
+
+/** Lấy id từ where khi có — đường nhanh; không có thì fallback findFirst(where). */
+function extractId(where: Record<string, any> | undefined): string | null {
+  if (!where?.id) return null;
+  if (typeof where.id === "string") return where.id;
+  if (typeof where.id === "object" && where.id?.equals)
+    return String(where.id.equals);
+  return null;
+}
+
+/**
+ * Chuẩn hoá dữ liệu để nhét vào cột JSON: bỏ undefined, đổi Date/BigInt/Decimal,
+ * và LOẠI các nhánh quan hệ lồng (`create`/`connect`/…) — chúng không phải giá
+ * trị trường, ghi vào chỉ làm diff rối.
+ */
+function sanitizeData(data: unknown): Record<string, unknown> | null {
+  if (!data || typeof data !== "object") return null;
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+    if (value === undefined) continue;
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      !Array.isArray(value) &&
+      !(value instanceof Date)
+    ) {
+      const keys = Object.keys(value);
+      if (
+        keys.some((k) =>
+          [
+            "create",
+            "connect",
+            "connectOrCreate",
+            "set",
+            "disconnect",
+          ].includes(k),
+        )
+      ) {
+        continue;
+      }
+    }
+    if (value instanceof Date) {
+      result[key] = value.toISOString();
+    } else if (typeof value === "bigint") {
+      result[key] = Number(value);
+    } else if (
+      value !== null &&
+      typeof value === "object" &&
+      "toNumber" in (value as any)
+    ) {
+      result[key] = (value as any).toNumber();
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+function modelDelegate(rawClient: AuditRawClient, model: string): any {
+  return rawClient[model.charAt(0).toLowerCase() + model.slice(1)];
+}
+
+interface AuditWritePayload {
+  action: string;
+  resource: string;
+  resourceId?: string | undefined;
+  actor: AuditContext | undefined;
+  description: string;
+  oldData: Record<string, unknown> | null;
+  newData: Record<string, unknown> | null;
+  model: string;
+  operation: string;
+}
+
+export function createAuditExtension(options: CreateAuditExtensionOptions) {
+  const {
+    prisma,
+    rawClient,
+    resolveSessionActor,
+    maxBulkEntries = 100,
+    onError,
+  } = options;
+
+  const skipModels = new Set<string>(
+    options.skipModelsOverride ?? DEFAULT_SKIP_MODELS,
+  );
+  for (const extra of options.skipModels ?? []) skipModels.add(extra);
+
+  const reportError = (message: string, error: unknown): void => {
+    if (onError) onError(message, error);
+    else console.error(message, error);
+  };
+
+  /** Ghi audit fire-and-forget — không await, không throw. */
+  const fireAuditWrite = (p: AuditWritePayload): void => {
+    rawClient.auditLog
+      .create({
+        data: {
+          action: p.action,
+          resource: p.resource,
+          resourceId: p.resourceId,
+          userId: p.actor?.userId || undefined,
+          description: p.description,
+          oldData: p.oldData ?? undefined,
+          newData: p.newData ?? undefined,
+          ipAddress: p.actor?.ip || undefined,
+        },
+      })
+      .catch((err: unknown) => {
+        reportError("[AuditExtension] Failed to write audit log:", {
+          model: p.model,
+          operation: p.operation,
+          resourceId: p.resourceId,
+          error:
+            err instanceof Error
+              ? { message: err.message, code: (err as any).code }
+              : err,
+        });
+      });
+  };
+
+  /** ALS trước, phiên đăng nhập sau — cứu actor cho route chưa bọc withAudit. */
+  const resolveActor = async (): Promise<AuditContext | undefined> => {
+    const ctx = getAuditContext();
+    if (ctx?.userId) return ctx;
+    const fromSession = await resolveSessionActor?.();
+    // Giữ lại ip đã có trong ctx.
+    return { ...(ctx ?? {}), ...(fromSession ?? {}) };
+  };
+
+  return prisma.defineExtension({
+    name: "audit-log",
+    query: {
+      $allModels: {
+        async $allOperations({ model, operation, args, query }: any) {
+          if (!AUDITED_OPERATIONS.has(operation)) return query(args);
+          if (!model || skipModels.has(model)) return query(args);
+
+          const action = toAuditAction(operation);
+          const resource = toResourceName(model);
+          const where = (args as any)?.where;
+
+          // ── Chộp dữ liệu CŨ trước khi update/delete ──
+          // Đường nhanh là where.id. Không có id thì tra bằng chính where, để
+          // xoá-theo-code hay sửa-theo-email vẫn để lại dấu vết.
+          let oldData: Record<string, unknown> | null = null;
+          let oldRows: Array<Record<string, unknown>> | null = null;
+          let resourceId: string | null = null;
+
+          const isMutationByWhere = action === "update" || action === "delete";
+
+          if (isMutationByWhere && where) {
+            const delegate = modelDelegate(rawClient, model);
+
+            if (BULK_OPERATIONS.has(operation)) {
+              // `take: max + 1` để phát hiện tràn mà không phải SELECT khổng lồ.
+              try {
+                if (delegate?.findMany) {
+                  const rows = await delegate.findMany({
+                    where,
+                    take: maxBulkEntries + 1,
+                  });
+                  if (Array.isArray(rows) && rows.length > 0) {
+                    oldRows = rows
+                      .map((r: any) => sanitizeData(r))
+                      .filter(Boolean) as Array<Record<string, unknown>>;
+                  }
+                }
+              } catch {
+                /* nuốt — audit không được làm vỡ nghiệp vụ */
+              }
+            } else {
+              resourceId = extractId(where);
+              try {
+                let existing: any = null;
+                if (resourceId && delegate?.findUnique) {
+                  existing = await delegate.findUnique({
+                    where: { id: resourceId },
+                  });
+                } else if (delegate?.findFirst) {
+                  existing = await delegate.findFirst({ where });
+                  if (existing?.id) resourceId = existing.id;
+                }
+                if (existing) oldData = sanitizeData(existing);
+              } catch {
+                /* nuốt */
+              }
+            }
+          }
+
+          // ── Chạy lệnh gốc ──
+          const result = await query(args);
+
+          // ── Dựng & ghi audit ──
+          try {
+            const actor = await resolveActor();
+
+            if (BULK_OPERATIONS.has(operation)) {
+              const userName = actor?.userName || "Hệ thống";
+
+              if (operation === "createMany") {
+                const payload = (args as any)?.data;
+                const rows = Array.isArray(payload) ? payload : [payload];
+                const affected =
+                  typeof (result as any)?.count === "number"
+                    ? (result as any).count
+                    : rows.length;
+
+                if (rows.length > maxBulkEntries) {
+                  fireAuditWrite({
+                    action: "create",
+                    resource,
+                    resourceId: undefined,
+                    actor,
+                    description: `[${userName}] Tạo hàng loạt ${resource} (${affected} bản ghi)`,
+                    oldData: null,
+                    newData: {
+                      bulk: true,
+                      count: affected,
+                      sample: rows
+                        .slice(0, 5)
+                        .map((r) => sanitizeData(r))
+                        .filter(Boolean),
+                    },
+                    model,
+                    operation,
+                  });
+                  return result;
+                }
+
+                for (const row of rows) {
+                  const sanitized = sanitizeData(row);
+                  if (!sanitized) continue;
+                  fireAuditWrite({
+                    action: "create",
+                    resource,
+                    resourceId: undefined,
+                    actor,
+                    description: buildDescription(
+                      "create",
+                      resource,
+                      userName,
+                      null,
+                      sanitized,
+                      null,
+                    ),
+                    oldData: null,
+                    newData: sanitized,
+                    model,
+                    operation,
+                  });
+                }
+                return result;
+              }
+
+              // updateMany / deleteMany
+              const rows = oldRows ?? [];
+              const newPayload =
+                operation === "updateMany"
+                  ? sanitizeData((args as any)?.data)
+                  : null;
+              const affected =
+                typeof (result as any)?.count === "number"
+                  ? (result as any).count
+                  : rows.length;
+
+              // Tràn trần: gom MỘT dòng tóm tắt thay vì N dòng.
+              if (rows.length > maxBulkEntries) {
+                fireAuditWrite({
+                  action,
+                  resource,
+                  resourceId: undefined,
+                  actor,
+                  description: `[${userName}] ${action === "delete" ? "Xóa" : "Cập nhật"} hàng loạt ${resource} (${affected} bản ghi)`,
+                  oldData: null,
+                  newData: {
+                    bulk: true,
+                    count: affected,
+                    where: sanitizeData(where),
+                    data: action === "delete" ? null : newPayload,
+                    sampleIds: rows
+                      .slice(0, 20)
+                      .map((r: any) => r?.id)
+                      .filter(Boolean),
+                  },
+                  model,
+                  operation,
+                });
+                return result;
+              }
+
+              for (const row of rows) {
+                const rowId =
+                  typeof row?.id === "string" ? (row.id as string) : null;
+                fireAuditWrite({
+                  action,
+                  resource,
+                  resourceId: rowId ?? undefined,
+                  actor,
+                  description: buildDescription(
+                    action,
+                    resource,
+                    userName,
+                    row,
+                    action === "delete" ? null : newPayload,
+                    rowId,
+                  ),
+                  oldData: row,
+                  newData: action === "delete" ? null : newPayload,
+                  model,
+                  operation,
+                });
+              }
+              if (rows.length === 0) {
+                fireAuditWrite({
+                  action,
+                  resource,
+                  resourceId: undefined,
+                  actor,
+                  description: `[${userName}] ${action === "delete" ? "Xóa" : "Cập nhật"} hàng loạt ${resource}${affected ? ` (${affected} bản ghi)` : ""}`,
+                  oldData: null,
+                  newData: {
+                    bulk: true,
+                    count: affected,
+                    where: sanitizeData(where),
+                    data: action === "delete" ? null : newPayload,
+                  },
+                  model,
+                  operation,
+                });
+              }
+              return result;
+            }
+
+            // Đường một dòng
+            let newData: Record<string, unknown> | null = null;
+            if (action === "create" && result) {
+              resourceId = (result as any)?.id || null;
+              newData = sanitizeData(result);
+            } else if (action === "update") {
+              newData = sanitizeData((args as any)?.data);
+            }
+
+            const userName = actor?.userName || "Hệ thống";
+            const description = buildDescription(
+              action,
+              resource,
+              userName,
+              oldData,
+              newData,
+              resourceId,
+            );
+
+            fireAuditWrite({
+              action,
+              resource,
+              resourceId: resourceId ?? undefined,
+              actor,
+              description,
+              oldData,
+              newData,
+              model,
+              operation,
+            });
+          } catch (auditError) {
+            reportError(
+              "[AuditExtension] Error preparing audit log:",
+              auditError,
+            );
+          }
+
+          return result;
+        },
+      },
+    },
+  });
+}
+
+/**
+ * Mô tả đọc-được-bằng-mắt cho hàng audit. Với update thì kèm tối đa 3 trường
+ * đổi, để tra nhật ký khỏi phải mở panel chi tiết từng dòng.
+ */
+export function buildDescription(
+  action: string,
+  resource: string,
+  userName: string,
+  oldData?: Record<string, unknown> | null,
+  newData?: Record<string, unknown> | null,
+  resourceId?: string | null,
+): string {
+  const actionLabels: Record<string, string> = {
+    create: "Tạo mới",
+    update: "Cập nhật",
+    delete: "Xóa",
+  };
+  const actionLabel = actionLabels[action] || action;
+
+  const skipKeys = new Set([
+    "id",
+    "createdAt",
+    "updatedAt",
+    "updatedBy",
+    "createdBy",
+    "userAgent",
+    "ipAddress",
+    "password",
+    "token",
+    "refreshToken",
+  ]);
+
+  let changeSummary = "";
+  if (action === "update" && oldData && newData) {
+    const allKeys = Object.keys(newData).filter((k) => !skipKeys.has(k));
+    const changedPairs: string[] = [];
+
+    for (const key of allKeys) {
+      const ov = oldData[key],
+        nv = newData[key];
+      if (JSON.stringify(ov) === JSON.stringify(nv)) continue;
+      if (typeof ov === "object" && typeof nv === "object") continue;
+      const ovStr = ov !== undefined ? String(ov ?? "—") : undefined;
+      const nvStr = nv !== undefined ? String(nv ?? "—") : undefined;
+      if (ovStr !== undefined && nvStr !== undefined) {
+        changedPairs.push(`${key}: ${ovStr}→${nvStr}`);
+      } else if (nvStr !== undefined) {
+        changedPairs.push(`${key}: ${nvStr}`);
+      }
+      if (changedPairs.length >= 3) break;
+    }
+
+    if (changedPairs.length > 0) {
+      changeSummary = ` — ${changedPairs.join(", ")}`;
+    }
+  } else if (action === "create" && newData) {
+    changeSummary = identifierSuffix(newData, [
+      "code",
+      "name",
+      "number",
+      "email",
+      "status",
+      "title",
+    ]);
+  } else if (action === "delete" && oldData) {
+    changeSummary = identifierSuffix(oldData, [
+      "code",
+      "name",
+      "number",
+      "email",
+      "title",
+    ]);
+  }
+
+  const idSuffix = resourceId ? ` #${resourceId.slice(-8)}` : "";
+  return `[${userName}] ${actionLabel} ${resource}${idSuffix}${changeSummary}`;
+}
+
+/** " (VH001 · Nguyễn Văn A)" — tối đa 2 trường nhận dạng đầu tiên tìm thấy. */
+function identifierSuffix(
+  data: Record<string, unknown>,
+  keys: string[],
+): string {
+  const identifiers: string[] = [];
+  for (const key of keys) {
+    const val = data[key];
+    if (val && typeof val !== "object") {
+      identifiers.push(String(val));
+      if (identifiers.length >= 2) break;
+    }
+  }
+  return identifiers.length > 0 ? ` (${identifiers.join(" · ")})` : "";
+}