@goplusvn/core 0.1.70 → 0.1.72

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 };
+}

package/src/crud/index.ts

@@ -28,8 +28,11 @@ export * from "./components/crud-virtual-table";
 export { EntityCrudPage } from "./pages/entity-crud-page";
 
 // Re-export lib logic
+export * from "./lib/coerce";
 export * from "./lib/crud-service";
 export * from "./lib/crud-utils";
+export * from "./lib/entity-endpoints";
+export * from "./lib/errors";
 export * from "./lib/crud-validator";
 export * from "./lib/data-loader";
 export * from "./lib/field-calculator";

package/src/crud/lib/coerce.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest";
+import { coerceFieldValue } from "./coerce";
+import type { FieldConfig } from "../../types";
+
+const field = (over: Partial<FieldConfig>): FieldConfig => ({
+  name: "f",
+  label: "F",
+  type: "text",
+  ...over,
+});
+
+describe("coerceFieldValue", () => {
+  it("giữ nguyên undefined/null", () => {
+    const f = field({ type: "number" });
+    expect(coerceFieldValue(f, undefined)).toBeUndefined();
+    expect(coerceFieldValue(f, null)).toBeNull();
+  });
+
+  it("number: chuỗi số → number, chuỗi rỗng → null, chuỗi rác giữ nguyên", () => {
+    const f = field({ type: "number" });
+    expect(coerceFieldValue(f, "5")).toBe(5);
+    expect(coerceFieldValue(f, "5.5")).toBe(5.5);
+    expect(coerceFieldValue(f, "")).toBeNull();
+    expect(coerceFieldValue(f, "  ")).toBeNull();
+    expect(coerceFieldValue(f, "abc")).toBe("abc");
+    expect(coerceFieldValue(f, 7)).toBe(7);
+  });
+
+  it("boolean: các chuỗi truthy quy ước → true", () => {
+    const f = field({ type: "boolean" });
+    expect(coerceFieldValue(f, "true")).toBe(true);
+    expect(coerceFieldValue(f, "active")).toBe(true);
+    expect(coerceFieldValue(f, "1")).toBe(true);
+    expect(coerceFieldValue(f, "on")).toBe(true);
+    expect(coerceFieldValue(f, "false")).toBe(false);
+    expect(coerceFieldValue(f, "inactive")).toBe(false);
+  });
+
+  it("switch có cặp option → map về value của option, không phải boolean", () => {
+    const f = field({
+      type: "switch",
+      options: [
+        { label: "Hoạt động", value: "active" },
+        { label: "Vô hiệu", value: "inactive" },
+      ],
+    });
+    expect(coerceFieldValue(f, "active")).toBe("active");
+    expect(coerceFieldValue(f, "inactive")).toBe("inactive");
+    expect(coerceFieldValue(f, true)).toBe("active");
+    expect(coerceFieldValue(f, false)).toBe("inactive");
+  });
+
+  it("date/datetime: chuỗi ISO → Date, chuỗi rỗng → null, chuỗi rác giữ nguyên", () => {
+    const f = field({ type: "datetime" });
+    const out = coerceFieldValue(f, "2026-01-02T00:00:00.000Z");
+    expect(out).toBeInstanceOf(Date);
+    expect((out as Date).toISOString()).toBe("2026-01-02T00:00:00.000Z");
+    expect(coerceFieldValue(f, "")).toBeNull();
+    expect(coerceFieldValue(f, "not-a-date")).toBe("not-a-date");
+  });
+
+  it('FK: "" → undefined cho relation và *Id dạng select', () => {
+    expect(
+      coerceFieldValue(field({ name: "department", type: "relation" }), ""),
+    ).toBeUndefined();
+    expect(
+      coerceFieldValue(field({ name: "departmentId", type: "select" }), ""),
+    ).toBeUndefined();
+  });
+
+  it('*Id scalar (kiểu text, không phải FK) giữ nguyên ""', () => {
+    expect(
+      coerceFieldValue(field({ name: "citizenId", type: "text" }), ""),
+    ).toBe("");
+  });
+
+  it("mảng: ép từng phần tử (giá trị filter in/notIn)", () => {
+    const f = field({ type: "integer" });
+    expect(coerceFieldValue(f, ["1", "2", 3])).toEqual([1, 2, 3]);
+  });
+
+  it('FK snake_case: "" → undefined cho *_id/*_ids dạng select', () => {
+    expect(
+      coerceFieldValue(field({ name: "meal_time_id", type: "select" }), ""),
+    ).toBeUndefined();
+    expect(
+      coerceFieldValue(
+        field({ name: "default_meal_time_ids", type: "multiselect" }),
+        "",
+      ),
+    ).toBeUndefined();
+  });
+
+  it('valueType "int": select/multiselect chở chuỗi → number (FK Int autoincrement)', () => {
+    const f = field({
+      name: "meal_time_id",
+      type: "select",
+      valueType: "int",
+    });
+    expect(coerceFieldValue(f, "3")).toBe(3);
+    expect(coerceFieldValue(f, 3)).toBe(3);
+    expect(coerceFieldValue(f, "")).toBeUndefined(); // FK "" = bỏ trống
+    expect(coerceFieldValue(f, "abc")).toBe("abc"); // rác giữ nguyên cho validate
+
+    const multi = field({
+      name: "default_meal_time_ids",
+      type: "multiselect",
+      valueType: "int",
+    });
+    expect(coerceFieldValue(multi, ["1", "2", 3])).toEqual([1, 2, 3]);
+  });
+
+  it('valueType "int" trên select KHÔNG phải FK: "" → null (cột Int nullable)', () => {
+    const f = field({ name: "level", type: "select", valueType: "int" });
+    expect(coerceFieldValue(f, "2")).toBe(2);
+    expect(coerceFieldValue(f, "")).toBeNull();
+  });
+});

