Recebimento no Paraguai

O Recebimento é a porta de entrada de todo o fluxo do iMportex. É aqui que um aparelho, que até então só existia como uma linha cadastrada no sistema (com status AGUARDANDO_CHEGADA, ou seja, "comprado mas ainda não chegou fisicamente"), passa a existir de verdade no galpão do Paraguai (PY). Antes do Recebimento, o aparelho é só uma promessa de compra. Depois do Recebimento, ele vira estoque físico rastreável por IMEI (o número de série de 15 dígitos que identifica cada aparelho), pronto para seguir para a Triagem (onde recebe um laudo de qualidade e uma grade de classificação A/AB/B/C/MIX) e, mais adiante, para a Expedição rumo a São Paulo (SP) e a venda.

Existem três jeitos diferentes de registrar essa chegada, porque na prática a mercadoria chega de formas físicas diferentes:

1. Por CAIXA (com QR/código de barras) — quando a mercadoria chega em volumes fechados e etiquetados.
2. Por LOTE (a "esteira") — quando você vai conferir aparelho a aparelho contra a lista do lote de compra, item a item.
3. AVULSO (bipe solto) — quando é um aparelho isolado, sem caixa e sem lote para conferir contra uma lista.

O sistema não obriga a usar um só: a tela Receber mercadoria (/recebimento/guia) existe justamente para orientar qual modo usar em cada situação, porque escolher o modo errado (por exemplo, usar o Avulso quando na verdade existe um lote com lista) faz o sistema perder a conferência de divergência (falta/sobra) em silêncio.

Uma peça central do desenho é a relação caixa → aparelho: uma caixa é um contêiner lógico com um código e uma quantidade esperada; cada aparelho bipado dentro dela fica vinculado àquela caixa específica. Essa relação é o que permite depois imprimir o romaneio (a lista de conferência) e rastrear "esse aparelho veio de qual caixa, de qual lote, bipado por quem".

Fluxo do módulo em 1 olhada

1. A mercadoria chega fisicamente no galpão do PY.
2. O operador abre Receber mercadoria (/recebimento/guia) e escolhe o modo certo: Caixa, Lote (esteira) ou Avulso.
3. Modo Caixa (preferido pelo cliente KL para remessas em volume): cadastra cada caixa (código + quantidade esperada) → confirma que ela chegou → abre a caixa e bipa os IMEIs de dentro → fecha a caixa (o sistema já avisa se faltou algum) → opcionalmente libera a caixa para a Triagem, endereçando-a a uma ou mais testadoras.
4. Modo Lote/Esteira (protege a conferência com o fornecedor): abre uma sessão de recebimento para o lote → bipa os IMEIs que chegaram um a um contra a lista esperada → o que não bate vira divergência (falta, sobra, item errado ou dano) → finaliza a sessão, e o que não foi bipado vira "falta" automaticamente.
5. Modo Avulso: bipa ou digita o IMEI direto, sem lista de conferência — o aparelho muda de status na hora, sem gerar divergência.
6. Em qualquer um dos três modos, o aparelho recebido muda de status AGUARDANDO_CHEGADA para CHEGADO_PY (localização RECEPCAO_PY) — esse é o evento que "liga a luz" do aparelho no sistema e o torna visível para a Triagem.
7. Etiquetas (58,8×40mm, para colar no volume físico) e romaneios (folha A4, para conferência/arquivo) podem ser impressos a qualquer momento, individualmente ou em lote.

Receber mercadoria (porta guiada)

Pra que serve: é o ponto de entrada único do módulo — uma tela de escolha que explica, em linguagem simples, quando usar cada um dos três modos de recebimento (Caixa, Lote, Avulso), para evitar que o operador escolha o modo errado e perca rastreabilidade de divergência.

Quem usa: ADMIN, GERENTE, OPERADOR_SP, OPERADOR_PY. Quem não é um desses perfis é redirecionado pro painel geral ao tentar acessar a tela diretamente — aqui a trava é real, não é só o menu que esconde o link.

Ações principais: três cartões clicáveis, cada um leva a um modo:

• "Por CAIXA (com QR)" → Recebimento por caixa
• "Por LOTE (esteira)" → Recebimento por lote (esteira)
• "AVULSO (bipe solto)" → Recebimento avulso

