Backend (Curio)

Conexão e sessão Curio, caso de uso e React Query.

05 — Curio: conexão e sessão
06 — Caso de uso
07 — React Query

05 — Curio: conexão e sessão

Como o front autentica, mantém e encerra a sessão com o backend Curio. Toda a integração com @curio/client está confinada em src/lib/curio/ e src/api/session.ts. Nenhuma página importa @curio/client para configurar transporte.

Camadas

Página
  └─ useAuth()                 src/context/AuthProvider.tsx    ← o que a página usa
       └─ useAuthQuery()       src/hooks/useAuthQuery.ts       estado via React Query
            └─ login/connect   src/api/session.ts              operações de sessão
                 └─ getSessionManager()  src/lib/curio/index.ts  transporte
                      └─ @curio/client

Componentes usam useAuth(). Nunca useAuthQuery diretamente, nunca getSessionManager().

`src/lib/curio/`

Quatro arquivos.

`index.ts` — fábrica do transporte

// src/lib/curio/index.ts
import { V3RequestParser } from "@curio/client/parsers";
import { Session } from "./Session";
import { SessionManager } from "./SessionManager";
import { createV3Validator } from "@curio/client/validators";
import { FetchLink } from "@curio/client/links";

export interface Config {
  service: { url: string; server: string; system: string; port: string };
  accessToken: string;
  resources: { get: string; put: string; viewer: string };
  logs: boolean;
}

const createSessionManager = (configuration: Config) => {
  const link = new FetchLink(configuration.service);
  const requestParser = new V3RequestParser(configuration.service);

  // pipeline: request -> parse -> json -> post -> valida
  return new SessionManager(configuration.service, (request) =>
    Promise.resolve(request)
      .then(requestParser.parse)
      .then(JSON.stringify)
      .then(link.parse)
      .then(link.post)
      .then((response) => response.json())
      .then(createV3Validator(request).validate)
  );
};

export const getSessionManager = async () => {
  const CONFIG_PATH = "./config.json";
  const cnfg = await (await fetch(CONFIG_PATH)).json();
  return createSessionManager(cnfg);
};

export type { Service as SV } from "./SessionManager";
export { Session, SessionManager };
export { isAuthError } from "./isAuthError";
export * from "./SessionManager";

getSessionManager() cria uma instância nova a cada chamada — não é singleton, apesar do nome. Isso é aceitável porque só é chamado em login, connect e em requests anônimos. Não chame dentro de componente ou hook de página. Para falar com o backend a partir de uma tela, use a sessão do useAuth() — ver 06.

`Session.ts` — a sessão do app

// src/lib/curio/Session.ts
import { MainUseCase } from "@curio/client";

export class Session extends MainUseCase {
  module: number | undefined;
  storageToken: string | undefined;
}

Estende MainUseCase só para carregar module e storageToken. Se o projeto precisar de mais estado por sessão, é aqui.

`SessionManager.ts` — detecção de sessão morta

// src/lib/curio/SessionManager.ts
import { MainUseCase, RequestDriver, SecurityManager, UseCaseMessageType } from "@curio/client";
import { Session } from "./Session";
import { isAuthError } from "./isAuthError";
import { ABORT } from "@curio/client/utils/constants";

export interface ConfigService {
  url: string;
  server: string;
  system: number;
  port: number;
  module: number;
  version: number;
}

// chave unica por app — nunca reaproveitar de outro projeto
export const STORAGEKEY = "br.com.nomedoprojeto";

export class SessionManager extends SecurityManager {
  public session: MainUseCase | undefined;
  private _service: ConfigService;
  private _driver: RequestDriver;

  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @curio nao tipa o service
  constructor(service: any, driver: RequestDriver) {
    super(service, driver);
    this._service = service;
    this._driver = driver;
  }

  public async openMainUseCase<U extends typeof MainUseCase>(username: string, password: string, constructor?: U) {
    this.session = await super.openMainUseCase(username, password, constructor);
    this._attachListeners();
    return this.session! as InstanceType<U>;
  }

  public connectMainUseCase(mainUseCase: MainUseCase) {
    this.session = mainUseCase;
    this._attachListeners();
    return super.connectMainUseCase(mainUseCase);
  }

  // sessao anonima: pre-login (ex. obter versao)
  public anonymousSession() {
    return new Session(0, this._service, this._driver);
  }