package/src/crud/lib/coerce.ts

@@ -0,0 +1,95 @@
+import type { FieldConfig } from "../../types";
+
+function optionValue(option: unknown): unknown {
+  return typeof option === "object" && option !== null && "value" in option
+    ? (option as { value: unknown }).value
+    : option;
+}
+
+/**
+ * Ép kiểu MỘT giá trị theo FieldConfig — điểm coercion tập trung, dùng chung
+ * cho body create/update (mutation-builder) và giá trị filter từ query string
+ * (route-handlers). Client gửi chuỗi (form/URL) là chuyện thường; không ép thì
+ * Prisma nổ type mismatch với cột Int/Boolean/DateTime.
+ *
+ * Trả `undefined` nghĩa là "coi như bỏ trống" — với cột FK, chuỗi rỗng ""
+ * phải thành undefined chứ không được lọt xuống DB (nổ P2003).
+ */
+export function coerceFieldValue(field: FieldConfig, value: unknown): unknown {
+  if (value === undefined || value === null) return value;
+  if (Array.isArray(value)) {
+    return value.map((v) => coerceFieldValue(field, v));
+  }
+
+  // BẪY empty-string FK: "" vào cột FK là "bỏ trống", không phải giá trị —
+  // trả undefined để mutation disconnect/bỏ key, filter thì bỏ qua điều kiện.
+  // CHỈ áp cho field thực sự là FK (relation, hoặc *Id/*_id dạng select) —
+  // nhận CẢ HAI convention camelCase (`branchId`) và snake_case
+  // (`meal_time_id`, `default_meal_time_ids`); *Id scalar kiểu text
+  // (citizenId, targetId…) giữ nguyên "".
+  const fkName =
+    (field.name.endsWith("Id") && field.name.length > 2) ||
+    /_ids?$/.test(field.name);
+  const isForeignKey =
+    field.type === "relation" ||
+    Boolean(field.relation) ||
+    (fkName && (field.type === "select" || field.type === "multiselect"));
+  if (value === "" && isForeignKey) {
+    return undefined;
+  }
+
+  // Cột Int đứng sau select/multiselect/relation (FK autoincrement): `type`
+  // không nói lên kiểu cột nên phải khai `valueType: "int"` trong FieldConfig.
+  // Chuỗi không phải số giữ nguyên cho tầng validate/Prisma báo.
+  if (field.valueType === "int" && typeof value === "string") {
+    if (value.trim() === "") return null;
+    const num = Number(value);
+    return Number.isNaN(num) ? value : num;
+  }
+
+  switch (field.type) {
+    case "number":
+    case "integer": {
+      if (typeof value !== "string") return value;
+      if (value.trim() === "") return null;
+      const num = Number(value);
+      // Chuỗi không phải số: giữ nguyên cho tầng validate/Prisma báo, không âm thầm NaN.
+      return Number.isNaN(num) ? value : num;
+    }
+
+    case "boolean":
+    case "switch": {
+      let isTrue: boolean;
+      if (typeof value === "string") {
+        const lv = value.toLowerCase();
+        isTrue =
+          lv === "true" || lv === "active" || value === "1" || value === "on";
+      } else {
+        isTrue = Boolean(value);
+      }
+      // switch có cặp option = cột string 2 trạng thái (active/inactive…),
+      // map về value của option chứ không phải boolean.
+      if (
+        field.type === "switch" &&
+        field.options &&
+        field.options.length >= 2
+      ) {
+        return isTrue
+          ? optionValue(field.options[0])
+          : optionValue(field.options[1]);
+      }
+      return isTrue;
+    }
+
+    case "date":
+    case "datetime": {
+      if (typeof value !== "string") return value;
+      if (value.trim() === "") return null;
+      const date = new Date(value);
+      return Number.isNaN(date.getTime()) ? value : date;
+    }
+
+    default:
+      return value;
+  }
+}

