@goplusvn/core 0.1.49 → 0.1.51

package/bin/goerp-features.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// CLI `goerp-features` — đồng bộ feature CÓ BẢNG DB của @goerp/core vào app.
+//
+//   pnpm goerp-features status          # feature/bước nào còn thiếu
+//   pnpm goerp-features sync            # copy schema + materialize migrations
+//   pnpm goerp-features sync --only background-tasks
+//
+// Sau sync: chạy `pnpm prisma migrate deploy` (flow deploy hiện có) rồi
+// `pnpm prisma generate`. SQL của core viết IDEMPOTENT nên app đã có bảng
+// từ trước chạy lại vô hại.
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { featureStatus, syncFeatures } from "../scripts/feature-sync.mjs";
+
+const featuresRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "features");
+const appRoot = process.cwd();
+
+const [, , command = "status", ...rest] = process.argv;
+const onlyIdx = rest.indexOf("--only");
+const only = onlyIdx >= 0 ? rest.slice(onlyIdx + 1).filter((a) => !a.startsWith("-")) : undefined;
+
+if (command === "status") {
+  const statuses = featureStatus({ featuresRoot, appRoot });
+  if (statuses.length === 0) {
+    console.log("Không có feature nào trong @goerp/core/features.");
+    process.exit(0);
+  }
+  for (const f of statuses) {
+    const pending = f.steps.filter((s) => !s.materialized).length;
+    console.log(
+      `${pending === 0 && (!f.hasSchema || f.schemaSynced) ? "✓" : "•"} ${f.feature}` +
+        `  (schema: ${f.hasSchema ? (f.schemaSynced ? "đã sync" : "CHƯA sync") : "—"};` +
+        ` migrations: ${f.steps.length - pending}/${f.steps.length})`
+    );
+    for (const s of f.steps.filter((s) => !s.materialized)) {
+      console.log(`    ↳ thiếu bước ${s.num}_${s.slug}`);
+    }
+  }
+  process.exit(0);
+}
+
+if (command === "sync") {
+  const actions = syncFeatures({ featuresRoot, appRoot, only });
+  if (actions.length === 0) {
+    console.log("✓ Không có gì để sync — app đã đủ schema + migrations.");
+  } else {
+    for (const a of actions) {
+      if (a.type === "schema") console.log(`✓ schema  ${a.feature} → ${a.target}`);
+      else console.log(`✓ migrate ${a.feature} + ${a.step} → prisma/migrations/${a.dir}`);
+    }
+    console.log(
+      "\nTiếp theo: pnpm prisma migrate deploy && pnpm prisma generate"
+    );
+  }
+  process.exit(0);
+}
+
+console.error(`Lệnh không hợp lệ: ${command}. Dùng: status | sync [--only <feature>…]`);
+process.exit(1);

package/features/README.md

@@ -0,0 +1,33 @@
+# @goerp/core features — tính năng có bảng DB
+
+Mỗi thư mục con là một feature core ship kèm **bảng DB**. App tiêu thụ chạy:
+
+```bash
+pnpm goerp-features status   # xem thiếu gì
+pnpm goerp-features sync     # copy schema + materialize migrations
+pnpm prisma migrate deploy && pnpm prisma generate
+```
+
+`sync` copy `schema.prisma` → `prisma/schema/goerp-<feature>.prisma` (file
+GENERATED — đừng sửa tay) và tạo thư mục migration
+`<timestamp>_goerp_<feature>_<NNN>_<slug>/` cho bước nào app chưa có. App giữ
+**một** hệ migration duy nhất (`prisma migrate deploy`), không có DDL lúc boot.
+
+## Luật viết feature (tác giả core PHẢI theo)
+
+1. **SQL idempotent tuyệt đối** — `CREATE TABLE IF NOT EXISTS`,
+   `CREATE INDEX IF NOT EXISTS`, `ALTER TABLE … ADD COLUMN IF NOT EXISTS`.
+   Lý do: app từng tự tạo bảng bằng migration tay (vinhhoa) chạy lại phải vô hại.
+2. **Bước đã publish là BẤT BIẾN** — không sửa file `NNN_*.sql` cũ; đổi schema
+   thì thêm bước mới `NNN+1_*.sql` (và cập nhật `schema.prisma` fragment khớp).
+3. Tên bước: `NNN_slug.sql` (NNN ≥ 3 chữ số, slug kebab-case).
+4. `schema.prisma` fragment chỉ chứa model của feature này, dùng `@map`/`@@map`
+   snake_case như convention chung.
+5. Feature cần seed/RBAC: ghi rõ trong README của feature — seed chạy phía app
+   (Permission Registry của app là nguồn sự thật quyền).
+
+## Feature hiện có
+
+- `background-tasks` — bảng `background_tasks` cho trung tâm tác vụ nền
+  (export/import chạy nền). Runtime hiện ở app (vinhhoa `src/server/tasks`);
+  sẽ dời lên core ở đợt F1.

package/features/background-tasks/migrations/0001_init.sql

