@goplusvn/core 0.1.71 → 0.1.73

package/src/crud/crud-route-handlers.test.ts

@@ -0,0 +1,352 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// @vitest-environment node
+// Route handler thuần Request/Response — PHẢI chạy env node: jsdom ghi đè
+// global File làm chính parser multipart của undici (req.formData) assert chết.
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  createCrudCollectionHandlers,
+  createCrudExportHandler,
+  createCrudImportHandler,
+  createCrudItemHandlers,
+} from "./crud-route-handlers";
+import { CrudRequestError } from "./lib/errors";
+import type { ServerCrudService } from "./server-service";
+import type { EntityConfig } from "../types";
+
+// Admin session → getCrudPermissionsFromSession trả full quyền, test không
+// phụ thuộc permission map.
+const session = { user: { id: "u1", roles: ["SUPER_ADMIN"] } };
+
+const config: EntityConfig = {
+  name: "job-title",
+  label: "Chức danh",
+  pluralLabel: "Chức danh",
+  apiEndpoint: "/api/crud/job-titles",
+  idField: "id",
+  displayField: "name",
+  fields: [
+    { name: "id", label: "ID", type: "text" },
+    { name: "name", label: "Tên", type: "text", filterable: true },
+    { name: "level", label: "Cấp", type: "number", filterable: true },
+  ],
+};
+
+const makeService = (): ServerCrudService => ({
+  list: vi.fn(async () => ({ data: [], total: 0, page: 1, pageSize: 10 })),
+  getById: vi.fn(async () => ({ id: "1" })),
+  create: vi.fn(async (_e, d) => d),
+  update: vi.fn(async () => ({})),
+  delete: vi.fn(async () => ({})),
+  deleteMany: vi.fn(async () => ({})),
+});
+
+const ctx = (entity: string, id?: string) => ({
+  params: Promise.resolve(id === undefined ? { entity } : { entity, id }),
+});
+
+describe("createCrudCollectionHandlers GET", () => {
+  let service: ServerCrudService;
+  let GET: ReturnType<typeof createCrudCollectionHandlers>["GET"];
+
+  beforeEach(() => {
+    service = makeService();
+    ({ GET } = createCrudCollectionHandlers({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+    }));
+  });
+
+  it("filters không phải JSON → 400 (không rơi xuống 500)", async () => {
+    const req = new Request(
+      "http://t/api/crud/job-titles?filters=%7Bnot-json",
+    );
+    const res = await GET(req, ctx("job-titles") as any);
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("filters");
+    expect(service.list).not.toHaveBeenCalled();
+  });
+
+  it("filterTree không phải JSON → 400", async () => {
+    const req = new Request(
+      "http://t/api/crud/job-titles?filterTree=%5Bbroken",
+    );
+    const res = await GET(req, ctx("job-titles") as any);
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("filterTree");
+  });
+
+  it("giá trị filter được ép kiểu theo field config (number)", async () => {
+    const filters = JSON.stringify([
+      { name: "level", operator: "eq", value: "5" },
+    ]);
+    const req = new Request(
+      `http://t/api/crud/job-titles?filters=${encodeURIComponent(filters)}`,
+    );
+    const res = await GET(req, ctx("job-titles") as any);
+    expect(res.status).toBe(200);
+    const params = (service.list as any).mock.calls[0][2];
+    expect(params.filters).toEqual([
+      { name: "level", operator: "eq", value: 5 },
+    ]);
+  });
+
+  it("filterTree hợp lệ được parse và truyền xuống service.list", async () => {
+    const tree = JSON.stringify({
+      $and: [{ field: "name", operator: "contains", value: "a" }],
+    });
+    const req = new Request(
+      `http://t/api/crud/job-titles?filterTree=${encodeURIComponent(tree)}`,
+    );
+    const res = await GET(req, ctx("job-titles") as any);
+    expect(res.status).toBe(200);
+    const params = (service.list as any).mock.calls[0][2];
+    expect(params.filterTree).toEqual({
+      $and: [{ field: "name", operator: "contains", value: "a" }],
+    });
+  });
+});
+
+describe("createCrudItemHandlers", () => {
+  it("service ném CrudRequestError → map ra status của lỗi (400)", async () => {
+    const service = makeService();
+    (service.delete as any).mockRejectedValue(
+      new CrudRequestError('Id không hợp lệ cho "job-titles": "abc" (idKind=int cần số nguyên)'),
+    );
+    const { DELETE } = createCrudItemHandlers({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+    });
+    const req = new Request("http://t/api/crud/job-titles/abc", {
+      method: "DELETE",
+    });
+    const res = await DELETE(req, ctx("job-titles", "abc") as any);
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("Id không hợp lệ");
+  });
+
+  it("DELETE truyền config xuống service (idField/idKind/modelName)", async () => {
+    const service = makeService();
+    const { DELETE } = createCrudItemHandlers({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+    });
+    const req = new Request("http://t/api/crud/job-titles/1", {
+      method: "DELETE",
+    });
+    const res = await DELETE(req, ctx("job-titles", "1") as any);
+    expect(res.status).toBe(204);
+    expect(service.delete).toHaveBeenCalledWith("job-titles", "1", config);
+  });
+});
+
+describe("createCrudExportHandler", () => {
+  const staffNoExport = {
+    user: { id: "u2", permissionMap: { "job-title": ["view"] } },
+  };
+
+  it("thiếu quyền export → 403", async () => {
+    const { GET } = createCrudExportHandler({
+      getSession: () => staffNoExport,
+      getEntityConfig: () => config,
+      service: makeService(),
+    });
+    const req = new Request("http://t/api/crud/job-titles/export");
+    const res = await GET(req, ctx("job-titles") as any);
+    expect(res.status).toBe(403);
+  });
+
+  it("format lạ → 400", async () => {
+    const { GET } = createCrudExportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service: makeService(),
+    });
+    const req = new Request("http://t/api/crud/job-titles/export?format=pdf");
+    const res = await GET(req, ctx("job-titles") as any);
+    expect(res.status).toBe(400);
+  });
+
+  it("json: kéo đủ các trang qua service.list, tôn trọng filter/sort", async () => {
+    const service = makeService();
+    // Trang 1 đầy (2 dòng = pageSize), trang 2 vơi → dừng.
+    (service.list as any)
+      .mockResolvedValueOnce({ data: [{ id: "1" }, { id: "2" }], total: 3, page: 1, pageSize: 2 })
+      .mockResolvedValueOnce({ data: [{ id: "3" }], total: 3, page: 2, pageSize: 2 });
+    const { GET } = createCrudExportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+      pageSize: 2,
+    });
+    const filters = encodeURIComponent(
+      JSON.stringify([{ name: "level", operator: "eq", value: "3" }]),
+    );
+    const req = new Request(
+      `http://t/api/crud/job-titles/export?format=json&sortField=name&sortDirection=desc&filters=${filters}`,
+    );
+    const res = await GET(req, ctx("job-titles") as any);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-disposition")).toContain(".json");
+    const rows = JSON.parse(await res.text());
+    expect(rows.map((r: any) => r.id)).toEqual(["1", "2", "3"]);
+    // Filter chuỗi "3" đã ép number theo field type trước khi vào engine.
+    expect((service.list as any).mock.calls[0][2].filters[0].value).toBe(3);
+    expect((service.list as any).mock.calls[0][2].sort).toEqual({
+      field: "name",
+      direction: "desc",
+    });
+  });
+
+  it("csv: có BOM cho Excel + đúng content-type", async () => {
+    const service = makeService();
+    (service.list as any).mockResolvedValueOnce({
+      data: [{ name: "Kỹ sư" }],
+      total: 1, page: 1, pageSize: 500,
+    });
+    const { GET } = createCrudExportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+    });
+    const req = new Request("http://t/api/crud/job-titles/export?format=csv");
+    const res = await GET(req, ctx("job-titles") as any);
+    // Response.text() strip BOM khi decode — soi bytes thô để chắc BOM đã gửi.
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    expect([bytes[0], bytes[1], bytes[2]]).toEqual([0xef, 0xbb, 0xbf]);
+    const text = new TextDecoder().decode(bytes);
+    expect(text).toContain("Kỹ sư");
+    expect(res.headers.get("content-type")).toContain("text/csv");
+  });
+
+  it("maxRows cắt bớt dòng thừa", async () => {
+    const service = makeService();
+    (service.list as any).mockResolvedValue({
+      data: [{ id: "a" }, { id: "b" }],
+      total: 100, page: 1, pageSize: 2,
+    });
+    const { GET } = createCrudExportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+      pageSize: 2,
+      maxRows: 3,
+    });
+    const req = new Request("http://t/api/crud/job-titles/export?format=json");
+    const res = await GET(req, ctx("job-titles") as any);
+    const rows = JSON.parse(await res.text());
+    expect(rows).toHaveLength(3);
+  });
+});
+
+describe("createCrudImportHandler", () => {
+  it("thiếu quyền import → 403", async () => {
+    const { POST } = createCrudImportHandler({
+      getSession: () => ({ user: { id: "u2", permissionMap: { "job-title": ["view"] } } }),
+      getEntityConfig: () => config,
+      service: makeService(),
+    });
+    const req = new Request("http://t/api/crud/job-titles/import", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "[]",
+    });
+    const res = await POST(req, ctx("job-titles") as any);
+    expect(res.status).toBe(403);
+  });
+
+  it("JSON array: mỗi dòng qua service.create, header label dịch về tên cột", async () => {
+    const service = makeService();
+    const { POST } = createCrudImportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+    });
+    const req = new Request("http://t/api/crud/job-titles/import", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify([{ "Tên": "Kỹ sư", "Cấp": "2" }]),
+    });
+    const res = await POST(req, ctx("job-titles") as any);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toMatchObject({ success: true, imported: 1, failed: 0 });
+    expect((service.create as any).mock.calls[0][1]).toEqual({
+      name: "Kỹ sư",
+      level: "2",
+    });
+  });
+
+  it("dòng lỗi không chặn dòng sau — gom vào errors", async () => {
+    const service = makeService();
+    (service.create as any)
+      .mockRejectedValueOnce(new Error("Tên đã tồn tại"))
+      .mockResolvedValueOnce({});
+    const { POST } = createCrudImportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+    });
+    const req = new Request("http://t/api/crud/job-titles/import", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify([{ name: "A" }, { name: "B" }]),
+    });
+    const res = await POST(req, ctx("job-titles") as any);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+    expect(body.imported).toBe(1);
+    expect(body.failed).toBe(1);
+    expect(body.errors[0]).toMatchObject({ row: 1, message: "Tên đã tồn tại" });
+  });
+
+  it("multipart {file, format} từ ImportDialog: parse tại server", async () => {
+    const service = makeService();
+    const { POST } = createCrudImportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service,
+    });
+    // Dựng multipart thô — File/FormData của môi trường test (jsdom) khác
+    // realm với undici Request, đưa thẳng vào body sẽ hỏng serialize.
+    const boundary = "----vitest-boundary";
+    const body =
+      `--${boundary}\r\n` +
+      `Content-Disposition: form-data; name="file"; filename="rows.json"\r\n` +
+      `Content-Type: application/json\r\n\r\n` +
+      JSON.stringify([{ name: "Từ file" }]) +
+      `\r\n--${boundary}\r\n` +
+      `Content-Disposition: form-data; name="format"\r\n\r\n` +
+      `json\r\n--${boundary}--\r\n`;
+    const req = new Request("http://t/api/crud/job-titles/import", {
+      method: "POST",
+      headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
+      body,
+    });
+    const res = await POST(req, ctx("job-titles") as any);
+    expect(res.status).toBe(200);
+    const result = await res.json();
+    expect(result.imported).toBe(1);
+    expect((service.create as any).mock.calls[0][1]).toEqual({ name: "Từ file" });
+  });
+
+  it("body không phải array → 400", async () => {
+    const { POST } = createCrudImportHandler({
+      getSession: () => session,
+      getEntityConfig: () => config,
+      service: makeService(),
+    });
+    const req = new Request("http://t/api/crud/job-titles/import", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ not: "array" }),
+    });
+    const res = await POST(req, ctx("job-titles") as any);
+    expect(res.status).toBe(400);
+  });
+});

