Levantamento Tecnico

• Solicitação - DasNutri
• BUSCA PREÇO AVANÇO: PASSO A PASSO DE CONFIGURAÇÃO

Solicitação - DasNutri

1) Preço de Atacado na Gôndola (Etiqueta)

Contexto

Hoje a etiqueta exibe apenas o preço de varejo. Necessário incluir preço de atacado (ou faixa/quantidade mínima) e ajustar o layout.

Escopo / O que será feito

• Backend

  • Expor campo(s) de atacado no endpoint de etiquetas (ex.: GET /api/etiquetas/lote?...).

  • Se não houver estrutura: criar tabela produto_preco_atacado (produtoId, qtdeMin, preco, vigenciaIni/Fim, lojaId opcional).

  • Regras de negócio: escolher o nível (empresa/loja), vigência, e fallback para varejo se não houver atacado válido.

• Frontend / Serviço de Etiquetas

  • Adicionar variável de template (ex.: ${precoAtacado}, ${qtdeMinAtacado}).

  • Criar novo layout (ZPL/PDF) com campo “ATACADO X por R$ Y”.

  • Visualização/preview no backoffice antes de imprimir (thumb em PDF).

• Integrações/DevOps

  • Feature flag “etiqueta.atacado” por loja.

  • Migração de dados de atacado (se necessário).

Critérios de conclusão (aceite)

• Etiqueta mostra claramente preço varejo e preço atacado + quantidade mínima.

• Layout aprovado (tamanho, legibilidade, contraste).

• Geração em lote e unitária funcionando.

• Testes: produtos com e sem preço atacado; validade expirada; múltiplas lojas.

Riscos/Dependências

• Dados de atacado indisponíveis → exigir carga inicial.

• Impressoras com memória limitada (ZPL antigos) → otimizar template.

Estimativa de Esforço (22h)

• Backend: 10h (modelo + endpoint + regras + migração simples)

• Frontend/Serviço Etiquetas: 8h (template, preview, parametrização)

• QA/Testes: 3h

• Docs/Alinhamentos: 1h

---

2) Identificação de Vendedor no Self-Checkout

Contexto

Não há mecanismo para identificar o vendedor na venda em self-checkout. Precisa permitir associação opcional do vendedor à transação.

Escopo / O que será feito

• Backend

  • Novo endpoint: POST /api/selfcheckout/sessao/vendedor (define/atualiza vendedor da sessão).

  • Validações: vendedor ativo, lotação/loja válida, permissões.

  • Persistir vendedorId no cabeçalho da venda e enviar no fluxo fiscal (quando aplicável).

• Frontend (Self-Checkout)

  • Fluxo de leitura do vendedor:

    • Modal de identificação no início da sessão ou botão “Vendedor” fixo.

    • Opções: leitura de código (ID/QR/CPF) ou busca por nome com autocomplete.

  • Sinalização visual quando houver vendedor selecionado; opção trocar/limpar.

• Relatórios/Backoffice

  • Expor vendedorId em consulta de vendas (lista/detalhe).

• Segurança/Telemetria

  • Auditoria: quem definiu/alterou o vendedor e quando.

Critérios de conclusão (aceite)

• Venda finalizada contém vendedorId.

• Alterar/limpar vendedor antes do fechamento funciona.

• Relatório/consulta exibe vendedor por venda.

• UX: fluxo não aumenta fricção do cliente (tempo de passagem).

Riscos/Dependências

• Variação de hardware (leitor de código) — padronizar eventos.

• Políticas de comissionamento (fora do escopo, mas contempladas no dado).

Estimativa de Esforço (20h)

• Backend: 8h (endpoints + persistência + auditoria mínima)

• Frontend: 9h (UI/fluxo + scanner + estados + acessibilidade)

• QA/Testes: 2h

• Docs/Alinhamentos: 1h

---

3) Exibição de Imagem do Produto no Self-Checkout

Contexto

Funcionalidade não existente. Requer servir imagens com boa performance e alterar UI do self-checkout para exibir miniatura/thumbnail durante a compra.

Escopo / O que será feito

• Backend

  • Novo serviço/rota de mídia: GET /api/produtos/{id}/imagem retornando URL assinada ou CDN pública.

  • Se necessário, processamento de imagens (thumb 256px/512px, WebP/JPEG) e metadados (hash/etag).

  • Expandir GET /api/produtos/{gtin} para incluir imageUrl, imageLastModified.

  • Cache-Control e ETag. Rate-limit básico.

• Frontend (Self-Checkout)

  • Alterar card do item para exibir thumbnail (fallback placeholder).

  • Pré-carregamento de imagem após leitura do código de barras.

  • Estratégias de cache no cliente (IndexedDB/CacheStorage quando PWA).

  • Tratamento de rede lenta (mostrar skeleton/loading).

• Backoffice

  • Campo para upload/gestão de imagem (mínimo viável) ou documentar fonte externa.

• Observabilidade

  • Métricas: taxa de acerto de cache, latência de imagem, % itens sem imagem.

Critérios de conclusão (aceite)

