iMportex!

Usuários, fornecedores, freteiros, peças, serviços, técnicos e as configurações da empresa.

Este módulo é o "estoque de dados" que sustenta o fluxo operacional PY→SP→venda: antes de comprar um lote, alguém precisa existir como fornecedor; antes de transportar, precisa existir um freteiro; antes de trocar dólar por real numa venda, precisa existir um cambista; antes de abrir uma OS (ordem de serviço) de conserto, precisam existir peças, serviços e técnicos cadastrados; antes da testadora reprovar um aparelho na triagem, precisa existir a lista de problemas que ela vai marcar. E por trás de tudo isso está o cadastro raiz — a empresa (o "tenant", ou seja, o cliente da plataforma multi-empresa) e os usuários que fazem login nela.

A segunda metade do capítulo é diferente: são as telas de Configurações, que não cadastram entidades do dia a dia, mas ligam/desligam políticas que mudam o comportamento de outras partes do sistema — quantos dias até uma OS virar "atrasada", se a venda pode reservar mais estoque do que existe fisicamente, se o dono recebe alerta extra por WhatsApp, e o PIN de 6 dígitos que autoriza correções sensíveis (como devolver um aparelho pra triagem).

Um fio condutor aparece o capítulo inteiro: o menu lateral e a permissão real de gravar no banco nem sempre são a mesma coisa. O menu decide o que cada perfil vê como link; uma trava de segurança que mora dentro do próprio banco de dados (não no código da tela) decide o que cada perfil pode gravar de fato. Nas telas de Cadastros "clássicas" (fornecedores, freteiros, cambistas, técnicos, peças, serviços) o padrão é: todo mundo da empresa lê a lista, só ADMIN/GERENTE grava — mas o botão "Editar" aparece pra todo mundo que acessa a tela, então um clique de quem não tem permissão volta com um erro (às vezes cru, direto do banco de dados) em vez de o botão simplesmente sumir.

Fluxo do módulo em 1 olhada

Empresa (/cadastros/empresas) nasce primeiro — é o "dono" de tudo (multi-tenant: cada empresa só vê seus próprios dados). Só existe 1 empresa ativa por vez.
Usuários (/cadastros/usuarios) são criados dentro da empresa — cada um com um perfil (ADMIN, GERENTE, VENDEDOR, FINANCEIRO, TECNICO_PROPRIO, OPERADOR_SP, OPERADOR_PY, TESTADOR, SUPERVISOR_ASSISTENCIA) que decide o que a pessoa vê e pode fazer no sistema inteiro.
Os parceiros externos entram no cadastro antes de qualquer fluxo de compra/venda usar eles: Fornecedores (quem vende o lote de aparelhos), Freteiros (quem transporta EUA→PY, PY→BR, ou dentro do Brasil) e Cambistas (quem intermedeia a troca de dólar/real numa venda).
Os catálogos operacionais alimentam a assistência técnica: Problemas de triagem (o que a testadora pode marcar como defeito, com a árvore de "qualificadores" — perguntas de diagnóstico — dentro de cada problema), Peças (catálogo com custo médio calculado automaticamente) e Serviços (o catálogo de reparos, com tempo padrão em minutos), e Técnicos (quem conserta, próprio ou parceiro, com o custo por minuto calculado pra quem é CLT).
Configurações (/configuracoes) é o hub que reúne 5 políticas que qualquer usuário logado pode acessar (mas só alguns itens aparecem, dependendo do perfil): Preferências de notificação (todo mundo edita a própria), SLA de Assistência, Venda a descoberto, Alertas de WhatsApp (ADMIN/GERENTE) e Segurança/PIN (ADMIN).

Empresas

