# Alocação de Localização WMS — Spec

## Contexto e problema
Hoje o sistema só conhece a posição de um produto em termos grosseiros (andar 1 / andar 2), sem endereçamento físico detalhado de armazém (corredor/prateleira/posição). Sem esse registro confiável, operadores procuram itens manualmente, o que torna a separação e o carregamento mais lentos e sujeitos a erro. A feature cria um fluxo de missão para registrar e manter a localização WMS de cada produto, reaproveitando a infraestrutura de missões logísticas e bipagem já existente, e propagando o dado para ERP e base WMS.

## Escopo
- ✅ Faz parte:
  - Novo tipo de missão "Alocação WMS" criada por um gestor, selecionando produtos e responsável (ou deixando disponível para captura por qualquer operador habilitado).
  - Execução pelo operador no aplicativo (sinal `App`), bipando código de localização WMS e código do produto, em qualquer ordem.
  - Validação no momento da confirmação: produto pertence à missão, localização WMS existe na base de validação, missão ativa, operador com permissão.
  - Lista de produtos pendentes na missão com filtros (categoria, região, marca, código, descrição, status).
  - Execução sem sequência obrigatória: operador escolhe qualquer produto, executa parcialmente e retoma depois.
  - Controle de status da missão refletindo o ciclo de vida (criada/disponível → em andamento → parcialmente concluída → concluída/cancelada).
  - Registro de origem da leitura (código de barras vs manual) por alocação.
  - Propagação da localização confirmada para Genesis (TMS), ERP e base WMS, com indicação de pendência/sucesso de cada integração.
- ❌ Fora de escopo:
  - Substituir ou alterar os campos de andar 1 e andar 2 existentes (continuam intactos).
  - Movimentação de estoque — a feature só registra localização, não transfere/abate quantidade.
  - Fluxos de retorno ou devolução de localização.
  - Gerenciamento de layout de armazém (criar/editar corredores, prateleiras e posições via UI). A base de localizações WMS é apenas consultada para validação.

## User stories

### US1 — Gestor cria missão de Alocação WMS
**Como** gestor logístico **eu quero** criar uma missão de Alocação WMS selecionando produtos e responsável **para** organizar quem vai endereçar quais itens no armazém.

**Critérios de aceite:**
- AC1.1: O gestor consegue escolher "Alocação WMS" como tipo de missão na tela de criação.
- AC1.2: O gestor consegue selecionar um ou mais produtos para a missão; cada produto entra como item pendente.
- AC1.3: O gestor pode atribuir um operador responsável OU deixar a missão disponível para captura por qualquer operador habilitado.
- AC1.4: Ao criar, a missão nasce em status equivalente a "criada/disponível" e seus itens em status pendente.
- AC1.5: Uma missão sem nenhum produto selecionado não pode ser criada (validação bloqueante com mensagem).

### US2 — Operador visualiza e filtra produtos pendentes
**Como** operador de armazém **eu quero** abrir a missão no app e ver a lista de produtos pendentes com filtros **para** localizar rapidamente o item que vou endereçar.

**Critérios de aceite:**
- AC2.1: A lista mostra, por produto, ao menos: código, descrição e status do item na missão.
- AC2.2: A lista pode ser filtrada por categoria, região, marca, código e descrição.
- AC2.3: A lista pode ser filtrada por status do item (ex.: pendente, concluído).
- AC2.4: Itens já concluídos ficam visualmente distintos dos pendentes.
- AC2.5: A ordem de execução é livre — o operador pode iniciar por qualquer produto da lista.

### US3 — Operador registra a localização bipando dois códigos
**Como** operador de armazém **eu quero** bipar o código de localização WMS e o código do produto, em qualquer ordem, e confirmar **para** registrar onde o item está fisicamente.

**Critérios de aceite:**
- AC3.1: O operador pode bipar primeiro a localização e depois o produto, ou o inverso, sem ordem obrigatória.
- AC3.2: A confirmação só é habilitada após os dois códigos estarem informados.
- AC3.3: Cada leitura registra a origem (código de barras ou entrada manual).
- AC3.4: Bipar um produto que não pertence à missão é rejeitado com mensagem clara, sem concluir o item.
- AC3.5: Bipar uma localização WMS que não existe na base de validação é rejeitado com mensagem clara, sem concluir o item.
- AC3.6: Ao confirmar com sucesso, o item do produto passa para concluído na lista e some/fica marcado entre os pendentes.

### US4 — Sistema valida regras de negócio na confirmação
**Como** gestor logístico **eu quero** que o sistema valide a alocação antes de salvar **para** garantir que só localizações válidas e dentro do escopo da missão sejam registradas.

**Critérios de aceite:**
- AC4.1: Confirmação é bloqueada se a missão não estiver ativa (ex.: cancelada/concluída).
- AC4.2: Confirmação é bloqueada se o operador não tiver permissão para executar a missão.
- AC4.3: O produto confirmado precisa pertencer à missão.
- AC4.4: A localização WMS confirmada precisa existir na base de validação.
- AC4.5: Toda confirmação rejeitada exibe o motivo específico e não altera o estado do item.

