rl-core-front 0.7.0 → 0.8.0

package/src/features/queues/queues-screen.tsx

@@ -0,0 +1,264 @@
+"use client";
+
+import type {
+  ColumnDef,
+  OnChangeFn,
+  PaginationState,
+} from "@tanstack/react-table";
+import { RotateCcw, Trash2 } from "lucide-react";
+import type { JSX } from "react";
+import { useMemo } from "react";
+
+import {
+  Badge,
+  Button,
+  Card,
+  DataTable,
+  DataTableFeatures,
+  RowActions,
+  SegmentedControl,
+  SegmentedOption,
+} from "#core/components/ui";
+import { useAuth, useI18n } from "#core/contexts";
+import { useQueueJobs } from "#core/features/queues/hooks/use-queue-jobs";
+import {
+  QueueJob,
+  QueueJobState,
+} from "#core/features/queues/services/queues.service";
+import { useConfirm } from "#core/hooks/use-confirm";
+
+/** Rótulo de cada estado — a mesma chave serve à barra e aos cartões. */
+const STATE_LABEL: Record<QueueJobState, string> = {
+  [QueueJobState.WAITING]: "queues.stateWaiting",
+  [QueueJobState.ACTIVE]: "queues.stateActive",
+  [QueueJobState.COMPLETED]: "queues.stateCompleted",
+  [QueueJobState.FAILED]: "queues.stateFailed",
+  [QueueJobState.DELAYED]: "queues.stateDelayed",
+};
+
+const STATE_VARIANT: Record<
+  QueueJobState,
+  "secondary" | "warning" | "success" | "destructive"
+> = {
+  [QueueJobState.WAITING]: "secondary",
+  [QueueJobState.ACTIVE]: "warning",
+  [QueueJobState.COMPLETED]: "success",
+  [QueueJobState.FAILED]: "destructive",
+  [QueueJobState.DELAYED]: "secondary",
+};
+
+/**
+ * Fila de processamento — o que está rodando, o que falhou e o que fazer com
+ * isso.
+ *
+ * Substitui o painel do bull-board: aqui a tela mora no mesmo shell, com a
+ * mesma permissão e a mesma tradução do resto do sistema, em vez de um segundo
+ * frontend embutido no backend com autenticação própria.
+ */
+export function QueuesScreen(): JSX.Element {
+  const { t } = useI18n();
+  const { hasPermission } = useAuth();
+  const { confirm, confirmDialog } = useConfirm();
+  const queue = useQueueJobs();
+
+  const canManage = hasPermission("queues:manage:any");
+
+  const stateOptions = useMemo<SegmentedOption[]>(
+    () =>
+      Object.values(QueueJobState).map((value) => ({
+        value,
+        label: t(STATE_LABEL[value]),
+      })),
+    [t],
+  );
+
+  /** Remover é sem volta: some da fila e não há de onde reprocessar depois. */
+  const removeJob = async (id: string): Promise<void> => {
+    const confirmed = await confirm({
+      title: t("queues.removeTitle"),
+      description: t("queues.removeDescription"),
+      destructive: true,
+    });
+    if (confirmed) {
+      await queue.remove(id);
+    }
+  };
+
+  const columns = useMemo<ColumnDef<DataTableFeatures, QueueJob, unknown>[]>(
+    () => [
+      {
+        accessorKey: "name",
+        header: t("queues.job"),
+        meta: { label: t("queues.job") },
+        enableSorting: false,
+        cell: ({ row }) => (
+          <div className="flex flex-col">
+            <span className="font-medium">{row.original.name}</span>
+            <span className="font-mono text-xs text-muted-foreground">
+              #{row.original.id}
+            </span>
+          </div>
+        ),
+      },
+      {
+        accessorKey: "state",
+        header: t("queues.state"),
+        meta: { label: t("queues.state") },
+        enableSorting: false,
+        cell: ({ row }) => {
+          const state = row.original.state as QueueJobState;
+          return (
+            <Badge variant={STATE_VARIANT[state] ?? "secondary"}>
+              {t(STATE_LABEL[state] ?? "queues.stateWaiting")}
+            </Badge>
+          );
+        },
+      },
+      {
+        accessorKey: "percent",
+        header: t("queues.progress"),
+        meta: { label: t("queues.progress") },
+        enableSorting: false,
+        cell: ({ getValue }) => {
+          const percent = getValue() as number | null;
+          return percent == null ? "—" : `${percent}%`;
+        },
+      },
+      {
+        accessorKey: "attemptsMade",
+        header: t("queues.attempts"),
+        meta: { label: t("queues.attempts") },
+        enableSorting: false,
+      },
+      {
+        accessorKey: "createdAt",
+        header: t("queues.createdAt"),
+        meta: { label: t("queues.createdAt") },
+        enableSorting: false,
+        cell: ({ getValue }) => new Date(String(getValue())).toLocaleString(),
+      },
+      {
+        accessorKey: "failedReason",
+        header: t("queues.reason"),
+        meta: { label: t("queues.reason") },
+        enableSorting: false,
+        // Cru e por inteiro no `title`: quem lê esta tela é quem vai consertar
+        // a causa, e a mensagem truncada some justamente na parte útil.
+        cell: ({ getValue }) => {
+          const reason = getValue() as string | null;
+          return reason ? (
+            <span
+              className="line-clamp-2 max-w-md font-mono text-xs"
+              title={reason}
+            >
+              {reason}
+            </span>
+          ) : (
+            "—"
+          );
+        },
+      },
+      {
+        id: "actions",
+        header: () => <div className="text-center">{t("common.actions")}</div>,
+        meta: { shrink: true },
+        enableHiding: false,
+        enableSorting: false,
+        cell: ({ row }) =>
+          canManage ? (
+            <RowActions>
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => void queue.retry(row.original.id)}
+              >
+                <RotateCcw className="h-4 w-4" />
+                {t("queues.retry")}
+              </Button>
+              <Button
+                variant="ghost"
+                size="sm"
+                className="text-destructive"
+                onClick={() => void removeJob(row.original.id)}
+              >
+                <Trash2 className="h-4 w-4" />
+                {t("common.delete")}
+              </Button>
+            </RowActions>
+          ) : null,
+      },
+    ],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [t, canManage, queue],
+  );
+
+  const pagination: PaginationState = {
+    pageIndex: queue.page,
+    pageSize: queue.pageSize,
+  };
+  const onPaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    const next = typeof updater === "function" ? updater(pagination) : updater;
+    if (next.pageSize !== queue.pageSize) {
+      queue.setPageSize(next.pageSize);
+      queue.setPage(0);
+    } else if (next.pageIndex !== queue.page) {
+      queue.setPage(next.pageIndex);
+    }
+  };
+
+  return (
+    <div>
+      <h1 className="mb-1 text-3xl font-bold">{t("queues.title")}</h1>
+      <p className="mb-4 text-sm text-muted-foreground">
+        {t("queues.subtitle")}
+      </p>
+
+      {/* Os cartões são o resumo E o atalho: clicar troca o estado listado —
+          ver "3 falhos" e não poder abri-los seria uma informação morta. */}
+      <div className="mb-4 grid grid-cols-2 gap-3 sm:grid-cols-5">
+        {Object.values(QueueJobState).map((state) => (
+          <Card
+            key={state}
+            role="button"
+            tabIndex={0}
+            onClick={() => queue.setState(state)}
+            className={`cursor-pointer p-3 transition-colors hover:bg-accent ${
+              queue.state === state ? "border-primary" : ""
+            }`}
+          >
+            <p className="text-xs text-muted-foreground">
+              {t(STATE_LABEL[state])}
+            </p>
+            <p className="text-2xl font-bold tabular-nums">
+              {queue.counts[state]}
+            </p>
+          </Card>
+        ))}
+      </div>
+
+      <DataTable
+        columns={columns}
+        data={queue.rows}
+        getRowId={(r) => r.id}
+        storageKey="queues-jobs"
+        loading={queue.loading}
+        manualPagination
+        rowCount={queue.total}
+        pagination={pagination}
+        onPaginationChange={onPaginationChange}
+        enableSorting={false}
+        emptyMessage={t("queues.empty")}
+        toolbar={
+          <SegmentedControl
+            value={queue.state}
+            onValueChange={(value) => queue.setState(value as QueueJobState)}
+            options={stateOptions}
+            label={t("queues.state")}
+          />
+        }
+      />
+
+      {confirmDialog}
+    </div>
+  );
+}