Fluxo correto:

1. Pergunte: a mercadoria chegou em caixas etiquetadas com QR do sistema? Use Caixa.
2. Senão: você vai conferir item a item contra a lista de um lote de compra? Use Lote (esteira) — é o modo que protege a conferência e registra divergência.
3. Senão (aparelho solto, sem caixa e sem lote): use Avulso, mas trate como exceção, não como rotina.

Se pular ou errar:

⚠️ Atenção: escolher Avulso quando existe lote ou caixa faz o aparelho entrar "silenciosamente" — sem gerar divergência de falta/sobra, mesmo que a remessa real tenha vindo incompleta. Na dúvida entre Lote e Avulso, use o Lote: é o que registra divergência.

Detalhes e estados: as três rotas antigas (Caixa, Esteira, Avulso) continuam vivas e acessíveis por link direto ou favorito — esta tela só reorganizou o menu, não removeu nada.

Recebimento por caixa

Pra que serve: é o modo preferido para remessas grandes que chegam em volumes fechados (pedido explícito do cliente KL). Cada caixa física vira uma caixa lógica no sistema; o operador bipa os aparelhos de dentro dela um a um, e o sistema conta automaticamente quantos já entraram contra quantos eram esperados.

Quem usa: não há trava de perfil na própria tela — qualquer usuário autenticado da empresa consegue abrir e operar as ações. O menu lateral (que só esconde o link, não bloqueia de verdade) mostra este item só para ADMIN, GERENTE, OPERADOR_SP e OPERADOR_PY. Só uma ação tem checagem de perfil embutida: cancelar um recebimento por esteira que esteja travando o cadastro de caixa exige ADMIN, GERENTE ou OPERADOR_PY.

Ações principais:

• Escolher o lote que chegou (lista os lotes com aparelhos ainda AGUARDANDO_CHEGADA, ou que já têm caixa aberta/chegada não concluída).
• "Bipe a etiqueta da caixa pra abrir" — bipa o código de barras de uma etiqueta já impressa e a caixa correspondente abre direto no modo de bipagem (tolera diferença de zeros à esquerda, comum em leitores 1D).
• Cadastrar nova caixa (código + quantidade esperada) — ao salvar, a etiqueta da caixa já abre em nova aba pronta para imprimir.
• "Chegou" — marca a caixa como fisicamente chegada.
• "Bipar aparelhos" — abre o painel de bipagem por IMEI (câmera ou digitação) dentro daquela caixa.
• "Fechar caixa" — encerra a bipagem daquela caixa (mesmo incompleta); se faltar algo, pede confirmação e registra a falta como divergência auditável; o romaneio A4 abre automaticamente para impressão.
• "Esvaziar" — reverte todos os aparelhos já bipados na caixa de volta para AGUARDANDO_CHEGADA, zera a contagem e limpa os vínculos — serve para refazer a bipagem do zero.
• "Corrigir qtd" (09/09) — corrige a quantidade esperada de uma caixa digitada errada no cadastro (ex.: digitou 100 em vez de 54). Só aparece enquanto a caixa está CADASTRADA, com 0 aparelhos bipados e 0 itens vinculados — nesse estado, mudar o número não move estoque nem desfaz trabalho de ninguém. O botão some assim que a caixa recebe o primeiro bipe, e a partir daí a correção fica registrada (quem mudou, de quanto pra quanto).
• "Liberar pro teste →" — só aparece quando a caixa está completa (CONCLUIDA); abre um seletor de testadoras para nomear quem vai receber a custódia da caixa na Triagem.
• "Recolher da testadora" — aparece quando a caixa está EM_TRIAGEM; devolve a caixa para CONCLUIDA (só funciona se nada foi triado ainda) — é uma válvula de escape para caixa presa.
• "Imprimir as N etiquetas do lote →" — atalho para a impressão em lote de todas as etiquetas do lote atual.
• Links "Etiqueta" e "Romaneio" em cada caixa, para reimpressão a qualquer momento.

Fluxo correto:

1. Escolha o lote (ou continue de um lote já em andamento).
2. Cadastre cada caixa da remessa: código (normalmente bipado da etiqueta física do fornecedor) + quantidade que deveria ter dentro.
3. Confirme "Chegou" para cada caixa conforme ela é conferida fisicamente.
4. Abra "Bipar aparelhos" numa caixa CHEGOU e bipe cada IMEI de dentro dela — o contador de "X/Y bipados" atualiza a cada bipe; ao bater o esperado, a caixa se fecha sozinha e o romaneio já abre para impressão.
5. Se a caixa ficar incompleta, use "Fechar caixa" manualmente — confirme a falta, que fica registrada.
6. Quando a caixa estiver CONCLUIDA, use "Liberar pro teste →" e escolha a(s) testadora(s) responsável(is) — isso gera um recibo de custódia rastreável, e notifica a testadora.

Se pular ou errar:

• Bipar um IMEI que já está vinculado a outra caixa (em outra sessão simultânea) é bloqueado por uma trava no banco de dados — a mensagem aponta em qual caixa o aparelho já está.
• Bipar um IMEI de outro lote é recusado ("Esse aparelho é de outro lote").
• Tentar bipar numa caixa já LIBERADA_PARA_TESTE é recusado — a partir daí, qualquer correção de bipagem só é possível via "Esvaziar" (a custódia já foi travada na liberação; bipar por cima geraria divergência fantasma para a testadora).
• Cadastrar caixa quando o mesmo lote já tem um recebimento por LOTE (esteira) aberto é bloqueado — os dois fluxos juntos gerariam divergência falsa. A própria tela oferece "Cancelar recebimento por esteira" (só funciona se nada nela já foi conferido de verdade).
• Tentar "Corrigir qtd" numa caixa que já tem aparelho bipado, ou que já saiu de CADASTRADA, é recusado — a mensagem explica qual dos dois motivos bloqueou. Nesses casos use "Esvaziar" primeiro (se ainda estiver a tempo), não peça correção manual no banco.
• Clicar "Fechar caixa" numa caixa que não está no estado CHEGOU (ex.: já avançou para liberada/em triagem) é bloqueado — evita regredir uma caixa que já saiu do Recebimento.

Detalhes e estados: ciclo de status da caixa: CADASTRADA → CHEGOU → CONCLUIDA (fechada, completa ou com falta registrada) → LIBERADA_PARA_TESTE (custódia entregue à Triagem) → (a partir daqui já é módulo de Triagem) EM_TRIAGEM → TRIAGEM_FINALIZADA → TRIADA. O aparelho, ao ser bipado dentro da caixa, muda para CHEGADO_PY (reaproveitando a mesma rotina do Avulso). A contagem de aparelhos recebidos é sempre recalculada pela contagem real do que foi bipado (não por soma incremental), justamente para não perder bipes quando dois operadores bipam a mesma caixa ao mesmo tempo.

Etiqueta da caixa

Pra que serve: gera a etiqueta física (58,8×40mm — o mesmo rolo de etiqueta térmica usado nos aparelhos) que vai colada no volume. Traz o código da caixa em dois formatos: um código de barras (o que o leitor 1D da bancada lê) e um QR code (que, ao ser bipado/fotografado, abre a caixa direto na tela de bipagem pelo celular).

Quem usa: sem trava de perfil própria — qualquer usuário autenticado consegue abrir. Na navegação normal, esta tela é aberta a partir de "Recebimento por caixa" (cadastro de caixa nova, ou botão "Etiqueta" de uma caixa existente), então na prática só chega aqui quem já tem acesso a essa tela; TESTADOR também tem acesso via a versão em lote (ver próxima seção).

Ações principais:

• Botão para imprimir direto na impressora térmica QL-800; se a QL-800 estiver offline, cai automaticamente no Ctrl+P do navegador (a página já está configurada para o tamanho certo — nunca fica sem opção de imprimir).
• Link para ver o romaneio A4 da mesma caixa.
• Ao abrir a partir do cadastro de uma caixa nova, a impressão dispara sozinha (é assim que a caixa nova já abre a etiqueta pronta para imprimir).

Fluxo correto: ao cadastrar uma caixa em "Recebimento por caixa", esta tela abre automaticamente numa nova aba já mandando imprimir. Cole a etiqueta impressa no volume físico correspondente.