  private _attachListeners() {
    this.session!.addListener(ABORT, () => this._unauthenticate(false));
    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @curio nao tipa a mensagem
    this.session!.addListener(UseCaseMessageType.RESPONSE, (message: any) => {
      if (isAuthError(message.error)) this._unauthenticate(true);
    });
  }

  private _unauthenticate(expired: boolean) {
    this.session = undefined;
    if (expired) localStorage.removeItem(STORAGEKEY);
  }
}

STORAGEKEY identifica a sessão no storage. Troque por um valor próprio do projeto novo.

Cuidado com storage inconsistente. Se o token é escrito em sessionStorage mas a limpeza remove de localStorage (ou vice-versa), a limpeza não limpa nada — são storages diferentes. Escolha um e use o mesmo nos dois lugares. O snippet acima e o de session.ts abaixo usam sessionStorage de forma consistente — token de sessão não deve sobreviver ao fechamento da aba.

`isAuthError.ts` — o que conta como falha de autenticação

// src/lib/curio/isAuthError.ts
import { DestinataryNotFoundError } from "@curio/client/errors";

// code -1 = sessao inexistente no servidor
export const isAuthError = (error: unknown): boolean =>
  error instanceof DestinataryNotFoundError || String((error as { code?: unknown } | null | undefined)?.code) === "-1";

Ponto único de decisão. Se o backend introduzir outro código de sessão inválida, muda só aqui.

`src/api/session.ts`

// src/api/session.ts
import { ConnectionError, DestinataryNotFoundError } from "@curio/client/errors";
import { Session, getSessionManager } from "../lib/curio";
import { STORAGEKEY } from "../lib/curio/SessionManager";

export interface LoginParams {
  email: string;
  password?: string;
}

export async function login(params: LoginParams) {
  const { email, password } = params;
  try {
    const sessionManager = await getSessionManager();
    const session = await sessionManager.openMainUseCase(email, password ?? "", Session);
    session.module = 0;
    session.storageToken = STORAGEKEY;
    sessionStorage.setItem(STORAGEKEY, session.token.toString());
    return session;
  } catch (error) {
    return error as Error;
  }
}

// reconecta a partir do token guardado (refresh de pagina)
export async function connect(token: string) {
  try {
    const sessionManager = await getSessionManager();
    sessionManager.connectMainUseCase(new Session(token, sessionManager.service, sessionManager.driver));
    await sessionManager.session!.timeoutCheck();
    const session = sessionManager.session! as Session;
    session.module = 0;
    session.storageToken = STORAGEKEY;
    sessionStorage.setItem(STORAGEKEY, session.token.toString());
    return session;
  } catch (error) {
    if (error instanceof DestinataryNotFoundError) return error;
    if (error instanceof ConnectionError) return error;
    return error as Error;
  }
}

export async function logoutSession(session?: Session) {
  if (session) session.abort();
  sessionStorage.removeItem(STORAGEKEY);
}

login e connect retornam o erro em vez de lançar. Quem chama precisa testar result instanceof Error. É contraintuitivo e fácil de errar — se o projeto novo puder, prefira deixar lançar e tratar no hook.

Cuidado com localStorage.clear() no logout — ele apaga preferências de UI não relacionadas à sessão. O snippet acima remove só a chave da sessão.

Requests anônimos (pré-login)

Para chamar o backend antes de autenticar — por exemplo, exibir a versão do servidor na tela de login:

// src/api/session.ts
export const VERSION = { useCase: "3916", getVersion: "RM_OBTER_VERSAO" };

export async function obterVersaoRequest() {
  const sessionManager = await getSessionManager();
  const anonymousSession = sessionManager.anonymousSession();
  const uc = await anonymousSession?.openUseCase(VERSION.useCase);
  const response = await uc?.sendRequest(VERSION.getVersion);
  await uc?.abort(); // sempre fechar — sessao anonima nao tem dono
  return response.Versao._ as string;
}

`AuthProvider`

