# API de Alocação de Localização WMS — PRD bruto

> Este é o ponto de entrada do pipeline `/genesis-feature`.

## Problema / dor

O sistema já sabe onde um produto está em termos de andar 1 e andar 2, mas não possui localização física detalhada (endereçamento WMS). Isso dificulta a operação no armazém: operadores precisam procurar produtos manualmente, sem um registro confiável de onde cada item está na prateleira/corredor/posição.

## Quem usa

- **Gestor logístico**: cria a missão de alocação, define quais produtos precisam ter localização registrada e associa responsável.
- **Operador de armazém**: executa a missão pelo aplicativo TMS (separação/carregamento), bipando código de localização WMS e código do produto.
- **ERP / WMS externo**: recebe a localização registrada via integração após cada alocação confirmada.

## O que precisa fazer (alto nível)

- Gestor cria missão de tipo "Alocação WMS" selecionando produtos, quantidades e responsável (ou deixa disponível para captura).
- Operador abre missão no app, vê lista de produtos pendentes com filtros (categoria, região, marca, código, descrição, status).
- Operador bipa código de localização WMS e código do produto (em qualquer ordem).
- Após os dois códigos informados, confirma a alocação.
- Sistema valida: produto pertence à missão, localização WMS existe, quantidade não ultrapassa o esperado, missão está ativa, operador tem permissão.
- Ao confirmar, salva localização no Genesis (TMS), no ERP e na base WMS.
- Missão tem controle de status: Criada → Disponível → Em andamento → Parcialmente concluída → Concluída / Cancelada.
- Execução sem sequência obrigatória: operador pode escolher qualquer produto da lista, executar parcialmente e retomar depois.

## O que NÃO precisa fazer (escopo negativo)

- Não substitui os campos de andar 1 e andar 2 já existentes.
- Não inclui movimentação de estoque (apenas registro de localização).
- Não cobre fluxos de retorno ou devolução de localização.
- Não é um módulo de gerenciamento de layout de armazém (não cria corredores/prateleiras via UI — apenas valida se a localização bipada existe).

## Restrições conhecidas

- Deve reaproveitar a infraestrutura de missões já existente (`missao_logistica`, `TipoMissao`, `MissoesBipagem`, padrão de Handlers/Strategies).
- Integração com ERP usa o padrão de Hook Strategy já em uso (`HookSincronizadorBase`).
- O aplicativo é o sinal `App` em `Missoes/Logistica/sinais/App`.
- Localização WMS precisa de tabela própria (`wms_localizacoes`) para validação no momento da bipagem.
- A missão pode ser criada pelo `Central` ou `Armazem` — a definir no techplan.

## Inspirações / referências

- `TipoMissao::INVENTARIO` + `InventarioExecucaoStrategy` — missão sem sequência obrigatória, mais próxima do fluxo desejado.
- `MissoesBipagem::biparItem` — base para `alocarLocalizacao`.
- `componentes/Missoes/Logistica/sinais/App/Handlers/InventarioHandler.php` — template para o novo handler.
- `componentes/Constelacoes/Logistica/MissaoLogistica/Strategies/Execucao/` — onde entra `AlocacaoWmsExecucaoStrategy`.
- PRD anterior: `PRD/bipagem-codigo-barras-fator/` — mesmo padrão de bipagem com dois códigos.

## Estrutura de dados mínima por alocação

- ID da missão, ID do produto, código do produto, descrição do produto
- Código da localização WMS
- Quantidade alocada
- Operador responsável, data/hora da alocação
- Status da alocação
- Origem da leitura (código de barras, manual)
- Flags de integração ERP e WMS

## Notas

- `missao_logistica_itens.dados_adicionais JSONB` pode absorver `codigo_localizacao_wms`, `origem_leitura`, `integrado_erp` sem migration obrigatória — a definir no techplan se vale uma coluna dedicada.
- Próximo ID disponível no enum `TipoMissao` é 13.
- O operador pode bipar localização primeiro e produto depois, ou vice-versa — fluxo de dois passos sem ordem obrigatória.