package/src/features/queues/services/queues.service.ts

@@ -0,0 +1,57 @@
+import { api } from "#core/_services/api/axios.factory";
+import type { components } from "#core/_services/api/schema";
+
+/** Tipos derivados do `openapi.json` (§5) — não redigitar a forma da resposta. */
+export type QueueJob = components["schemas"]["QueueJobResponse"];
+export type QueueCounts = components["schemas"]["QueueCountsResponse"];
+
+export interface Paginated<T> {
+  items: T[];
+  meta: components["schemas"]["PaginationMetaResponse"];
+}
+
+/**
+ * Estados que a tela lista.
+ *
+ * Espelha o `LISTABLE_STATES` do backend. `paused` não está aqui porque é
+ * estado da fila inteira, não de um job.
+ */
+export enum QueueJobState {
+  WAITING = "waiting",
+  ACTIVE = "active",
+  COMPLETED = "completed",
+  FAILED = "failed",
+  DELAYED = "delayed",
+}
+
+export interface QueueJobsQuery {
+  state: QueueJobState;
+  page: number;
+  limit: number;
+}
+
+export const queuesService = {
+  counts(): Promise<QueueCounts> {
+    return api.get<QueueCounts>("/queues/counts").then((r) => r.data);
+  },
+
+  /**
+   * Uma página de jobs de **um** estado.
+   *
+   * O estado é obrigatório: no Redis cada estado é uma estrutura própria, e
+   * "todos" não é uma consulta que exista.
+   */
+  list(query: QueueJobsQuery): Promise<Paginated<QueueJob>> {
+    return api
+      .get<Paginated<QueueJob>>("/queues/jobs", { params: query })
+      .then((r) => r.data);
+  },
+
+  retry(id: string): Promise<void> {
+    return api.post(`/queues/jobs/${id}/retry`).then(() => undefined);
+  },
+
+  remove(id: string): Promise<void> {
+    return api.delete(`/queues/jobs/${id}`).then(() => undefined);
+  },
+};