Se pular ou errar: sem a etiqueta colada, a caixa fica sem identificação física rápida — o operador teria que digitar o código manualmente em vez de bipar, o que é mais lento e mais sujeito a erro de digitação.

Detalhes e estados: a contagem exibida na etiqueta muda de sentido conforme o estado: enquanto a caixa ainda não fechou (CADASTRADA/CHEGOU), mostra "N esperados"; depois de fechada, mostra "N aparelhos" (o que de fato tem dentro) — isso evita imprimir uma contagem que ainda vai mudar a cada bipe. Se o número do lote não estiver disponível (uma trava no banco impede a leitura desse dado para o perfil, ou o lote não tem o número interno preenchido), a linha do lote simplesmente some da etiqueta — não aparece como "Lote —". Se a geração do código de barras falhar, a etiqueta sai sem ele em vez de mostrar um quadrado quebrado.

Etiquetas — Caixas (impressão em lote)

Pra que serve: imprime de uma vez as etiquetas de todas (ou parte) das caixas de um lote — em vez de abrir uma aba por caixa, cadastrou 9 caixas, sai a folha das 9 juntas.

Quem usa: sem trava de perfil própria. É a única tela deste capítulo com acesso explícito também para TESTADOR no menu (além de ADMIN, GERENTE, OPERADOR_SP, OPERADOR_PY) — a decisão é que a testadora também imprime as etiquetas pra colar nos volumes, embora bipar aparelho dentro da caixa continue bloqueado para ela por uma regra do banco de dados.

Ações principais:

• Grade visual mostrando exatamente o que sai impresso (o que você vê é o que imprime).
• Checkbox por etiqueta + "Marcar/Desmarcar todas" (começa com todas marcadas, já que o caso comum é "cadastrei N caixas, quero as N").
• Botão para imprimir as selecionadas na QL-800 (mesmo mecanismo de fallback para Ctrl+P das outras telas de impressão).

Fluxo correto: acesse a partir do link "Imprimir as N etiquetas do lote →" dentro de "Recebimento por caixa" → confira a seleção → imprima.

Se pular ou errar: sem um lote selecionado e sem nenhuma caixa aguardando etiqueta no sistema, a tela mostra um aviso de que não há nada para imprimir — não trava, só orienta a cadastrar caixas primeiro.

Romaneio da caixa

Pra que serve: gera a folha A4 de conferência da caixa — cabeçalho com código, lote, contagem e QR, seguido da lista completa (IMEI, modelo, capacidade/cor) de todos os aparelhos já bipados dentro dela. É o papel que vai dentro da caixa ou para o arquivo, servindo de prova de conferência.

Quem usa: sem trava de perfil própria — qualquer usuário autenticado consegue abrir. Na prática é aberta a partir de "Recebimento por caixa" (link "Romaneio" de cada caixa com pelo menos 1 item bipado, ou automaticamente ao fechar/completar a bipagem de uma caixa).

Ações principais:

• Impressão via Ctrl+P numa impressora comum A4 (não a QL-800 térmica) — a lista quebra em várias páginas sozinha, repetindo o cabeçalho da tabela em cada uma.
• Impressão automática ao abrir (é assim que "Fechar caixa" e o bipe do último aparelho esperado já abrem o romaneio pronto).
• Link para voltar à etiqueta 58,8×40mm da mesma caixa.
• Duas linhas de assinatura no rodapé: "Conferido por" e "Recebido por".

Fluxo correto: a caixa é fechada (manualmente ou automaticamente ao bater a quantidade esperada) → o romaneio abre já pronto para imprimir → confira a lista impressa contra o que está fisicamente dentro da caixa → assine e arquive/guarde junto ao volume.

Se pular ou errar: se a caixa ainda não tem nenhum aparelho bipado, o romaneio mostra a mensagem "Nenhum aparelho bipado nesta caixa ainda" em vez de uma tabela vazia — não há erro, só nada para conferir ainda.

Detalhes e estados: se faltou algum aparelho em relação ao esperado, a folha destaca isso visualmente com um selo vermelho "FALTAM N" — decisão deliberada de deixar isso visível, e não escondido, justamente para virar assunto na hora e não depois.

Recebimento por lote (esteira)

