# Design: AlocacaoWms — Busca Manual de Produto + Sugestão de Código de Barras

**Data:** 2026-06-18
**Status:** Aprovado

---

## Contexto

A missão `ALOCACAO_WMS` (tipo ID 14) permite que operadores registrem a localização física de produtos no armazém, bipando produto + localização WMS. Quando o código de barras físico está ilegível ou ausente, o operador precisa de uma forma alternativa de identificar o produto e, opcionalmente, sugerir um código de barras para aquele produto.

---

## Escopo

### Dentro do escopo

1. **UX de seleção manual**: deixar claro ao operador que ele pode tocar em um item da lista para selecioná-lo quando não conseguir bipar.
2. **Sugestão de código de barras inline**: ao selecionar um produto (via scan ou toque), exibir opção de sugerir um código de barras usando o sinal `SugestoesCodigoBarras` existente.

### Fora do escopo

- Novo endpoint ERP para múltiplos códigos de barras (usar fluxo existente SugestoesCodigoBarras → AjusteDados → ERP).
- Alterações no fluxo de aprovação/AjusteDados.
- Qualquer mudança em outras missões (Separação, Carregamento, etc.).

---

## Feature 1: UX de Seleção Manual

### Problema

O operador que não consegue bipar o produto não sabe intuitivamente que pode tocar um card da lista para selecioná-lo. A busca existente (`#wms-busca-item`) e a seleção por toque já funcionam, mas não há indicação visual de que esse é o fluxo de "modo manual".

### Solução

Quando o operador toca no campo Produto enquanto ele está vazio, além de exibir o input manual de código existente, adicionar uma linha de hint:

> "ou selecione da lista abaixo ↓"

Clicar nesse hint faz scroll suave até a seção de pendentes e aplica um pulso visual breve na lista (bordas piscam uma vez) para chamar atenção.

**Nenhuma lógica de backend alterada.** Apenas JS cosmético em `item.js`.

---

## Feature 2: Sugestão de Código de Barras

### Fluxo

```
Produto selecionado (scan ou lista)
  → link "Sugerir código de barras" aparece abaixo do campo Produto
  → operador clica → expande input inline + botão "Sugerir"
  → operador digita ou bipa o código
  → AJAX → SugestoesCodigoBarras sinal (sinalGxData=sugerir)
  → toast sucesso/erro
  → campo de alocação (localização) permanece intocado
  → operador prossegue com a alocação normalmente
```

As duas ações (sugestão e alocação) são completamente independentes. O operador pode:
- Só alocar (sem sugerir)
- Sugerir e depois alocar
- Sugerir sem alocar (produto sem localização ainda)

### Backend — única mudança

**Arquivo:** `componentes/Missoes/Logistica/sinais/SugestoesCodigoBarras/Validators/SugerirCodigoBarrasValidator.php`

**Linha 43** — adicionar `TipoMissao::ALOCACAO_WMS->id()` no array `$tiposPermitidos`:

```php
// antes
$tiposPermitidos = [TipoMissao::SEPARACAO->id(), TipoMissao::CARREGAMENTO->id()];

// depois
$tiposPermitidos = [
    TipoMissao::SEPARACAO->id(),
    TipoMissao::CARREGAMENTO->id(),
    TipoMissao::ALOCACAO_WMS->id(),
];
```

O restante do validator permanece igual, incluindo a constraint `!empty($produto->codigo_barras)` (sugestão só é permitida para produtos sem código primário cadastrado — comportamento correto para o contexto WMS onde produtos chegam sem EAN).

### Frontend — UI inline

**`item.php`**: abaixo do campo Produto (`.wms-scan-field#campo-produto`), adicionar um elemento oculto `#wms-sugestao-area` que contém:
- Link "Sugerir código de barras" (visível quando produto selecionado)
- Input de código (`#wms-sugestao-input`) — aceita scan de hardware via input fantasma ou digitação manual
- Botão "Sugerir" (`#btn-sugestao-confirmar`)
- O input só fica visível após clicar no link

**`item.js`**: nova seção `_bindSugestao()`:
- Mostra/oculta `#wms-sugestao-area` conforme `estado.produtoId > 0`
- Ao confirmar: valida `codigo_sugerido.length >= 6` (regra do validator)
- AJAX para o sinal SugestoesCodigoBarras:

```js
payload = {
    sinalGxData:      'sugerir',
    missao_origem_id: missaoId,
    produto_id:       estado.produtoId,
    codigo_sugerido:  codigoSugerido,
}
```

- Sucesso: toast verde "Código sugerido com sucesso!" + limpa o input de sugestão
- Erro: toast vermelho com `resposta.erro`
- O estado de alocação (`estado.produtoCodigo`, `estado.localizacaoCodigo`) não é alterado

### AJAX — roteamento

A chamada vai para o sinal `SugestoesCodigoBarras` via Galaxia. O PHP do handler AlocacaoWms não precisa de alterações — a sugestão chama o sinal diretamente.

---

## Arquivos alterados

| Arquivo | Tipo de mudança |
|---|---|
| `componentes/Missoes/Logistica/sinais/SugestoesCodigoBarras/Validators/SugerirCodigoBarrasValidator.php` | +1 tipo permitido (ALOCACAO_WMS) |
| `componentes/Missoes/Logistica/sinais/App/html/alocacaowms/item.php` | UI: hint de seleção manual + área de sugestão inline |
| `componentes/Missoes/Logistica/sinais/App/html/alocacaowms/item.js` | JS: hint scroll + lógica de sugestão AJAX |

**Sem migrations. Sem novos Laboratorios. Sem novas Sondas.**

---

## Critérios de aceite

1. Quando o operador toca no campo Produto (vazio), aparece o hint "ou selecione da lista abaixo ↓".
2. Clicar no hint rola a tela até a lista e pulsa visualmente os cards.
3. Quando um produto está selecionado, o link "Sugerir código de barras" aparece abaixo do campo.
4. O link expande um input + botão "Sugerir".
5. Submeter um código válido (≥6 chars, produto sem EAN, missão ativa) retorna `ok: true` com toast de sucesso.
6. Erros do validator retornam toast com a mensagem específica do backend.
7. A sugestão não interfere com o campo de localização nem com o botão de confirmar alocação.
8. Após sugestão bem-sucedida, o input de sugestão é limpo; a alocação pode prosseguir normalmente.