@goplusvn/core 0.1.54 → 0.1.55

package/features/README.md

@@ -40,6 +40,12 @@ GENERATED — đừng sửa tay) và tạo thư mục migration
   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).
+- `audit-logs` — bảng `audit_logs` cho nhật ký thay đổi dữ liệu. Runtime:
+  `@goerp/core/audit` (`createAuditExtension` chộp tự động create/update/delete
+  ở tầng Prisma, `logEntityAction` ghi hành động nghiệp vụ, `withAuditContext`
+  đưa actor xuống) + trang admin `system/pages/system-audit-page`. YÊU CẦU
+  back-relation `auditLogs AuditLog[]` trên model `User` — xem
+  `features/audit-logs/README.md`.
 - `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/audit-logs/README.md

@@ -0,0 +1,18 @@
+# Feature: audit-logs
+
+Bảng `audit_logs` cho `@goerp/core/audit`: extension Prisma
+(`createAuditExtension`) chộp tự động create/update/delete, `logEntityAction`
+ghi hành động nghiệp vụ, trang admin `SystemAuditPage` đọc.
+
+**Yêu cầu phía app (Prisma bắt buộc 2 chiều relation):** model `User` phải khai
+
+```prisma
+auditLogs AuditLog[]
+```
+
+**Bảng người dùng phải tên `users`** — SQL neo FK `audit_logs.user_id → users.id`.
+
+**Trước khi bật extension, xem lại `skipModels`:** mặc định core đã bỏ qua bảng
+hạ tầng (audit/auth/log/task/notification). App còn bảng ghi dày kiểu hàng đợi
+tin nhắn thì khai thêm, không thì nhật ký nghiệp vụ bị rác nhấn chìm — đo ở
+vinhhoa: 67% số hàng audit 7 ngày là từ 1 bảng hàng đợi ZNS.

package/features/audit-logs/migrations/0001_init.sql

@@ -0,0 +1,33 @@
+-- goerp feature: audit-logs — bước 0001 (idempotent). Bảng `audit_logs` cho
+-- @goerp/core/audit: extension Prisma chộp create/update/delete tự động +
+-- logEntityAction ghi hành động nghiệp vụ, và trang admin SystemAuditPage đọc.
+-- 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 "audit_logs" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT,
+    "action" TEXT NOT NULL,
+    "resource" TEXT NOT NULL,
+    "resource_id" TEXT,
+    "old_data" JSONB,
+    "new_data" JSONB,
+    "ip_address" TEXT,
+    "user_agent" TEXT,
+    "description" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "audit_logs_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "audit_logs_user_id_idx" ON "audit_logs"("user_id");
+CREATE INDEX IF NOT EXISTS "audit_logs_action_idx" ON "audit_logs"("action");
+CREATE INDEX IF NOT EXISTS "audit_logs_resource_idx" ON "audit_logs"("resource");
+CREATE INDEX IF NOT EXISTS "audit_logs_created_at_idx" ON "audit_logs"("created_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 = 'audit_logs_user_id_fkey') THEN
+    ALTER TABLE "audit_logs" ADD CONSTRAINT "audit_logs_user_id_fkey"
+      FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+  END IF;
+END $$;

package/features/audit-logs/schema.prisma

@@ -0,0 +1,20 @@
+model AuditLog {
+  id          String   @id @default(cuid()) @map("id")
+  userId      String?  @map("user_id")
+  action      String   @map("action")
+  resource    String   @map("resource")
+  resourceId  String?  @map("resource_id")
+  oldData     Json?    @map("old_data")
+  newData     Json?    @map("new_data")
+  ipAddress   String?  @map("ip_address")
+  userAgent   String?  @map("user_agent")
+  description String?  @map("description")
+  createdAt   DateTime @default(now()) @map("created_at")
+  user        User?    @relation(fields: [userId], references: [id])
+
+  @@index([userId])
+  @@index([action])
+  @@index([resource])
+  @@index([createdAt])
+  @@map("audit_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.54",
+  "version": "0.1.55",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -81,7 +81,9 @@
     "./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",
+    "./system/pages/system-audit-page": "./src/system/pages/system-audit-page.tsx",
     "./cron": "./src/cron/index.ts",
+    "./audit": "./src/audit/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/audit/__tests__/audit-context.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { getAuditContext, withAuditContext } from "../audit-context";
+import { resolveAuditActor } from "../audit-actor";
+import { logEntityAction } from "../entity-audit";
+
+describe("withAuditContext / getAuditContext", () => {
+  it("ngoài context trả undefined (extension tự biết là không có actor)", () => {
+    expect(getAuditContext()).toBeUndefined();
+  });
+
+  it("giữ context xuyên qua await", async () => {
+    await withAuditContext(
+      { userId: "user-1", userName: "Nguyễn Văn A" },
+      async () => {
+        await Promise.resolve();
+        expect(getAuditContext()).toEqual({
+          userId: "user-1",
+          userName: "Nguyễn Văn A",
+        });
+      },
+    );
+  });
+
+  it("lồng nhau: thoát context trong thì context ngoài trở lại", async () => {
+    await withAuditContext({ userId: "outer" }, async () => {
+      expect(getAuditContext()?.userId).toBe("outer");
+      await withAuditContext({ userId: "inner" }, async () => {
+        expect(getAuditContext()?.userId).toBe("inner");
+      });
+      expect(getAuditContext()?.userId).toBe("outer");
+    });
+  });
+
+  it("trả về giá trị của fn và không nuốt lỗi", async () => {
+    await expect(
+      withAuditContext({ userId: "u" }, async () => 42),
+    ).resolves.toBe(42);
+    await expect(
+      withAuditContext({ userId: "u" }, async () => {
+        throw new Error("test error");
+      }),
+    ).rejects.toThrow("test error");
+  });
+});
+
+describe("resolveAuditActor", () => {
+  it("phiên thường: lấy id + tên người dùng", async () => {
+    await expect(
+      resolveAuditActor({
+        user: { id: "u1", name: "Kế toán", email: "kt@x.vn" },
+      }),
+    ).resolves.toEqual({ userId: "u1", userName: "Kế toán" });
+  });
+
+  it("không có tên thì rơi về email", async () => {
+    await expect(
+      resolveAuditActor({ user: { id: "u1", name: null, email: "kt@x.vn" } }),
+    ).resolves.toEqual({ userId: "u1", userName: "kt@x.vn" });
+  });
+
+  it("mạo danh: audit quy về ADMIN THẬT, không phải người bị mạo danh", async () => {
+    const resolveName = vi.fn().mockResolvedValue("Quản trị");
+
+    await expect(
+      resolveAuditActor(
+        { user: { id: "u-nv", name: "Nhân viên" }, impersonatedBy: "u-admin" },
+        resolveName,
+      ),
+    ).resolves.toEqual({
+      userId: "u-admin",
+      userName: "Quản trị (mạo danh Nhân viên)",
+    });
+    expect(resolveName).toHaveBeenCalledWith("u-admin");
+  });
+
+  it("tra tên admin hỏng vẫn ghi được actor", async () => {
+    await expect(
+      resolveAuditActor(
+        { user: { id: "u-nv", name: "Nhân viên" }, impersonatedBy: "u-admin" },
+        async () => {
+          throw new Error("DB down");
+        },
+      ),
+    ).resolves.toEqual({
+      userId: "u-admin",
+      userName: "Admin (mạo danh Nhân viên)",
+    });
+  });
+});
+
+describe("logEntityAction", () => {
+  const makeClient = () => ({
+    auditLog: { create: vi.fn().mockResolvedValue({ id: "a1" }) },
+  });
+
+  it("ghi qua ĐÚNG client được truyền (tx → rollback cùng nghiệp vụ)", async () => {
+    const tx = makeClient();
+    await logEntityAction({
+      resource: "sales-order",
+      resourceId: "so-1",
+      action: "confirm-payment",
+      description: "Xác nhận thanh toán",
+      userId: "u1",
+      userName: "Kế toán",
+      referenceNumber: "DH001",
+      newData: { amount: 500000 },
+      client: tx,
+    });
+
+    expect(tx.auditLog.create).toHaveBeenCalledWith({
+      data: {
+        action: "confirm-payment",
+        resource: "sales-order",
+        resourceId: "so-1",
+        userId: "u1",
+        description: "[Kế toán] Xác nhận thanh toán",
+        oldData: undefined,
+        newData: { amount: 500000, orderNumber: "DH001" },
+      },
+    });
+  });
+
+  it("không có userName thì mô tả giữ nguyên, không có tiền tố []", async () => {
+    const client = makeClient();
+    await logEntityAction({
+      resource: "sales-order",
+      resourceId: "so-1",
+      action: "cancel",
+      description: "Huỷ đơn",
+      client,
+    });
+
+    expect(client.auditLog.create.mock.calls[0][0].data.description).toBe(
+      "Huỷ đơn",
+    );
+  });
+
+  it("chỉ có số chứng từ vẫn nhét được vào newData để tra cứu", async () => {
+    const client = makeClient();
+    await logEntityAction({
+      resource: "purchase-order",
+      resourceId: "po-1",
+      action: "receive",
+      description: "Nhận hàng",
+      referenceNumber: "PN001",
+      client,
+    });
+
+    expect(client.auditLog.create.mock.calls[0][0].data.newData).toEqual({
+      orderNumber: "PN001",
+    });
+  });
+
+  it("audit hỏng KHÔNG throw ra nghiệp vụ", async () => {
+    const client = {
+      auditLog: { create: vi.fn().mockRejectedValue(new Error("DB fail")) },
+    };
+    const onError = vi.fn();
+
+    await expect(
+      logEntityAction({
+        resource: "sales-order",
+        resourceId: "so-1",
+        action: "cancel",
+        description: "Huỷ đơn",
+        client,
+        onError,
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(onError).toHaveBeenCalledWith(expect.any(Error));
+  });
+});