package/src/hooks/use-job-progress.ts

@@ -0,0 +1,192 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+import { api } from "#core/_services/api/axios.factory";
+import { useSocket } from "#core/contexts/socket-context";
+
+/**
+ * Eventos que a fila do backend empurra (ver `job.constants.ts` do
+ * `rl-core-api`). Saem pela mesma conexão das notificações — o hook não abre
+ * socket nenhum.
+ */
+export const JOB_PROGRESS_EVENT = "job:progress";
+export const JOB_COMPLETED_EVENT = "job:completed";
+export const JOB_FAILED_EVENT = "job:failed";
+
+export type JobState = "idle" | "running" | "completed" | "failed";
+
+interface JobProgressEvent {
+  jobId: string;
+  name: string;
+  processed: number;
+  total: number;
+  percent: number;
+  message?: string;
+}
+
+interface JobCompletedEvent<TSummary> {
+  jobId: string;
+  name: string;
+  summary: TSummary;
+}
+
+interface JobFailedEvent {
+  jobId: string;
+  name: string;
+  errorCode: string | null;
+  message: string;
+}
+
+/** `GET /jobs/:id` — a mesma informação, para quem perdeu os eventos. */
+interface JobStatusResponse<TSummary> {
+  id: string;
+  name: string;
+  state: "waiting" | "active" | "completed" | "failed" | "delayed" | "unknown";
+  progress: {
+    processed: number;
+    total: number;
+    percent: number;
+    message?: string;
+  } | null;
+  summary: TSummary | null;
+  error: { code: string | null; message: string } | null;
+}
+
+export interface UseJobProgressResult<TSummary> {
+  state: JobState;
+  percent: number;
+  processed: number;
+  total: number;
+  message: string | null;
+  /** Relatório que o processador devolveu — só depois de `completed`. */
+  summary: TSummary | null;
+  error: { code: string | null; message: string } | null;
+}
+
+const IDLE = {
+  state: "idle" as JobState,
+  percent: 0,
+  processed: 0,
+  total: 0,
+  message: null,
+  summary: null,
+  error: null,
+};
+
+/**
+ * Acompanha um job em segundo plano.
+ *
+ * ```tsx
+ * const [jobId, setJobId] = useState<string | null>(null);
+ * const job = useJobProgress<ImportSummary>(jobId);
+ * ```
+ *
+ * Três coisas que o evento sozinho não resolve, e por isso o hook também
+ * consulta `GET /jobs/:id`:
+ *
+ * - o job pode ter terminado **antes** de a tela assinar (arquivo pequeno);
+ * - a aba pode ter sido recarregada no meio, com o `jobId` guardado;
+ * - o socket pode cair, e o que passou na janela offline não volta sozinho —
+ *   por isso a releitura também acontece a cada reconexão.
+ */
+export function useJobProgress<TSummary = unknown>(
+  jobId: string | null,
+): UseJobProgressResult<TSummary> {
+  const { on, reconnectCount } = useSocket();
+  const [result, setResult] = useState<UseJobProgressResult<TSummary>>(
+    IDLE as UseJobProgressResult<TSummary>,
+  );
+
+  // Job novo começa do zero: sem isto a barra do anterior ficaria em 100%.
+  useEffect(() => {
+    setResult(IDLE as UseJobProgressResult<TSummary>);
+  }, [jobId]);
+
+  const sync = useCallback(async (): Promise<void> => {
+    if (!jobId) {
+      return;
+    }
+    try {
+      const { data } = await api.get<JobStatusResponse<TSummary>>(
+        `/jobs/${jobId}`,
+      );
+      setResult({
+        state:
+          data.state === "completed"
+            ? "completed"
+            : data.state === "failed"
+              ? "failed"
+              : "running",
+        percent: data.progress?.percent ?? 0,
+        processed: data.progress?.processed ?? 0,
+        total: data.progress?.total ?? 0,
+        message: data.progress?.message ?? null,
+        summary: data.summary,
+        error: data.error,
+      });
+    } catch {
+      // Job expirado ou fora de alcance: o socket ainda pode trazer o fim, e
+      // derrubar a tela por causa da consulta de apoio seria pior.
+    }
+  }, [jobId]);
+
+  useEffect(() => {
+    void sync();
+  }, [sync, reconnectCount]);
+
+  useEffect(() => {
+    if (!jobId) {
+      return;
+    }
+
+    const offProgress = on<JobProgressEvent>(JOB_PROGRESS_EVENT, (data) => {
+      if (data.jobId !== jobId) {
+        return;
+      }
+      setResult((current) => ({
+        ...current,
+        state: "running",
+        percent: data.percent,
+        processed: data.processed,
+        total: data.total,
+        message: data.message ?? null,
+      }));
+    });
+
+    const offCompleted = on<JobCompletedEvent<TSummary>>(
+      JOB_COMPLETED_EVENT,
+      (data) => {
+        if (data.jobId !== jobId) {
+          return;
+        }
+        setResult((current) => ({
+          ...current,
+          state: "completed",
+          percent: 100,
+          summary: data.summary,
+          error: null,
+        }));
+      },
+    );
+
+    const offFailed = on<JobFailedEvent>(JOB_FAILED_EVENT, (data) => {
+      if (data.jobId !== jobId) {
+        return;
+      }
+      setResult((current) => ({
+        ...current,
+        state: "failed",
+        error: { code: data.errorCode, message: data.message },
+      }));
+    });
+
+    return () => {
+      offProgress();
+      offCompleted();
+      offFailed();
+    };
+  }, [jobId, on]);
+
+  return result;
+}