Pra que serve: cadastrar/editar os dados da empresa (tenant, ou seja, o cliente que roda a operação dentro da plataforma) — nome, CNPJ (Brasil) ou RUC (Paraguai), país, moeda principal e logo. Uma regra de negócio trava que só 1 empresa pode estar ativa por vez.
Quem usa: o menu lateral só mostra este link pra ADMIN e GERENTE (os dois aparecem com acesso total no cadastro de permissões). Só ADMIN de fato consegue criar/editar/arquivar: essa permissão é checada tanto na hora de salvar quanto por uma trava dentro do próprio banco de dados, mais estreita que o menu (nem GERENTE grava, mesmo vendo o link).
Ações principais: Nova empresa (janela pop-up), Editar, Arquivar (soft delete — nunca apaga de verdade).
Fluxo correto:
1. Abrir a tela — a lista mostra a(s) empresa(s) cadastrada(s) (na prática, sempre 1, porque a trava de leitura do banco só devolve a própria empresa do usuário logado).
2. Clicar em "Editar" pra corrigir nome/documento/moeda, ou "Nova Empresa" só no cenário raro de setup inicial de uma nova instância.
3. Salvar. Se já existir outra empresa marcada como ativa, o sistema recusa com a mensagem "Já existe uma empresa ativa; desative-a primeiro."
Se pular ou errar:
- Um GERENTE vendo o link no menu e clicando em "Editar" recebe o erro amigável "Seu perfil não pode gerir empresas." — a tela deixa ele entrar e tentar, mas a gravação é recusada.
- A página em si não tem nenhum bloqueio de leitura — qualquer perfil autenticado que digitar a URL diretamente consegue ver a lista, mesmo sem o link no menu. Na prática o vazamento é pequeno (a trava de leitura do banco já limita a 1 linha, a própria empresa), mas é uma inconsistência: as outras telas administrativas (Usuários, SLA, Segurança) bloqueiam a rota inteira pra quem não tem a permissão; esta não.
- Arquivar a empresa (soft delete) não roda uma atualização direta no banco — usa uma função interna do próprio banco, porque a regra de gravação normal proíbe apagar registros diretamente sem passar por ela.
Gotchas e estados: moeda principal e país decidem se a empresa opera em BRL (Brasil) ou USD/PYG (Paraguai) — essa configuração raiz é o que alimenta a trava "BRL=SP / USD=PY" usada nas telas de Vendas e Cotações (fora deste capítulo).

Usuários

Pra que serve: criar login para a equipe, definir o perfil (o "cargo" no sistema, que decide o que a pessoa vê e faz), ativar/desativar acesso e trocar o perfil de alguém.
Quem usa: a tela tem um bloqueio real (a rota inteira fica indisponível, não só o link do menu) pra 3 perfis:
- ADMIN: gestão total — cria, edita, promove, arquiva qualquer perfil, inclusive outro ADMIN.
- GERENTE: só mexe na "equipe operacional" (TESTADOR, TECNICO_PROPRIO, OPERADOR_PY, OPERADOR_SP, SUPERVISOR_ASSISTENCIA) — nunca cria/edita/promove alguém pra ADMIN, GERENTE, FINANCEIRO ou VENDEDOR (mesmo que o formulário tentasse mandar esse valor, o sistema recusa).
- OPERADOR_PY: só cria perfis operacionais; não edita, promove nem arquiva ninguém que já existe.
- Os demais perfis (VENDEDOR, FINANCEIRO, TECNICO_PROPRIO, OPERADOR_SP, TESTADOR, SUPERVISOR_ASSISTENCIA) recebem a mensagem "Você não tem permissão para acessar o cadastro de usuários" mesmo digitando a URL direto.
Ações principais: Novo usuário (nome, e-mail, telefone, perfil, senha inicial — mín. 12 caracteres com letra e número), Ativar (usuários pendentes, criados via convite, esperam ativação), Editar, Excluir (arquivar — nunca some do banco).
Fluxo correto:
1. ADMIN/GERENTE/OPERADOR_PY clicam em "Novo usuário".
2. Preenchem nome, e-mail, telefone (opcional), escolhem o perfil na lista suspensa (o dropdown já filtra pra mostrar só os perfis que o cargo de quem está logado pode criar) e definem uma senha inicial.
3. Ao salvar, o usuário nasce já ativo, na mesma empresa de quem criou. Se o perfil escolhido for TECNICO_PROPRIO ou SUPERVISOR_ASSISTENCIA, o sistema também cria automaticamente o registro-espelho na tela de Técnicos (pra ele aparecer no dropdown de abrir uma Ordem de Serviço).
4. Usuários criados por outro caminho (convite/self-signup) nascem inativos ("Pendente") até um ADMIN clicar em "Ativar".
Se pular ou errar:
- Tentar rebaixar o único ADMIN ativo do sistema é bloqueado ("Não é possível rebaixar o único ADMIN ativo do sistema. Promova outro usuário a ADMIN primeiro.") — evita a empresa ficar sem ninguém com acesso total.
- Ninguém consegue arquivar o próprio usuário logado.
- Um GERENTE tentando promover um TESTADOR pra ADMIN recebe "Você só pode editar usuários da equipe operacional (e sem promover além dela). Perfis de gestão são do ADMIN."
Gotchas e estados: a criação de usuário passa por um caminho de acesso mais amplo, que ignora as travas normais do banco de dados. Na prática, a única barreira real contra um OPERADOR_PY tentar criar um ADMIN e tomar o sistema é a checagem feita no código da tela — não uma trava do banco. É um controle de aplicação, mais frágil por natureza, então quem recebe o perfil OPERADOR_PY merece confiança redobrada, e qualquer mudança futura nessa regra merece revisão cuidadosa.

