Regras que valem em todo lugar

Este capítulo não descreve uma tela: descreve as regras que valem em TODAS as telas do iMportex ao mesmo tempo. São os "trilhos" por baixo do sistema — quem pode fazer o quê (RBAC, sigla de Role-Based Access Control, controle de acesso por perfil), como um aparelho muda de estado sem se perder, como a grade (A/AB/B/C) é protegida, como a moeda BRL/USD é travada por praça, como a comissão é gerada, o que roda sozinho sem ninguém clicar em nada (as rotinas automáticas, chamadas de "crons"), quais interruptores (feature flags) ligam/desligam pedaço de sistema sem precisar reconstruir o site inteiro, o que fica gravado pra sempre em log, e como a etiqueta física + a impressora QL-800 atravessam quase toda a operação.

1. RBAC — quem pode fazer o quê

Pra que serve

Decidir, pra cada perfil de usuário, o que ele PODE fazer no sistema — e recusar o resto antes que vire um erro feio no banco de dados ou, pior, uma operação indevida (ex.: um vendedor vendo o lucro da loja, ou um operador travando um aparelho sozinho).

Como funciona

O sistema tem 9 perfis de usuário:

A regra de ouro do sistema: existe UM mapa central que decide, pra cada "capacidade" de negócio — perguntas do tipo "esse perfil pode fazer isso?", como ver dinheiro, criar venda, operar expedição, dar crédito a cliente, gerenciar usuários ou triar aparelho — quais perfis têm acesso. Alguns exemplos:

• Ver dinheiro (custo/lucro/margem): ADMIN, GERENTE, FINANCEIRO
• Ver a própria comissão: ADMIN, GERENTE, FINANCEIRO, VENDEDOR
• Dar crédito a cliente: ADMIN, GERENTE, FINANCEIRO
• Criar venda: ADMIN, GERENTE, VENDEDOR
• Gerenciar usuários: só ADMIN
• Triar aparelho: ADMIN, GERENTE, TESTADOR, OPERADOR_PY

Antes desse mapa único existir, havia dezenas de checagens de perfil espalhadas pelo sistema, que discordavam entre si — foi daí que saíram dois vazamentos reais: dinheiro aparecendo pra quem não devia ver, e uma função quebrada pro vendedor. O mapa central resolveu isso: o menu (o que aparece pra cada perfil) e as ações que gravam no banco a partir de um clique consultam sempre a mesma fonte.

Essa checagem sozinha não basta — ela vive só no aplicativo. Por isso o sistema aplica, em cada capacidade sensível, uma segunda trava, dentro do próprio banco de dados: mesmo que alguém tentasse pular o aplicativo e chamar o sistema direto, o banco recusaria por conta própria. Quando as duas travas (aplicativo e banco) divergem, o resultado pro usuário é ou um erro cru, ou — pior — uma tela que aparece vazia sem avisar que foi negada (o banco, quando nega, simplesmente não devolve nenhuma linha, não um erro).

Existem duas formas de bloqueio: uma que impede a ação mas deixa a própria função decidir como avisar o usuário (usada dentro de uma operação específica), e outra que impede a PÁGINA inteira de abrir e redireciona quem tenta entrar sem permissão — essa segunda fecha o furo clássico de "o menu esconde o botão, mas digitando o endereço na mão a tela abre do mesmo jeito".

Existe também uma regra específica — a regra de visibilidade de dinheiro — que controla quem vê custo/lucro/margem nas telas e nos relatórios financeiros. Ela só esconde a exibição: nunca muda o cálculo por baixo. Ver Financeiro.

Se ignorar

Um perfil de operação (ex.: TESTADOR) veria custo/lucro da loja, ou um VENDEDOR conseguiria dar crédito a cliente sozinho — os dois vazamentos reais que motivaram a criação desse mapa central.

2. A máquina de estados do aparelho

Pra que serve

Garantir que o aparelho (rastreado por IMEI) nunca "pule" de estado sem deixar rastro — sem isso, o custo não é acumulado direito, o histórico fica furado e aprovações são puladas.