// src/context/AuthProvider.tsx (trecho essencial)
export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const { notification } = useNotification();
  const navigate = useNavigate();
  const { session, isLoading, isAuth, login: authLogin, logout: authLogout, refetchConnection } = useAuthQuery();

  // reconecta no boot se ha token guardado
  useEffect(() => {
    if (sessionStorage.getItem(STORAGEKEY)) refetchConnection();
  }, []);

  const logout = useCallback(() => {
    authLogout();
    navigate("/", { replace: true });
  }, [authLogout, navigate]);

  // fonte unica de logout: reage a notificacao de erro de auth.
  // ref evita disparar 2x — logout muda de identidade a cada render.
  const handledNotificationRef = useRef<NotificationType | null>(null);

  useEffect(() => {
    if (!notification) return;
    const expiredSession = notification.message === "Sessão expirada!";
    if (!notification.isAuthError && !expiredSession) return;
    if (handledNotificationRef.current === notification) return;
    handledNotificationRef.current = notification;
    logout();
  }, [notification, logout]);

  const login = async (params: LoginCredentials) => {
    await authLogin(params);
    navigate("/dashboard");
  };

  return (
    <AuthContext.Provider value={{ isAuth, session, isLoading, login, logout }}>{children}</AuthContext.Provider>
  );
};

Ciclo de vida

Evento	O que acontece
Boot com token	`refetchConnection()` → `connect(token)` → sessão restaurada
Login	`login()` → token no `sessionStorage` → navega para `/dashboard`
Request com sessão morta	`isAuthError` → notificação com `isAuthError: true` → `AuthProvider` desloga
`ABORT` do servidor	Listener no `SessionManager` limpa a sessão
Logout manual	`session.abort()` → limpa storage → navega para `/`

Detecção de expiração por string

const expiredSession = notification.message === "Sessão expirada!";

Comparar mensagem literal é frágil: muda a tradução no backend, o auto-logout para de funcionar sem erro visível. Preferível é o backend sinalizar com um código que isAuthError reconheça. Se precisar manter, isole a string numa constante e documente a dependência.

06 — Caso de uso

Como uma tela fala com o backend Curio. Padrão vigente: UseCaseManager envolve a página, useUseCaseControls abre/fecha, useCurioMutation envia requests. Não use session.openUseCase() direto numa página. Esse é o caminho de baixo nível.

O modelo mental

O Curio não é REST. Não há endpoint por recurso. Há:

Um caso de uso, identificado por um id numérico ("2544"). Ele tem estado no servidor: você o abre, interage, e fecha.
Requests nomeados dentro dele ("RM_INCLUI_OBJETO"), que recebem e devolvem objetos.

Um caso de uso é aproximadamente "uma tela do sistema" do lado do servidor. Por isso o casamento natural é um caso de uso por página.

Página (UseCaseManager useCaseId="2544")
  ├─ useUseCaseControls()   → open() / close() / status
  └─ useCurioMutation("RM_INCLUI_OBJETO")  → mutate() / mutateAsync()

Cadeia de chamada

Toda chamada ao backend segue a mesma cadeia de três camadas, sempre nesta ordem:

Componente (.tsx)  →  hook específico da feature (service/hooks.ts)  →  useCurioMutation

Componente — chama o hook da feature, nunca useCurioMutation direto.
Hook específico da feature — uma função de uma linha por request, tipada, nomeada pelo verbo do RM. É a única coisa que sabe qual string vai para o backend.
useCurioMutation — genérico, não sabe nada sobre Fornecedor. Ver 21.

// service/hooks.ts — o hook específico é a ÚNICA camada que conhece o nome do RM
export const useSalvaFornecedor = () => useCurioMutation<void, SalvaFornecedorRequest>(FORNECEDOR_RMS.SALVAR);

// Page.tsx — o componente so conhece o hook, nunca a string do RM
const { mutateAsync: salvar, isPending } = useSalvaFornecedor();

Nunca pule uma camada. Chamar useCurioMutation("RM_SALVA_OBJETO") direto no componente espalha o nome do request por várias telas — renomear o RM no backend exige grep no projeto inteiro em vez de editar uma linha.

Convenção `_RMS`: use case e requests num só objeto

Cada feature declara um objeto de constantes com o id do caso de uso e o nome de todos os seus requests. Um arquivo, uma fonte da verdade.

// src/pages/Cadastro/Fornecedor/service/constants.ts
export const FORNECEDOR_RMS = {
  USE_CASE: "4821",
  OBTEM_DADOS: "RM_OBTEM_DADOS_FORNECEDOR",
  SALVAR: "RM_SALVAR_DADOS_FORNECEDOR",
  REMOVER: "RM_REMOVER_FORNECEDOR"
};

Regras:

Nome do objeto: {ENTIDADE}_RMS, maiúsculo, no plural de "requests do módulo" — não é o plural da entidade.
USE_CASE é sempre a primeira chave. É o único valor que o UseCaseManager da página consome.
Os demais valores são os nomes exatos dos requests, em SCREAMING_SNAKE_CASE com prefixo RM_ no valor (a chave do objeto pode ser mais curta e legível — SALVAR, não SALVAR_DADOS_FORNECEDOR).
Nenhuma string de RM ou de id de caso de uso literal fora deste arquivo. Nem em hooks.ts, nem na página.