Fornecedores

Pra que serve: cadastrar quem vende os lotes de iPhones — leilões, fornecedores diretos e outros parceiros de aquisição. Cada fornecedor guarda país de origem, contato, avaliação e um contador automático de quantos lotes de compra já foram feitos com ele.
Quem usa: desde 06/09/2026 o menu só mostra este link pra ADMIN e GERENTE — antes disso VENDEDOR também via o link e conseguia gravar de verdade (criar/editar/arquivar), porque nenhuma trava de perfil existia ainda por trás desta tela. O dono mediu e decidiu fechar: fornecedor errado entra em compra, e cadastro mestre suja todos os fluxos depois. Hoje a gravação exige a capacidade gerir_cadastro_mestre (ADMIN/GERENTE), checada dentro de cada ação que grava — não é mais só uma trava de banco de dados.
Ações principais: Novo Fornecedor, Editar, Arquivar (soft delete).
Fluxo correto:
1. Cadastrar nome, tipo (leilão/direto/outro), país de origem, contato, avaliação e observações.
2. Usar esse fornecedor ao criar um Lote de Compra (ver Recebimento).
3. O contador "nº de lotes" na lista é só informativo — não é editável, é calculado somando os lotes vinculados.
Se pular ou errar: arquivar um fornecedor não apaga o histórico de lotes já feitos com ele (soft delete = a data de exclusão é preenchida, o registro nunca é apagado de verdade) — só some da lista ativa e do dropdown de novos lotes.
Gotchas e estados: a empresa do fornecedor nunca vem do formulário — vem sempre de uma busca no banco pelo usuário logado, fechando a possibilidade de alguém mal-intencionado tentar cadastrar um fornecedor em outra empresa.

Freteiros

Pra que serve: cadastrar transportadores por trecho — a rota de um lote pode passar por até 2 pernas diferentes (ex: EUA→PY com um freteiro, PY→BR com outro), então cada freteiro registra quais trechos atende, a taxa padrão (%) e a base de cálculo padrão.
Quem usa: mesmo padrão de Fornecedores desde 06/09/2026 — menu visível só a ADMIN e GERENTE (antes, VENDEDOR também via e gravava); gravação exige a capacidade gerir_cadastro_mestre (ADMIN/GERENTE), checada em cada ação que grava.
Ações principais: Novo Freteiro, Editar, Arquivar.
Fluxo correto:
1. Cadastrar nome, os trechos que ele atende, taxa/base de cálculo padrão (usadas para pré-preencher o formulário de lote de compra), contato e observações.
2. O freteiro fica disponível nos dropdowns "Freteiro Trecho 1" e "Freteiro Trecho 2" do cadastro de Lote de Compra (ver Recebimento).
Se pular ou errar:

⚠️ Atenção: um lote de compra sem freteiro vinculado simplesmente não tem esse custo de frete rastreado. O campo é opcional no lote, então o erro é silencioso — o custo total do lote fica subestimado, sem nenhum aviso na tela.
Gotchas e estados: o contador "nº de fretes" soma aparições do freteiro tanto no Trecho 1 quanto no Trecho 2 do mesmo lote — um freteiro que faz os dois trechos de um lote conta 2 vezes.

Cambistas

Pra que serve: cadastrar os operadores de câmbio (pessoas que trocam dólar/real/guarani numa venda) que a loja usa, com a taxa (%) que cada um cobra. A lista mostra também o volume em R$ que cada cambista já intermediou em vendas não canceladas — um contador de uso, não um saldo financeiro.
Quem usa: mesmo padrão de Fornecedores e Freteiros desde 06/09/2026 — menu visível só a ADMIN e GERENTE; a gravação (criar/editar) exige a capacidade gerir_cadastro_mestre (ADMIN/GERENTE).
Ações principais: Novo Cambista, Editar, Arquivar.
Fluxo correto:
1. Cadastrar nome, contato, taxa (%) e observações.
2. O cambista fica selecionável na tela de Vendas quando a venda envolve câmbio.
Se pular ou errar: antes de 06/09/2026, um VENDEDOR conseguia gravar de verdade (não havia trava por perfil na ação); hoje o item nem aparece mais no menu dele, e tentar pela URL direta é recusado pela mesma capacidade que trava Fornecedores e Freteiros.
Gotchas e estados: a taxa (%) é opcional — cambista sem taxa cadastrada aparece na lista, mas o cálculo de comissão de câmbio (fora deste capítulo) precisa desse valor pra funcionar.