Como funciona

Os estados possíveis, na ordem em que nasceram no sistema:

AGUARDANDO_CHEGADA → CHEGADO_PY → EM_TRIAGEM → EM_ASSISTENCIA → AGUARDANDO_APROVACAO → RETESTE → DISPONIVEL_PY → EM_TRANSITO → CHEGADO_SP → DISPONIVEL_SP → RESERVADO → VENDIDO → EM_GARANTIA → DEVOLVIDO → CANCELADO

Mais um estado terminal, adicionado depois: SUCATA — aparelho reprovado no reteste que o operador decide descartar; sai do estoque, e o custo dele vira "perda reconhecida" (não conta mais como valor em estoque, mas também não some sem explicação).

Junto do status existe também a localização física do aparelho (ex.: triagem no Paraguai, estoque em São Paulo, em trânsito, reservado, vendido, em garantia ativa) — os dois campos sempre mudam juntos.

A regra mais importante deste capítulo inteiro: mudança de status ou localização só é permitida por UM caminho. Nenhuma tela, nenhum sistema externo, nenhum comando direto no banco pode simplesmente "mudar o status" de um aparelho — existe uma única função responsável por isso, e o próprio banco de dados recusa qualquer tentativa de alterar o status por fora dela. É literalmente impossível pular esse caminho.

Essa função foi reforçada depois de duas falhas encontradas em auditoria:

1. Corrida (duas pessoas mexendo ao mesmo tempo): antes, o sistema lia o status, decidia o que fazer, e só depois gravava — entre a leitura e a gravação, outra pessoa podia ter mudado o aparelho (ex.: duplo despacho do mesmo aparelho). A correção trava o registro do aparelho durante toda a operação e só aceita a mudança se o estado ainda for o mesmo que foi lido; senão, recusa com a mensagem "o aparelho mudou de X para Y enquanto você operava — recarregue a tela".
2. Log fantasma / custo fantasma: antes, o registro do movimento e a mudança de status de fato eram duas gravações separadas — se a segunda falhasse (ex.: usuário sem permissão pra aquele passo), o registro do movimento ficava gravado mesmo assim, e se ele carregava custo, esse custo entrava na margem sem o aparelho ter de fato se movido. A correção junta as duas coisas numa única operação: se uma falha, as duas revertem.

Quem pode mover o quê: ADMIN, GERENTE, OPERADOR_SP, TECNICO_PROPRIO, OPERADOR_PY e SUPERVISOR_ASSISTENCIA têm liberação ampla; o TESTADOR só pode mexer quando o aparelho está sob a custódia dele. Por cima disso, o sistema aplica mais quatro regras de negócio:

• VENDIDO é imutável — nenhuma mudança é aceita depois da venda, exceto exceções bem específicas (registro de garantia, cancelamento). Ver OS, Garantia e RMA.
• Enviar pra SUCATA exige ADMIN ou GERENTE — checado num único ponto central, não em cada tela que poderia disparar a mudança (uma tela de movimentação em lote também conseguia mudar status e não tinha esse limite antes).
• Aprovação pendente bloqueia — se existe uma movimentação anterior que precisa de aprovação e ainda não foi aprovada, nenhum movimento novo é aceito.
• Movimentação em lote usa uma lista fechada de destinos (nunca inclui SUCATA) — porque em lote seria fácil descartar estoque vendável por engano ou abuso.

Duas travas irmãs, no mesmo padrão, protegem outros campos sensíveis do aparelho:

• Exclusão: nenhuma alteração direta apaga um aparelho — só uma função específica, reservada a ADMIN, que exige um motivo escrito com no mínimo 10 caracteres e grava tudo em auditoria. Antes dessa trava, qualquer um dos 6 perfis com permissão ampla de edição podia apagar um aparelho de todas as telas sem motivo, sem segunda pessoa validando, sem rastro.
• Bloqueio administrativo: protegido do mesmo jeito. Há dois caminhos legítimos: uma decisão de gestão direta (ADMIN/GERENTE, sem PIN) e um bloqueio/desbloqueio que qualquer perfil pode acionar, mas que exige o PIN de 6 dígitos de um ADMIN pra validar. Um aparelho bloqueado some das telas de grade disponível — é a ferramenta pra "segurar" um aparelho sem excluí-lo.