package/src/crud/crud-route-handlers.ts

@@ -13,7 +13,12 @@
 //   // src/app/api/crud/[entity]/[id]/route.ts
 //   export const { GET, PUT, PATCH, DELETE } = createCrudItemHandlers({ getSession, getEntityConfig, service: crudService });
 
-import type { EntityConfig } from "../types";
+import type { ActiveFilter, EntityConfig, ImportResult } from "../types";
+import { toCsv } from "../export/to-csv";
+import { coerceFieldValue } from "./lib/coerce";
+import { CrudRequestError } from "./lib/errors";
+import { exportToJSON, exportToXLSX } from "./lib/import-export-service";
+import { readImportRows } from "./lib/import-request";
 import { getCrudPermissions } from "./lib/permissions";
 import type { ServerCrudService } from "./server-service";
 
@@ -42,13 +47,46 @@ function makeServiceResolver(
 }
 
 const json = (data: unknown, status = 200) =>
-  new Response(JSON.stringify(data), { status, headers: { "content-type": "application/json" } });
+  new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
 
 const unauthorized = () => json({ error: "Unauthorized" }, 401);
 const forbidden = () => json({ error: "Forbidden" }, 403);
 const unknownEntity = () => json({ error: "Unknown entity" }, 404);
 
-async function resolvePerms(session: any, config: EntityConfig, entity: string) {
+// JSON hỏng trên query param là lỗi CLIENT → CrudRequestError để catch chung
+// trả 400 (trước đây JSON.parse ném thẳng → 500 khó hiểu).
+function parseJsonParam(raw: string | null, name: string): unknown {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CrudRequestError(`Query param "${name}" không phải JSON hợp lệ`);
+  }
+}
+
+// Ép giá trị filter theo kiểu field trong config — URL chỉ chở chuỗi, cột
+// Int/Boolean/DateTime cần giá trị đúng kiểu trước khi vào Prisma.
+function coerceFilters(
+  config: EntityConfig,
+  filters: unknown,
+): ActiveFilter[] | undefined {
+  if (!Array.isArray(filters)) return undefined;
+  return filters.map((filter) => {
+    const f = filter as ActiveFilter;
+    const field = config.fields.find((fd) => fd.name === f?.name);
+    if (!field) return f; // field lạ/dotted path: query-builder tự allowlist
+    return { ...f, value: coerceFieldValue(field, f.value) };
+  });
+}
+
+async function resolvePerms(
+  session: any,
+  config: EntityConfig,
+  entity: string,
+) {
   return getCrudPermissions(session, config.permissionResource ?? entity);
 }
 