### US5 — Sistema propaga a localização para ERP e WMS
**Como** integrador (ERP/WMS externo) **eu quero** receber a localização confirmada **para** manter o endereçamento sincronizado entre os sistemas.

**Critérios de aceite:**
- AC5.1: Toda alocação confirmada gera o envio da localização para ERP e para a base WMS.
- AC5.2: Cada alocação mantém o estado de integração com ERP e com WMS (pendente, enviado/sucesso, falha).
- AC5.3: Uma falha de integração fica visível/registrada e não some silenciosamente.
- AC5.4: O payload enviado ao ERP usa o identificador de produto compatível com o ERP legado (alinhar com `importacao_id` ↔ `codigomd5`).

### US6 — Missão reflete progresso e conclusão
**Como** gestor logístico **eu quero** acompanhar o status da missão conforme os itens são alocados **para** saber se a alocação ainda está pendente, parcial ou concluída.

**Critérios de aceite:**
- AC6.1: Ao primeiro item alocado, a missão passa para "em andamento".
- AC6.2: Com parte dos itens alocados e parte pendente, a missão reflete estado "parcialmente concluída".
- AC6.3: Quando todos os itens estão alocados, a missão passa para "concluída".
- AC6.4: A missão pode ser cancelada; uma missão cancelada não aceita novas alocações.
- AC6.5: O operador pode sair e retomar a missão mais tarde sem perder o progresso já registrado.

## Personas envolvidas
| Persona | Papel | Ponto de contato com a feature |
|---|---|---|
| Gestor logístico | Cria a missão de Alocação WMS, define produtos e responsável, acompanha status | Tela de criação/gestão de missões (Central ou Armazém — ver Dúvidas) |
| Operador de armazém | Executa a missão, bipa localização e produto, confirma alocação | Aplicativo (sinal `App`) — execução de missão |
| ERP / WMS externo | Recebe a localização registrada após cada alocação confirmada | Integração via hook (consumidor do dado, não opera UI) |

## Dados / entidades-chave (alto nível)
- **Missão de Alocação WMS** — instância de missão logística do novo tipo; tem status, responsável e itens.
- **Item da missão (produto pendente)** — produto a ser endereçado; tem status próprio (pendente/concluído).
- **Produto** — código, descrição, categoria, marca, região (usados em filtros e identificação).
- **Localização WMS** — código de endereçamento físico (corredor/prateleira/posição) consultado para validação.
- **Alocação** — registro do vínculo produto ↔ localização, com: operador, data/hora, quantidade (ver Dúvidas), origem da leitura, e estados de integração ERP/WMS.

## Regras de negócio
1. A alocação só registra localização física; nunca movimenta nem abate estoque.
2. A alocação não altera os campos de andar 1 e andar 2 do produto.
3. Um produto só pode ser alocado dentro de uma missão à qual ele pertence.
4. A localização WMS bipada precisa existir na base de validação para a alocação ser aceita.
5. A confirmação exige os dois códigos (localização e produto), em qualquer ordem.
6. Só missões ativas aceitam novas alocações; missões canceladas ou concluídas não aceitam.
7. O operador precisa ter permissão para executar a missão.
8. A execução não tem sequência obrigatória entre itens; pode ser parcial e retomável.
9. Toda alocação confirmada deve ser propagada para ERP e WMS, com rastreio de estado de integração.
10. A origem da leitura (código de barras ou manual) é registrada em cada alocação.

## Métricas de sucesso
- Percentual de produtos do catálogo (ou do escopo das missões) com localização WMS registrada cresce ao longo do tempo.
- Percentual de missões de Alocação WMS concluídas vs criadas.
- Percentual de alocações com integração ERP e WMS confirmada (sem pendência/falha residual).
- Redução do tempo de localização de itens na separação/carregamento após adoção (medida operacional, se houver baseline).

## Dúvidas em aberto
- [ ] **Localizações por produto**: um produto pode ter mais de uma localização WMS (estoque dividido) ou exatamente uma? Muda escopo (lista de posições por item vs valor único/sobrescrita). *Assunção atual até decisão: uma localização efetiva por produto, bipar nova substitui a anterior.*
- [ ] **Quantidade na alocação**: o PRD valida "não ultrapassar o esperado", mas sendo registro de localização (sem movimentar estoque), a quantidade é obrigatória e bloqueante, apenas informativa, ou não entra no fluxo? Afeta os ACs de US3/US4.
- [ ] **Re-alocação**: o que ocorre ao bipar um produto que já tem localização de missão anterior — sobrescreve direto, exige confirmação, ou esse produto fica fora de escopo da missão? Afeta US3/US6.
- [ ] **Integração síncrona vs assíncrona**: a confirmação espera ERP/WMS aceitarem (síncrona) ou confirma no Genesis e sincroniza depois (assíncrona)? Impacta a experiência do operador em AC5.x.
- [ ] **Origem da criação da missão**: criada pelo Central, pelo Armazém, ou ambos? O PRD deixa explícito para o techplan; registrado aqui apenas para alinhamento de produto.
- [ ] **Entrada manual de código**: o PRD cita origem "manual" como alternativa ao código de barras — a digitação manual é permitida para ambos os códigos, só para a localização, ou é apenas fallback de exceção? Afeta AC3.3.