Se ignorar

Uma tentativa de mudar status, localização, exclusão ou bloqueio por fora do caminho oficial (por exemplo, uma ferramenta de banco de dados direta) é recusada pelo sistema — ele é desenhado pra que "por fora" simplesmente não funcione. Quando essas travas ainda não existiam, o resultado histórico foi: aparelho sumindo sem rastro (exclusão), aparelho reaparecendo pra venda depois de travado pela gestão (bloqueio), ou duplo despacho por corrida entre duas pessoas.

3. Grade A/AB/B/C e MIX

Pra que serve

Classificar o estado físico/estético de cada aparelho numa escala simples (A = melhor, C = pior) que vira preço, etiqueta e o que o cliente recebe.

Como funciona

A grade é calculada, não digitada livremente. Ela sai da combinação entre o estado da carcaça e o estado da tela — a bateria virou só informativa ("84%, mas lindão, continua A"):

• Carcaça ruim OU tela "precisa trocar" → grade C, e o aparelho vai pra assistência (nunca vira C "limpo" pronto pra venda — a grade C aqui sempre vem acompanhada de "vai pro conserto").
• Carcaça ótima → grade A.
• Carcaça boa → grade A se a tela também for excelente, senão AB.
• Carcaça média → grade AB se a tela for excelente, senão B.

Qualquer defeito funcional marcado (câmera, Face ID, auricular, alto-falante, microfone, tela fantasma, aparelho bloqueado, botões, conector) ou "não liga" também manda o aparelho pra assistência, com prioridade máxima. Só quando não há nenhum desses problemas o aparelho vira disponível pra estoque, com a grade calculada. Existe também uma sugestão automática de grade que o técnico pode revisar e sobrescrever antes de salvar.

⚠️ Atenção: um aparelho fisicamente pronto, mas sem a grade preenchida, fica invisível no despacho Paraguai → São Paulo e no estoque — o sistema já descobriu isso represado três vezes em produção: 131 aparelhos, depois 192 (R$ 375.015,14), depois mais 7 (R$ 13.214), dinheiro parado sem ninguém perceber. Hoje existe uma trava que impede um aparelho de entrar em "disponível" sem grade preenchida; se já existe uma sugestão automática, ela é promovida pra grade sozinha, e se não existe nenhuma, o sistema recusa a entrada com uma mensagem indicando pra resolver na Triagem. Aparelho legado — já parado assim antes da trava existir — não é bloqueado retroativamente; esses são escoados por uma fila de conferência manual separada.

A grade também é protegida contra alteração direta: qualquer tentativa de mudar a grade por fora dos caminhos oficiais é recusada — a mesma proteção da máquina de estados (item 2 deste capítulo), agora aplicada à grade. Essa trava nasceu depois que 7 aparelhos de um pedido real tiveram a grade alterada por fora do sistema, sem passar por nenhuma correção auditada. As portas oficiais de mudança de grade são três, e cada uma fica registrada numa linha do tempo única de mudanças de grade:

1. Correção com PIN do dono — ADMIN/GERENTE aciona, com motivo obrigatório (de uma lista fechada de motivos), podendo mover o aparelho de destino junto.
2. Conclusão de Ordem de Serviço — grava a grade final quando o conserto termina, ou reverte a grade se o movimento falhar.
3. Conferência em São Paulo — o operador de SP confere a grade que veio do Paraguai e corrige se divergir; isso alimenta um placar de acerto por quem gradeou no Paraguai.