hooks.ts importa a constante em vez de repetir a string:

// service/hooks.ts
import { useCurioMutation } from "@/hooks";
import { FORNECEDOR_RMS } from "./constants";
import type {
  SalvaFornecedorRequest,
  BuscaFornecedoresRequest,
  BuscaFornecedoresResponse,
  FornecedorInicialResponse
} from "./interfaces";

export const useIncluiFornecedor = () => useCurioMutation<FornecedorInicialResponse, void>(FORNECEDOR_RMS.OBTEM_DADOS);

export const useBuscaFornecedores = () =>
  useCurioMutation<BuscaFornecedoresResponse, BuscaFornecedoresRequest>(FORNECEDOR_RMS.SALVAR);

export const useRemoveFornecedor = () => useCurioMutation<unknown, { Fornecedor: string }>(FORNECEDOR_RMS.REMOVER);

E a página importa a mesma constante para o useCaseId do UseCaseManager — ver "A página" abaixo. Um único arquivo muda quando o backend renumerar o caso de uso ou renomear um request.

Anatomia de uma tela

Uma tela que fala com o backend tem quatro arquivos:

src/pages/Fornecedor/Cadastro/
├── IncluirFornecedorPage.tsx    componente + UseCaseManager
├── schemas.ts                    validação zod
└── service/
    ├── constants.ts               FORNECEDOR_RMS — useCaseId + nomes dos requests
    ├── interfaces.ts              tipos de request/response
    └── hooks.ts                   um hook por request

`service/interfaces.ts`

Tipa o que entra e sai do backend. Convenção _Prefixo — ver 13.

// src/pages/Fornecedor/Cadastro/service/interfaces.ts

export interface FornecedorXML {
  _OID: string;
  _Nome: string;
  _CNPJ: string;
  _Ativo: boolean;
  Endereco?: EnderecoXML;
}

export interface EnderecoXML {
  _OID: string;
  _Logradouro: string;
  _Cidade: string;
}

// resposta de abertura: backend devolve o objeto recem-criado
export interface FornecedorInicialResponse {
  Fornecedor: FornecedorXML;
}

export interface SalvaFornecedorRequest {
  Fornecedor: {
    _OID: string;
    _Nome: string;
    _CNPJ: string;
    Endereco?: { _OID: string };
  };
}

export interface BuscaFornecedoresRequest {
  OBJECTID: { _Nome: string; _Ativo: boolean };
}

export interface BuscaFornecedoresResponse {
  Response: FornecedorXML[];
}

`service/hooks.ts`

Um hook por request. Uma linha cada.

// src/pages/Fornecedor/Cadastro/service/hooks.ts
import { useCurioMutation } from "@/hooks/useCurioMutation";
import { FORNECEDOR_RMS } from "./constants";
import {
  BuscaFornecedoresRequest,
  BuscaFornecedoresResponse,
  FornecedorInicialResponse,
  SalvaFornecedorRequest
} from "./interfaces";

export const useIncluiFornecedor = () => useCurioMutation<FornecedorInicialResponse, void>(FORNECEDOR_RMS.OBTEM_DADOS);

export const useBuscaFornecedores = () =>
  useCurioMutation<BuscaFornecedoresResponse, BuscaFornecedoresRequest>(FORNECEDOR_RMS.SALVAR);

export const useSalvaFornecedor = () => useCurioMutation<void, SalvaFornecedorRequest>(FORNECEDOR_RMS.SALVAR);

Assinatura: useCurioMutation<TResposta, TParametros>(nomeDoRequest). Use void quando não há parâmetros ou não há resposta útil.

A página

// src/pages/Fornecedor/Cadastro/IncluirFornecedorPage.tsx
import React, { useEffect, useRef } from "react";
import { Box, Button } from "@mui/material";
import { UseCaseManager } from "@curio/client/react";

import { useAuth } from "@/context/AuthProvider";
import { useUseCaseControls, useValidatedForm } from "@/hooks";
import { fornecedorSchema, type FornecedorFormData } from "./schemas";
import { FORNECEDOR_RMS } from "./service/constants";
import { useIncluiFornecedor, useSalvaFornecedor } from "./service/hooks";