Problemas de triagem

Pra que serve: manter a lista de defeitos que a testadora vê na Estação de Triagem ao avaliar um aparelho — cada problema tem uma "chavinha" condena: ligada = reprova o aparelho e manda pra assistência (ou trava, dependendo do destino escolhido); desligada = só registra a observação, sem reprovar.
Quem usa: o único cadastro deste capítulo em que menu e permissão de escrita batem exatamente: o link só aparece pra ADMIN, GERENTE e OPERADOR_PY (o operador do PY, que monta a lista de problemas do galpão do Paraguai), e a gravação no banco exige o mesmo trio. A leitura é liberada a todos os perfis da empresa (a lista é consumida pela Estação de Triagem, usada por TESTADOR).
Ações principais: Novo problema (nome + chavinha condena + destino, se condena estiver ligada), Editar, ligar/desligar a chavinha "condena" direto na tabela (toggle rápido), ativar/desativar.
Fluxo correto:
1. Cadastrar o nome do problema (ex: "tela trincada").
2. Decidir se ele condena o aparelho — se sim, escolher o destino: Assistência (vai pro conserto) ou Travado (fica bloqueado, sem seguir fluxo).
3. Definir a ordem de exibição na lista da testadora.
4. Salvar. O problema passa a aparecer na Estação de Triagem imediatamente.
Se pular ou errar: desativar um problema preserva o histórico — laudos antigos que já usaram aquele problema continuam intactos, só some da lista de opções pra novos laudos.
Gotchas e estados: quando "condena" está desligada, o destino é gravado como Assistência por padrão (mesmo que a interface não mostre o campo) — é só um valor sem efeito prático, porque um problema que não condena não dispara nenhum redirecionamento de aparelho.

Diagnóstico do problema (qualificadores)

Pra que serve: montar a árvore de perguntas (qualificadores) que aparece na Estação de Triagem depois que a testadora marca um problema — ex: "tela trincada" pode abrir a pergunta "trinca só no vidro ou no LCD também?", e cada resposta pode abrir uma sub-pergunta, até chegar numa folha (o fim do galho) que sugere a peça certa pro laudo.
Quem usa: a página não tem bloqueio de rota próprio — qualquer usuário autenticado da empresa que souber a URL consegue abrir e ver a árvore. Na prática, só chega até aqui quem tem o link "Diagnóstico" na lista de Problemas, ou seja, ADMIN, GERENTE, OPERADOR_PY (mesma restrição de menu da tela-mãe). A gravação (criar/editar qualificador) segue a mesma trava do banco, também limitada a ADMIN/GERENTE/OPERADOR_PY.
Ações principais: Adicionar qualificador (nome + peça sugerida opcional + a que nó ele pertence — raiz ou filho de outro), Editar peça sugerida de uma folha, Desativar (preserva histórico).
Fluxo correto:
1. Abrir "Diagnóstico" a partir da lista de Problemas.
2. Adicionar o 1º nível de perguntas (a raiz da árvore).
3. Para cada resposta que precisa de mais detalhe, adicionar um qualificador filho dela (escolhendo o pai no seletor "1º nível (raiz)" ou um nó existente).
4. Numa folha (nó sem filhos), preencher "Peça sugerida" — é o texto que aparece no laudo pra guiar o técnico.
5. Salvar. A árvore fica disponível na próxima triagem que usar esse problema.
Se pular ou errar: um problema sem qualificador nenhum simplesmente não abre sub-perguntas na triagem — a testadora marca o problema e segue direto, sem diagnóstico refinado nem sugestão de peça.
Gotchas e estados: desativar um qualificador que já tem filhos não desativa os filhos automaticamente (preserva o histórico de cada nó individualmente) — é preciso desativar nó por nó se a intenção é aposentar o galho inteiro.

Peças