Grade MIX: MIX nunca é uma grade de verdade no sistema — em vez disso, é marcado como um tipo especial de item de venda, sem grade própria. A composição real (quais aparelhos A/AB/B entram na caixa) só é decidida na hora de separar fisicamente o pedido. Regra de preço: MIX é sempre um alias da grade AB — "AB é o mix", nunca vira uma linha de preço própria.

Se ignorar

Sem a trava de grade obrigatória: dinheiro em estoque fica invisível no despacho (já aconteceu 3 vezes, centenas de milhares de reais represados). Sem a trava de escrita direta: a grade impressa na etiqueta pode divergir do que foi gravado por fora, sem ninguém saber quem mudou ou por quê.

4. Travas de moeda: BRL só em SP, USD só no Paraguai

Pra que serve

Impedir que uma venda em reais saia do estoque errado (Paraguai) e vice-versa — a regra é simples: quem vende em reais só vende o que já chegou em São Paulo; quem vende em dólar só vende o que está no Paraguai. Ninguém cruza.

Como funciona

Hoje, os dois lados são travados por uma regra automática no banco de dados que dispara toda vez que um item de venda vinculado a um aparelho por IMEI é registrado:

• Se a venda é em dólar e o aparelho NÃO está disponível no Paraguai → recusa.
• Se a venda é em reais e o aparelho NÃO está disponível em São Paulo → recusa.

Essa trava só age quando o aparelho está de fato num status "disponível" saindo numa venda nova — um registro histórico ou um aparelho em outro estado não é afetado.

Existe uma trava companheira que garante que a moeda do item bate com a moeda da venda como um todo: acessório é sempre em reais, não importa a moeda da venda geral; já aparelho, grade e MIX seguem o par de moeda gravado no próprio item.

Como regra de negócio: preço em reais é exclusivo do estoque recebido em São Paulo; preço em dólar é exclusivo do estoque no Paraguai — e o próprio banco só aceita um conjunto de campos preenchido por vez (ou preço/custo em reais, ou o conjunto equivalente em dólar — nunca os dois juntos na mesma linha).

Se ignorar

Uma venda em dólar tentando sair de um aparelho que fisicamente está em São Paulo (ou vice-versa) é recusada pelo sistema com uma mensagem explícita — não existe caminho, nem por fora do aplicativo, pra isso passar batido.

5. Comissão automática por aparelho vendido

Pra que serve

Pagar o vendedor por cada aparelho que ele vendeu, de forma automática, sem depender de ninguém calcular na mão.

Como funciona

A comissão é gerada automaticamente no momento em que uma venda é efetivada, seguindo uma regra de comissão configurável — não um valor fixo travado no sistema. Essa regra tem um tipo de cálculo, um valor base e, opcionalmente, um vendedor específico (se vazio, vale pra todo mundo), mais uma data de início e, opcionalmente, uma data de fim de validade.

O valor de R$ 3,00 por aparelho é o que veio configurado como exemplo desde o começo do sistema; o valor real usado hoje é configurado nessa mesma regra e pode ser outro.

O cálculo em si é deliberadamente simples: só sabe calcular comissão como "valor fixo × número de aparelhos vendidos". Se um dia surgir uma regra de comissão por percentual da venda, o sistema recusa calcular em vez de inventar um resultado — isso ainda está fora do escopo atual.

"Número de aparelhos", pra fim de comissão, conta tanto os aparelhos com IMEI quanto as unidades de grade vendidas sem IMEI atribuído ainda. Acessório fica de fora — não é aparelho, não gera comissão.

Quando existe mais de uma regra vigente na data da venda, uma regra específica de um vendedor tem prioridade sobre a regra geral (a que vale pra todo mundo).

A geração é feita de forma que nunca duplica, mesmo que a venda seja processada duas vezes. Quando gerada, a comissão nasce como pendente — o fechamento e o pagamento dela são um passo posterior, feito em outro lugar do sistema. Ver Financeiro.

⚠️ Atenção: sem uma regra de comissão cadastrada e vigente pra aquela data, a venda simplesmente não gera comissão nenhuma — silenciosamente, sem nenhum erro na tela. Se um vendedor reclamar que não recebeu comissão de uma venda específica, o primeiro lugar a checar é se existe uma regra vigente (dele ou geral) na data daquela venda.

