# ENG-3113 — Inventário manual com abrangência do WMS

**Status:** desenho aprovado em 2026-11-05, por seções, antes da implementação.
**Issue:** https://linear.app/soelx/issue/ENG-3113/cadastrar-inventario-manual-com-abrangencia-do-wms

## Objetivo

Permitir criar, editar, salvar e reabrir inventários gerais ou cíclicos manuais como rascunhos compartilhados. Usar os cadastros atuais do WMS, sem fixture do protótipo, persistência de inventário no navegador ou consulta e alteração de saldos do ERP.

Esta etapa entrega cadastro e abrangência. Não inicia inventários, não gera contagens e não altera estoque.

## Contexto e decisões confirmadas

- O depósito ERP **004 corresponde a todos os endereços da Expedição**, representada por `SectorEnum::EXPEDITION` (`2`). Não há recorte adicional por rua, raiz ou posição.
- O catálogo do inventário contém todos os produtos vinculados a pelo menos um endereço da Expedição, **sem filtrar por saldo**. O cadastro global de produtos não define, sozinho, a elegibilidade.
- O inventário geral começa com todo esse catálogo selecionado e permite revisar a seleção. O cíclico manual começa vazio.
- O cadastro terá **Dados → Abrangência → Revisão**, sem exigir participantes, distribuição ou configuração de contagens para salvar.
- Selecionar um produto inclui todos os seus endereços na Expedição. Um grupo de endereço é um facilitador para selecionar produtos, não um limite para sua contagem.
- Reaproveitar componentes existentes somente se preservarem exatamente o comportamento definido pelo protótipo, dentro deste recorte aprovado. Não forçar encaixes ou alterar contratos compartilhados indevidamente.
- A funcionalidade será implementada depois do planejamento; este documento não autoriza antecipar a execução.

## Repositórios e branches

Criar `feature/eng-3113` separadamente nos dois repositórios:

| Repositório | Base aprovada | Commit da base no planejamento |
| --- | --- | --- |
| `rex-front` | `eng-2966` | `67305ddb8fd153385832198c614d216d4cc01dae` |
| `rex-back` | `main` | `a6b49a5f412709ce5285f082db44cfd7b60d06f6` |

O protótipo não está integrado à `main` do frontend. O repositório `Rex-Estoque` não será alterado nesta atividade. Este documento, mantido em `rex-back/docs/plans/`, é a referência comum aos dois repositórios.

## Abordagens consideradas

1. **Reaproveitar a interface com persistência relacional no backend — escolhida.** Preserva o trabalho visual e oferece integridade dos vínculos, compartilhamento e uma base para as próximas entregas.
2. **Persistir o estado completo como JSON.** Reduz a adaptação inicial, mas mantém acoplamentos do protótipo e dificulta validar vínculos e consultar a abrangência.
3. **Construir outro cadastro independente.** Isola as simulações, mas duplica interface e exige mais retrabalho.

A opção escolhida reaproveita componentes visuais, não o store local, a fixture ou as transições simuladas.

## Arquitetura e persistência

Criar um contexto de inventário no backend Laravel, seguindo a organização existente de Models, DTOs, Requests, Policies, Resources e serviços de domínio.

A persistência relacional contempla:

- **Cabeçalho do inventário:** identificador e número gerados no servidor, tipo geral/cíclico, modalidade manual, nome, descrição opcional, prazo, setor, depósito, situação, versão e autoria/data de criação e última alteração.
- **Produtos selecionados por inventário e depósito:** vínculos únicos aos produtos reais do WMS, sem duplicar cadastros ou armazenar o estado inteiro do protótipo.

Criar e editar sempre mantém a situação **rascunho**. Essas operações não iniciam contagens, não bloqueiam movimentações e não dependem de participantes ou rodadas.

O vínculo `004 ↔ Expedição` deve ser configurado no backend e documentado conforme as regras de configuração por instância do repositório. O cliente não escolhe arbitrariamente depósito ou setor. Não descobrir esse vínculo por chamadas ao ERP nem usar os depósitos da fixture.

Criar/atualizar cabeçalho e produtos deve ser atômico. O servidor valida a situação e os vínculos, independentemente das validações da interface.

## Abrangência e atualização dos cadastros