const IncluirFornecedorContent: React.FC = () => {
  const { open, status } = useUseCaseControls();

  const { data: fornecedorData, mutate: incluirFornecedor, isPending: isIncluindo } = useIncluiFornecedor();
  const { mutateAsync: salvarAsync, isPending: isSalvando } = useSalvaFornecedor();

  // refs evitam reabrir/reinicializar em re-render
  const hasAttemptedOpenRef = useRef(false);
  const hasInitializedRef = useRef(false);

  useEffect(() => {
    if (status === "idle" && !hasAttemptedOpenRef.current) {
      hasAttemptedOpenRef.current = true;
      open();
    } else if (status === "open" && !hasInitializedRef.current) {
      hasInitializedRef.current = true;
      incluirFornecedor();
    }
  }, [status, open, incluirFornecedor]);

  const form = useValidatedForm({
    schema: fornecedorSchema,
    defaultValues: { _Nome: "", _CNPJ: "" }
  });

  const handleSalvar = async (data: FornecedorFormData) => {
    await salvarAsync({
      Fornecedor: {
        _OID: String(fornecedorData?.Fornecedor._OID ?? ""),
        _Nome: data._Nome,
        _CNPJ: data._CNPJ
      },
      msgSucesso: "Fornecedor salvo com sucesso!"
    });
  };

  return (
    <Box>
      <Button onClick={form.handleSubmit(handleSalvar)} disabled={isIncluindo || isSalvando}>
        Salvar
      </Button>
      {/* campos — ver 11 */}
    </Box>
  );
};

const IncluirFornecedorPage: React.FC = () => {
  const { session } = useAuth();

  return (
    <UseCaseManager session={session} useCaseId={FORNECEDOR_RMS.USE_CASE} autoClose={false} openOnMount={false}>
      <IncluirFornecedorContent />
    </UseCaseManager>
  );
};

export default IncluirFornecedorPage;

Por que dois componentes

UseCaseManager é um provider. Os hooks useUseCaseControls e useCurioMutation consomem o contexto dele, então precisam estar em um componente filho. O componente externo só faz o wiring; o conteúdo real vive no Content.

Isso não é opcional. Chamar useCurioMutation no mesmo componente que renderiza UseCaseManager falha em runtime.

Props do `UseCaseManager`

Prop	Valor usual	Efeito
`session`	`useAuth()`	Sessão autenticada
`useCaseId`	`FORNECEDOR_RMS.USE_CASE`	Id do caso de uso no servidor
`autoClose`	`false`	`true` fecha ao desmontar. Use `false` com navegação por abas
`openOnMount`	`false`	`false` dá controle explícito da abertura via `open()`

Com openOnMount={false}, a página é responsável por chamar open() — daí o useEffect com o hasAttemptedOpenRef.

`useUseCaseControls`

// src/hooks/useUseCaseControls.ts
export const useUseCaseControls = (options: UseUseCaseControlsOptions = {}) => {
  const { enableLogs = false } = options;
  const { open, close, status, error, triggersFromCurrentState } = useUseCaseManager();
  const { setNotification } = useNotification();

  // open() do curio lanca; aqui vira notificacao
  const openSafe = useCallback(
    async (openOptions?: OpenOptions) => {
      try {
        await open(openOptions);
      } catch (err) {
        const message = err instanceof Error ? err.message : "Erro ao abrir o caso de uso";
        setNotification({ message, type: "error", isAuthError: isAuthError(err) });
      }
    },
    [open, setNotification]
  );

  // ...
  return { open: openSafe, close, status, error, logCurrentStateTriggers: logCurrentState };
};

status assume "idle" → "open". A máquina de estados típica da página é exatamente o useEffect mostrado acima: abrir quando idle, inicializar quando open.

Descobrir os requests disponíveis

Passe enableLogs: true para logar, em desenvolvimento, os triggers que o caso de uso expõe no estado atual:

const { open, status } = useUseCaseControls({ enableLogs: true });

Útil quando você não sabe o nome exato do request. Remova antes de commitar.

`useCurioMutation`

Envolve useMutation do React Query sobre o sendRequest do caso de uso.

const { data, mutate, mutateAsync, isPending, isError } = useCurioMutation<TData, TParams>("RM_NOME");

Mensagens de sucesso e erro

msgSucesso, msgErro e msgErroFallback são passados junto dos parâmetros e removidos antes de chegar ao backend:

salvar({
  Fornecedor: { _OID: "123", _Nome: "ACME" },
  msgSucesso: "Fornecedor salvo com sucesso!",
  msgErro: "Não foi possível salvar."
});