Se ignorar

Ver acima — sem regra vigente, comissão zero e sem aviso.

6. Rotinas automáticas que rodam sozinhas

Pra que serve

Fazer o sistema "se auto-limpar" no tempo certo, sem depender de alguém abrir uma tela específica e clicar num botão manual.

Como funciona

O agendamento dessas rotinas roda por fora do sistema principal, numa infraestrutura separada mantida pelo dono — cada rotina só executa quando é chamada, e essa chamada é protegida por uma senha compartilhada que só a própria automação conhece (por isso ela não passa pelo login normal de usuário).

Existem 4 rotinas automáticas hoje:

A rotina de reservas existe porque, antes dela, uma reserva vencida continuava marcada como ativa e travava a venda do aparelho pra outro cliente indefinidamente, mesmo com a própria tela já mostrando "vencida" — sem erro visível em lugar nenhum. A correção foi em duas frentes: a checagem de venda passou a exigir o prazo válido na hora (conserta o efeito imediatamente), e essa rotina conserta o estado de fato (pra tela, relatório e histórico contarem a mesma história).

O mesmo padrão se repete com cotações: elas reusam a mesma estrutura de reserva de grade, mas a rotina vizinha não cobria esse caso até ser criada — uma proposta que esfriava segurava estoque pra sempre. Essa rotina, adicionalmente, registra a cada execução um sinal de vida — se ela parar de ser chamada, a ausência de execução recente é detectada e vira alarme na tela de Pendências (o sistema é desenhado pra que silêncio nunca seja confundido com sucesso).

⚠️ Atenção: essas rotinas dependem do agendador externo continuar chamando o sistema. Se ele parar: reserva vencida continua travando o aparelho pra outro cliente, cotação vencida continua segurando estoque de grade indefinidamente, solicitação de assistência abandonada nunca libera o aparelho de volta, e assinatura vencida nunca avança de estágio de cobrança.

Se ignorar

Ver acima.

7. Interruptores de ambiente (feature flags)

Pra que serve

Ligar/desligar um pedaço específico do sistema sem precisar reconstruir e reimplantar o código — trocando só uma configuração no servidor.

Como funciona

O sistema usa duas famílias distintas de interruptor.

A) Configurações lidas em tempo real — cinco hoje:

Nenhum desses três interruptores é visível pro navegador — só o próprio servidor sabe o valor deles, então desligar um deles não exige reconstruir o site inteiro. O valor atual de cada um em produção depende da configuração do ambiente onde o sistema está publicado.

B) Configurações fixas no próprio código — um segundo mecanismo, mais permanente: duas chaves que desligam por completo o trade-in (usar um aparelho usado como parte do pagamento) e a venda de acessório avulso por código de peça. Decisão de negócio: os dois saem do sistema porque não é o foco dele. Isso é uma desativação em duas etapas: a etapa atual esconde do menu, mostra aviso nas páginas, e recusa criação nova — mas o histórico (venda antiga com acessório, crédito de troca já concedido) continua acessível pra leitura, impressão e relatório. Uma segunda etapa, de apagar de vez o recurso, está deliberadamente adiada e exigiria backup, contagem e um período de quarentena antes de acontecer.

Diferente dos três primeiros, essas duas configurações exigem editar o código e reimplantar o sistema pra mudar — não são um interruptor de uso imediato.

Se ignorar

Confundir as duas famílias leva a tentar desligar o MIX mexendo na configuração errada (não afeta nada), ou tentar reativar o trade-in mudando uma configuração de ambiente (também não afeta nada — é preciso editar o código).

8. Auditoria e logs

Pra que serve

Deixar um rastro inforjável — que ninguém, nem alguém com acesso amplo ao sistema, consegue apagar ou adulterar — de quem fez o quê, quando, em qual registro.

Como funciona