1. Consultar o catálogo elegível no WMS, com identidade do produto, códigos, descrição, unidade, origem/família e endereços necessários à seleção. Não projetar saldos de referência.
2. No geral, inicializar a seleção com todos os produtos elegíveis, sem o limite artificial de 100 produtos. Paginação de exibição não pode limitar a seleção inicial.
3. No cíclico, permitir adicionar/remover produtos individualmente ou pelos grupos da árvore de endereços, incluindo a descendência do grupo.
4. Converter a seleção por grupo em produtos distintos. Se um produto aparece no grupo escolhido e também em outros endereços da Expedição, todos esses endereços permanecem obrigatórios.
5. O backend resolve os endereços pelo produto e pelo contexto de Expedição. Não confiar em uma lista restrita de endereços enviada pelo navegador.
6. Persistir a seleção dos produtos. Ao reabrir e salvar, atualizar os endereços desses produtos pelo cadastro atual do WMS.
7. Reabrir um geral não adiciona automaticamente novos produtos à seleção já revisada. O usuário pode revisar e alterar a seleção explicitamente.
8. Se um produto selecionado perder seus vínculos elegíveis, apresentar a inconsistência e exigir revisão; não removê-lo silenciosamente.

A abrangência ainda não é uma fotografia operacional imutável. Seu congelamento definitivo acontece no início do inventário, pela ENG-3114. Grupos escolhidos não se tornam regras automáticas de inclusão futura.

## Acesso e concorrência

- Administradores e Masters com **sessão ativa na Expedição** podem consultar e editar os mesmos rascunhos, independentemente do criador.
- Validar setor e nível ativos no backend em todas as operações. Não depender da proteção da rota/menu, do criador ou de um filtro global de setor que possa ser dispensado para Master.
- Manter autoria original e registrar quem realizou a última alteração, sem trocar o responsável/criador a cada edição.
- Usar controle de versão: a atualização informa a versão lida e o backend recusa uma versão desatualizada, sem persistência parcial.
- Não implementar colaboração em tempo real, mesclagem automática ou bloqueio pessimista prolongado de edição.

## Interface e fluxo de dados

Reaproveitar a estrutura do cadastro em `src/pages/Inventory/`, com três etapas:

1. **Dados:** geral/cíclico manual, nome, descrição opcional e prazo.
2. **Abrangência:** busca e seleção por produto/grupo, com visualização de todos os endereços obrigatórios dos produtos selecionados.
3. **Revisão:** conferir os dados e a abrangência antes de salvar.

Exigir nome, prazo válido e ao menos um produto para salvar. Permitir revisar a seleção tanto no geral quanto no cíclico.

O fluxo entregue usa somente a API: carregar contexto/catálogo → montar seleção → revisar → salvar no backend → abrir detalhe persistido. O salvamento é assíncrono, impede submissão duplicada na interface e só comunica sucesso após confirmação do servidor.

Disponibilizar uma listagem básica de rascunhos compartilhados para localizar e reabrir o registro. O detalhe mostra número, situação, dados e abrangência, com ação de edição. Busca/filtros gerenciais e histórico avançado ficam para a ENG-3115.

Não expor nesse fluxo as ações simuladas do protótipo: aplicativo de contagem, parametrizações de participantes, início, resultados, aprovação, integração ou bloqueio. Salvar não chama `createStarted` nem executa transições locais.

Manter sessão e credenciais existentes. Não ler, migrar, gravar ou apagar chaves locais de inventário como parte da persistência desta entrega. Dados de teste ou módulos legados não podem entrar no grafo de dependências de runtime do novo fluxo.

## Reaproveitamento de componentes

A análise preliminar foi feita contra os componentes existentes na base do protótipo. Ela orienta a implementação, mas não substitui validação funcional e visual no navegador.

| Componente existente | Direção e condição |
| --- | --- |
| `PageHeader`, `Button`, `SidePanel` | Manter o uso já existente no protótipo, preservando foco, fechamento, estados e composição. |
| `Pagination`, `Spinner` | Avaliar para listagem básica e carregamento, respeitando o contrato da API e a interação esperada. |
| `Form/InputField` | Não substituir automaticamente os inputs. `maxLenght` acrescenta contador e o componente desfoca ao rolar; conferir equivalência antes do uso. |
| `Form/TextArea` | Não substituir automaticamente. O contrato atual não encaminha `id`/`disabled` nem associa o label ao textarea; não degradar acessibilidade ou estados do formulário. |
| `DefaultTable` | Avaliar para listagem simples. O corpo plano não atende diretamente à seleção agrupada e sua semântica. |
| `FamilySearch`, `OriginSearch`, `SearchFilter`, `Filters` | Não substituir diretamente os filtros do cadastro: apresentam dropdowns, múltipla seleção, aplicação explícita ou consultas próprias com comportamento diferente. |
| `Teams/OrderAddress/AddressTree` | Não usar diretamente na seleção de inventário. Implementa arrastar/ordenar endereços, não seleção de produtos por grupo com estado parcial. |