@@ -56,10 +94,16 @@ async function resolvePerms(session: any, config: EntityConfig, entity: string)
 export function createCrudCollectionHandlers(deps: CrudHandlerDeps) {
   const { getSession, getEntityConfig, onError } = deps;
   const resolveService = makeServiceResolver(deps.service);
-  const fail = (e: unknown, req: Request) =>
-    onError ? onError(e, req) : json({ error: "Internal error" }, 500);
+  const fail = (e: unknown, req: Request) => {
+    if (e instanceof CrudRequestError)
+      return json({ error: e.message }, e.status);
+    return onError ? onError(e, req) : json({ error: "Internal error" }, 500);
+  };
 
-  async function GET(req: Request, ctx: { params: Promise<{ entity: string }> }) {
+  async function GET(
+    req: Request,
+    ctx: { params: Promise<{ entity: string }> },
+  ) {
     const { entity } = await ctx.params;
     try {
       const session = await getSession();
@@ -75,9 +119,16 @@ export function createCrudCollectionHandlers(deps: CrudHandlerDeps) {
         pageSize: parseInt(sp.get("pageSize") || "10", 10),
         search: sp.get("search") || undefined,
         sort: sp.get("sortField")
-          ? { field: sp.get("sortField")!, direction: (sp.get("sortDirection") as "asc" | "desc") || "asc" }
+          ? {
+              field: sp.get("sortField")!,
+              direction: (sp.get("sortDirection") as "asc" | "desc") || "asc",
+            }
           : undefined,
-        filters: sp.get("filters") ? JSON.parse(sp.get("filters")!) : undefined,
+        filters: coerceFilters(
+          config,
+          parseJsonParam(sp.get("filters"), "filters"),
+        ),
+        filterTree: parseJsonParam(sp.get("filterTree"), "filterTree"),
       };
       const service = await resolveService(entity);
       const data = await service.list(entity, config, params as any);
@@ -87,7 +138,10 @@ export function createCrudCollectionHandlers(deps: CrudHandlerDeps) {
     }
   }
 
-  async function POST(req: Request, ctx: { params: Promise<{ entity: string }> }) {
+  async function POST(
+    req: Request,
+    ctx: { params: Promise<{ entity: string }> },
+  ) {
     const { entity } = await ctx.params;
     try {
       const session = await getSession();
@@ -101,7 +155,8 @@ export function createCrudCollectionHandlers(deps: CrudHandlerDeps) {
       const service = await resolveService(entity);
       if (Array.isArray(body)) {
         const results = [];
-        for (const item of body) results.push(await service.create(entity, item, config));
+        for (const item of body)
+          results.push(await service.create(entity, item, config));
         return json(results);
       }
       return json(await service.create(entity, body, config));
@@ -117,8 +172,11 @@ export function createCrudCollectionHandlers(deps: CrudHandlerDeps) {
 export function createCrudItemHandlers(deps: CrudHandlerDeps) {
   const { getSession, getEntityConfig, onError } = deps;
   const resolveService = makeServiceResolver(deps.service);
-  const fail = (e: unknown, req: Request) =>
-    onError ? onError(e, req) : json({ error: "Internal error" }, 500);
+  const fail = (e: unknown, req: Request) => {
+    if (e instanceof CrudRequestError)
+      return json({ error: e.message }, e.status);
+    return onError ? onError(e, req) : json({ error: "Internal error" }, 500);
+  };
 
   type Ctx = { params: Promise<{ entity: string; id: string }> };
 
@@ -168,7 +226,8 @@ export function createCrudItemHandlers(deps: CrudHandlerDeps) {
       const perms = await resolvePerms(session, config, entity);
       if (!perms.delete) return forbidden();
       const service = await resolveService(entity);
-      await service.delete(entity, id);
+      // Truyền config để service dùng đúng idField/idKind/modelName.
+      await service.delete(entity, id, config);
       return new Response(null, { status: 204 });
     } catch (e) {
       return fail(e, req);
@@ -177,3 +236,191 @@ export function createCrudItemHandlers(deps: CrudHandlerDeps) {
 
   return { GET, PUT, PATCH: PUT, DELETE };
 }
+
+// ── Export/Import generic — `/api/crud/[entity]/export|/import` ─────────────
+// Nút Export/ImportDialog của CrudPage mặc định trỏ về đúng 2 URL này
+// (getEntityEndpoints: `${apiEndpoint}/export|/import`) — không có handler thì
+// bật feature export/import là 404 ngay cả trong template.
+
+export interface CrudExportHandlerDeps extends CrudHandlerDeps {
+  /** Số dòng mỗi lần gọi service.list khi kéo trang. Default 500. */
+  pageSize?: number;
+  /** Backstop chống kéo cả bảng khổng lồ trong một request. Default 10 000. */
+  maxRows?: number;
+}
+
+// GET `/api/crud/[entity]/export?format=xlsx|csv|json` — tôn trọng
+// search/sort/filters/filterTree đang áp trên bảng (client gửi kèm query).
+export function createCrudExportHandler(deps: CrudExportHandlerDeps) {
+  const { getSession, getEntityConfig, onError } = deps;
+  const pageSize = deps.pageSize ?? 500;
+  const maxRows = deps.maxRows ?? 10_000;
+  const resolveService = makeServiceResolver(deps.service);
+  const fail = (e: unknown, req: Request) => {
+    if (e instanceof CrudRequestError)
+      return json({ error: e.message }, e.status);
+    return onError ? onError(e, req) : json({ error: "Internal error" }, 500);
+  };
+
+  async function GET(
+    req: Request,
+    ctx: { params: Promise<{ entity: string }> },
+  ) {
+    const { entity } = await ctx.params;
+    try {
+      const session = await getSession();
+      if (!session) return unauthorized();
+      const config = getEntityConfig(entity);
+      if (!config) return unknownEntity();
+      const perms = await resolvePerms(session, config, entity);
+      if (!perms.export) return forbidden();
+
+      const sp = new URL(req.url).searchParams;
+      const format = sp.get("format") || "xlsx";
+      if (format !== "xlsx" && format !== "csv" && format !== "json") {
+        throw new CrudRequestError(
+          `Format "${format}" không hỗ trợ (xlsx|csv|json)`,
+        );
+      }
+
+      const search = sp.get("search") || undefined;
+      const sort = sp.get("sortField")
+        ? {
+            field: sp.get("sortField")!,
+            direction: (sp.get("sortDirection") as "asc" | "desc") || "asc",
+          }
+        : undefined;
+      const filters = coerceFilters(
+        config,
+        parseJsonParam(sp.get("filters"), "filters"),
+      );
+      const filterTree = parseJsonParam(sp.get("filterTree"), "filterTree");
+
+      const service = await resolveService(entity);
+      const rows: Record<string, unknown>[] = [];
+      let page = 1;
+      for (;;) {
+        const result = await service.list(entity, config, {
+          page,
+          pageSize,
+          search,
+          sort,
+          filters,
+          filterTree,
+        } as any);
+        rows.push(...(result.data as Record<string, unknown>[]));
+        if (result.data.length < pageSize || rows.length >= maxRows) break;
+        page += 1;
+      }
+      if (rows.length > maxRows) rows.length = maxRows;
+
+      // Tên file lấy từ entity slug (ASCII) — config.name có thể chứa tiếng
+      // Việt, đưa thẳng vào Content-Disposition là hỏng header.
+      const filename = `${entity}-export-${new Date().toISOString().slice(0, 10)}`;
+
+      if (format === "json") {
+        return new Response(exportToJSON(rows), {
+          headers: {
+            "content-type": "application/json",
+            "content-disposition": `attachment; filename="${filename}.json"`,
+          },
+        });
+      }
+      if (format === "csv") {
+        // BOM để Excel mở đúng UTF-8 tiếng Việt.
+        return new Response("\uFEFF" + toCsv(rows), {
+          headers: {
+            "content-type": "text/csv; charset=utf-8",
+            "content-disposition": `attachment; filename="${filename}.csv"`,
+          },
+        });
+      }
+      return new Response(await exportToXLSX(rows), {
+        headers: {
+          "content-type":
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+          "content-disposition": `attachment; filename="${filename}.xlsx"`,
+        },
+      });
+    } catch (e) {
+      return fail(e, req);
+    }
+  }
+
+  return { GET };
+}
+
+export interface CrudImportHandlerDeps extends CrudHandlerDeps {
+  /**
+   * Header legacy → tên cột theo entity (file mẫu tiếng Việt của hệ cũ…).
+   * Label trong EntityConfig và tên cột máy luôn được nhận sẵn, không cần khai.
+   */
+  legacyHeaders?: (entity: string) => Record<string, string> | undefined;
+}
+
+// POST `/api/crud/[entity]/import` — nhận multipart {file, format} từ
+// ImportDialog của core LẪN JSON array (client tự parse). Mỗi dòng đi qua
+// service.create (coercion + validate + audit của engine áp y như tạo tay);
+// dòng lỗi không chặn các dòng sau, gom vào ImportResult.errors.
+export function createCrudImportHandler(deps: CrudImportHandlerDeps) {
+  const { getSession, getEntityConfig, onError } = deps;
+  const resolveService = makeServiceResolver(deps.service);
+  const fail = (e: unknown, req: Request) => {
+    if (e instanceof CrudRequestError)
+      return json({ error: e.message }, e.status);
+    return onError ? onError(e, req) : json({ error: "Internal error" }, 500);
+  };
+
+  async function POST(
+    req: Request,
+    ctx: { params: Promise<{ entity: string }> },
+  ) {
+    const { entity } = await ctx.params;
+    try {
+      const session = await getSession();
+      if (!session) return unauthorized();
+      const config = getEntityConfig(entity);
+      if (!config) return unknownEntity();
+      const perms = await resolvePerms(session, config, entity);
+      if (!perms.import) return forbidden();
+
+      const rows = await readImportRows(
+        req,
+        config,
+        deps.legacyHeaders?.(entity),
+      );
+      if (!rows) {
+        throw new CrudRequestError(
+          "Body import không hợp lệ — cần file (multipart) hoặc JSON array",
+        );
+      }
+
+      const service = await resolveService(entity);
+      const result: ImportResult = {
+        success: true,
+        imported: 0,
+        failed: 0,
+        errors: [],
+      };
+      for (const [index, row] of rows.entries()) {
+        try {
+          await service.create(entity, row, config);
+          result.imported += 1;
+        } catch (e) {
+          result.failed += 1;
+          result.errors.push({
+            row: index + 1,
+            field: "",
+            message: e instanceof Error ? e.message : String(e),
+          });
+        }
+      }
+      result.success = result.failed === 0;
+      return json(result);
+    } catch (e) {
+      return fail(e, req);
+    }
+  }
+
+  return { POST };
+}