Existe uma tabela central de auditoria que registra: qual empresa, qual usuário, qual ação, em qual tipo de registro e qual registro específico, o que era antes e o que passou a ser depois, de qual endereço e navegador, e em que data/hora. Ela não tem como apagar uma linha — é um log imutável por design, não um registro que se edita ou se apaga.

Essa tabela tem uma proteção reforçada: a regra vale até pra quem administra o sistema por dentro. Só duas coisas são permitidas nela:

• Consultar: só ADMIN/GERENTE da própria empresa podem ler.
• Inserir direto: proibido pra todo mundo — nem o próprio sistema grava direto ali.

O único jeito de gravar é por uma rotina especial, com privilégio elevado, que descobre sozinha — a partir da própria sessão logada no servidor — quem é o usuário e de qual empresa, nunca confiando num dado que o navegador do cliente poderia forjar. É por isso que esse log é chamado, internamente, de "inforjável".

Duas regras de projeto:

• Falha de log não derruba a operação real — se a gravação do log falhar, a venda (ou outra ação de negócio) não é desfeita por causa disso, mas o erro é reportado à parte pra alguém investigar depois — não fica escondido.
• Dado pessoal nunca cru — telefone, CPF e WhatsApp nunca aparecem em texto puro nos campos de "antes"/"depois" do log; só identificadores e valores. A proteção do dado pessoal em repouso é responsabilidade de outra camada do sistema.

Além do log geral, existem duas trilhas específicas pras ações mais sensíveis, cada uma com sua própria tabela e consulta restrita a ADMIN/GERENTE:

• Correções com PIN do dono — toda ação que precisou do PIN de um ADMIN pra ser autorizada (bloquear/desbloquear aparelho, corrigir grade, devolver aparelho pra triagem), sempre separando quem clicou de quem autorizou com o PIN.
• Histórico de mudanças de grade — linha do tempo unificada de toda mudança de grade, com a origem de cada uma (correção com PIN, conclusão de Ordem de Serviço, reversão de Ordem de Serviço, ou conferência em São Paulo).

Essa auditoria também pode ser consultada dentro do próprio sistema, numa tela dedicada — ver Ferramentas.

Se ignorar

Sem esse caminho único de escrita, um perfil com permissão ampla de edição poderia inserir uma entrada de auditoria falsa direto na tabela — o log "inforjável" deixaria de ser inforjável.

9. Etiquetas e a impressora QL-800

Pra que serve

Toda vez que um aparelho é triado, ele ganha uma etiqueta física impressa — com IMEI, grade, código de barras e QR — que o acompanha fisicamente do Paraguai até a venda em São Paulo. Não é uma tela: é um pedaço de hardware que quase todo fluxo operacional passa por perto.

Como funciona

A etiqueta junta os dados de UM aparelho: modelo, especificações, bateria, grade, cor da grade, IMEI formatado, número do laudo, código de barras, QR, destino e — quando existir — o defeito conhecido de um aparelho liberado pra venda mesmo assim. Essa última parte é uma correção recente: antes, quando um aparelho com defeito era liberado de propósito (sem reparo), a etiqueta impressa ficava idêntica à de um aparelho perfeito; hoje a faixa de defeito aparece na etiqueta.

A impressão física passa por um programa chamado QZ Tray, que fica rodando no computador do operador e faz a ponte entre o sistema (no navegador) e a impressora instalada no Windows. O sistema nunca fala o protocolo da impressora Brother diretamente — ele manda uma imagem já pronta (o mesmo desenho que aparece na tela) e deixa o driver da Brother, instalado no Windows, cuidar do resto. Se o QZ Tray não estiver rodando, o sistema cai de volta pro diálogo de impressão comum do navegador.