Pra que serve: catálogo de peças de reposição (tela, bateria, câmera etc.) usado pelas Ordens de Serviço de conserto. O custo médio atual e o estoque atual são calculados automaticamente pelo sistema (via uma rotina que roda sozinha a cada movimentação) toda vez que uma compra de peça é registrada — nunca são digitados diretamente.
Quem usa: o menu mostra este link a ADMIN, GERENTE (acesso total), VENDEDOR, TECNICO_PROPRIO e SUPERVISOR_ASSISTENCIA — ou seja, quem monta orçamento de venda e quem executa/supervisiona o conserto. Mas dentro da própria tela, a coluna custo médio só aparece para quem tem permissão de ver dado financeiro (ADMIN, GERENTE, FINANCEIRO) — outros perfis veem a peça, o estoque e o alerta de "abaixo do mínimo", mas o valor em R$ chega nulo desde o servidor (não é só escondido visualmente, o dado nem trafega). Gravar (criar/editar/arquivar peça) é restrito a ADMIN/GERENTE.
Ações principais: Nova Peça, Editar, Arquivar, e — só para quem vê custo — o atalho "Histórico de compras" (ícone de caixa) que leva à sub-tela de Compras da peça.
Fluxo correto:
1. Cadastrar nome, tipo, modelos compatíveis (lista separada por vírgula) e estoque mínimo desejado.
2. Nunca preencher custo ou estoque atual direto — eles nascem zerados e só sobem quando uma Compra de Peça é registrada.
3. Acompanhar o alerta "abaixo do mínimo" (badge vermelho no topo da lista) pra saber quando reabastecer.
Se pular ou errar:
- TECNICO_PROPRIO e SUPERVISOR_ASSISTENCIA veem os botões "Editar"/"Arquivar" na tabela mesmo sem ter permissão de gravação real — um clique deles em "Salvar" retorna "Sem permissão ou peça não encontrado." em vez de um botão desabilitado.
- Uma peça sem estoque mínimo correto nunca aciona o alerta visual, mesmo ficando sem estoque nenhum.
Gotchas e estados: o campo de texto livre onde se digitam os modelos compatíveis (separados por vírgula) é convertido em lista só no momento de salvar — não existe validação de que os nomes batem exatamente com os modelos usados no resto do sistema.

Compras de peça

Pra que serve: registrar cada compra (entrada em estoque) de uma peça específica — quantidade, custo unitário, fornecedor, número da nota fiscal e data. Cada registro dispara automaticamente o recálculo do custo médio ponderado e do estoque total da peça.
Quem usa: rota bloqueada de verdade pra quem não pode ver dinheiro — só ADMIN, GERENTE ou FINANCEIRO conseguem sequer abrir a tela; qualquer outro perfil é redirecionado antes de a página carregar. A gravação segue a mesma dupla ADMIN/GERENTE.
Ações principais: Registrar Compra (quantidade, custo unitário — o custo total é calculado automaticamente multiplicando os dois, nunca digitado —, fornecedor, número da NF, data, observações).
Fluxo correto:
1. Abrir a partir do ícone "Histórico de compras" na lista de Peças.
2. Clicar em "Registrar Compra", preencher quantidade e custo unitário.
3. Salvar — o custo total é calculado no servidor (nunca confia no que o navegador mandaria), o registro entra no histórico, e o card "Custo médio atual" da peça-mãe atualiza sozinho.
Se pular ou errar: peça sem nenhuma compra registrada mostra custo médio R$ 0,00 e estoque zero — mesmo que fisicamente existam peças, se elas nunca passaram por esta tela, o sistema não sabe do custo delas.
Gotchas e estados: o histórico segue o mesmo padrão do resto do sistema — só mostra compras que não foram excluídas (soft delete); não há nada de diferente nesta tela específica nesse quesito.

Serviços

Pra que serve: catálogo dos tipos de reparo oferecidos (ex: "troca de tela", "troca de bateria") — cada serviço tem modelo aplicável, peça principal associada, tempo padrão em minutos (usado pra calcular custo de mão de obra do técnico próprio) e preço sugerido pra assistência externa.
Quem usa: desde 06/09/2026 o menu só mostra este link pra ADMIN e GERENTE. Antes disso VENDEDOR, TECNICO_PROPRIO e SUPERVISOR_ASSISTENCIA também viam e gravavam de verdade — o agravante aqui é que é nesta tela que se define o preço sugerido pra assistência externa, inclusive do próprio serviço que o técnico executa. A leitura não se perdeu: o técnico continua escolhendo o serviço de dentro da OS e da Triagem (não desta tela de cadastro). Gravar exige a capacidade gerir_cadastro_mestre (ADMIN/GERENTE).
Ações principais: Novo Serviço, Editar, Arquivar.
Fluxo correto:
1. Cadastrar nome, categoria, modelo aplicável, peça principal (opcional — linka ao catálogo de Peças), tempo padrão em minutos e preço sugerido pra terceirizar.
2. O serviço fica disponível no dropdown de "Serviço" ao abrir uma OS.
Se pular ou errar: um serviço sem tempo padrão preenchido não entra no cálculo de custo do técnico próprio (que usa custo-por-minuto × tempo do serviço) — a OS ainda abre, mas o custo de mão de obra fica sem base de cálculo.
Gotchas e estados: a lista distingue serviços ativos de inativos com contadores no cabeçalho ("X serviços ativos" + "Y inativos") — inativos continuam visíveis na tabela (não somem), só saem do dropdown de nova OS.

