# Design: Redesign de UX da execução da Alocação WMS (App do operador)

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

---

## Contexto

A tela de execução da Alocação WMS (`App/html/alocacaowms/item.php`, estado `em_andamento`) é usada pelo operador o dia inteiro, num coletor de hardware, sob pressa e com a mão ocupada. A versão atual empilha tudo numa só coluna rolável (progresso, 2 cards de scan, 2 inputs manuais sempre visíveis, sugestão, quantidade, confirmar, busca, 2 listas), gerando densidade vertical alta, redundância (card de scan + input manual para o mesmo dado) e o botão Confirmar no meio da tela.

Este redesign otimiza para o operador em operação **sem alterar a lógica de domínio** (bipagem, roteamento do scanner, alocação). É arquitetura de informação + layout (CSS) + glue de interação (JS).

## Decisões (do brainstorming)

| Decisão | Escolha |
|---|---|
| Entrada predominante | Coletor de hardware (bipa quase sempre) → **scan-first**, manual em divulgação progressiva. |
| Confirmação | **Botão fixo no rodapé**, toque manual (sem auto-confirmar). |
| Abordagem | Refinar no lugar (A) + rodapé fixo e lista rolável (C). Preserva a máquina de estados do `item.js`. |

## Nova arquitetura da tela (`em_andamento`)

Três regiões num container flex-column de altura cheia:

1. **Topo fixo:** header (voltar, título, refresh) + barra de progresso.
2. **Área de scan (flex: none, no topo do conteúdo):**
   - Card **Produto** (tocável). Placeholder "Bipe o produto". Toque revela o input manual do produto + foca; hint "ou selecione da lista abaixo ↓" atrelado a esse input.
   - **Sugerir código de barras** — logo abaixo do card de Produto, visível só quando há produto selecionado.
   - Card **Localização** (tocável). Placeholder "Bipe a localização". Toque revela o input manual da localização + foca.
   - **Quantidade** — só se `quantidadeObrigatoria`.
3. **Meio rolável (flex: 1, overflow-y: auto):** busca nos itens + lista de Pendentes + lista de Concluídos (recolhida).
4. **Rodapé fixo:** botão **Confirmar alocação** (full-width, sempre alcançável), desabilitado até produto + localização (+ qtd) prontos.

## Componentes / mudanças

### `App/html/alocacaowms/item.php`
- Reordenar a `wms-sugestao-area` para logo após o card de Produto (hoje está depois da Localização).
- Inputs manuais (`#input-manual-produto`, `#input-manual-localizacao`) passam a iniciar **ocultos** (a revelação é via tap, no JS).
- Trocar placeholders dos valores dos cards: "Aguardando leitura..." → `show('Bipe o produto')` / `show('Bipe a localização')`. Inputs manuais mantêm os textos atuais.
- Reestruturar o markup do `em_andamento` em 3 regiões (scan / lista / rodapé) para o layout flex.

### CSS (no `<style>` do `item.php`)
- `.app-conteudo` (ou wrapper equivalente do estado em_andamento) vira flex-column de altura cheia.
- Área de scan: `flex: none`.
- Bloco busca+listas: `flex: 1; overflow-y: auto`.
- Rodapé do confirmar: fixo no rodapé do container (sticky/fixed), com safe-area no mobile.
- Manual inputs: estado oculto por padrão; classe que o JS alterna para revelar.

### `App/html/alocacaowms/item.js`
- **Divulgação progressiva JÁ EXISTE** e fica intacta: inputs manuais já iniciam ocultos (`style="display:none"`), `_bindCamposTap` → `_toggleInputManual` já revela+foca ao tocar no card, e bipar já seleciona pelo scanner (`_processarCodigo` → `_buscarItemPorCodigo` → `_selecionarItemPorElemento`). Nada a mudar aqui.
- Única mudança (para #4): o objeto `txt` tem uma só string `aguardando` usada por `_limparProduto`/`_limparLocalizacao`. Separar em `aguardandoProduto`/`aguardandoLocalizacao` e usar a respectiva em cada limpar, para o texto de reset bater com o novo placeholder de cada campo.
- **Sem mudança** em: `_processarCodigo`, `_setProdutoCodigo`, `_setLocalizacao`, `_selecionarItemPorElemento`, `_atualizarBotaoConfirmar`, `_enviarSugestao`, `_bindConfirmar`. Mover o botão Confirmar no DOM não afeta o bind (é por id).

### i18n
- Novas strings PT (`show('Bipe o produto')`, `show('Bipe a localização')`) — auto-harvest gera as chaves (md5 do literal PT); preencher en/es nos 3 arquivos de linguagem.

## Lógica e testes

A mudança é predominantemente apresentacional (IA/CSS) + glue de DOM (tap → revelar input). **Não há lógica de domínio nova.** Verificação:
- `php -l` no `item.php`; `node --check` no `item.js`.
- Smoke manual no `dev-genesis` (coletor/responsivo): bipar produto+localização preenche os cards sem toque; tocar card revela input manual; sugestão aparece sob o produto ao selecionar; confirmar fixo no rodapé; lista rola sem empurrar header/rodapé.

Se durante a implementação surgir um helper puro (ex.: normalização de código), aplica-se TDD; não serão fabricados testes para glue de DOM (sem harness JS de DOM no repo).

## Critérios de aceite

1. Com coletor, bipar produto e localização preenche os dois cards sem nenhum toque (fluxo atual preservado).
2. (Já existente — preservar) Inputs manuais iniciam ocultos; tocar no card revela e foca o input; bipar com o coletor seleciona o item pelo bipe sem nenhum toque.
3. "Sugerir código de barras" aparece imediatamente abaixo do card de Produto, só quando há produto selecionado.
4. Botão Confirmar fica fixo no rodapé, sempre visível, e só habilita com produto + localização (+ qtd se exigida).
5. A lista de Pendentes/Concluídos é a única região que rola; header + área de scan + rodapé não saem da tela.
6. Placeholders dos cards dizem "Bipe o produto" / "Bipe a localização" (PT/EN/ES).
7. Estados `iniciar`, `concluido`, `erro` inalterados.

## Fora de escopo

- Refresh suave (substituir `location.reload()` por re-fetch da lista).
- Auto-confirmar.
- Qualquer mudança na lógica de bipagem/alocação ou nos Satélites/Laboratórios.