Pular para o conteúdo principal

Matérias-primas

Homologação da rota /materias-primas e fluxos ligados (cadastro MP em /produtos/novo?tipo=materia-prima, detalhe/edição em /produtos/:id e /produtos/:id/editar).
Nota: os itens abrangem o comportamento esperado do produto; incluem cenários ainda não concluídos na UI ou na integração — servem também como registo de pendências de implementação. Marque cada linha ao validar ou ao fechar uma pendência.

Cabeçalho e navegação​

  • Título e descrição — “Matérias Primas” e subtítulo de gestão/controlo de stock visíveis e corretos em desktop e mobile.
  • Nova Matéria Prima — Botão leva a /produtos/novo?tipo=materia-prima e o formulário abre com tipo matéria-prima pré-definido.
  • Permissão de acesso — Apenas utilizadores com permissão de stock (StockView) acedem à rota; sem permissão, fluxo de negação coerente com a app.

Resumo (cartões superiores)​

  • Total de itens — Mostra o total global de MP da API de produtos (paginação), não só a página corrente.
  • Estoque baixo e crítico — Contagens refletem todo o universo de matérias-primas segundo as regras de negócio (mínimo, percentagens, etc.).
    Hoje: os contadores “Estoque Baixo” e “Crítico” são calculados só sobre os itens da página atual; homologar se aceitável ou registar correção para agregado global. (pendência / revisão)
  • Estados de carregamento — Enquanto carrega, exibe “—” nos números sem layout partido.

Busca​

  • Campo de busca — Placeholder “Buscar por nome, código ou categoria…”; alteração reinicia a página para 1.
  • Envio do termo à API — O termo é passado como searchTerm na listagem de produtos filtrada por productTypeId = matéria-prima.
  • Busca vazia — Sem termo, lista o conjunto completo (por página).
  • Debounce (opcional) — Se no futuro existir debounce, validar atraso e menos pedidos; hoje não há debounce explícito na página.

Listagem em cartões​

  • Dados por item — Nome (link), código, badge de estado (Normal / Estoque baixo / Crítico), categoria, estoque atual + unidade, mínimo (ou “—”), fornecedor.
  • Regra de estado — Crítico abaixo do mínimo; baixo entre mínimo e 120% do mínimo; normal caso contrário ou sem mínimo definido (conforme deriveStatus no hook).
  • Merge produtos + saldos — Estoque e mínimo vêm de /api/stock/product-balances cruzado com /api/products (tipo MP); itens sem saldo assumem stock 0.
  • Fornecedor — Exibe fornecedor real quando existir vínculo ou catálogo.
    Hoje: texto fixo “-” para todos. (pendência de implementação)
  • Categoria — Reflete productTypeName ou equivalente; validar rótulo para MP.
  • Responsividade — Grelha e botões adaptam (textos “Ver”/“Editar”/“Mov.” em mobile).

Paginação​

  • Controles — Anterior, seguinte, ir para página e texto “X–Y de Z” alinhados ao total da API de produtos.
  • Tamanho de página — 50 itens por página (ou valor atual no código).

Estado vazio​

  • Sem resultados com filtros/busca — Mensagem clara e ação sugerida (ex.: limpar busca ou cadastrar MP).
    Hoje: lista pode ficar vazia sem cartão dedicado. (pendência de implementação — UX vazio)
  • Nenhuma MP no sistema — Mesmo tratamento de empty state.

Ações por item​

  • Ver detalhes — Navega para /produtos/{id}; detalhe reconhece MP e mostra “Matéria Prima”, voltar para /materias-primas.
  • Editar — Navega para /produtos/{id}/editar sem query tipo; formulário carrega MP e tipo bloqueado em edição.
  • Movimentar — Abre fluxo de movimentação de stock (entrada/saída/transferência) contextual ao produto.
    Hoje: botão sem Link/onClick. (pendência de implementação)

Erros e resiliência​

  • Erro ao carregar produtos — Mensagem “Não foi possível carregar as matérias primas…”.
  • Erro ao carregar saldos — Utilizador é informado ou lista degrada de forma controlada (ex.: só dados de produto sem stock).
    Hoje: isError só reflete falha de produtos; falha só em saldos pode passar despercebida. (pendência de implementação)
  • Sessão / token — Comportamento consistente com o restante da app em 401/403.

Filtros e ordenação (escopo alargado)​

  • Filtro por estado de stock — Filtrar só baixo/crítico na listagem. (pendência de implementação — se desejado)
  • Filtro por fornecedor — Quando fornecedor existir no modelo. (pendência de implementação)
  • Ordenação escolhível — Por nome, código, stock, criticidade.
    Hoje: ordenação fixa por nome ascendente na API.
  • Exportação — CSV/Excel da lista de MP. (pendência de implementação — se desejado)

Integração com cadastro de produto (MP)​

  • Criar MP e voltar — Após criar matéria-prima, redireciona para /materias-primas (não para lista de produtos acabados).
  • Qualidade no cadastro — Aba e vínculos com tipos de análise para MP, quando aplicável ao negócio.

Performance e consistência​

  • Saldos em grande volume — product-balances com PageSize=500: validar se cobre todos os produtos ou se há risco de MP fora da primeira página de saldos.
    Possível pendência se existirem >500 produtos com saldo. (revisão técnica)

Regressão​

  • Caracteres especiais — Nome/código com acentos na lista e nos links.
  • Valores decimais de stock — Exibição coerente com unidade e arredondamentos.

Use esta página em revisões de sprint: itens em pendência podem ser copiados para o backlog até serem implementados e homologados.