package/src/crud/lib/crud-utils.ts

@@ -31,6 +31,10 @@ export function buildQueryString(params: CrudQueryParams): string {
     searchParams.append("filters", JSON.stringify(params.filters));
   }
 
+  if (params.filterTree) {
+    searchParams.append("filterTree", JSON.stringify(params.filterTree));
+  }
+
   return searchParams.toString();
 }
 

package/src/crud/lib/entity-endpoints.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { getEntityEndpoints } from "./entity-endpoints";
+import type { EntityConfig } from "../../types";
+
+const base: EntityConfig = {
+  name: "job-title",
+  label: "Chức danh",
+  pluralLabel: "Chức danh",
+  apiEndpoint: "/api/crud/job-titles",
+  idField: "id",
+  displayField: "name",
+  fields: [],
+};
+
+describe("getEntityEndpoints", () => {
+  it("default: suy từ apiEndpoint theo cùng một quy tắc", () => {
+    expect(getEntityEndpoints(base)).toEqual({
+      import: "/api/crud/job-titles/import",
+      export: "/api/crud/job-titles/export",
+    });
+  });
+
+  it("apiEndpoint có query params: giữ query sau path import/export", () => {
+    const config = { ...base, apiEndpoint: "/api/stocks?type=in" };
+    expect(getEntityEndpoints(config)).toEqual({
+      import: "/api/stocks/import?type=in",
+      export: "/api/stocks/export?type=in",
+    });
+  });
+
+  it("config.endpoints override từng endpoint riêng lẻ", () => {
+    const config = {
+      ...base,
+      endpoints: { export: "/api/reports/job-titles/xlsx" },
+    };
+    expect(getEntityEndpoints(config)).toEqual({
+      import: "/api/crud/job-titles/import",
+      export: "/api/reports/job-titles/xlsx",
+    });
+  });
+});

package/src/crud/lib/entity-endpoints.ts

@@ -0,0 +1,23 @@
+import type { EntityConfig } from "../../types";
+
+/**
+ * Endpoint import/export của entity — MỘT quy tắc duy nhất cho cả ImportDialog
+ * lẫn CrudExportButton (trước đây hai nơi tự build hai kiểu khác nhau → 404).
+ *
+ * Default: `${base}/import|/export` với base = apiEndpoint bỏ query string,
+ * query params (nếu có) được giữ lại nối sau path. Override từng cái qua
+ * `config.endpoints`.
+ */
+export function getEntityEndpoints(config: EntityConfig): {
+  import: string;
+  export: string;
+} {
+  const [base, query] = config.apiEndpoint.split("?");
+  const derive = (suffix: string) =>
+    `${base}/${suffix}${query ? `?${query}` : ""}`;
+
+  return {
+    import: config.endpoints?.import ?? derive("import"),
+    export: config.endpoints?.export ?? derive("export"),
+  };
+}

package/src/crud/lib/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Lỗi request CRUD do client gửi sai (id sai kiểu, filters/filterTree hỏng…).
+ * Route-handler bắt instanceof để trả đúng status (mặc định 400) thay vì rơi
+ * xuống onError/500 chung.
+ */
+export class CrudRequestError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status = 400) {
+    super(message);
+    this.name = "CrudRequestError";
+    this.status = status;
+  }
+}