Pra que serve: modo de conferência item a item contra a lista de um lote de compra — o sistema já sabe quais IMEIs são esperados (fotografados no momento em que a sessão é aberta) e classifica cada bipe como esperado, sobra ou item não cadastrado. É o modo que "protege" a conferência: toda divergência (falta, sobra, dano) fica registrada e rastreável, em vez de só entrar em silêncio.

Quem usa: sem trava de perfil própria na tela nem nas ações do servidor (só é checado login, não perfil). No menu, aparece para ADMIN, GERENTE, OPERADOR_SP e OPERADOR_PY.

Ações principais:

• Lista os lotes com aparelhos AGUARDANDO_CHEGADA — clique num lote para abrir (ou reabrir) a sessão de recebimento.
• Dentro da sessão: scanner de câmera ou digitação manual de IMEI para "bipar" cada aparelho que chegou.
• "Finalizar recebimento" — fecha a sessão (pede confirmação); tudo que ficou faltando vira divergência do tipo FALTA automaticamente.
• Em cada divergência: "Resolver" ou "Cobrar fornecedor" (marca como PENDENTE_FORNECEDOR).
• Lista "Recebimentos recentes" para reabrir uma sessão já iniciada (aberta ou fechada, para consulta).

Fluxo correto:

1. Escolha o lote que chegou na lista de "Lotes aguardando chegada".
2. Abrir a sessão fotografa (congela) a lista de IMEIs esperados naquele momento.
3. Bipe os aparelhos conforme conferem fisicamente contra a pilha — cada bipe move o aparelho automaticamente para CHEGADO_PY se ele era esperado.
4. Ao terminar, clique "Finalizar recebimento" — confirme; os IMEIs esperados e não bipados viram divergência FALTA.
5. Resolva as divergências pendentes (marcar como resolvida, ou pendente de cobrança do fornecedor, ou perda).

Se pular ou errar:

• Bipar um IMEI que já foi conferido nesta sessão é recusado como "duplicado".
• Bipar um IMEI que existe no sistema mas não pertence a este lote é registrado como divergência tipo SOBRA ("Bipado mas não esperado neste lote").
• Bipar um IMEI que não existe em lugar nenhum do sistema é registrado como ITEM_ERRADO ("IMEI não cadastrado").
• Tentar abrir uma sessão por LOTE para um lote que na verdade é recebido por CAIXA é bloqueado — a mensagem orienta a usar "Recebimento por caixa" em vez disso (evita gerar divergências falsas, já que os aparelhos chegariam pelas caixas, não soltos).
• Não finalizar a sessão deixa o que faltou sem virar divergência formal — a falta só é gravada no momento da finalização.

Detalhes e estados: status da sessão de recebimento: ABERTO → FECHADO. Tipos de divergência possíveis: FALTA, SOBRA, DANO, ITEM_ERRADO; status de resolução: PENDENTE_FORNECEDOR (default ao nascer de uma falta), RESOLVIDA, PERDA. O registro de "Recebido por" de cada aparelho usa exatamente o mesmo mecanismo interno do modo Avulso — é o único caminho de mudança de status/localização no sistema, o que garante que os mesmos critérios (aparelho VENDIDO é recusado, já recebido é tratado como duplicado) valem aqui também.

Recebimento avulso (bipe solto)

Pra que serve: a estação de scan mais simples e direta — bipa ou digita um IMEI e o aparelho muda de status na hora, sem conferência contra nenhuma lista. Foi desenhada para alto volume (otimizada para sessões de até 300 bipes), com contadores em tempo real e feedback sonoro/visual a cada bipe.

Quem usa: sem trava de perfil própria na tela nem na ação que processa o bipe (só é checado login). No menu, aparece para ADMIN, GERENTE, OPERADOR_SP e OPERADOR_PY.

Ações principais:

• Scanner de câmera e/ou campo de digitação manual — os dois sempre disponíveis, um não substitui o outro.
• Contadores da sessão: "Recebidos" (verde), "Duplicados" (amarelo), "Recusados" (vermelho) — zeram a cada vez que a página é recarregada (é contagem só da sessão atual do navegador, não histórico persistido).
• Lista dos últimos 20 bipes da sessão, com horário e resultado.
• Bipe sonoro de sucesso ou erro a cada tentativa.

Fluxo correto:

