Carteira de Clientes — Visão Geral

Última atualização: 15 de julho de 2026

O que é este fluxo

A carteira de clientes é a tela onde o vendedor consulta a base de clientes que atende. É também o ponto de partida de quase tudo que ele faz em campo: a partir de um cliente selecionado, o vendedor pode abrir o catálogo já filtrado por aquele cliente, iniciar uma nova venda, ver detalhes cadastrais, consultar últimas compras, pedir uma rota até o endereço de entrega ou acionar sugestão e importação de pedido por IA. Por isso a skill do projeto trata essa área como um hub de navegação, não como uma tela isolada.

Esta seção documenta o fluxo em seis partes:

Doc	Conteúdo
Visão Geral (este documento)	Arquitetura, tabs internas, flags de configuração
Lista, Busca e Filtros	FTS5, busca por letra, filtros de status/venda/financeiro/localização, paginação
Seleção e Navegação	selectedClient, modal de opções, rotas para catálogo, nova venda, detalhes e mapa externo
Mapa de Clientes	Clustering com Supercluster na aba Mapa, e o botão "Como Chegar"
Cadastro e Edição	Formulário dinâmico, busca de CEP, salvar online-first com fallback offline
Detalhes do Cliente	Sub-abas de detalhes, endereços, contatos, atividades e mais

Arquitetura em camadas

A tela de carteira segue o mesmo princípio de outras áreas do app: a rota em app/ é fina e só decide se a tela pode ser exibida, enquanto toda a lógica mora em features/client.

useClientController, em features/client/client.controller.ts, é um arquivo grande (mais de 1.600 linhas) porque concentra praticamente todo o estado da carteira: busca, letra selecionada, filtros, paginação, cliente selecionado, visibilidade de modais e todas as ações que partem de um cliente. A tela de mapa interna (MapClient) reaproveita esse mesmo controller em vez de duplicar busca e filtros, lendo search, letter, selectedFilters e service dele.

Três abas dentro de uma tab

A carteira tem sua própria navegação interna, controlada por navigatorBar, com três valores possíveis: "Carteira" (lista), "Atividades" e "Mapa". Isso é diferente da tab bar principal do app, que já tem sua própria aba "Clientes".

A feature inteira é controlada por flags de configuração

Praticamente toda ação e toda aba dentro da carteira é ligada a uma flag de configuração (cfg-*), lida via useSettings. Um trecho representativo do controller:

// client.controller.ts
const isActivitiesEnabled = settings.get("cfg-ativaratividades") === "S";
const isEngagementEnabled = settings.get("cfg-ativarengajamento") === "S";
const isStartSaleEnabled = settings.get("cfg-ativariniciarvenda") === "S";
const isClientRegisterEnabled = settings.get("cfg-ativarcadastrocliente") === "S";
const isClientMapEnabled = settings.get("cfg-ativarmapadeclientes") === "S";
const isCatalogEnabled = settings.get("cfg-ativarcatalogodeprodutos") === "S";
const isClientDirectionsEnabled = settings.get("cfg-ativarcomochegarcliente") === "S";

A própria carteira como um todo é gated dessa forma, e em dois lugares diferentes ao mesmo tempo, como reforço um do outro. A tab é escondida na tab bar quando a flag está desligada:

// app/(tabs)/_layout.tsx
<Tabs.Screen
  name="clientes"
  options={{
    title: "Clientes",
    ...(isClientPortfolioEnabled ? {} : { href: null }),
  }}
/>

E a própria rota redireciona para a home se alguém tentar acessá-la diretamente, por exemplo por um deep link, mesmo com a tab escondida:

// app/(tabs)/clientes.tsx
export default function Clientes() {
  const settings = useSettings();

  if (settings.get("cfg-ativarcarteiradeclientes") !== "S") {
    return <Redirect href="/(tabs)/home" />;
  }

  return <ClientScreen />;
}

Essa dupla checagem, escondendo a tab e também redirecionando a rota, é um padrão que se repete em outras rotas do app (a tela de cadastro de cliente, documentada em Cadastro e Edição, faz o mesmo). Ao adicionar uma nova ação ou aba baseada em cliente, vale seguir esse mesmo padrão em vez de confiar só na UI escondida.

Arquivos-chave

Arquivo	Responsabilidade
app/(tabs)/clientes.tsx	Rota da tab, redireciona para home se a carteira estiver desabilitada
features/client/client.tsx	Screen da carteira: lista, cabeçalho de busca, modais e bottom sheets
features/client/client.controller.ts	Hub de estado: busca, filtros, paginação, cliente selecionado, todas as ações de navegação
features/client/components/client-list/client-list.tsx	Lista da carteira, renderizada com FlashList
features/client/components/map/map.client.tsx + .controller.ts	Aba Mapa interna, com clustering
services/client/client.service.ts	Orquestra sincronização remota e leitura/escrita local
repositories/client/client.repository.ts	Queries SQLite, incluindo a tabela virtual FTS5 client_search
features/client/client-register/*	Cadastro e edição de cliente
features/client-details/*	Detalhes do cliente e suas sub-abas