Configuração física do fluxo principal (etiqueta automática da triagem, Central de Etiquetas, conferência SP): rolo contínuo de 62mm, etiqueta de 58,8×40mm, alta resolução (300 DPI), com opção de conversão pra preto-e-vermelho puro (sem tons intermediários), porque o rolo é dessas duas cores. Existe ainda um formato menor de 50×30mm (rolo destacável) usado por telas específicas — na dúvida de qual bobina comprar, o padrão da operação é o rolo contínuo de 62mm. As preferências de impressora (nome exato, se imprime automaticamente ao concluir a triagem) ficam salvas só naquele computador — nunca sobem pro servidor — porque cada bancada pode ter uma impressora com nome diferente.

A Central de Etiquetas (ver Ferramentas) consolida todas as ferramentas de etiqueta num lugar só: busca em todo o histórico de triagens (por IMEI, modelo, caixa ou período) com reimpressão em lote. Perfis liberados: ADMIN, GERENTE, OPERADOR_PY, OPERADOR_SP, TESTADOR, SUPERVISOR_ASSISTENCIA (este último entrou por decisão mais recente — reimprime etiqueta depois de um conserto).

Uma segunda impressora — térmica de cupom 80mm, modelo Celark CE-O1509R, na expedição — usa um caminho totalmente diferente: manda o texto pronto direto pra impressora, não uma imagem, porque numa térmica de cupom o texto nativo sai instantâneo e uma imagem entupiria a fila em dia de muita venda. É essa impressora que gera a comanda de separação quando a venda fecha, listando os itens pro operador separar fisicamente.

Se ignorar

Sem o QZ Tray rodando, a impressão silenciosa não funciona e cai no diálogo de impressão manual do navegador — mais lento, mas o fluxo não trava. Uma etiqueta impressa sem a faixa de "defeito conhecido" (já corrigido) faria o estoque parecer mais limpo do que realmente está pra quem manuseia o aparelho depois.

10. Roteamento e sessão: o que roda antes de qualquer tela

Pra que serve

Esta seção não é sobre uma tela específica: é a única coisa que roda em 100% dos acessos ao sistema, antes de qualquer outra regra deste capítulo — vale registrar porque é o exemplo mais transversal que existe.

Como funciona

Toda navegação passa por uma camada de verificação que roda antes de qualquer página carregar, em três passos, nesta ordem:

1. Guarda de endereço — o sistema vive em 3 endereços diferentes (o principal, pra quem usa o dia a dia; um painel administrativo da plataforma; e o site público) e redireciona quem está no endereço errado, preservando o caminho que a pessoa tentou acessar.
2. Roteamento da página inicial — cada endereço tem seu próprio destino padrão ao entrar sem especificar uma página (o principal vai pro painel de controle, o administrativo vai pro painel de administração, o público vai pra página pública).
3. Sessão de login — atualiza o token de sessão e decide se a página pedida precisa de login. Por padrão, tudo exige login, exceto uma lista fechada de páginas que precisam ficar abertas: login, recuperação de senha, confirmação de login por redes sociais, verificação de saúde do servidor, as rotinas automáticas (ver item 6 deste capítulo), a integração que recebe mensagens do WhatsApp (protegida por lista de números permitidos), rastreio público de pacote, certificado público de laudo/qualidade, e a proposta pública de cotação (que nunca mostra custo, já que o link dela circula por WhatsApp).

Duas proteções extras, nascidas de bugs reais em produção:

• Freio contra loop de login: se uma sessão válida cair na tela de login 3 vezes em menos de 20 segundos, o sistema interrompe o ciclo sozinho e mostra uma mensagem de "sessão instável", em vez de deixar o navegador travar com erro de redirecionamentos demais.
• Chamada automática sem sessão nunca é redirecionada — ela recebe um erro claro na hora, porque quem chama esse tipo de rota é outro sistema, não uma pessoa navegando; redirecionar pra tela de login faria essa chamada tentar interpretar uma página como se fosse dado, escondendo o erro de verdade.

Se ignorar

Sem essa camada, uma página nova nasceria acessível sem login por padrão (o padrão mais perigoso é "libera por padrão, restringe depois"); o padrão deste sistema é o oposto, de propósito: tudo é fechado, a menos que esteja explicitamente na lista de exceções.