Técnicos

Pra que serve: cadastrar quem conserta os aparelhos — próprios (CLT/funcionário, com salário/encargos/benefícios que alimentam o cálculo automático de custo-por-minuto) ou parceiros (terceirizados, sem esses campos de custo mensal). Mostra também quantas OSs cada técnico concluiu no mês corrente.
Quem usa: desde 05/09/2026 a rota inteira exige a capacidade ver_dinheiro — ADMIN, GERENTE ou FINANCEIRO —, não só o menu: quem não tem essa capacidade é redirecionado antes mesmo da página carregar. Isso muda o que valia antes: VENDEDOR tinha o link no menu "só pra consulta" e hoje não acessa mais a tela (nem digitando a URL direto); FINANCEIRO ganhou acesso que não tinha. O motivo é a própria tela expor a folha de pagamento: salário, encargos, benefícios e o custo por minuto calculado de cada técnico próprio — em produção, antes desta trava, qualquer perfil logado (inclusive VENDEDOR e TECNICO_PROPRIO) conseguia abrir a página e ver esses valores, e também criar/editar/arquivar técnico. Gravar também passou a exigir a mesma capacidade ver_dinheiro, checada dentro de cada ação — gate de rota e gate de ação são coisas separadas, e as duas existem agora.
Ações principais: Novo Técnico (tipo Próprio/Parceiro, dados de contato, e — só se Próprio — salário/encargos/benefícios/carga horária), Editar, Arquivar.
Fluxo correto:
1. Escolher o tipo: Próprio (CLT) libera os campos de custo mensal e carga horária produtiva; Parceiro não.
2. Se Próprio, preencher salário mensal, encargos, benefícios, outros custos e a carga horária produtiva do mês (em minutos).
3. Salvar — o campo custo por minuto aparece somente leitura, calculado automaticamente (soma de todos os custos mensais dividida pela carga horária) — nunca digitado.
4. Opcionalmente vincular o técnico a um usuário existente (pra ele acessar o sistema com login próprio).
Se pular ou errar: um técnico Próprio sem carga horária cadastrada corretamente distorce o custo por minuto calculado (divisão por um número errado) — o valor sai visível na tabela, mas sem sentido de negócio.
Gotchas e estados: o custo por minuto só aparece pra técnicos do tipo Próprio — parceiros não têm essa coluna preenchida (não fazem sentido: o custo deles é o preço acordado por serviço, não uma taxa mensal rateada).

Configurações

Pra que serve: página central que reúne links para as telas de configuração do sistema — não mostra nem edita dado nenhum diretamente, só organiza o acesso.
Quem usa: qualquer usuário autenticado consegue abrir a página. O que muda por perfil é quais itens aparecem na lista:
- Todo mundo vê: Preferências de notificação, Relatórios, LGPD.
- ADMIN ou GERENTE também veem: SLA de Assistência, Venda a descoberto (grade), Alertas de WhatsApp.
- Só ADMIN também vê: Segurança (PIN).
Ações principais: nenhuma além dos links — é puramente navegação.
Fluxo correto: entrar em Configurações e escolher o item desejado na lista; os itens que a pessoa não tem permissão de usar simplesmente não aparecem (em vez de aparecer e recusar depois).
Se pular ou errar: não se aplica — não há como "errar" numa tela sem formulário.
Gotchas e estados: esta é a única tela do sistema que decide o que mostrar checando o perfil de um jeito um pouco diferente do resto do módulo — funciona certinho porque os perfis com acesso batem exatamente com ADMIN/GERENTE, mas é uma pequena divergência de padrão em relação às outras telas.

Preferências de notificação

Pra que serve: cada usuário escolhe, evento por evento, se quer receber e-mail além do aviso dentro do próprio sistema (o sininho — esse é sempre ligado e não pode ser desligado).
Quem usa: todo perfil autenticado — é uma configuração pessoal, não administrativa. Cada um só edita a própria preferência (a gravação é sempre travada no próprio usuário logado, nunca aceita id de outra pessoa vindo do navegador).
Ações principais: ligar/desligar o e-mail por tipo de evento (uma matriz evento × canal — 11 linhas, uma por tipo de aviso disparável), Salvar.
Fluxo correto:
1. Abrir a tela — ela já vem com o estado atual de cada evento marcado.
2. Alternar os toggles de e-mail que fizerem sentido (a coluna "No app" é fixa, sempre ligada, sem toggle).
3. Salvar — grava tudo de uma vez.
Se pular ou errar: nada quebra — quem nunca visitou a tela recebe os avisos no comportamento padrão já definido no sistema.
Gotchas e estados: existe um tipo de evento (aviso de "lote chegou em SP") que é "não disparável" e por isso nunca aparece nesta matriz — é um evento que o sistema sabe descrever mas que hoje não dispara notificação nenhuma.