@@ -0,0 +1,23 @@
+-- goerp feature: background-tasks — bước 0001 (idempotent: app đã tự tạo bảng
+-- từ trước chạy lại vô hại; quy ước MỌI bước SQL của core đều IF NOT EXISTS).
+CREATE TABLE IF NOT EXISTS "background_tasks" (
+    "id" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'pending',
+    "progress" INTEGER NOT NULL DEFAULT 0,
+    "params" JSONB,
+    "result" JSONB,
+    "error" TEXT,
+    "created_by" TEXT NOT NULL,
+    "branch_id" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "started_at" TIMESTAMP(3),
+    "finished_at" TIMESTAMP(3),
+
+    CONSTRAINT "background_tasks_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "background_tasks_created_by_created_at_idx" ON "background_tasks"("created_by", "created_at");
+
+CREATE INDEX IF NOT EXISTS "background_tasks_status_idx" ON "background_tasks"("status");

package/features/background-tasks/schema.prisma

@@ -0,0 +1,22 @@
+// Tác vụ nền (export/import lớn…): hàng đợi trong DB, worker in-process.
+// status: pending → running → success | error.
+// result: { fileKey?, fileName?, rowCount?, errorFileKey?, summary? }.
+model BackgroundTask {
+  id         String    @id @default(cuid()) @map("id")
+  type       String    @map("type")
+  title      String    @map("title")
+  status     String    @default("pending") @map("status")
+  progress   Int       @default(0) @map("progress")
+  params     Json?     @map("params")
+  result     Json?     @map("result")
+  error      String?   @map("error")
+  createdBy  String    @map("created_by")
+  branchId   String?   @map("branch_id")
+  createdAt  DateTime  @default(now()) @map("created_at")
+  startedAt  DateTime? @map("started_at")
+  finishedAt DateTime? @map("finished_at")
+
+  @@index([createdBy, createdAt])
+  @@index([status])
+  @@map("background_tasks")
+}

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.49",
+  "version": "0.1.51",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -11,8 +11,14 @@
   "module": "./src/index.ts",
   "types": "./src/index.ts",
   "sideEffects": false,
+  "bin": {
+    "goerp-features": "./bin/goerp-features.mjs"
+  },
   "files": [
     "src",
+    "bin",
+    "scripts",
+    "features",
     "README.md",
     "CHANGELOG.md",
     "PLATFORM.md"
@@ -37,6 +43,8 @@
     "./assets/*": "./src/assets/*",
     "./styles/*": "./src/styles/*",
     "./auth/api-handler": "./src/auth/api-handler.ts",
+    "./tasks": "./src/tasks/index.ts",
+    "./tasks/ui": "./src/tasks/ui/task-list-client.tsx",
     "./auth/proxy-gate": "./src/auth/proxy-gate.ts",
     "./rbac/route-handlers": "./src/rbac/route-handlers.ts",
     "./rbac/permissions-version": "./src/rbac/permissions-version.ts",

package/scripts/feature-sync.mjs

@@ -0,0 +1,145 @@
+// Feature sync — bộ máy cho CLI `goerp-features` (bin/goerp-features.mjs).
+//
+// BÀI TOÁN: @goerp/core ship tính năng CÓ BẢNG DB (background-tasks,
+// notifications, error-logs…) qua npm; mỗi app tiêu thụ (vinhhoa, thingtodo,
+// app init mới) trước đây phải chép tay schema + migration → thiếu sót, lệch.
+//
+// THIẾT KẾ (chọn "materialize vào prisma/migrations của app" thay vì ledger
+// runtime kiểu NocoBase — không DDL lúc boot, app giữ MỘT hệ migration duy
+// nhất `prisma migrate deploy`):
+//   - Core ship mỗi feature tại features/<name>/:
+//       schema.prisma            — fragment model (copy vào schema dir của app)
+//       migrations/NNN_slug.sql  — bước SQL đánh số, PHẢI viết IDEMPOTENT
+//                                  (CREATE TABLE IF NOT EXISTS…) để app đã có
+//                                  bảng từ trước (vinhhoa) chạy lại vô hại.
+//   - `sync`: copy fragment → prisma/schema/goerp-<feature>.prisma (đè, có
+//     header GENERATED) + với mỗi bước CHƯA materialize, tạo thư mục
+//     <timestamp>_goerp_<feature>_<NNN>_<slug>/migration.sql. Nhận bước đã
+//     materialize bằng ĐUÔI TÊN (bỏ qua timestamp) nên chạy lại idempotent.
+//   - `status`: liệt kê feature/bước, cái nào pending.
+//
+// Logic thuần (fs qua tham số path) để unit-test được bằng vitest trên tmp dir.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** features/<name>/migrations/NNN_slug.sql → [{num, slug, file}] theo thứ tự. */
+export function listFeatureSteps(featureDir) {
+  const dir = join(featureDir, "migrations");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /^\d{3,}_[a-z0-9-]+\.sql$/.test(f))
+    .sort()
+    .map((f) => {
+      const m = f.match(/^(\d{3,})_([a-z0-9-]+)\.sql$/);
+      return { num: m[1], slug: m[2], file: join(dir, f) };
+    });
+}
+
+/** Tên mọi feature trong thư mục features/ của core. */
+export function listFeatures(featuresRoot) {
+  if (!existsSync(featuresRoot)) return [];
+  return readdirSync(featuresRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+/** Đuôi định danh của một bước — phần tên KHÔNG đổi giữa các app/timestamp. */
+export function stepDirSuffix(feature, step) {
+  return `goerp_${feature.replace(/-/g, "_")}_${step.num}_${step.slug.replace(/-/g, "_")}`;
+}
+
+/** Bước đã được materialize vào prisma/migrations của app chưa? */
+export function isStepMaterialized(appMigrationsDir, feature, step) {
+  if (!existsSync(appMigrationsDir)) return false;
+  const suffix = `_${stepDirSuffix(feature, step)}`;
+  return readdirSync(appMigrationsDir).some((d) => d.endsWith(suffix));
+}
+
+/**
+ * Timestamp prefix kiểu prisma (YYYYMMDDHHMMSS). `offset` giây cộng thêm để
+ * nhiều bước sinh trong cùng lần sync giữ đúng thứ tự.
+ */
+export function migrationTimestamp(now, offset = 0) {
+  const d = new Date(now.getTime() + offset * 1000);
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return (
+    `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}` +
+    `${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`
+  );
+}
+
+/**
+ * Trạng thái toàn bộ feature so với một app.
+ * → [{feature, steps: [{num, slug, materialized}] , schemaTarget, schemaSynced}]
+ */
+export function featureStatus({ featuresRoot, appRoot }) {
+  const migrationsDir = join(appRoot, "prisma", "migrations");
+  return listFeatures(featuresRoot).map((feature) => {
+    const featureDir = join(featuresRoot, feature);
+    const schemaSource = join(featureDir, "schema.prisma");
+    const schemaTarget = join(appRoot, "prisma", "schema", `goerp-${feature}.prisma`);
+    const schemaSynced =
+      existsSync(schemaSource) &&
+      existsSync(schemaTarget) &&
+      readFileSync(schemaTarget, "utf8").includes(readFileSync(schemaSource, "utf8").trim());
+    return {
+      feature,
+      hasSchema: existsSync(schemaSource),
+      schemaTarget,
+      schemaSynced,
+      steps: listFeatureSteps(featureDir).map((step) => ({
+        ...step,
+        materialized: isStepMaterialized(migrationsDir, feature, step),
+      })),
+    };
+  });
+}
+
+const GENERATED_HEADER = (feature) =>
+  `// GENERATED từ @goerp/core (features/${feature}/schema.prisma) — ĐỪNG sửa tay.\n` +
+  `// Nâng cấp core xong chạy: pnpm goerp-features sync\n\n`;
+
+/**
+ * Đồng bộ 1 app: copy schema fragments + materialize các bước SQL còn thiếu.
+ * Trả về log hành động (để CLI in + test assert). KHÔNG chạy prisma — app tự
+ * `prisma migrate deploy` (giữ nguyên flow deploy hiện có).
+ *
+ * @param {{ featuresRoot: string, appRoot: string, now?: Date, only?: string[] }} options
+ */
+export function syncFeatures({ featuresRoot, appRoot, now = new Date(), only = [] }) {
+  const actions = [];
+  const migrationsDir = join(appRoot, "prisma", "migrations");
+  let offset = 0;
+
+  for (const feature of listFeatures(featuresRoot)) {
+    if (only.length > 0 && !only.includes(feature)) continue;
+    const featureDir = join(featuresRoot, feature);
+
+    // 1) Schema fragment → prisma/schema/goerp-<feature>.prisma (đè)
+    const schemaSource = join(featureDir, "schema.prisma");
+    if (existsSync(schemaSource)) {
+      const schemaDir = join(appRoot, "prisma", "schema");
+      mkdirSync(schemaDir, { recursive: true });
+      const target = join(schemaDir, `goerp-${feature}.prisma`);
+      const content = GENERATED_HEADER(feature) + readFileSync(schemaSource, "utf8");
+      const changed = !existsSync(target) || readFileSync(target, "utf8") !== content;
+      if (changed) {
+        writeFileSync(target, content);
+        actions.push({ type: "schema", feature, target });
+      }
+    }
+
+    // 2) Materialize các bước SQL chưa có
+    for (const step of listFeatureSteps(featureDir)) {
+      if (isStepMaterialized(migrationsDir, feature, step)) continue;
+      const dirName = `${migrationTimestamp(now, offset++)}_${stepDirSuffix(feature, step)}`;
+      const dir = join(migrationsDir, dirName);
+      mkdirSync(dir, { recursive: true });
+      cpSync(step.file, join(dir, "migration.sql"));
+      actions.push({ type: "migration", feature, step: `${step.num}_${step.slug}`, dir: dirName });
+    }
+  }
+  return actions;
+}

package/src/features/__tests__/feature-sync.test.ts

@@ -0,0 +1,135 @@
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { featureStatus, migrationTimestamp, syncFeatures } from "../../../scripts/feature-sync.mjs";
+
+let featuresRoot: string;
+let appRoot: string;
+
+function writeFeature(name: string, steps: Record<string, string>, schema?: string) {
+  const dir = join(featuresRoot, name);
+  mkdirSync(join(dir, "migrations"), { recursive: true });
+  if (schema) writeFileSync(join(dir, "schema.prisma"), schema);
+  for (const [file, sql] of Object.entries(steps)) {
+    writeFileSync(join(dir, "migrations", file), sql);
+  }
+}
+
+beforeEach(() => {
+  featuresRoot = mkdtempSync(join(tmpdir(), "goerp-features-"));
+  appRoot = mkdtempSync(join(tmpdir(), "goerp-app-"));
+  mkdirSync(join(appRoot, "prisma", "migrations"), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(featuresRoot, { recursive: true, force: true });
+  rmSync(appRoot, { recursive: true, force: true });
+});
+
+describe("syncFeatures", () => {
+  it("materialize schema fragment + bước SQL vào app trắng", () => {
+    writeFeature(
+      "background-tasks",
+      { "0001_init.sql": "CREATE TABLE IF NOT EXISTS t(id text);" },
+      "model BackgroundTask { id String @id }"
+    );
+
+    const actions = syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+    expect(actions.map((a: { type: string }) => a.type)).toEqual(["schema", "migration"])
+
+    // Schema fragment có header GENERATED
+    const schema = readFileSync(
+      join(appRoot, "prisma", "schema", "goerp-background-tasks.prisma"),
+      "utf8"
+    )
+    expect(schema).toContain("GENERATED từ @goerp/core")
+    expect(schema).toContain("model BackgroundTask")
+
+    // Migration folder đúng tên <ts>_goerp_<feature>_<step>
+    const dirs = readdirSync(join(appRoot, "prisma", "migrations"))
+    expect(dirs).toEqual(["20260731000000_goerp_background_tasks_0001_init"])
+    expect(
+      readFileSync(
+        join(appRoot, "prisma", "migrations", dirs[0], "migration.sql"),
+        "utf8"
+      )
+    ).toContain("CREATE TABLE IF NOT EXISTS")
+  })
+
+  it("idempotent: sync lần 2 không tạo gì thêm (bất kể timestamp khác)", () => {
+    writeFeature("background-tasks", { "0001_init.sql": "SELECT 1;" })
+    syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+    const again = syncFeatures({ featuresRoot, appRoot, now: new Date("2026-08-01T09:09:09Z") })
+    expect(again).toEqual([])
+    expect(readdirSync(join(appRoot, "prisma", "migrations"))).toHaveLength(1)
+  })
+
+  it("nâng cấp core thêm bước mới → chỉ materialize bước thiếu, giữ thứ tự", () => {
+    writeFeature("background-tasks", { "0001_init.sql": "SELECT 1;" })
+    syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+
+    writeFileSync(
+      join(featuresRoot, "background-tasks", "migrations", "0002_add-col.sql"),
+      "ALTER TABLE t ADD COLUMN IF NOT EXISTS x text;"
+    )
+    const actions = syncFeatures({ featuresRoot, appRoot, now: new Date("2026-08-02T00:00:00Z") })
+    expect(actions).toHaveLength(1)
+    expect(actions[0].step).toBe("0002_add-col")
+
+    const dirs = readdirSync(join(appRoot, "prisma", "migrations")).sort()
+    expect(dirs[0]).toContain("0001_init")
+    expect(dirs[1]).toContain("0002_add_col")
+  })
+
+  it("nhiều bước trong 1 lần sync giữ thứ tự qua timestamp tăng dần", () => {
+    writeFeature("f-a", { "0001_one.sql": "SELECT 1;", "0002_two.sql": "SELECT 2;" })
+    syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+    const dirs = readdirSync(join(appRoot, "prisma", "migrations")).sort()
+    expect(dirs[0]).toContain("0001_one")
+    expect(dirs[1]).toContain("0002_two")
+    expect(dirs[0] < dirs[1]).toBe(true)
+  })
+
+  it("--only giới hạn feature; schema đổi nội dung thì được ghi đè", () => {
+    writeFeature("f-a", { "0001_a.sql": "SELECT 1;" }, "model A { id String @id }")
+    writeFeature("f-b", { "0001_b.sql": "SELECT 1;" })
+    const actions = syncFeatures({ featuresRoot, appRoot, only: ["f-a"] })
+    expect(actions.every((a: { feature: string }) => a.feature === "f-a")).toBe(true)
+
+    // core bump: schema fragment đổi → sync ghi đè bản GENERATED
+    writeFileSync(
+      join(featuresRoot, "f-a", "schema.prisma"),
+      "model A { id String @id\n  extra String? }"
+    )
+    const again = syncFeatures({ featuresRoot, appRoot, only: ["f-a"] })
+    expect(again.some((a: { type: string }) => a.type === "schema")).toBe(true)
+    expect(
+      readFileSync(join(appRoot, "prisma", "schema", "goerp-f-a.prisma"), "utf8")
+    ).toContain("extra String?")
+  })
+})
+
+describe("featureStatus", () => {
+  it("báo pending trước sync, đủ sau sync", () => {
+    writeFeature("f-a", { "0001_a.sql": "SELECT 1;" }, "model A { id String @id }")
+    let status = featureStatus({ featuresRoot, appRoot })
+    expect(status[0].steps[0].materialized).toBe(false)
+    expect(status[0].schemaSynced).toBe(false)
+
+    syncFeatures({ featuresRoot, appRoot })
+    status = featureStatus({ featuresRoot, appRoot })
+    expect(status[0].steps[0].materialized).toBe(true)
+    expect(status[0].schemaSynced).toBe(true)
+  })
+})
+
+describe("migrationTimestamp", () => {
+  it("dạng YYYYMMDDHHMMSS UTC + offset giây", () => {
+    const now = new Date("2026-07-31T01:02:03Z")
+    expect(migrationTimestamp(now)).toBe("20260731010203")
+    expect(migrationTimestamp(now, 2)).toBe("20260731010205")
+  })
+})

package/src/tasks/__tests__/task-runner.test.ts

@@ -0,0 +1,213 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  configureTaskRunner,
+  enqueueTask,
+  readTaskFile,
+  reclaimStaleTasks,
+  registerTaskHandler,
+  saveTaskFile,
+  type TaskDb,
+  type TaskNotifyInput,
+} from "../task-runner";
+
+function makeDb(overrides: Partial<Record<string, unknown>> = {}) {
+  const rows = new Map<string, Record<string, unknown>>();
+  let seq = 0;
+  const db = {
+    backgroundTask: {
+      create: vi.fn(async ({ data }: { data: Record<string, unknown> }) => {
+        const id = `t${++seq}`;
+        const row = { id, status: "pending", ...data };
+        rows.set(id, row);
+        return row;
+      }),
+      update: vi.fn(
+        async ({
+          where,
+          data,
+        }: {
+          where: { id: string };
+          data: Record<string, unknown>;
+        }) => {
+          const row = rows.get(where.id);
+          if (row) Object.assign(row, data);
+          return row;
+        },
+      ),
+      updateMany: vi.fn(
+        async ({
+          where,
+          data,
+        }: {
+          where: Record<string, unknown>;
+          data: Record<string, unknown>;
+        }) => {
+          let count = 0;
+          for (const row of rows.values()) {
+            const statusCond = where.status as
+              | string
+              | { in: string[] }
+              | undefined;
+            const statusOk =
+              statusCond === undefined ||
+              (typeof statusCond === "string"
+                ? row.status === statusCond
+                : (statusCond.in as string[]).includes(row.status as string));
+            const idOk = where.id === undefined || row.id === where.id;
+            if (statusOk && idOk) {
+              Object.assign(row, data);
+              count++;
+            }
+          }
+          return { count };
+        },
+      ),
+      findUnique: vi.fn(async ({ where }: { where: { id: string } }) => {
+        return rows.get(where.id) ?? null;
+      }),
+      ...overrides,
+    },
+    __rows: rows,
+  };
+  return db as unknown as TaskDb & { __rows: Map<string, Record<string, unknown>> };
+}
+
+const flush = () => new Promise((r) => setTimeout(r, 10));
+
+describe("task-runner", () => {
+  let notifications: TaskNotifyInput[];
+
+  beforeEach(() => {
+    notifications = [];
+  });
+
+  it("chưa configure → enqueue throw với hướng dẫn", async () => {
+    // Reset config bằng cách configure với db hợp lệ SAU test này — ở đây
+    // module có thể đã được configure bởi test khác nên chỉ chạy khi chưa có.
+    // (Thứ tự an toàn: test này đứng đầu file, config module-level còn null.)
+    await expect(
+      enqueueTask({ type: "x", title: "x", createdBy: "u1" }),
+    ).rejects.toThrow(/configureTaskRunner/);
+  });
+
+  it("enqueue → handler chạy, success + progress 100 + notify có link tải", async () => {
+    const db = makeDb();
+    configureTaskRunner({
+      db,
+      notify: async (n) => {
+        notifications.push(n);
+      },
+    });
+    registerTaskHandler("demo:ok", async ({ setProgress }) => {
+      await setProgress(50);
+      return { fileKey: "local:a.xlsx", fileName: "a.xlsx", rowCount: 3 };
+    });
+
+    const task = await enqueueTask({
+      type: "demo:ok",
+      title: "Xuất demo",
+      createdBy: "u1",
+    });
+    await flush();
+
+    const row = db.__rows.get(task.id)!;
+    expect(row.status).toBe("success");
+    expect(row.progress).toBe(100);
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].type).toBe("success");
+    expect(notifications[0].url).toBe(`/api/tasks/${task.id}/download`);
+  });
+
+  it("handler throw → status error + notify thất bại", async () => {
+    const db = makeDb();
+    configureTaskRunner({
+      db,
+      notify: async (n) => {
+        notifications.push(n);
+      },
+    });
+    registerTaskHandler("demo:boom", async () => {
+      throw new Error("nổ có chủ đích");
+    });
+
+    const task = await enqueueTask({
+      type: "demo:boom",
+      title: "Nổ",
+      createdBy: "u1",
+    });
+    await flush();
+
+    const row = db.__rows.get(task.id)!;
+    expect(row.status).toBe("error");
+    expect(row.error).toBe("nổ có chủ đích");
+    expect(notifications[0].type).toBe("error");
+  });
+
+  it("kết quả chỉ có errorFileKey (import lỗi) → notify warning + link ?file=error", async () => {
+    const db = makeDb();
+    configureTaskRunner({
+      db,
+      notify: async (n) => {
+        notifications.push(n);
+      },
+    });
+    registerTaskHandler("demo:import-err", async () => ({
+      errorFileKey: "local:loi.xlsx",
+      summary: "3 dòng lỗi",
+    }));
+
+    const task = await enqueueTask({
+      type: "demo:import-err",
+      title: "Nhập demo",
+      createdBy: "u1",
+    });
+    await flush();
+
+    expect(notifications[0].type).toBe("warning");
+    expect(notifications[0].url).toBe(
+      `/api/tasks/${task.id}/download?file=error`,
+    );
+  });
+
+  it("type chưa đăng ký → enqueue throw ngay (không tạo row)", async () => {
+    const db = makeDb();
+    configureTaskRunner({ db });
+    await expect(
+      enqueueTask({ type: "demo:missing", title: "x", createdBy: "u1" }),
+    ).rejects.toThrow(/chưa đăng ký/);
+    expect(db.__rows.size).toBe(0);
+  });
+
+  it("reclaimStaleTasks: pending/running mồ côi → error", async () => {
+    const db = makeDb();
+    configureTaskRunner({ db });
+    db.__rows.set("stale1", { id: "stale1", status: "running" });
+    db.__rows.set("stale2", { id: "stale2", status: "pending" });
+    db.__rows.set("done", { id: "done", status: "success" });
+
+    await reclaimStaleTasks();
+
+    expect(db.__rows.get("stale1")!.status).toBe("error");
+    expect(db.__rows.get("stale2")!.status).toBe("error");
+    expect(db.__rows.get("done")!.status).toBe("success");
+  });
+
+  it("storage seam: có storage thì save/read đi qua storage", async () => {
+    const store = new Map<string, Buffer>();
+    configureTaskRunner({
+      db: makeDb(),
+      storage: {
+        save: async (buf, key) => {
+          store.set(`s3:${key}`, buf);
+          return `s3:${key}`;
+        },
+        read: async (key) => store.get(key)!,
+      },
+    });
+
+    const key = await saveTaskFile(Buffer.from("abc"), "x/y.xlsx", "app/x");
+    expect(key).toBe("s3:x/y.xlsx");
+    expect((await readTaskFile(key)).toString()).toBe("abc");
+  });
+});

package/src/tasks/index.ts

@@ -0,0 +1,19 @@
+// Trung tâm tác vụ nền — engine dùng chung. Bảng đi kèm ship qua
+// `goerp-features sync` (feature background-tasks). App wiring mẫu: vinhhoa
+// src/server/tasks (configureTaskRunner + handlers + routes /api/tasks).
+export {
+  configureTaskRunner,
+  enqueueTask,
+  readTaskFile,
+  reclaimStaleTasks,
+  registerTaskHandler,
+  saveTaskFile,
+  type EnqueueInput,
+  type TaskContext,
+  type TaskDb,
+  type TaskFileResult,
+  type TaskHandler,
+  type TaskNotifyInput,
+  type TaskRecord,
+  type TaskStorage,
+} from "./task-runner";

package/src/tasks/task-runner.ts

@@ -0,0 +1,307 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+
+/**
+ * Trung tâm tác vụ nền — engine dùng chung cho mọi app goerp (bảng
+ * `background_tasks` ship qua `goerp-features sync`, feature background-tasks).
+ *
+ * Hàng đợi trong DB, worker IN-PROCESS: enqueue xong là `void runTask(id)`
+ * ngay trong container đang phục vụ request (deploy 1 container — không cần
+ * queue ngoài). Vòng đời: pending → running (CAS updateMany, chống chạy đôi)
+ * → success | error. Server restart giữa chừng → `reclaimStaleTasks()` (gọi
+ * từ instrumentation) đánh dấu error để user chạy lại.
+ *
+ * App cắm phụ thuộc qua `configureTaskRunner` (cùng khuôn
+ * `configureSettingsService`): db (Prisma client có model BackgroundTask),
+ * notify (chuông/push — tuỳ chọn), storage (S3/MinIO — tuỳ chọn, mặc định
+ * thư mục local PRIVATE, KHÔNG để trong public/).
+ */
+
+export interface TaskFileResult {
+  fileKey?: string;
+  fileName?: string;
+  contentType?: string;
+  rowCount?: number;
+  errorFileKey?: string;
+  errorFileName?: string;
+  summary?: string;
+}
+
+export interface TaskContext {
+  taskId: string;
+  params: unknown;
+  /** Cập nhật % tiến độ (0–100) — throttle sẵn, gọi thoải mái theo chunk. */
+  setProgress: (percent: number) => Promise<void>;
+}
+
+export type TaskHandler = (ctx: TaskContext) => Promise<TaskFileResult>;
+
+export interface TaskRecord {
+  id: string;
+  type: string;
+  title: string;
+  status: string;
+  params: unknown;
+  createdBy: string;
+}
+
+/**
+ * Delegate Prisma tối thiểu — structural, args nới thành `any` CÓ CHỦ ĐÍCH:
+ * client Prisma sinh ra của app có kiểu args HẸP hơn (contravariance) nên
+ * khai chặt ở đây sẽ không assignable (cùng bài học SettingsDb).
+ */
+export interface TaskDb {
+  backgroundTask: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    create(args: any): Promise<TaskRecord>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    update(args: any): Promise<unknown>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    updateMany(args: any): Promise<{ count: number }>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findUnique(args: any): Promise<TaskRecord | null>;
+  };
+}
+
+export interface TaskNotifyInput {
+  userIds: string[];
+  type: "success" | "error" | "warning" | "info";
+  category: string;
+  title: string;
+  content: string;
+  url?: string;
+  resourceType?: string;
+  resourceId?: string;
+}
+
+export interface TaskStorage {
+  /** Trả key đã lưu, hoặc `null` = "để core fallback local" (vd S3 đang tắt). */
+  save(buffer: Buffer, key: string, contentType: string): Promise<string | null>;
+  /** Chỉ được gọi cho key KHÔNG phải `local:` — key local core tự đọc. */
+  read(fileKey: string): Promise<Buffer>;
+}
+
+interface TaskRunnerConfig {
+  db: TaskDb;
+  /** Báo chuông/push khi task xong-lỗi — bỏ trống thì im lặng. */
+  notify?: (input: TaskNotifyInput) => Promise<unknown>;
+  /** Kho file kết quả — bỏ trống dùng thư mục local `localDir`. */
+  storage?: TaskStorage;
+  /** Thư mục fallback local (mặc định <cwd>/storage/task-files). */
+  localDir?: string;
+}
+
+let config: TaskRunnerConfig | null = null;
+
+export function configureTaskRunner(next: TaskRunnerConfig): void {
+  config = next;
+}
+
+function requireConfig(): TaskRunnerConfig {
+  if (!config) {
+    throw new Error(
+      "[tasks] chưa configureTaskRunner({ db, notify?, storage? }) — gọi 1 lần lúc khởi tạo app (cạnh configureSettingsService).",
+    );
+  }
+  return config;
+}
+
+const registry = new Map<string, TaskHandler>();
+
+export function registerTaskHandler(type: string, handler: TaskHandler): void {
+  registry.set(type, handler);
+}
+
+export interface EnqueueInput {
+  type: string;
+  title: string;
+  params?: unknown;
+  createdBy: string;
+  branchId?: string | null;
+}
+
+/**
+ * Tạo task + chạy ngay trong process (fire-and-forget). AUTHORIZE TRƯỚC KHI
+ * GỌI: worker chạy ngoài request nên không còn session — mọi giới hạn quyền
+ * (scope chi nhánh, quyền xem giá vốn…) phải được snapshot vào `params`.
+ */
+export async function enqueueTask(input: EnqueueInput): Promise<TaskRecord> {
+  const { db } = requireConfig();
+  if (!registry.has(input.type)) {
+    throw new Error(`[tasks] type "${input.type}" chưa đăng ký handler`);
+  }
+  const task = await db.backgroundTask.create({
+    data: {
+      type: input.type,
+      title: input.title,
+      params: input.params ?? undefined,
+      createdBy: input.createdBy,
+      branchId: input.branchId ?? null,
+    },
+  });
+  void runTask(task.id);
+  return task;
+}
+
+async function runTask(id: string): Promise<void> {
+  const { db } = requireConfig();
+  // CAS pending→running: chỉ một luồng thắng (chống double-run khi retry).
+  const claimed = await db.backgroundTask.updateMany({
+    where: { id, status: "pending" },
+    data: { status: "running", startedAt: new Date() },
+  });
+  if (claimed.count === 0) return;
+
+  const task = await db.backgroundTask.findUnique({ where: { id } });
+  if (!task) return;
+  const handler = registry.get(task.type);
+
+  try {
+    if (!handler) {
+      throw new Error(`[tasks] type "${task.type}" chưa đăng ký handler`);
+    }
+
+    let lastWrite = 0;
+    const setProgress = async (percent: number) => {
+      const now = Date.now();
+      if (now - lastWrite < 500) return; // throttle ghi DB
+      lastWrite = now;
+      await db.backgroundTask.update({
+        where: { id },
+        data: { progress: Math.max(0, Math.min(99, Math.round(percent))) },
+      });
+    };
+
+    const result = await handler({
+      taskId: id,
+      params: task.params,
+      setProgress,
+    });
+
+    await db.backgroundTask.update({
+      where: { id },
+      data: {
+        status: "success",
+        progress: 100,
+        result: result as unknown as Record<string, unknown>,
+        finishedAt: new Date(),
+      },
+    });
+    await notifyTaskDone(task.createdBy, id, task.title, result);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[tasks] ${task.type} (${id}) lỗi:`, error);
+    await db.backgroundTask
+      .update({
+        where: { id },
+        data: {
+          status: "error",
+          error: message || "Tác vụ thất bại",
+          finishedAt: new Date(),
+        },
+      })
+      .catch(() => {});
+    await notifyTaskFailed(task.createdBy, task.title, message);
+  }
+}
+
+/**
+ * Gọi 1 lần khi server boot (instrumentation): task còn "running"/"pending"
+ * là mồ côi của process trước (restart giữa chừng) → error để user chạy lại.
+ */
+export async function reclaimStaleTasks(): Promise<void> {
+  const { db } = requireConfig();
+  const { count } = await db.backgroundTask.updateMany({
+    where: { status: { in: ["pending", "running"] } },
+    data: {
+      status: "error",
+      error: "Server khởi động lại giữa chừng — vui lòng chạy lại tác vụ.",
+      finishedAt: new Date(),
+    },
+  });
+  if (count > 0) {
+    console.warn(`[tasks] reclaim ${count} task mồ côi sau restart`);
+  }
+}
+
+// ─── Thông báo khi xong (qua seam notify — app cắm chuông/push) ───
+
+async function notifyTaskDone(
+  userId: string,
+  taskId: string,
+  title: string,
+  result: TaskFileResult,
+): Promise<void> {
+  const { notify } = requireConfig();
+  if (!notify) return;
+  // Task chạy XONG nhưng nghiệp vụ fail từng dòng (import) → warning + link
+  // tải file lỗi để sửa-rồi-nạp-lại.
+  const hasErrorFile = !result.fileKey && !!result.errorFileKey;
+  await notify({
+    userIds: [userId],
+    type: hasErrorFile ? "warning" : "success",
+    category: "task",
+    title: hasErrorFile ? `Cần sửa file: ${title}` : `Hoàn tất: ${title}`,
+    content: result.fileKey
+      ? `${result.summary ?? `${result.rowCount ?? ""} dòng`} — bấm để tải file.`.trim()
+      : hasErrorFile
+        ? `${result.summary ?? "Có dòng lỗi."} Bấm để tải file lỗi từng dòng.`
+        : (result.summary ?? "Tác vụ đã chạy xong."),
+    url: result.fileKey
+      ? `/api/tasks/${taskId}/download`
+      : hasErrorFile
+        ? `/api/tasks/${taskId}/download?file=error`
+        : undefined,
+    resourceType: "background_task",
+    resourceId: taskId,
+  });
+}
+
+async function notifyTaskFailed(
+  userId: string,
+  title: string,
+  message?: string,
+): Promise<void> {
+  const { notify } = requireConfig();
+  if (!notify) return;
+  await notify({
+    userIds: [userId],
+    type: "error",
+    category: "task",
+    title: `Thất bại: ${title}`,
+    content: message || "Tác vụ nền gặp lỗi — thử chạy lại.",
+  });
+}
+
+// ─── Lưu/đọc file kết quả (storage seam; fallback thư mục PRIVATE local) ───
+
+function localDir(): string {
+  return requireConfig().localDir ?? join(process.cwd(), "storage", "task-files");
+}
+
+export async function saveTaskFile(
+  buffer: Buffer,
+  key: string,
+  contentType: string,
+): Promise<string> {
+  const { storage } = requireConfig();
+  if (storage) {
+    const saved = await storage.save(buffer, key, contentType);
+    if (saved) return saved;
+  }
+  const filepath = join(localDir(), key);
+  await mkdir(dirname(filepath), { recursive: true });
+  await writeFile(filepath, buffer);
+  return `local:${key}`;
+}
+
+export async function readTaskFile(fileKey: string): Promise<Buffer> {
+  const { storage } = requireConfig();
+  if (fileKey.startsWith("local:")) {
+    return readFile(join(localDir(), fileKey.slice("local:".length)));
+  }
+  if (!storage) {
+    throw new Error(`[tasks] fileKey "${fileKey}" cần storage seam (S3/MinIO) nhưng chưa cấu hình.`);
+  }
+  return storage.read(fileKey);
+}

package/src/tasks/ui/task-list-client.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { format } from "date-fns";
+import { Download, FileWarning, ListChecks } from "lucide-react";
+import useSWR from "swr";
+
+import { getStatusMeta } from "../../ui/shared/status-indicator";
+
+/**
+ * Trang "Tác vụ nền" của CHÍNH user — dùng chung mọi app goerp: list 50 task,
+ * poll 3s khi còn task chạy, progress bar, nút tải file kết quả / file lỗi.
+ * App chỉ cần page server-shell (gate session) render component này; API
+ * chuẩn: GET /api/tasks + GET /api/tasks/[id]/download (xem app mẫu vinhhoa).
+ */
+
+interface TaskRow {
+  id: string;
+  type: string;
+  title: string;
+  status: "pending" | "running" | "success" | "error";
+  progress: number;
+  result?: {
+    fileKey?: string;
+    fileName?: string;
+    errorFileKey?: string;
+    errorFileName?: string;
+    summary?: string;
+  } | null;
+  error?: string | null;
+  createdAt: string;
+  finishedAt?: string | null;
+}
+
+const fetcher = (url: string) => fetch(url).then((r) => r.json());
+
+const STATUS_LABEL: Record<TaskRow["status"], string> = {
+  pending: "Chờ chạy",
+  running: "Đang chạy",
+  success: "Hoàn tất",
+  error: "Lỗi",
+};
+
+export function TaskListClient({ apiUrl = "/api/tasks" }: { apiUrl?: string }) {
+  const { data } = useSWR<{ tasks: TaskRow[] }>(`${apiUrl}?take=50`, fetcher, {
+    // Còn task đang chạy → poll nhanh để progress nhảy; yên ắng thì thôi.
+    refreshInterval: (latest) =>
+      latest?.tasks?.some(
+        (t) => t.status === "running" || t.status === "pending",
+      )
+        ? 3000
+        : 0,
+  });
+  const tasks = data?.tasks ?? [];
+
+  return (
+    <div className="mx-auto max-w-3xl space-y-3 p-4">
+      <div className="flex items-center gap-2">
+        <ListChecks className="h-5 w-5 text-muted-foreground" />
+        <h1 className="text-base font-bold text-foreground">Tác vụ nền</h1>
+        <span className="text-xs text-muted-foreground">
+          export/import lớn chạy nền — xong sẽ báo qua chuông thông báo
+        </span>
+      </div>
+
+      {tasks.length === 0 ? (
+        <p className="rounded-xl border border-border bg-card px-4 py-10 text-center text-sm text-muted-foreground">
+          Chưa có tác vụ nào. Xuất/Nhập Excel dữ liệu lớn sẽ hiện ở đây.
+        </p>
+      ) : (
+        <div className="divide-y divide-border overflow-hidden rounded-xl border border-border bg-card">
+          {tasks.map((task) => {
+            const meta = getStatusMeta(
+              task.status === "success"
+                ? "completed"
+                : task.status === "error"
+                  ? "cancelled"
+                  : "pending",
+              STATUS_LABEL[task.status],
+            );
+            return (
+              <div key={task.id} className="flex items-center gap-3 px-4 py-3">
+                <span
+                  className={`h-2 w-2 shrink-0 rounded-full ${meta.dotClass}`}
+                />
+                <div className="min-w-0 flex-1">
+                  <p className="truncate text-sm font-medium text-foreground">
+                    {task.title}
+                  </p>
+                  <p className="mt-0.5 truncate text-xs text-muted-foreground">
+                    {format(new Date(task.createdAt), "dd/MM HH:mm")} ·{" "}
+                    {task.status === "error"
+                      ? task.error || "Tác vụ thất bại"
+                      : (task.result?.summary ?? meta.label)}
+                  </p>
+                  {(task.status === "running" ||
+                    task.status === "pending") && (
+                    <div className="mt-1.5 h-1.5 w-full overflow-hidden rounded-full bg-muted">
+                      <div
+                        className="h-full rounded-full bg-primary transition-all"
+                        style={{ width: `${Math.max(task.progress, 4)}%` }}
+                      />
+                    </div>
+                  )}
+                </div>
+                {task.status === "success" && task.result?.fileKey && (
+                  <a
+                    href={`${apiUrl}/${task.id}/download`}
+                    className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border bg-card px-2.5 py-1.5 text-xs font-medium text-foreground hover:bg-muted"
+                  >
+                    <Download className="h-3.5 w-3.5" /> Tải file
+                  </a>
+                )}
+                {task.status === "success" && task.result?.errorFileKey && (
+                  <a
+                    href={`${apiUrl}/${task.id}/download?file=error`}
+                    className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-amber-200 bg-amber-50 px-2.5 py-1.5 text-xs font-medium text-amber-700 hover:bg-amber-100 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-300"
+                  >
+                    <FileWarning className="h-3.5 w-3.5" /> File lỗi
+                  </a>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}