Comparar interação, aparência, acessibilidade e estados de carregamento/erro. Quando um componente não atender ao contrato esperado, preservar/compor o componente específico do inventário. Não refatorar componentes globais apenas para aumentar o reaproveitamento.

## Tratamento de erros

- **Carregamento ou salvamento indisponível:** mostrar erro e permitir nova tentativa. Durante a edição, preservar o formulário em memória; nunca recorrer a fixture ou persistência local como fallback.
- **Validação:** mostrar os campos/produtos que exigem revisão e manter o trabalho do usuário.
- **Versão desatualizada:** informar que outra pessoa alterou o rascunho; não sobrescrever nem mesclar silenciosamente. Recarregar é uma ação explícita, com proteção contra descarte inadvertido da edição.
- **Produto sem vínculo elegível:** manter a inconsistência visível até revisão da seleção.
- **Sem autenticação/permissão ou registro inexistente:** respeitar os fluxos de sessão e respostas de acesso existentes, sem revelar registros de outro contexto.
- **Catálogo vazio:** apresentar estado vazio real, sem inventários ou produtos de demonstração.

## Validação

### Backend

- Criar, editar e consultar um rascunho com produtos reais da base de testes; verificar os vínculos e a atomicidade.
- Criar com um usuário autorizado e reabrir/editar com outro; negar níveis/setores indevidos, inclusive tentativas diretas contra a API.
- Cobrir controle de versão e recusa de edição fora da situação de rascunho.
- Cobrir catálogo geral com mais de 100 produtos e ausência de filtro por saldo.
- Selecionar grupos sobrepostos e produto com endereços dentro/fora do grupo; incluir todos os endereços da Expedição e excluir outros setores.
- Cobrir atualização de endereços e produtos que perdem elegibilidade, sem remoção silenciosa.
- Confirmar que cadastro/edição não consulta o ERP, não altera quantidades e não inicia contagens ou bloqueios.
- Testar migrations, constraints e rollback conforme as convenções do repositório.

### Frontend e integração

- Cobrir geral, cíclico e seleção por grupos, estado parcial, remoção, filtros e preservação de seleção entre páginas.
- Criar/reabrir/editar a partir da API em duas sessões autorizadas, sem depender de dados de um navegador.
- Cobrir carregamento, estado vazio, falhas de API, validações, conflitos e bloqueio de submissão duplicada.
- Confirmar ausência de fixture/store/saldos fictícios no runtime e de chamadas de integração ao ERP.
- Validar teclado, foco, fechamento do painel, estados de salvamento e responsividade; comparar os componentes reutilizados ao comportamento do protótipo no recorte aprovado.

Dados sintéticos/fixtures são permitidos exclusivamente nos testes. Testes de banco devem seguir `docs/testing-database.md`, usar apenas a instância de testes e executar o preflight de segurança antes de qualquer suíte que altere schema. Nunca usar o banco oficial para `RefreshDatabase` ou `migrate:fresh`.

## Limites e dependências

| Atividade | Responsabilidade |
| --- | --- |
| Cadastro, abrangência e rascunho compartilhado | **ENG-3113** |
| Início, fotografia definitiva e bloqueio de movimentações | ENG-3114 |
| Consulta/filtros gerenciais e acompanhamento avançado | ENG-3115 |
| Distribuição e assunção de tarefas | ENG-3116 |
| Modalidades e registro de contagens no aplicativo | ENG-3117 |
| Conferência e encerramento local | ENG-3118 |
| Dashboard com dados reais | ENG-3119 |

Não implementar automação de inventário cíclico, importação do progresso local do protótipo, exclusão de inventários, integração com ERP, alterações no aplicativo ou refatoração global de componentes.

## Ordem de execução aprovada

1. Consolidar o contrato da API e a matriz de componentes reutilizáveis.
2. Implementar persistência, autorização e resolução de abrangência no backend.
3. Conectar cadastro, listagem básica e detalhe à API, retirando as dependências simuladas desse fluxo.
4. Executar testes e revisão visual/funcional.

O próximo artefato é o plano detalhado de implementação por tarefa, arquivo e validação. Sua produção ainda faz parte do planejamento, não da execução da funcionalidade.

## Referências

- ENG-3113 e seus critérios de aceitação.
- Alinhamento de 04/11/2026 nos comentários da ENG-3078, que prioriza a primeira entrega sem integração com ERP.
- ENG-3114, ENG-3115 e demais entregas do projeto `[WMS] Inventário`.
- `rex-back/AGENTS.md` e `rex-back/docs/testing-database.md`.
- Base `eng-2966` de `rex-front`: `DraftPanel.jsx`, `ProductSelection.jsx`, `Inventory.jsx`, `store.mjs`, `selection.mjs` e documentos históricos do protótipo.