SLA de Assistência

Pra que serve: definir, em dias, quando um aparelho em conserto passa a ser considerado "atrasado" nos painéis do módulo de Assistência Técnica — dois números: dias sem aceite (tempo esperando um técnico assumir a OS) e dias em reparo (tempo total até concluir).
Quem usa: rota bloqueada de verdade — só ADMIN ou GERENTE conseguem abrir a tela; qualquer outro perfil é redirecionado pro painel principal antes mesmo de a página carregar. A gravação segue a mesma trava.
Ações principais: editar os dois campos numéricos (dias sem aceite, dias em reparo), Salvar.
Fluxo correto:
1. ADMIN/GERENTE abre a tela — se a empresa nunca configurou, vê o valor padrão do sistema.
2. Ajusta os dois números conforme a política da empresa.
3. Salva — o valor vale pra empresa inteira (não é por técnico ou por tipo de aparelho).
Se pular ou errar: enquanto a empresa nunca salvar nada aqui, os painéis de Assistência usam o SLA padrão do sistema — não há "erro" possível, só a ausência de customização.
Gotchas e estados: essa configuração só passa a existir no banco depois do primeiro salvamento — antes disso, o sistema simplesmente usa o padrão embutido. A gravação salva ou atualiza numa única operação, sempre 1 registro por empresa.

Venda a descoberto (grade)

Pra que serve: um único interruptor (toggle) que decide se a venda "por grade" (vender um modelo+capacidade+grade sem escolher o IMEI exato, reservando de um pool) pode ultrapassar o estoque físico disponível no momento, ou se é bloqueada quando não sobra unidade.
Quem usa: rota bloqueada de verdade — só ADMIN ou GERENTE.
Ações principais: ligar/desligar o toggle "Permitir venda a descoberto", Salvar.
Fluxo correto:
1. ADMIN/GERENTE decide a política: deixar vender além do estoque físico (aceitando o risco de prometer um aparelho que ainda não existe fisicamente) ou travar.
2. Salva — a mudança vale imediatamente pras próximas vendas por grade.
Se pular ou errar:

⚠️ Atenção: enquanto ninguém mexe nessa configuração, o padrão do sistema é permitir a venda além do estoque físico — ou seja, de fábrica o iMportex deixa vender um aparelho que ainda não existe de verdade no estoque.
Gotchas e estados: esta é a configuração que resolve a política interna da casa de proibir vender o que não existe fisicamente — desligar o toggle é o que ativa essa proteção.

Alertas de WhatsApp

Pra que serve: configurar um canal extra (além do sininho e do e-mail) de aviso pro dono — hoje usado, por exemplo, pra avisar de divergência de grade na conferência de SP. É "melhor esforço": se o envio falhar, os outros dois canais continuam funcionando normalmente.
Quem usa: rota bloqueada de verdade — só ADMIN ou GERENTE. Esta rota não tem entrada no menu lateral de propósito (mesma decisão de outras telas avançadas do sistema) — só é alcançável por quem sabe a URL ou entra pelo hub de Configurações.
Ações principais: cadastrar o número do dono, ligar/desligar o alerta, "Enviar teste" (manda uma mensagem de verificação pro número que está na tela, não o que já foi salvo — evita o admin trocar o número, testar antes de salvar, e concluir errado que o número antigo ainda funciona).
Fluxo correto:
1. Preencher o número do WhatsApp do dono.
2. Ligar o toggle "ativo".
3. Clicar em "Enviar teste" pra confirmar que a integração está funcionando antes de contar com ela de verdade.
4. Salvar.
Se pular ou errar: se a integração de envio não estiver configurada no servidor, o teste e os envios reais falham com um erro interno — a tela mostra a falha, mas o sistema nunca trava por causa disso (é só um canal extra, best-effort/melhor esforço).
Gotchas e estados: este canal é distinto do WhatsApp usado pra atender cliente (a tela de atendimento, que roda em outra integração) — são dois sistemas de WhatsApp diferentes dentro do iMportex, propositalmente sem se misturar.

Segurança (PIN)

