@goplusvn/core 0.1.54 → 0.1.56

package/PLATFORM.md

@@ -117,6 +117,50 @@ import { toCsv } from "@goerp/core/export/to-csv"           // server CSV routes
 return new Response(toCsv(rows, columns), { headers: { ... } })
 ```
 
+## Import
+
+One dialog for both server contracts — a workbook harness (`templateApiUrl`) or
+an EntityConfig-driven CRUD import (`config`). A `202` reply means the server
+queued a background task; the dialog closes instead of reporting "0 rows".
+
+```tsx
+import { ImportDialog } from "@goerp/core/import"
+
+<ImportDialog
+  apiUrl={`/api/purchase-orders/import`}
+  templateApiUrl={`/api/purchase-orders/import/template`}
+  tasksPath={`/${lang}/tasks`}      // where the 202 toast links to
+  canImport={can("purchase-orders", "create")}
+/>
+```
+
+The parsing half is pure and server-side — domain import services keep the DB
+work and call these:
+
+```ts
+import { parseExcelBuffer, validateHeaders, normalizeRow } from "@goerp/core/import"
+```
+
+`parseFlexibleDate` refuses impossible dates (`31/06`) instead of rolling them
+into the next month, and decodes Excel serials in UTC — local-time arithmetic is
+off by a day in zones with pre-1911 LMT offsets (Asia/Ho_Chi_Minh among them).
+
+Note: `@goerp/core/import` types carry a `Workbook` prefix
+(`WorkbookImportResult`, …) so they don't collide with the flat CRUD
+`ImportResult`/`ImportOptions` in `@goerp/core/types`.
+
+## Advanced filters
+
+The client half of the CRUD filter-tree DSL — nested AND/OR groups that
+serialize to the same `FilterTreeNode` the server query builder consumes.
+
+```tsx
+import { AdvancedFilterBuilder } from "@goerp/core/ui/filters/advanced-filter-builder"
+
+<AdvancedFilterBuilder fields={FIELDS} value={tree} onChange={setTree} />
+// tzOffset defaults to "+07:00": a date leaf means that zone's whole day
+```
+
 ## Print
 
 Core owns *how* to print; the app supplies *what* via `renderContent`.

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.56",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -47,6 +47,7 @@
     "./notification/ui": "./src/notification/ui/index.ts",
     "./tasks": "./src/tasks/index.ts",
     "./tasks/ui": "./src/tasks/ui/task-list-client.tsx",
+    "./import": "./src/import/index.ts",
     "./auth/proxy-gate": "./src/auth/proxy-gate.ts",
     "./rbac/route-handlers": "./src/rbac/route-handlers.ts",
     "./rbac/permissions-version": "./src/rbac/permissions-version.ts",
@@ -74,6 +75,7 @@
     "./ui/primitives/sidebar": "./src/ui/primitives/sidebar.tsx",
     "./ui/primitives/select": "./src/ui/primitives/select.tsx",
     "./ui/forms/multi-select": "./src/ui/forms/multi-select.tsx",
+    "./ui/filters/advanced-filter-builder": "./src/ui/filters/advanced-filter-builder.tsx",
     "./ui/data-display/collapsible": "./src/ui/data-display/collapsible.tsx",
     "./system/services/settings-service": "./src/system/services/settings-service.ts",
     "./system/services/system-category-service": "./src/system/services/system-category-service.ts",
@@ -81,7 +83,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));
+  });
+});