msgSucesso dispara notificação verde no sucesso. Para erro, a mensagem exibida segue uma ordem de prioridade, decidida uma única vez no mutationCache.onError global (07) — não no hook:

msgErro, se informado — sempre prevalece, mesmo que o backend tenha devolvido mensagem própria. É o dev pedindo explicitamente para sobrescrever.
Mensagem do backend (error.message, ou error.detail se for ValidationError), se houver.
msgErroFallback, se informado — só é usado quando o backend não devolveu mensagem alguma.
Fallback genérico interno do hook ("Ocorreu um erro ao processar a requisição.").

salvar({
  Fornecedor: { _OID: "123", _Nome: "ACME" },
  msgErroFallback: "Não foi possível salvar o fornecedor."
  // se o backend devolver mensagem, ela aparece; msgErroFallback só entra se ele nao devolver nada
});

Omitir os três não silencia o erro — o queryClient global sempre notifica, no mínimo com o fallback genérico.

Não trate erro dentro de um hook específico da feature. A prioridade acima é resolvida uma vez, no mutationCache.onError global. Um onError local em useCurioMutation duplicaria a notificação — foi exatamente esse bug que motivou consolidar a lógica num só lugar.

Callbacks

onSuccess, onError, onSettled e onMutate vão no mesmo objeto dos parâmetros, não num segundo argumento:

salvar({
  Fornecedor: { _OID: "123", _Nome: "ACME" },
  onSuccess: () => setModalAberto(true),
  onError: (error) => console.error(error)
});

Difere do React Query puro. useCurioMutation separa os callbacks dos parâmetros internamente.

Buscas genéricas: `useSearcher`

Para telas de busca sobre entidades que o backend expõe via operações genéricas (120 = buscar, 134 = obter contexto), sem caso de uso dedicado:

const { getcontext, search } = useSearcher<FiltrosBusca, ResultadoBusca>("465");

const contexto = await getcontext.mutateAsync();
const resultado = await search.mutateAsync({ _Nome: "ACME", _Ativo: true });

Usa a sessão do useAuth() diretamente, sem UseCaseManager. Use quando a tela é só filtro + lista. Se houver estado no servidor (incluir, alterar, salvar), use UseCaseManager.

Contrato com o backend

O que o front precisa saber — o resto é responsabilidade de quem escreve o caso de uso no servidor.

Aspecto	Contrato
Identificação	Id numérico como string (`"4821"`)
Request	Nome em `SCREAMING_SNAKE_CASE`, prefixo `RM_` (`RM_SALVA_OBJETO`)
Parâmetros	Objeto aninhado espelhando a entidade (`{ Fornecedor: { _OID, _Nome } }`)
Filtros	Frequentemente sob a chave `OBJECTID`
Resposta	Objeto com a entidade na raiz (`{ Fornecedor: {...} }`) ou `{ Response: [...] }`
Primitivos	Prefixo `_` (`_Nome`, `_OID`)
Objetos	Sem prefixo (`Endereco`, `Documentos`)
Datas	String ISO com tempo: `"2026-08-18T00:00:00.0"`
Erro	`Error` lançado pelo transporte; `ValidationError` traz `detail: string[]`
Sessão morta	`DestinataryNotFoundError` ou `code === "-1"` — ver 05

Não invente nomes de request. Eles vêm do caso de uso do servidor. Confirme com quem o implementou ou use enableLogs.

Erros comuns

Sintoma	Causa
Hook lança "fora do contexto"	`useCurioMutation` no mesmo componente que renderiza o `UseCaseManager`
Request roda antes do caso de uso abrir	Faltou aguardar `status === "open"`
Caso de uso reabre a cada render	Faltou o `useRef` de guarda
`msgSucesso` chega ao backend	Versão do `useCurioMutation` sem o `delete params.msgSucesso`
Data rejeitada pelo backend	Faltou o sufixo `T00:00:00.0`

07 — React Query

Cache, tratamento global de erro e convenção de query keys. Versão 5.x (01) — cacheTime chama-se gcTime desde a v5. Regra central: nenhuma página trata erro de request para exibir mensagem — e nenhum hook específico trata, também. A prioridade da mensagem é resolvida uma única vez, no mutationCache.onError global.

O `QueryClient`

// src/api/queryClient.ts
import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
import { ValidationError } from "@curio/client/errors";
import { isAuthError } from "@/lib/curio";
import { NotificationType } from "@context/NotificationProvider";