1. Abra a tela — o campo de IMEI já entra em foco automaticamente.
2. Bipe (câmera) ou digite o IMEI e confirme.
3. O sistema busca o aparelho pelo IMEI, dentro da empresa logada, e decide o resultado (ver abaixo).
4. O campo refoca sozinho depois de cada bipe, para manter o ritmo sem precisar clicar de novo.

Se pular ou errar (resultados possíveis de cada bipe):

• Recebido (ok): o aparelho estava AGUARDANDO_CHEGADA → muda para CHEGADO_PY na localização RECEPCAO_PY. Se o aparelho pertence a um lote, a mensagem já mostra o progresso do lote inteiro (ex.: "Lote #123: 45/100 recebidos").
• Duplicado: o aparelho já está em qualquer status diferente de AGUARDANDO_CHEGADA (ou já foi bipado nesta mesma sessão do navegador) — é recusado como "já recebido", mostrando o status atual.
• Vendido: aparelho com status VENDIDO é recusado explicitamente — é uma regra de imutabilidade do sistema (um aparelho vendido não pode ser "recebido de novo").
• Não encontrado: IMEI não existe cadastrado no sistema para a empresa logada.
• Erro: falha de conexão ou de autenticação — a mensagem avisa claramente que "o bipe NÃO foi registrado", para o operador não achar que passou quando não passou.

Detalhes e estados: se o aparelho recebido pertencia a uma remessa em trânsito entre EUA e PY que já estava sendo rastreada pela Central de Logística, o sistema também marca esse item como conferido lá (melhor esforço — mesmo que essa parte falhe, o recebimento em si já foi efetivado).

⚠️ Atenção: este é o modo com menos rede de proteção dos três — não há lista esperada para comparar, então uma remessa que chegou incompleta não gera nenhum alerta automático de falta. Use o Avulso só como exceção (aparelho isolado), nunca como rotina para remessas grandes.

Erros comuns e como evitar

1. Usar o Avulso quando existe lote ou caixa. Ele não gera divergência — uma remessa incompleta passa em branco. Sempre prefira Caixa ou Esteira quando houver lista/volume para conferir; o Avulso é para exceção (aparelho isolado, sem contexto de lote).
2. Misturar Caixa e Esteira no mesmo lote. O sistema bloqueia ativamente essa combinação (cadastrar caixa com esteira aberta, ou abrir esteira com caixa já cadastrada) porque os dois fluxos juntos produzem divergência falsa — se travar, use o botão de destravamento oferecido na própria tela em vez de tentar corrigir por fora do sistema.
3. Bipar dentro de uma caixa já liberada para teste. Depois que a caixa vira LIBERADA_PARA_TESTE, a contagem de custódia já foi travada e entregue à Triagem — bipar por cima não é aceito. Se precisar corrigir, use "Esvaziar" antes.
4. Não colar a etiqueta impressa no volume físico. Sem ela, a caixa perde a leitura rápida por código de barras/QR e o operador é forçado a digitar o código manualmente, mais lento e mais sujeito a erro.
5. Fechar a caixa sem conferir a falta. "Fechar caixa" com quantidade menor que o esperado pede confirmação, mas segue em frente mesmo assim — a falta fica registrada, então vale checar fisicamente antes de confirmar, não só clicar "sim" no aviso.
6. Assumir que o menu lateral é a trava de segurança. Neste módulo, só a tela "Receber mercadoria" (porta guiada) tem checagem de perfil de verdade; as demais telas (Avulso, Esteira, Caixas e suas subtelas) não verificam o perfil do usuário no servidor — o menu apenas esconde o link de quem não deveria usar, mas a URL direta funciona para qualquer usuário autenticado da mesma empresa.

⚠️ Atenção: isso não é uma falha exclusiva do Recebimento — é um padrão que se repete em vários módulos do sistema — mas vale saber que, aqui, a barreira real é a visibilidade do menu, não uma trava de permissão de verdade.

1. Reimprimir sem necessidade. Os botões de reimpressão de etiqueta/romaneio não geram impressão automática (diferente do primeiro cadastro/fechamento, que já dispara sozinho) — é intencional, para não desperdiçar etiqueta térmica à toa; confira antes de imprimir de novo.