@seedgrid/fe-backup 2026.7.0

package/scaffold/src/app/backup/exports/(list)/page.tsx

@@ -0,0 +1,286 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import {
+  SgButton,
+  SgConfirmationDialog,
+  SgDatatable,
+  SgStack,
+  sgWhistle,
+} from "@seedgrid/fe-components";
+import { Download, Plus, Trash2 } from "lucide-react";
+import { useRouter } from "next/navigation";
+
+import { useI18n } from "@/i18n";
+import { PageFrame, RouteGuard } from "@/modules/security";
+
+import { backupConfig } from "@/modules/backup/config";
+import { ExportStatusBadge } from "@/modules/backup/components/ExportStatusBadge";
+import { extractBackupApiMessage } from "@/modules/backup/services/backup-api";
+import { backupService } from "@/modules/backup/services/backup-service";
+import { isExportDownloadable, isExportInProgress } from "@seedgrid/fe-backup";
+import type { ExportResponse } from "@/modules/backup/types";
+
+export default function ExportsListPage() {
+  return (
+    <RouteGuard permissions={["JOB_READ"]}>
+      <ExportsListScreen />
+    </RouteGuard>
+  );
+}
+
+function ExportsListScreen() {
+  const router = useRouter();
+  const { t } = useI18n();
+
+  const [exports, setExports] = useState<ExportResponse[]>([]);
+  const [page, setPage] = useState(0);
+  // <number>: defaultPageSize e literal, sem anotacao o setRows(number)
+  // falharia (TS2345 SetStateAction<literal>).
+  const [rows, setRows] = useState<number>(backupConfig.pagination.defaultPageSize);
+  const [loading, setLoading] = useState(true);
+  const [selectedJob, setSelectedJob] = useState<ExportResponse | null>(null);
+  const [downloadingId, setDownloadingId] = useState<string | null>(null);
+
+  const pollingRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const loadExports = useCallback(
+    async (silent = false) => {
+      if (!silent) setLoading(true);
+
+      try {
+        const data = await backupService.listExportJobs({ page, size: rows });
+        setExports(data);
+      } catch (error) {
+        if (!silent) {
+          sgWhistle.error({
+            message:
+              extractBackupApiMessage(error) ??
+              t("backup.exports.list.load_error"),
+          });
+        }
+      } finally {
+        if (!silent) setLoading(false);
+      }
+    },
+    [page, rows, t]
+  );
+
+  useEffect(() => {
+    void loadExports();
+  }, [loadExports]);
+
+  // Poll while any job is in progress
+  useEffect(() => {
+    const hasInProgress = exports.some((e) => isExportInProgress(e.status));
+
+    if (hasInProgress) {
+      pollingRef.current = setInterval(() => {
+        void loadExports(true);
+      }, backupConfig.polling.intervalMs);
+    }
+
+    return () => {
+      if (pollingRef.current) {
+        clearInterval(pollingRef.current);
+        pollingRef.current = null;
+      }
+    };
+  }, [exports, loadExports]);
+
+  async function handleDownload(job: ExportResponse) {
+    setDownloadingId(job.jobId);
+
+    try {
+      const downloadUrl = `/api/backup/exports/${encodeURIComponent(job.jobId)}/download`;
+      const anchor = document.createElement("a");
+      anchor.href = downloadUrl;
+      anchor.download = "";
+      document.body.appendChild(anchor);
+      anchor.click();
+      document.body.removeChild(anchor);
+    } catch (error) {
+      sgWhistle.error({
+        message:
+          extractBackupApiMessage(error) ??
+          t("backup.exports.list.download_error"),
+      });
+    } finally {
+      setDownloadingId(null);
+    }
+  }
+
+  async function handleDelete() {
+    if (!selectedJob) return;
+
+    try {
+      await backupService.deleteExportJob(selectedJob.jobId);
+      sgWhistle.success({ message: t("backup.exports.list.delete_success") });
+      setSelectedJob(null);
+      await loadExports();
+    } catch (error) {
+      sgWhistle.error({
+        message:
+          extractBackupApiMessage(error) ??
+          t("backup.exports.list.delete_error"),
+      });
+    }
+  }
+
+  function formatBytes(bytes?: number | null) {
+    if (bytes == null) return "-";
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+
+  function formatDate(dateStr?: string) {
+    if (!dateStr) return "-";
+    try {
+      return new Intl.DateTimeFormat(undefined, {
+        dateStyle: "short",
+        timeStyle: "short",
+      }).format(new Date(dateStr));
+    } catch {
+      return dateStr;
+    }
+  }
+
+  const columns = useMemo(
+    () => [
+      {
+        field: "jobId",
+        header: t("backup.exports.list.column.job_id"),
+        body: (row: ExportResponse) => (
+          <span className="font-mono text-xs text-slate-500">
+            {row.jobId.slice(0, 8)}…
+          </span>
+        ),
+      },
+      {
+        field: "format",
+        header: t("backup.exports.list.column.format"),
+        body: (row: ExportResponse) =>
+          t(`backup.exports.format.${row.format}`),
+      },
+      {
+        field: "scope",
+        header: t("backup.exports.list.column.scope"),
+        body: (row: ExportResponse) =>
+          t(`backup.exports.scope.${row.scope}`),
+      },
+      {
+        field: "status",
+        header: t("backup.exports.list.column.status"),
+        body: (row: ExportResponse) => (
+          <SgStack direction="row" gap={8} align="center">
+            <ExportStatusBadge status={row.status} />
+            {isExportInProgress(row.status) && row.progress != null ? (
+              <span className="text-xs text-slate-500">{row.progress}%</span>
+            ) : null}
+          </SgStack>
+        ),
+      },
+      {
+        field: "createdAt",
+        header: t("backup.exports.list.column.created_at"),
+        body: (row: ExportResponse) => formatDate(row.createdAt),
+      },
+      {
+        field: "totalSizeBytes",
+        header: t("backup.exports.list.column.size"),
+        body: (row: ExportResponse) => formatBytes(row.totalSizeBytes),
+      },
+      {
+        header: t("backup.common.actions"),
+        body: (row: ExportResponse) => (
+          <SgStack direction="row" gap={8} wrap data-sg-stop-row-select="true">
+            {isExportDownloadable(row.status) ? (
+              <SgButton
+                appearance="ghost"
+                severity="success"
+                iconOnly
+                leftIcon={<Download size={16} />}
+                title={t("backup.exports.list.action.download")}
+                aria-label={t("backup.exports.list.action.download")}
+                loading={downloadingId === row.jobId}
+                onClick={() => void handleDownload(row)}
+                className="border border-emerald-200/80 bg-emerald-50/45 text-emerald-700 hover:border-emerald-300 hover:bg-emerald-50 hover:text-emerald-800"
+              />
+            ) : null}
+            <SgButton
+              appearance="ghost"
+              severity="danger"
+              iconOnly
+              leftIcon={<Trash2 size={16} />}
+              title={
+                isExportInProgress(row.status)
+                  ? t("backup.exports.list.action.cancel")
+                  : t("backup.exports.list.action.delete")
+              }
+              aria-label={t("backup.exports.list.action.delete")}
+              onClick={() => setSelectedJob(row)}
+              className="border border-rose-200/80 bg-rose-50/45 text-rose-600 hover:border-rose-200 hover:bg-rose-50/70 hover:text-rose-700"
+            />
+          </SgStack>
+        ),
+      },
+    ],
+    [t, downloadingId]
+  );
+
+  return (
+    <PageFrame
+      title={t("backup.exports.list.title")}
+      description={t("backup.exports.list.description")}
+      actions={
+        <SgStack direction="row" gap={8}>
+          <SgButton
+            appearance="ghost"
+            severity="secondary"
+            label={t("backup.common.refresh")}
+            onClick={() => void loadExports()}
+            disabled={loading}
+          />
+          <SgButton
+            appearance="solid"
+            severity="primary"
+            shape="rounded"
+            leftIcon={<Plus size={16} />}
+            label={t("backup.exports.list.new")}
+            onClick={() => router.push(backupConfig.routes.newExport)}
+          />
+        </SgStack>
+      }
+    >
+      <SgStack gap={16}>
+        <SgDatatable<ExportResponse>
+          title=" "
+          value={exports}
+          columns={columns}
+          dataKey="jobId"
+          lazy
+          paginator
+          rows={rows}
+          first={page * rows}
+          loading={loading}
+          emptyMessage={t("backup.exports.list.empty")}
+          onPage={(event) => {
+            setRows(event.rows ?? backupConfig.pagination.defaultPageSize);
+            setPage(event.page ?? 0);
+          }}
+        />
+      </SgStack>
+
+      <SgConfirmationDialog
+        open={Boolean(selectedJob)}
+        severity="danger"
+        title={t("backup.exports.list.delete_title")}
+        message={t("backup.exports.list.delete_message")}
+        onCancel={() => setSelectedJob(null)}
+        onConfirm={() => void handleDelete()}
+      />
+    </PageFrame>
+  );
+}

package/scaffold/src/modules/backup/components/ExportStatusBadge.test.tsx

@@ -0,0 +1,75 @@
+// seedgrid:managed
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { classifyExportStatus, isExportDownloadable, isExportInProgress } from "@seedgrid/fe-backup";
+import type { ExportStatus } from "@seedgrid/fe-backup";
+
+describe("classifyExportStatus", () => {
+  it("classifies REQUESTED and QUEUED as pending", () => {
+    expect(classifyExportStatus("REQUESTED")).toBe("pending");
+    expect(classifyExportStatus("QUEUED")).toBe("pending");
+  });
+
+  it("classifies RUNNING as running", () => {
+    expect(classifyExportStatus("RUNNING")).toBe("running");
+  });
+
+  it("classifies DONE and DONE_NOTIFIED as done", () => {
+    expect(classifyExportStatus("DONE")).toBe("done");
+    expect(classifyExportStatus("DONE_NOTIFIED")).toBe("done");
+  });
+
+  it("classifies FAILED as failed", () => {
+    expect(classifyExportStatus("FAILED")).toBe("failed");
+  });
+
+  it("classifies EXPIRED and CANCELLED as terminal", () => {
+    expect(classifyExportStatus("EXPIRED")).toBe("terminal");
+    expect(classifyExportStatus("CANCELLED")).toBe("terminal");
+  });
+});
+
+describe("isExportInProgress", () => {
+  it("returns true for active states", () => {
+    const inProgressStates: ExportStatus[] = ["REQUESTED", "QUEUED", "RUNNING"];
+    for (const status of inProgressStates) {
+      expect(isExportInProgress(status)).toBe(true);
+    }
+  });
+
+  it("returns false for terminal and done states", () => {
+    const notInProgress: ExportStatus[] = [
+      "DONE",
+      "DONE_NOTIFIED",
+      "FAILED",
+      "EXPIRED",
+      "CANCELLED",
+    ];
+    for (const status of notInProgress) {
+      expect(isExportInProgress(status)).toBe(false);
+    }
+  });
+});
+
+describe("isExportDownloadable", () => {
+  it("returns true only for DONE and DONE_NOTIFIED", () => {
+    expect(isExportDownloadable("DONE")).toBe(true);
+    expect(isExportDownloadable("DONE_NOTIFIED")).toBe(true);
+  });
+
+  it("returns false for all other statuses", () => {
+    const nonDownloadable: ExportStatus[] = [
+      "REQUESTED",
+      "QUEUED",
+      "RUNNING",
+      "FAILED",
+      "EXPIRED",
+      "CANCELLED",
+    ];
+    for (const status of nonDownloadable) {
+      expect(isExportDownloadable(status)).toBe(false);
+    }
+  });
+});

package/scaffold/src/modules/backup/components/ExportStatusBadge.tsx

@@ -0,0 +1,54 @@
+// seedgrid:managed
+
+import { SgBadge } from "@seedgrid/fe-components";
+
+import { useI18n } from "@/i18n";
+
+import type { ExportStatus } from "@seedgrid/fe-backup";
+import { classifyExportStatus } from "@seedgrid/fe-backup";
+
+type SgBadgeSeverity =
+  | "primary"
+  | "secondary"
+  | "success"
+  | "warning"
+  | "danger"
+  | "info"
+  | "neutral";
+
+function resolveBadgeSeverity(status: ExportStatus): SgBadgeSeverity {
+  const group = classifyExportStatus(status);
+
+  switch (group) {
+    case "pending":
+      return "info";
+    case "running":
+      return "primary";
+    case "done":
+      return "success";
+    case "failed":
+      return "danger";
+    case "terminal":
+      return "neutral";
+    default:
+      return "neutral";
+  }
+}
+
+interface ExportStatusBadgeProps {
+  status: ExportStatus;
+}
+
+export function ExportStatusBadge({ status }: ExportStatusBadgeProps) {
+  const { t } = useI18n();
+  const key = `backup.exports.status.${status}` as const;
+
+  return (
+    <SgBadge
+      value={t(key)}
+      severity={resolveBadgeSeverity(status)}
+      badgeStyle="soft"
+      size="sm"
+    />
+  );
+}

package/scaffold/src/modules/backup/config.ts

@@ -0,0 +1,27 @@
+// seedgrid:managed
+
+import { appEnvironment } from "@/config/environment";
+
+function resolveApiBaseUrl() {
+  // Client-side: route through Next.js proxy to avoid CORS on error responses.
+  if (globalThis.window !== undefined) {
+    return "/api";
+  }
+
+  return appEnvironment.hosts.apiOrigin;
+}
+
+export const backupConfig = {
+  apiBaseUrl: resolveApiBaseUrl(),
+  pagination: {
+    defaultPageSize: 10,
+    pageSizeOptions: [10, 20, 50],
+  },
+  polling: {
+    intervalMs: 5000,
+  },
+  routes: {
+    exports: "/backup/exports",
+    newExport: "/backup/exports/new",
+  },
+} as const;

package/scaffold/src/modules/backup/index.ts

@@ -0,0 +1,19 @@
+// seedgrid:managed
+
+export { backupConfig } from "./config";
+export { useBackupAppShellSections } from "./useBackupAppShellSections";
+export { configureBackupApi, extractBackupApiMessage, isApiClientError } from "./services/backup-api";
+export { backupService } from "./services/backup-service";
+export { ExportStatusBadge } from "./components/ExportStatusBadge";
+export type { ArtifactInfo, BackupFormat, ExportRequest, ExportResponse, ExportScope } from "./types";
+
+// Promovidos pra lib versionada (@seedgrid/fe-backup) — ver ADR 0004/0005 e
+// scaffold/README.md pro critério lib vs scaffold usado nesta extração.
+export {
+  backupMessages,
+  classifyExportStatus,
+  isExportDownloadable,
+  isExportInProgress,
+  type ExportStatus,
+  type ExportStatusGroup,
+} from "@seedgrid/fe-backup";

package/scaffold/src/modules/backup/services/backup-api.test.ts

@@ -0,0 +1,122 @@
+// seedgrid:managed
+
+import { describe, expect, it } from "vitest";
+
+import { ApiClientError } from "@/modules/core";
+
+import { extractBackupApiMessage } from "./backup-api";
+
+describe("extractBackupApiMessage", () => {
+  it("returns the first violation message from backend validation errors", () => {
+    const error = new ApiClientError("API request failed with status 400", 400, {
+      type: "https://seedgrid.com.br/dados-invalidos",
+      title: "Dados invalidos",
+      status: 400,
+      detail: "Revise os campos informados.",
+      devMessage: "",
+      instance: "/exports",
+      violations: [
+        {
+          field: "exportRequest.format",
+          message: "Formato de exportacao invalido",
+        },
+      ],
+    });
+
+    expect(extractBackupApiMessage(error)).toBe("Formato de exportacao invalido");
+  });
+
+  it("returns the rfc7807 detail when the response has no violations", () => {
+    const error = new ApiClientError("API request failed with status 403", 403, {
+      type: "https://seedgrid.com.br/acesso-negado",
+      title: "Acesso negado",
+      status: 403,
+      detail: "Voce nao tem permissao para criar exportacoes",
+      devMessage: "",
+      instance: "/exports",
+    });
+
+    expect(extractBackupApiMessage(error)).toBe(
+      "Voce nao tem permissao para criar exportacoes"
+    );
+  });
+
+  it("parses stringified problem json responses before extracting the message", () => {
+    const error = new ApiClientError(
+      "API request failed with status 400",
+      400,
+      JSON.stringify({
+        type: "https://seedgrid.com.br/dados-invalidos",
+        title: "Dados invalidos",
+        status: 400,
+        detail: "Revise os campos informados.",
+        devMessage: "",
+        instance: "/exports",
+        violations: [
+          {
+            field: "exportRequest.format",
+            message: "Formato e obrigatorio",
+          },
+          {
+            field: "exportRequest.scope",
+            message: "Escopo e obrigatorio",
+          },
+        ],
+      })
+    );
+
+    expect(extractBackupApiMessage(error)).toBe("Formato e obrigatorio");
+  });
+
+  it("falls back to the api client message when the response has no readable details", () => {
+    const error = new ApiClientError("API request failed with status 500", 500, {
+      status: 500,
+    });
+
+    expect(extractBackupApiMessage(error)).toBe(
+      "API request failed with status 500"
+    );
+  });
+
+  it("falls back to the api client message for an empty response body", () => {
+    // Corpo vazio {} e tao "sem conteudo legivel" quanto { status: 500 } (o
+    // teste-irmao acima) — ambos caem no message do ApiClientError, de forma
+    // consistente. (Antes este teste esperava null, um contrato divergente do
+    // irmao que o codigo nunca honrou.)
+    const error = new ApiClientError("API request failed with status 500", 500, {});
+
+    expect(extractBackupApiMessage(error)).toBe(
+      "API request failed with status 500"
+    );
+  });
+
+  it("maps fetch failures to a friendly server connection message", () => {
+    const result = extractBackupApiMessage(new Error("fetch failed"));
+    // The message is resolved from i18n — verify it is a non-null string
+    expect(result).not.toBeNull();
+    expect(typeof result).toBe("string");
+  });
+
+  it("maps 'failed to fetch' to the server connection message", () => {
+    const result = extractBackupApiMessage(new Error("Failed to fetch"));
+    expect(result).not.toBeNull();
+    expect(typeof result).toBe("string");
+  });
+
+  it("returns null for non-Error unknown values", () => {
+    expect(extractBackupApiMessage(null)).toBeNull();
+    expect(extractBackupApiMessage(undefined)).toBeNull();
+    expect(extractBackupApiMessage("string error")).toBeNull();
+    expect(extractBackupApiMessage(42)).toBeNull();
+  });
+
+  it("returns null when the response body is an HTML page", () => {
+    const error = new ApiClientError(
+      "API request failed with status 502",
+      502,
+      "<!DOCTYPE html><html><body>Bad Gateway</body></html>"
+    );
+
+    expect(extractBackupApiMessage(error)).toBeNull();
+  });
+});