package/src/i18n/messages/en.ts

@@ -11,6 +11,7 @@ export const en: Messages = {
     profile: "My profile",
     logs: "Logs",
     audit: "Audit",
+    queues: "Queues",
   },
   logs: {
     outcomeSuccess: "Success",
@@ -84,6 +85,31 @@ export const en: Messages = {
     permissions: "Permissions",
     roles: "Roles",
   },
+  job: {
+    running: "Processing…",
+    completed: "Processing finished",
+    failed: "The processing could not be completed",
+  },
+  queues: {
+    title: "Queues",
+    subtitle: "Background processing — what is running and what failed",
+    job: "Job",
+    state: "State",
+    progress: "Progress",
+    attempts: "Attempts",
+    createdAt: "Created at",
+    reason: "Failure reason",
+    retry: "Retry",
+    removeTitle: "Remove this job?",
+    removeDescription:
+      "It leaves the queue and can no longer be retried from here.",
+    empty: "No jobs in this state",
+    stateWaiting: "Waiting",
+    stateActive: "Active",
+    stateCompleted: "Completed",
+    stateFailed: "Failed",
+    stateDelayed: "Delayed",
+  },
   table: {
     columns: "Columns",
     columnsButton: "Columns",

package/src/i18n/messages/pt.ts

@@ -9,6 +9,7 @@ export const pt = {
     profile: "Meu perfil",
     logs: "Logs",
     audit: "Auditoria",
+    queues: "Filas",
   },
   logs: {
     outcomeSuccess: "Sucesso",
@@ -86,6 +87,31 @@ export const pt = {
     permissions: "Permissões",
     roles: "Papéis",
   },
+  job: {
+    running: "Processando…",
+    completed: "Processamento concluído",
+    failed: "Não foi possível concluir o processamento",
+  },
+  queues: {
+    title: "Filas",
+    subtitle: "Processamento em segundo plano — o que está rodando e o que falhou",
+    job: "Job",
+    state: "Estado",
+    progress: "Progresso",
+    attempts: "Tentativas",
+    createdAt: "Criado em",
+    reason: "Motivo da falha",
+    retry: "Reprocessar",
+    removeTitle: "Remover este job?",
+    removeDescription:
+      "Ele sai da fila e não poderá mais ser reprocessado por aqui.",
+    empty: "Nenhum job neste estado",
+    stateWaiting: "Na fila",
+    stateActive: "Rodando",
+    stateCompleted: "Concluídos",
+    stateFailed: "Falhos",
+    stateDelayed: "Agendados",
+  },
   table: {
     columns: "Colunas",
     columnsButton: "Colunas",

package/src/index.ts

@@ -20,6 +20,16 @@ export { NotFoundScreen } from "#core/features/errors/not-found-screen";
 export { LoginScreen } from "#core/features/login/login-screen";
 export { LogsScreen } from "#core/features/logs/logs-screen";
 export { ProfileScreen } from "#core/features/profile/profile-screen";
+export { QueuesScreen } from "#core/features/queues/queues-screen";
+export type {
+  QueueCounts,
+  QueueJob,
+  QueueJobsQuery,
+} from "#core/features/queues/services/queues.service";
+export {
+  QueueJobState,
+  queuesService,
+} from "#core/features/queues/services/queues.service";
 export { RbacScreen } from "#core/features/rbac/rbac-screen";
 export { ForgotPasswordScreen } from "#core/features/recovery/forgot-password-screen";
 export { ResetPasswordScreen } from "#core/features/recovery/reset-password-screen";
@@ -60,6 +70,16 @@ export type { UseFilterSchemaResult } from "#core/hooks/use-filter-schema";
 export { useFilterSchema } from "#core/hooks/use-filter-schema";
 export type { FilterMode, FiltersState } from "#core/hooks/use-filters";
 export { useFilters } from "#core/hooks/use-filters";
+export type {
+  JobState,
+  UseJobProgressResult,
+} from "#core/hooks/use-job-progress";
+export {
+  JOB_COMPLETED_EVENT,
+  JOB_FAILED_EVENT,
+  JOB_PROGRESS_EVENT,
+  useJobProgress,
+} from "#core/hooks/use-job-progress";
 export type { UseListQueryResult } from "#core/hooks/use-list-query";
 export { useListQuery } from "#core/hooks/use-list-query";
 export type { RunOptions, UseRequestResult } from "#core/hooks/use-request";