@goplusvn/core 0.1.53 → 0.1.55

package/features/README.md

@@ -34,8 +34,18 @@ GENERATED — đừng sửa tay) và tạo thư mục migration
 - `notifications` — bảng `notifications` + `push_subscriptions` cho thông báo
   in-app NHÂN VIÊN. Runtime: `@goerp/core/notification`
   (`configureNotificationService`, seam `afterNotify` để app cắm web push/email)
-  + UI `@goerp/core/notification/ui` (chuông + hộp thư). YÊU CẦU model `User`
+  và UI `@goerp/core/notification/ui` (chuông + hộp thư). YÊU CẦU model `User`
   của app khai back-relation — xem `features/notifications/README.md`.
+- `system-jobs` — bảng `system_jobs` + `job_execution_logs` cho cron có trạng
+  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/features/system-jobs/README.md

@@ -0,0 +1,40 @@
+# Feature: system-jobs
+
+Bảng `system_jobs` + `job_execution_logs` cho engine `@goerp/core/cron`
+(`configureCronManager`) và trang admin
+`@goerp/core/system/pages/system-jobs-page`.
+
+Không phụ thuộc model nào của app (không FK sang `users`) — sync xong là dùng
+được ngay.
+
+## Cắm vào app
+
+```ts
+// src/lib/cron.ts (hoặc nơi khởi tạo)
+import { configureCronManager, cronManager } from "@goerp/core/cron"
+import { db } from "@/lib/prisma"
+
+configureCronManager({ db })
+export { cronManager }
+
+// instrumentation.ts — đăng ký job
+cronManager.addJob({ name: "sync-gold-price", cronTime: "5m", onTick: syncGoldPrice })
+```
+
+Trong job, ghi diễn biến để trang admin xem lại được:
+
+```ts
+import { getJobExecutionContext } from "@goerp/core/cron"
+getJobExecutionContext()?.log("Đã đồng bộ", `${n} bản ghi`)
+```
+
+## API app phải cung cấp (trang admin gọi)
+
+- `GET  <apiUrl>` → `{ data: SystemJob[] }` (gộp `cronManager.getJobsInfo()`
+  với row DB, thêm cờ `inMemory`)
+- `POST <apiUrl>` `{ name, action: "toggle" | "run" | "remove" }`
+- `GET  <apiUrl>/<name>/history?skip&take` → `{ data, meta.total }`
+
+Mẫu chuẩn: vinhhoa `src/app/api/admin/system/jobs/`. Quyền do app gác
+(`apiHandler(..., { resource, action })`) — Permission Registry của app là
+nguồn sự thật.

package/features/system-jobs/migrations/0001_init.sql

@@ -0,0 +1,47 @@
+-- goerp feature: system-jobs — bước 0001 (idempotent). 2 bảng cho engine cron
+-- có trạng thái DB (@goerp/core/cron, configureCronManager) + trang admin
+-- SystemJobsPage: cấu hình job (bật/tắt, lịch) và lịch sử từng lần chạy.
+-- 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 "system_jobs" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "cron_time" TEXT NOT NULL,
+    "enabled" BOOLEAN NOT NULL DEFAULT true,
+    "last_run" TIMESTAMP(3),
+    "next_run" TIMESTAMP(3),
+    "status" TEXT NOT NULL DEFAULT 'idle',
+    "error" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    "metadata" JSONB,
+
+    CONSTRAINT "system_jobs_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "system_jobs_name_key" ON "system_jobs"("name");
+
+CREATE TABLE IF NOT EXISTS "job_execution_logs" (
+    "id" TEXT NOT NULL,
+    "job_name" TEXT NOT NULL,
+    "started_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "finished_at" TIMESTAMP(3),
+    "duration_ms" INTEGER,
+    "status" TEXT NOT NULL DEFAULT 'running',
+    "error" TEXT,
+    "actions" JSONB,
+    "summary" TEXT,
+
+    CONSTRAINT "job_execution_logs_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "job_execution_logs_job_name_idx" ON "job_execution_logs"("job_name");
+CREATE INDEX IF NOT EXISTS "job_execution_logs_started_at_idx" ON "job_execution_logs"("started_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 = 'job_execution_logs_job_name_fkey') THEN
+    ALTER TABLE "job_execution_logs" ADD CONSTRAINT "job_execution_logs_job_name_fkey"
+      FOREIGN KEY ("job_name") REFERENCES "system_jobs"("name") ON DELETE CASCADE ON UPDATE CASCADE;
+  END IF;
+END $$;

package/features/system-jobs/schema.prisma

@@ -0,0 +1,42 @@
+/// Job định kỳ có TRẠNG THÁI TRONG DB (engine `@goerp/core/cron`). DB là nguồn
+/// sự thật của cờ enabled + lịch chạy: admin tắt job thì deploy mới không tự
+/// bật lại, và restart tiến trình không mất cấu hình. `name` trùng tên đăng ký
+/// trong code (`cronManager.addJob({ name })`) nên là khoá tự nhiên.
+model SystemJob {
+  id            String            @id @default(cuid()) @map("id")
+  name          String            @unique @map("name")
+  cronTime      String            @map("cron_time") // "5m" | "1h" | "0 * * * *"
+  enabled       Boolean           @default(true) @map("enabled")
+  lastRun       DateTime?         @map("last_run")
+  nextRun       DateTime?         @map("next_run")
+  status        String            @default("idle") @map("status") // idle | running | failed
+  error         String?           @map("error") // lỗi lần chạy gần nhất (xoá khi chạy lại được)
+  createdAt     DateTime          @default(now()) @map("created_at")
+  updatedAt     DateTime          @updatedAt @map("updated_at")
+  metadata      Json?             @map("metadata")
+  executionLogs JobExecutionLog[]
+
+  @@map("system_jobs")
+}
+
+/// Một LẦN chạy của job: mở row lúc bắt đầu (status=running) và đóng lúc kết
+/// thúc. `actions` là nhật ký diễn biến do chính job ghi qua
+/// `getJobExecutionContext().log()` — thứ giúp admin biết job "chạy rồi" đã
+/// làm được gì, không chỉ thành công/thất bại.
+model JobExecutionLog {
+  id         String    @id @default(cuid()) @map("id")
+  jobName    String    @map("job_name")
+  startedAt  DateTime  @default(now()) @map("started_at")
+  finishedAt DateTime? @map("finished_at")
+  durationMs Int?      @map("duration_ms")
+  status     String    @default("running") @map("status") // running | success | failed
+  error      String?   @map("error")
+  actions    Json?     @map("actions") // [{ time, action, details? }]
+  summary    String?   @map("summary")
+
+  job SystemJob @relation(fields: [jobName], references: [name], onDelete: Cascade)
+
+  @@index([jobName])
+  @@index([startedAt])
+  @@map("job_execution_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.53",
+  "version": "0.1.55",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -80,6 +80,10 @@
     "./system/pages/system-settings-page": "./src/system/pages/system-settings-page.tsx",
     "./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));
+  });
+});