• Para itens com imagem, thumbnail aparece em ≤ 2,5s em rede normal.

• Sem imagem → placeholder consistente.

• Queda de rede não trava fluxo de vendas.

• Telemetria coletada e visível (painel básico).

Riscos/Dependências

• Volume e tamanho de imagens (custo/banda).

• Direitos de uso de imagens (responsabilidade do cliente ou catálogo proprietário).

Estimativa de Esforço (38h)

• Backend: 16h (serving, thumbs, cache, headers, ampliação de contrato)

• Frontend: 18h (UI, estados, cache offline, loading, testes manuais em dispositivo)

• QA/Testes: 3h

• Docs/Alinhamentos: 1h

---

4) Resumo das Estimativas (Total 80h)

Observação: as horas de QA incluem roteiro de teste manual e evidências. Se for desejado teste automatizado (e2e/UI), acrescente ~20–30% no item 2 e 3.

BUSCA PREÇO AVANÇO: PASSO A PASSO DE CONFIGURAÇÃO

Guia rápido para deixar o app coletor pronto para uso. Leva cerca de 5 minutos.

ANTES DE COMEÇAR, TENHA EM MÃOS

• O celular ou coletor Android com internet (Wi-Fi ou dados móveis)
• O arquivo do app (app-busca-preco.apk)
• O número da loja (exemplo: 1)
• O token de consulta fornecido pela Avanço
• (Opcional) A imagem com a logo do supermercado

PARTE 1: INSTALAR O APP

Passo 1. Copie o arquivo app-busca-preco.apk para o aparelho (cabo USB, e-mail, WhatsApp ou pendrive).

Passo 2. No aparelho, abra o arquivo (pelo app "Arquivos" ou "Downloads").

Passo 3. Se o Android avisar que a instalação de fontes desconhecidas está bloqueada, toque em "Configurações" e ative "Permitir desta fonte". Depois volte e toque em "Instalar".

Passo 4. Ao terminar, toque em "Abrir". O app aparece com o nome "Busca Preço Avanço".

PARTE 2: CONFIGURAR O APP

Passo 5. Na tela inicial, toque na engrenagem (canto superior direito).

Passo 6. Preencha os campos:

• Ambiente (prefixo da URL da API): já vem preenchido com https://api.udi.avancoinfo.com.br. Só mude se a Avanço pedir.

• Número da loja: o número da loja onde o aparelho vai ficar. Exemplo: 1.

• Token de consulta: cole o token recebido. Toque no olhinho ao lado para conferir se digitou certo.

• Tempo de exibição do preço (segundos): por quanto tempo o preço fica na tela. O padrão é 5. Aceita de 1 a 60.

• Logo do supermercado: opcional. Toque em "Escolher arquivo" e selecione a imagem (PNG, JPG, WEBP ou SVG, até 2 MB). Para tirar, toque em "Remover logo".

Passo 7. Toque em "Salvar". Vai aparecer a mensagem "Configurações salvas."

Passo 8. Toque na seta (canto superior direito) para voltar à tela de busca.

PARTE 3: LIBERAR A CÂMERA

Passo 9. Na tela inicial, toque no ícone da câmera ao lado do campo de busca.

Passo 10. O Android vai perguntar se o app pode usar a câmera. Toque em "Permitir" (ou "Enquanto o app estiver em uso").

Negou sem querer? Vá em Configurações do Android > Apps > Busca Preço Avanço > Permissões > Câmera e escolha "Permitir".

PARTE 4: FAZER O PRIMEIRO TESTE

Passo 11. Aponte a câmera para o código de barras de um produto. O app lê sozinho.

Passo 12. Outra opção é digitar o código no campo e apertar Enter. Se o coletor tiver leitor físico, é só bipar o produto.

Passo 13. O resultado aparece na tela:
• Descrição do produto e código de barras
• Preço promocional (só aparece se o produto estiver em promoção)
• Preço normal
• Uma barra de tempo que esvazia e fecha o card sozinha

Se o preço apareceu, está tudo pronto.

SE ALGO DER ERRADO

• "Aplicação não configurada" ou "Número da loja não configurado": volte na engrenagem e preencha os campos.

• "Não foi possível conectar à API de preços": confira se o aparelho está com internet e se o campo Ambiente está correto.

• "Falha ao consultar a API (HTTP 401 ou 403)": o token está errado ou venceu. Confira se colou sem espaços ou peça um novo.

• "Produto não encontrado": o código pode estar errado ou o produto não existe na base. Tente de novo.

• "Produto não encontrado para a loja X": o produto não tem preço cadastrado para essa loja. Confira o número da loja nas configurações.

• "Permissão de câmera negada": libere a câmera como explicado na Parte 3.

• "Leitura por câmera não disponível neste dispositivo": use a digitação ou o leitor físico.

DICA FINAL

Depois de configurado, o app guarda tudo no aparelho. Não precisa configurar de novo ao fechar ou reiniciar. Para mudar a loja, o token ou a logo, é só voltar na engrenagem.

Dúvidas? Entre em contato com o suporte da Avanço: https://login.avancoinfo.com.br