@goplusvn/core 0.1.55 → 0.1.57

package/src/import/import-engine.ts

@@ -0,0 +1,357 @@
+/**
+ * Harness nhập workbook — đọc Excel, kiểm tra header, chuẩn hoá kiểu dữ liệu và
+ * dựng báo cáo lỗi. THUẦN: không React, không DB, không Next — service nhập của
+ * từng nghiệp vụ (đơn bán, đơn mua…) gọi các hàm này rồi tự lo phần ghi DB.
+ *
+ * Định dạng số/ngày mặc định theo thói quen Việt Nam ("1.234.567,89",
+ * "dd/MM/yyyy") vì đó là thứ người dùng dán từ Excel bản địa.
+ */
+
+import * as XLSX from "xlsx";
+
+import type {
+  ImportColumnDef,
+  ImportRowError,
+  ImportRowWarning,
+  ParsedRow,
+} from "./types";
+
+// ─────────────────────────────────────────────────
+// 1. Đọc Excel
+// ─────────────────────────────────────────────────
+
+/** Đọc buffer Excel thành object `{ tên sheet: mảng dòng }`. */
+export function parseExcelBuffer(
+  buffer: ArrayBuffer,
+): Record<string, ParsedRow[]> {
+  const workbook = XLSX.read(buffer, { type: "array", cellDates: true });
+  const result: Record<string, ParsedRow[]> = {};
+
+  for (const sheetName of workbook.SheetNames) {
+    const sheet = workbook.Sheets[sheetName];
+    // defval: "" để ô trống không thành undefined; raw: false để số/ngày về
+    // chuỗi, xử lý đồng nhất một chỗ trong normalizeRow.
+    const rows = XLSX.utils.sheet_to_json<ParsedRow>(sheet, {
+      defval: "",
+      raw: false,
+    });
+    result[sheetName] = rows;
+  }
+
+  return result;
+}
+
+// ─────────────────────────────────────────────────
+// 2. Kiểm tra header
+// ─────────────────────────────────────────────────
+
+/** Báo thiếu cột BẮT BUỘC. Cột không bắt buộc thiếu thì bỏ qua. */
+export function validateHeaders(
+  actualHeaders: string[],
+  columns: ImportColumnDef[],
+): ImportRowError[] {
+  const errors: ImportRowError[] = [];
+  const normalizedActual = new Set(
+    actualHeaders.map((h) => normalizeHeader(h)),
+  );
+
+  for (const col of columns) {
+    if (
+      col.required &&
+      !normalizedActual.has(normalizeHeader(col.excelHeader))
+    ) {
+      errors.push({
+        row: 0,
+        column: col.excelHeader,
+        value: null,
+        message: `Thiếu cột bắt buộc: "${col.excelHeader}"`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+/** Chuẩn hoá tên cột để so khớp (trim, thường hoá, gộp khoảng trắng). */
+function normalizeHeader(header: string): string {
+  return header.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+// ─────────────────────────────────────────────────
+// 3. Chuẩn hoá dòng + ép kiểu
+// ─────────────────────────────────────────────────
+
+/**
+ * Ánh xạ header Excel → fieldKey, trim chuỗi, parse số/ngày, áp mặc định.
+ * Ô lỗi vẫn ghi giá trị an toàn vào `data` để caller không phải kiểm tra null
+ * ở mọi chỗ — cứ nhìn `errors` để quyết định bỏ dòng hay không.
+ */
+export function normalizeRow(
+  raw: ParsedRow,
+  columns: ImportColumnDef[],
+  rowIndex: number,
+): { data: ParsedRow; errors: ImportRowError[]; warnings: ImportRowWarning[] } {
+  const data: ParsedRow = {};
+  const errors: ImportRowError[] = [];
+  const warnings: ImportRowWarning[] = [];
+
+  // Khoá thật trong file có thể lệch hoa/thường/khoảng trắng so với định nghĩa.
+  const rawKeyMap = new Map<string, string>();
+  for (const key of Object.keys(raw)) {
+    rawKeyMap.set(normalizeHeader(key), key);
+  }
+
+  for (const col of columns) {
+    const rawKey = rawKeyMap.get(normalizeHeader(col.excelHeader));
+    const value = rawKey !== undefined ? raw[rawKey] : undefined;
+
+    if (value === undefined || value === null || value === "") {
+      if (col.required) {
+        errors.push({
+          row: rowIndex,
+          column: col.excelHeader,
+          value,
+          message: `Trường "${col.excelHeader}" là bắt buộc`,
+        });
+      }
+      data[col.fieldKey] = col.defaultValue ?? null;
+      continue;
+    }
+
+    switch (col.type) {
+      case "string":
+        data[col.fieldKey] = String(value).trim();
+        break;
+
+      case "number":
+      case "decimal": {
+        const num = parseVietnameseNumber(value);
+        if (isNaN(num)) {
+          errors.push({
+            row: rowIndex,
+            column: col.excelHeader,
+            value,
+            message: `"${col.excelHeader}" phải là số hợp lệ (nhận được: "${value}")`,
+          });
+          data[col.fieldKey] = 0;
+        } else {
+          data[col.fieldKey] = num;
+        }
+        break;
+      }
+
+      case "date": {
+        const date = parseFlexibleDate(value);
+        if (!date) {
+          errors.push({
+            row: rowIndex,
+            column: col.excelHeader,
+            value,
+            message: `"${col.excelHeader}" phải là ngày hợp lệ (dd/MM/yyyy) (nhận được: "${value}")`,
+          });
+          data[col.fieldKey] = null;
+        } else {
+          data[col.fieldKey] = date;
+        }
+        break;
+      }
+
+      case "enum": {
+        const strVal = String(value).trim();
+        if (col.enumValues && !col.enumValues.includes(strVal)) {
+          const matched = col.enumValues.find(
+            (v) => v.toLowerCase() === strVal.toLowerCase(),
+          );
+          if (matched) {
+            data[col.fieldKey] = matched;
+          } else {
+            errors.push({
+              row: rowIndex,
+              column: col.excelHeader,
+              value: strVal,
+              message: `"${col.excelHeader}" phải là một trong: ${col.enumValues.join(", ")} (nhận được: "${strVal}")`,
+            });
+            data[col.fieldKey] = col.defaultValue ?? null;
+          }
+        } else {
+          data[col.fieldKey] = strVal;
+        }
+        break;
+      }
+
+      default:
+        data[col.fieldKey] = value;
+    }
+
+    if (col.validate) {
+      const err = col.validate(data[col.fieldKey], rowIndex);
+      if (err) errors.push(err);
+    }
+  }
+
+  return { data, errors, warnings };
+}
+
+// ─────────────────────────────────────────────────
+// 4. Parse ngày / số
+// ─────────────────────────────────────────────────
+
+/**
+ * Dựng ngày địa phương và TỪ CHỐI ngày không tồn tại. `new Date(2026, 5, 31)`
+ * tự cuộn sang 01/07 — nhập liệu mà im lặng đổi ngày chứng từ thì tệ hơn nhiều
+ * so với báo lỗi để người dùng sửa ô đó.
+ */
+function localDateFromParts(
+  year: number,
+  month: number,
+  day: number,
+): Date | null {
+  const d = new Date(year, month - 1, day);
+  if (
+    d.getFullYear() !== year ||
+    d.getMonth() !== month - 1 ||
+    d.getDate() !== day
+  ) {
+    return null;
+  }
+  return d;
+}
+
+/**
+ * Parse ngày linh hoạt: Date (từ cellDates), "dd/MM/yyyy", "yyyy-MM-dd", hoặc
+ * số serial của Excel (mốc 1899-12-30).
+ */
+export function parseFlexibleDate(value: any): Date | null {
+  if (value instanceof Date) {
+    return isNaN(value.getTime()) ? null : value;
+  }
+
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return null;
+    // Cộng dồn theo UTC rồi mới đổi sang giờ địa phương: mốc 1899 ở nhiều múi
+    // giờ còn là giờ mặt trời (Asia/Ho_Chi_Minh khi đó lệch +07:06:30), nên
+    // cộng thẳng vào `new Date(1899, 11, 30)` đẩy mọi serial về 23:53:30 hôm
+    // trước — cả file lùi một ngày.
+    const utc = new Date(Date.UTC(1899, 11, 30) + value * 86400000);
+    if (isNaN(utc.getTime())) return null;
+    return new Date(
+      utc.getUTCFullYear(),
+      utc.getUTCMonth(),
+      utc.getUTCDate(),
+      utc.getUTCHours(),
+      utc.getUTCMinutes(),
+      utc.getUTCSeconds(),
+      utc.getUTCMilliseconds(),
+    );
+  }
+
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+
+    const ddmmyyyy = trimmed.match(/^(\d{1,2})[/\-.](\d{1,2})[/\-.](\d{4})$/);
+    if (ddmmyyyy) {
+      const [, day, month, year] = ddmmyyyy;
+      return localDateFromParts(Number(year), Number(month), Number(day));
+    }
+
+    const yyyymmdd = trimmed.match(/^(\d{4})[/\-.](\d{1,2})[/\-.](\d{1,2})$/);
+    if (yyyymmdd) {
+      const [, year, month, day] = yyyymmdd;
+      return localDateFromParts(Number(year), Number(month), Number(day));
+    }
+
+    const parsed = new Date(trimmed);
+    return isNaN(parsed.getTime()) ? null : parsed;
+  }
+
+  return null;
+}
+
+/** Parse số, chấp nhận cách viết Việt Nam ("1.234.567,89"). */
+export function parseVietnameseNumber(value: any): number {
+  if (typeof value === "number") return value;
+  if (typeof value !== "string") return NaN;
+
+  let cleaned = value.trim();
+
+  if (cleaned.includes(".") && cleaned.includes(",")) {
+    // "1.234.567,89" → dấu chấm là phân nhóm nghìn
+    cleaned = cleaned.replace(/\./g, "").replace(",", ".");
+  } else if (cleaned.includes(",") && !cleaned.includes(".")) {
+    // "1234,56" → dấu phẩy là phần thập phân
+    cleaned = cleaned.replace(",", ".");
+  }
+
+  return Number(cleaned);
+}
+
+// ─────────────────────────────────────────────────
+// 5. Dựng báo cáo
+// ─────────────────────────────────────────────────
+
+/**
+ * Gộp kết quả thành báo cáo trả về client.
+ * Luật `success`: chế độ 'full' chỉ thành công khi KHÔNG có lỗi nào; 'partial'
+ * luôn coi là thành công (đã bỏ qua dòng lỗi). Chạy thử thì thành công = sạch lỗi.
+ */
+export function buildValidationReport(params: {
+  totalRows: number;
+  importedCount: number;
+  skippedCount: number;
+  errors: ImportRowError[];
+  warnings: ImportRowWarning[];
+  importedIds: string[];
+  mode: "full" | "partial";
+  dryRun: boolean;
+}): {
+  success: boolean;
+  mode: string;
+  dryRun: boolean;
+  totalRows: number;
+  importedCount: number;
+  skippedCount: number;
+  errors: ImportRowError[];
+  warnings: ImportRowWarning[];
+  importedIds: string[];
+} {
+  const { errors, mode, dryRun } = params;
+
+  const hasErrors = errors.length > 0;
+  const success = mode === "full" ? !hasErrors : true;
+
+  return {
+    success: dryRun ? !hasErrors : success,
+    mode,
+    dryRun,
+    totalRows: params.totalRows,
+    importedCount: dryRun ? 0 : params.importedCount,
+    skippedCount: params.skippedCount,
+    errors,
+    warnings: params.warnings,
+    importedIds: dryRun ? [] : params.importedIds,
+  };
+}
+
+// ─────────────────────────────────────────────────
+// 6. Tiện ích sheet
+// ─────────────────────────────────────────────────
+
+/** Lấy sheet theo tên (bỏ qua hoa/thường và khoảng trắng thừa). */
+export function findSheet(
+  parsed: Record<string, ParsedRow[]>,
+  name: string,
+): ParsedRow[] | null {
+  const normalizedName = name.trim().toLowerCase();
+  for (const [sheetName, rows] of Object.entries(parsed)) {
+    if (sheetName.trim().toLowerCase() === normalizedName) {
+      return rows;
+    }
+  }
+  return null;
+}
+
+/** Tên các cột, lấy từ dòng dữ liệu đầu tiên. */
+export function getHeaders(rows: ParsedRow[]): string[] {
+  if (rows.length === 0) return [];
+  return Object.keys(rows[0]);
+}

package/src/import/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Harness NHẬP DỮ LIỆU dùng chung.
+ *
+ * Ba tầng, dùng riêng lẻ được:
+ *  - `import-engine`: đọc/kiểm/chuẩn hoá workbook (thuần, chạy ở server).
+ *  - `use-import`:    máy trạng thái một lần nhập (client).
+ *  - `ImportDialog`:  MỘT hộp thoại nhập cho cả app (mẫu từ server hoặc từ
+ *                     EntityConfig). Đừng dựng hộp thoại nhập riêng nữa —
+ *                     `CrudImportDialog` cũ chỉ còn là lớp vỏ tương thích.
+ */
+
+export {
+  buildValidationReport,
+  findSheet,
+  getHeaders,
+  normalizeRow,
+  parseExcelBuffer,
+  parseFlexibleDate,
+  parseVietnameseNumber,
+  validateHeaders,
+} from "./import-engine";
+
+export { useImport, type WorkbookImportResponse } from "./use-import";
+
+export {
+  ImportDialog,
+  normalizeImportResult,
+  type ImportDialogProps,
+} from "./import-dialog";
+
+export type {
+  ImportColumnDef,
+  ImportRowError,
+  ImportRowWarning,
+  ParsedRow,
+  WorkbookImportConfig,
+  WorkbookImportOptions,
+  WorkbookImportResult,
+} from "./types";

package/src/import/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Kiểu dữ liệu cho HARNESS NHẬP WORKBOOK — nhập file Excel nhiều sheet, có
+ * định nghĩa cột và báo lỗi tới từng dòng/từng ô.
+ *
+ * ĐỪNG NHẦM với `ImportResult`/`ImportOptions` trong `@goerp/core/types`: bộ
+ * đó phục vụ nhập PHẲNG theo EntityConfig của CRUD (csv/json/xlsx một sheet,
+ * kết quả gọn `{imported, failed}`). Bộ ở đây dành cho chứng từ có phần đầu +
+ * phần dòng (đơn bán, đơn mua), nên tiền tố `Workbook`.
+ */
+
+export interface ImportRowError {
+  /** Số dòng trong Excel (đếm từ dòng dữ liệu, không tính header). */
+  row: number;
+  /** Tên cột. */
+  column: string;
+  /** Giá trị gây lỗi. */
+  value: any;
+  /** Thông báo cho người dùng. */
+  message: string;
+}
+
+export interface ImportRowWarning {
+  row: number;
+  column: string;
+  message: string;
+}
+
+export interface WorkbookImportOptions {
+  /** 'full' = có lỗi thì rollback tất cả; 'partial' = bỏ qua dòng lỗi. */
+  mode: "full" | "partial";
+  /** Chỉ kiểm tra, không ghi DB. */
+  dryRun: boolean;
+}
+
+export interface WorkbookImportResult {
+  success: boolean;
+  mode: "full" | "partial";
+  totalRows: number;
+  importedCount: number;
+  skippedCount: number;
+  errors: ImportRowError[];
+  warnings: ImportRowWarning[];
+  importedIds: string[];
+}
+
+/** Định nghĩa một cột trong file nhập. */
+export interface ImportColumnDef {
+  /** Tên cột hiển thị trong Excel. */
+  excelHeader: string;
+  /** Khoá trường nội bộ sau khi chuẩn hoá. */
+  fieldKey: string;
+  type: "string" | "number" | "decimal" | "date" | "enum";
+  /** Mặc định không bắt buộc — bảng cột dài thì khai `required: true` cho vài cột gọn hơn. */
+  required?: boolean;
+  /** Giá trị hợp lệ khi `type: 'enum'`. */
+  enumValues?: string[];
+  /** Giá trị mặc định khi ô trống. */
+  defaultValue?: any;
+  /** Kiểm tra riêng của nghiệp vụ. */
+  validate?: (value: any, row: number) => ImportRowError | null;
+}
+
+/** Một dòng đã đọc từ Excel (trước khi validate nghiệp vụ). */
+export type ParsedRow = Record<string, any>;
+
+/** Cấu hình một lần nhập: sheet phần đầu + sheet phần dòng. */
+export interface WorkbookImportConfig {
+  headerColumns: ImportColumnDef[];
+  lineColumns: ImportColumnDef[];
+  headerSheetName: string;
+  lineSheetName: string;
+  maxRows: number;
+}

package/src/import/use-import.ts

@@ -0,0 +1,156 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+
+import type { ImportRowError, ImportRowWarning } from "./types";
+
+/**
+ * Máy trạng thái cho một lần nhập file: chọn file → gửi → nhận báo cáo.
+ * Tách khỏi `ImportDialog` để màn hình nào muốn giao diện riêng vẫn dùng lại
+ * được luồng (và để test được không cần DOM).
+ */
+
+interface ImportState {
+  step: "idle" | "uploading" | "validating" | "importing" | "done" | "error";
+  file: File | null;
+  dryRun: boolean;
+  mode: "full" | "partial";
+  result: WorkbookImportResponse | null;
+  errorMessage: string | null;
+}
+
+/** Thân JSON server trả về cho một lần nhập workbook. */
+export interface WorkbookImportResponse {
+  success: boolean;
+  mode: string;
+  dryRun: boolean;
+  totalRows: number;
+  importedCount: number;
+  skippedCount: number;
+  errors: ImportRowError[];
+  warnings: ImportRowWarning[];
+  importedIds: string[];
+}
+
+interface UseImportOptions {
+  /** Endpoint nhận POST multipart. */
+  apiUrl: string;
+  /** Gọi khi nhập thật (không phải chạy thử) và có ít nhất 1 bản ghi vào. */
+  onSuccess?: (result: WorkbookImportResponse) => void;
+}
+
+export function useImport({ apiUrl, onSuccess }: UseImportOptions) {
+  const [state, setState] = useState<ImportState>({
+    step: "idle",
+    file: null,
+    dryRun: false,
+    mode: "full",
+    result: null,
+    errorMessage: null,
+  });
+
+  const abortRef = useRef<AbortController | null>(null);
+
+  const setFile = useCallback((file: File | null) => {
+    setState((prev) => ({
+      ...prev,
+      file,
+      step: "idle",
+      result: null,
+      errorMessage: null,
+    }));
+  }, []);
+
+  const setDryRun = useCallback((dryRun: boolean) => {
+    setState((prev) => ({ ...prev, dryRun }));
+  }, []);
+
+  const setMode = useCallback((mode: "full" | "partial") => {
+    setState((prev) => ({ ...prev, mode }));
+  }, []);
+
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    setState({
+      step: "idle",
+      file: null,
+      dryRun: false,
+      mode: "full",
+      result: null,
+      errorMessage: null,
+    });
+  }, []);
+
+  const execute = useCallback(async () => {
+    if (!state.file) {
+      setState((prev) => ({
+        ...prev,
+        errorMessage: "Vui lòng chọn file để import",
+      }));
+      return;
+    }
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    try {
+      setState((prev) => ({ ...prev, step: "uploading", errorMessage: null }));
+
+      const formData = new FormData();
+      formData.append("file", state.file);
+      formData.append("mode", state.mode);
+      formData.append("dryRun", String(state.dryRun));
+
+      setState((prev) => ({
+        ...prev,
+        step: state.dryRun ? "validating" : "importing",
+      }));
+
+      const response = await fetch(apiUrl, {
+        method: "POST",
+        body: formData,
+        signal: controller.signal,
+      });
+
+      const data: WorkbookImportResponse = await response.json();
+
+      // Lỗi không có thân báo cáo (401/403/500 trần) thì ném để nhánh catch lo.
+      if (!response.ok && !data.errors) {
+        throw new Error(
+          (data as any).error || `Lỗi server (${response.status})`,
+        );
+      }
+
+      setState((prev) => ({
+        ...prev,
+        step: "done",
+        result: data,
+        errorMessage: null,
+      }));
+
+      if (data.success && data.importedCount > 0 && !data.dryRun) {
+        onSuccess?.(data);
+      }
+    } catch (error: any) {
+      if (error.name === "AbortError") return;
+      setState((prev) => ({
+        ...prev,
+        step: "error",
+        errorMessage: error.message || "Lỗi không xác định",
+      }));
+    }
+  }, [state.file, state.mode, state.dryRun, apiUrl, onSuccess]);
+
+  return {
+    ...state,
+    setFile,
+    setDryRun,
+    setMode,
+    execute,
+    reset,
+    isLoading:
+      state.step === "uploading" ||
+      state.step === "validating" ||
+      state.step === "importing",
+  };
+}