Pra que serve: cadastrar ou trocar o PIN de 6 dígitos que autoriza ações sensíveis do sistema — hoje, principalmente a Ferramenta Correção (devolver um aparelho já processado de volta pra Triagem, uma ação que pode desfazer trabalho de várias etapas).
Quem usa: rota bloqueada de verdade — ADMIN-only (nem GERENTE entra; o racional é que o PIN é pessoal de cada dono/empresa).
Ações principais: definir/trocar o PIN (6 dígitos numéricos).
Fluxo correto:
1. ADMIN abre a tela — vê apenas se já existe um PIN cadastrado (nunca o valor, nem a versão criptografada).
2. Digita um novo PIN de 6 dígitos.
3. Salva — o PIN é transformado numa versão criptografada e irreversível (hash) dentro do próprio banco de dados, nunca em texto puro em lugar nenhum do sistema.
Se pular ou errar:

⚠️ Atenção: não existe "esqueci meu PIN". Como o sistema nunca guarda o valor original em lugar nenhum, a única forma de recuperar acesso é o ADMIN cadastrar um PIN novo — apagando o antigo. E sem PIN cadastrado, qualquer ferramenta que dependa dele (como a Correção de Triagem) fica indisponível pra quem tenta usá-la.
Gotchas e estados: esta tela teve uma correção de segurança real: até 12/08/2026, checar "será que já existe PIN?" trazia até o servidor uma informação mais sensível do que deveria (nunca chegava a aparecer na tela, mas ficava exposta a uma leitura mais ampla do que qualquer usuário autenticado deveria alcançar). Com um PIN de só 6 dígitos (1 milhão de combinações possíveis), uma informação sensível vazada é quebrável rápido por tentativa e erro em massa. Hoje a checagem devolve só um sim/não, nunca o dado sensível. É o tipo de ajuste que não aparece navegando na tela, mas que fecha um buraco real de segurança.

Erros comuns e como evitar

"O botão apareceu, então eu posso" — nem sempre. Em Peças, quem vê a tela nem sempre pode gravar — só ADMIN/GERENTE grava de verdade (uma trava dentro do banco decide, não o botão). Se salvar der erro estranho em vez de "sucesso", provavelmente é isso. Em Fornecedores, Freteiros, Cambistas e Serviços a trava é mais forte desde 06/09/2026: nem o botão aparece mais pra quem não é ADMIN/GERENTE.
Perfil errado ao criar usuário trava tudo depois. Promover alguém pra ADMIN sem necessidade real abre uma porta grande demais; e criar um perfil operacional (TESTADOR, OPERADOR_*) sem vincular ao registro de Técnico (quando aplicável) faz a pessoa logar mas não aparecer nos dropdowns de OS — confira sempre o perfil escolhido antes de salvar.
Peça ou serviço sem custo/tempo cadastrado corretamente vira "custo fantasma". Peça sem histórico de compra fica com custo médio zerado mesmo tendo estoque físico; serviço sem tempo padrão não entra no cálculo de mão de obra do técnico próprio.
Arquivar não é apagar — e isso é de propósito. Toda ação "Excluir"/"Arquivar" nas telas de Cadastros é soft delete (marca uma data, não remove a linha). Histórico de compras, laudos e vendas antigas continuam íntegros mesmo depois de arquivar o fornecedor/peça/técnico envolvido.
Configurações não tem "salvar automático". SLA de Assistência, Venda a descoberto e Alertas de WhatsApp só valem depois de clicar em Salvar — abrir a tela e sair sem salvar deixa a empresa no comportamento padrão do sistema (nem sempre o mais restritivo).
PIN esquecido não tem "recuperar senha". A única forma de "recuperar" é o ADMIN cadastrar um PIN novo — apagando o antigo.
Testar o alerta de WhatsApp antes de salvar, sempre. O botão "Enviar teste" manda pro número que está na tela, não o que já foi gravado — é assim de propósito, mas confunde quem espera testar o valor salvo.
Empresas e Diagnóstico do problema são as duas exceções sem trava de rota. Diferente do resto do módulo, essas duas telas não bloqueiam a leitura da página inteira — ficam acessíveis por URL direta a qualquer autenticado da empresa, mesmo que o menu esconda o link. A gravação continua protegida nos dois casos.
Técnicos não é mais "menu esconde, ação recusa" — é rota fechada de verdade. Desde 05/09/2026 a página inteira exige ver_dinheiro (ADMIN/GERENTE/FINANCEIRO), porque ela expõe salário e custo por minuto de cada técnico próprio. Um VENDEDOR que antes só "não gravava" hoje nem abre a tela.

Cadastros e Configurações