# ENG-1403 — Quantidade em entrada na posição de estoque

## Contexto

O dashboard **Posição de Estoque** apresenta o saldo físico armazenado, as
quantidades reservadas por requisições e o saldo disponível. A análise do
comentário mais recente no card ENG-1403 identificou que produtos já recebidos
em uma entrada, mas ainda não armazenados, não aparecem no cálculo.

O requisito associado pede visibilidade da posição operacional de estoque, sem
perder a distinção entre o que já está armazenado e o que ainda está em
processo de entrada.

## Decisão

Adicionar uma coluna separada **Em entrada**. O contrato da API usará
`input_stock_amount`, enquanto `stock_amount` continuará representando somente
o estoque físico armazenado.

O saldo disponível será calculado assim:

```
max(estoque_fisico + em_entrada - reservado, 0)
```

## Fonte e regras de cálculo

- A quantidade em entrada virá dos registros `items` vinculados a um `StockIO`
  de tipo entrada no setor Almoxarifado.
- Serão excluídas entradas concluídas, canceladas ou com falha de sincronização.
- A quantidade já separada para saída será deduzida do item da entrada; portanto
  o dashboard exibirá apenas o saldo ainda pendente de armazenamento.
- Produtos que existam somente em entrada também devem constar no resultado.
- A regra deve reutilizar a semântica já adotada em
  `StockIOProductMissingAmountService`, evitando divergência entre a posição de
  estoque e o saldo usado no fluxo operacional de saída.

## Alternativas consideradas

1. **Selecionada:** expor uma coluna separada com o saldo pendente real da
   entrada. Mantém transparência operacional e evita dupla contagem.
2. Somar diretamente produtos de entradas ativas. Foi descartada porque pode
   contar quantidades já separadas para uma saída.
3. Somar entradas no estoque físico. Foi descartada porque apagaria a distinção
   entre saldo armazenado e saldo em processamento.

## Alterações previstas

### Backend

- Estender `ProductAvailabilityService` com uma subconsulta agregada para
  `input_stock_amount`.
- Incluir esse valor na seleção de produtos e no cálculo de
  `available_stock_amount`.
- Atualizar `WarehouseStockPositionReportService` para que os totais de
  disponível/crítico usem a nova disponibilidade.
- Manter a rota e o recurso atuais: `GET
  /api/v1/report/warehouse/stock-position` receberá somente o novo campo por
  produto; não haverá migração nem nova rota.

### Frontend

- Inserir a coluna ordenável **Em entrada** entre **Estoque físico** e
  **Reservado** em `WarehouseStockPositionDashboard`.
- Adaptar a grade da tabela para a coluna adicional, mantendo rolagem horizontal
  em telas menores.
- Atualizar os helpers e seus testes para ordenar `input_stock_amount`.
- Preservar os cards existentes; **Disponíveis** refletirá a fórmula aprovada.

## Critérios de aceite e testes

- Uma entrada pendente integral aparece em **Em entrada** e aumenta o
  disponível.
- Uma entrada parcialmente separada exibe apenas o saldo pendente.
- Entradas concluídas, canceladas e com falha de sincronização não são contadas.
- Um produto apenas em entrada aparece na tabela.
- O cálculo combinado físico + entrada − reservado não pode resultar em saldo
  disponível negativo.
- A nova coluna é renderizada e ordena em ambos os sentidos no frontend.

## Fora do escopo

- Alterar o estoque físico persistido.
- Alterar regras de reserva de requisição ou o fluxo de armazenamento.
- Criar filtros, rota ou cards novos além da coluna e dos cálculos necessários.