// mensagem do backend, se houver — sem fallback, quem chama decide o que fazer na ausencia
const getErrorMessage = (error: unknown): string | undefined => {
  // ValidationError do curio traz lista de problemas
  if (error instanceof ValidationError) return error.detail.join("\n");
  return error instanceof Error && error.message ? error.message : undefined;
};

interface MutationVarsWithMessages {
  msgErro?: string;
  msgErroFallback?: string;
}

export const createQueryClient = (setNotification: (notification: NotificationType) => void) =>
  new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 5 * 60 * 1000,
        gcTime: 10 * 60 * 1000, // v5: cacheTime foi renomeado para gcTime
        retry: false,
        refetchOnWindowFocus: false,
        refetchOnReconnect: true
      },
      mutations: {
        retry: false,
        gcTime: 3 * 60 * 1000
      }
    },
    queryCache: new QueryCache({
      onError: (error) => {
        const message = getErrorMessage(error) ?? "Ocorreu um erro ao buscar os dados.";
        setNotification({ message, type: "error", isAuthError: isAuthError(error) });
      }
    }),
    mutationCache: new MutationCache({
      // fonte unica da mensagem de erro de mutation — useCurioMutation nao trata isso no
      // proprio onError, senao a notificacao dispara duas vezes (aqui + lá).
      onError: (error, variables) => {
        const vars = variables as MutationVarsWithMessages | undefined;
        // msgErro: o dev pediu pra sobrescrever qualquer mensagem do backend — sempre prevalece.
        // sem msgErro: mensagem do backend; sem essa, msgErroFallback; sem essa, fallback interno.
        const message =
          vars?.msgErro ?? getErrorMessage(error) ?? vars?.msgErroFallback ?? "Ocorreu um erro ao processar a requisição.";
        setNotification({ message, type: "error", isAuthError: isAuthError(error) });
      }
    })
  });

export default createQueryClient;

Por que é uma fábrica e não uma constante

O QueryClient precisa do setNotification, que só existe dentro do NotificationProvider. Daí o createQueryClient(setNotification) chamado em main.tsx dentro de useState(() => ...) — ver 03.

useState com inicializador de função, não useMemo: garante instância única mesmo sob StrictMode.

Defaults e o porquê

Opção	Valor	Razão
`staleTime`	5 min	Dados corporativos mudam devagar; evita refetch a cada navegação
`gcTime`	10 min	Mantém dados ao voltar para uma tela (era `cacheTime` até a v4)
`retry`	`false`	Retry sobre caso de uso com estado no servidor pode duplicar efeito
`refetchOnWindowFocus`	`false`	Refetch ao alternar janela é ruído em app interno
`refetchOnReconnect`	`true`	Voltar de queda de rede deve revalidar

retry: false é a decisão mais importante. Não mude sem entender que um RM_SALVA_OBJETO repetido pode gravar duas vezes.

Erro é global

O onError do QueryCache/MutationCache captura toda falha e converte em notificação — inclusive as de useCurioMutation e useHookMutation. Isso vale tanto para a página quanto para o hook específico da feature: nenhum dos dois deve ter seu próprio onError de notificação. Um onError local que também chama setNotification dispara duas notificações para o mesmo erro — uma do global, outra do local — porque o mutationCache.onError roda para toda mutation, sempre. Consequência prática:

// ERRADO — duplica a mensagem: a global ja apareceu
const handleSalvar = async () => {
  try {
    await salvarAsync(payload);
  } catch (error) {
    setNotification({ type: "error", message: "Erro ao salvar" });
  }
};

// CERTO — deixa o erro subir; global notifica
const handleSalvar = async () => {
  await salvarAsync(payload);
  setModalSucesso(true);
};

// CERTO — try/catch so pra controlar fluxo, sem notificar
const handleSalvar = async () => {
  try {
    await salvarAsync(payload);
    setModalSucesso(true);
  } catch {
    // notificacao ja veio do global; aqui so nao abre o modal
  }
};

Use try/catch para controlar fluxo, nunca para exibir mensagem de erro de request.

Para customizar a mensagem, use msgErro (sobrescreve sempre) ou msgErroFallback (só quando o backend não devolve mensagem) no useCurioMutation (06) em vez de capturar.

Query keys

Array, do mais genérico ao mais específico:

["fornecedores"]                                 // dominio inteiro
["fornecedores", "lista"]                        // uma colecao
["fornecedores", "lista", { ativo: true }]       // colecao com filtro
["fornecedores", "detalhe", oid]                 // um item

Regras:

Primeiro elemento é o domínio, sempre string.
Segundo é a operação ("lista", "detalhe").
Parâmetros que afetam o resultado entram na key. Se não entrarem, o cache serve dado errado.
Nunca interpole (`fornecedores-${oid}`) — impede invalidação por prefixo.

Centralize por domínio:

// src/pages/Fornecedor/service/queryKeys.ts
export const fornecedorKeys = {
  all: ["fornecedores"] as const,
  listas: () => [...fornecedorKeys.all, "lista"] as const,
  lista: (filtros: FiltrosFornecedor) => [...fornecedorKeys.listas(), filtros] as const,
  detalhe: (oid: string) => [...fornecedorKeys.all, "detalhe", oid] as const
};

Invalidar tudo do domínio: queryClient.invalidateQueries({ queryKey: fornecedorKeys.all }).

Query vs mutation

O Curio inverte a intuição de REST.

Situação	Use	Por quê
Request dentro de um `UseCaseManager`	mutation	Tem efeito no estado do caso de uso, mesmo "só lendo"
Busca disparada por botão	mutation	Ação do usuário, não dado que se auto-revalida
Dado que carrega sozinho e revalida	query	Ex.: lista do dashboard
Reconexão de sessão	query	Ver `useAuthQuery`

Por isso useCurioMutation e useSearcher usam useMutation, não useQuery. Não é engano.

Invalidação

const queryClient = useQueryClient();

const handleSalvar = async (data: FornecedorFormData) => {
  await salvarAsync({ Fornecedor: { ...data }, msgSucesso: "Salvo!" });
  await queryClient.invalidateQueries({ queryKey: fornecedorKeys.listas() });
};

Em telas com UseCaseManager, o padrão mais comum é refazer o request no próprio caso de uso (buscarFornecedores() de novo) em vez de invalidar cache — o estado vive no servidor, não no cache.

Devtools

<ReactQueryDevtools initialIsOpen={false} /> está em main.tsx. É removido automaticamente do bundle de produção pela própria biblioteca. Não condicione a import.meta.env.DEV manualmente.

Nomenclatura

Tipo	Padrão	Exemplo
Query de coleção	`use{Entidade}s`	`useFornecedores`
Query de item	`use{Entidade}`	`useFornecedor`
Mutation de caso de uso	`use{Verbo}{Entidade}`	`useSalvaFornecedor`
Mutation genérica	`use{Verbo}{Entidade}Mutation`	`useCreateFornecedorMutation`

Hooks de caso de uso usam o verbo em português, espelhando o nome do request do backend (RM_SALVA_OBJETO → useSalvaFornecedor). Isso torna rastreável qual hook corresponde a qual request.

Backend (Curio)

05 — Curio: conexão e sessão

05 — Curio: conexão e sessão

Camadas

src/lib/curio/

index.ts — fábrica do transporte

Session.ts — a sessão do app

SessionManager.ts — detecção de sessão morta

isAuthError.ts — o que conta como falha de autenticação

src/api/session.ts

Requests anônimos (pré-login)

AuthProvider

Ciclo de vida

Detecção de expiração por string

06 — Caso de uso

06 — Caso de uso

O modelo mental

Cadeia de chamada

Convenção _RMS: use case e requests num só objeto

Anatomia de uma tela

service/interfaces.ts

service/hooks.ts

A página

Por que dois componentes

Props do UseCaseManager

useUseCaseControls

Descobrir os requests disponíveis

useCurioMutation

Mensagens de sucesso e erro

Callbacks

Buscas genéricas: useSearcher

Contrato com o backend

Erros comuns

07 — React Query

07 — React Query

O QueryClient

Por que é uma fábrica e não uma constante

Defaults e o porquê

Erro é global

Query keys

Query vs mutation

Invalidação

Devtools

Nomenclatura

`src/lib/curio/`

`index.ts` — fábrica do transporte

`Session.ts` — a sessão do app

`SessionManager.ts` — detecção de sessão morta

`isAuthError.ts` — o que conta como falha de autenticação

`src/api/session.ts`

`AuthProvider`

Convenção `_RMS`: use case e requests num só objeto

`service/interfaces.ts`

`service/hooks.ts`

Props do `UseCaseManager`

`useUseCaseControls`

`useCurioMutation`

Buscas genéricas: `useSearcher`

O `QueryClient`