# ENG-3113 — Plano de implementação do inventário manual

**Status:** implementação do recorte executada em 2026-11-06; validação focal aprovada. Gates globais têm limitações preexistentes registradas nas [evidências](../testing/eng-3113-inventario-manual.md).
**Desenho aprovado:** [Inventário manual com abrangência do WMS](2026-11-05-eng-3113-inventario-manual-design.md).
**Registro do desenho:** commit `578fb31a` de `rex-back`.

## Resultado esperado e limites

Entregar **Dados → Abrangência → Revisão**, salvando inventários gerais/cíclicos manuais como rascunhos compartilhados entre Administradores e Masters com sessão ativa na Expedição.

O depósito configurado para esta instância é **004**, correspondente a todos os endereços da Expedição. O catálogo contém produtos vinculados a esses endereços, sem filtro por saldo. Seleção por grupo identifica produtos; sua abrangência inclui todos os endereços do produto na Expedição, não apenas o grupo selecionado.

Não implementar início, bloqueios, participantes, distribuição, contagens, aprovação, integração com ERP ou filtros gerenciais. Não migrar inventários do navegador. Não alterar `Rex-Estoque` nem componentes globais para forçar reaproveitamento.

## Estado inicial e segurança

- [x] `rex-back`: branch `feature/eng-3113` criada de `main`, base `a6b49a5f412709ce5285f082db44cfd7b60d06f6`.
- [x] `rex-front`: branch `feature/eng-3113` criada de `eng-2966`, base `67305ddb8fd153385832198c614d216d4cc01dae`.
- [x] Desenho aprovado e versionado.
- [x] Execução autorizada pelo usuário; realizada nas worktrees rex-back-eng-3113 e rex-front-eng-3113, a partir da integração preparada.

Antes da execução, verificar novamente os working trees. Não recriar branches, resetar alterações ou incorporar a `main` do frontend inadvertidamente. A raiz `Rex/` não é o repositório das aplicações; executar Git em cada repositório.

Usar PHP compatível com `rex-back/composer.json` (`^8.4`) e as dependências existentes. Não atualizar pacotes como parte desta issue. Seguir `rex-back/AGENTS.md`.

Antes de testes com banco, seguir `rex-back/docs/testing-database.md`:

```bash
cd rex-back
# Somente se a instância de testes precisar ser iniciada e estiver configurada:
docker compose --profile test up -d postgres-test
php artisan --env=testing test:database-safety
```

Não executar `migrate:fresh` manualmente. Não executar migrations ou testes destrutivos contra o banco oficial. Não rodar suítes com `RefreshDatabase` enquanto outro teste integrado estiver usando o mesmo banco.

## Contrato mínimo da API

Prefixo: `/api/v1/inventory`. Todas as operações exigem autenticação e o contexto administrativo ativo de Expedição, inclusive para Master.

| Método e caminho | Responsabilidade |
| --- | --- |
| `GET /inventory` | Listagem básica, paginada e compartilhada de rascunhos, ordenada pelos mais recentes. |
| `POST /inventory` | Criar rascunho, com número/autoria gerados no servidor. |
| `GET /inventory/{inventory}` | Reabrir dados e seleção persistidos, sem fotografia congelada dos endereços. |
| `PUT /inventory/{inventory}` | Atualizar atomicamente, exigindo a versão lida e situação de rascunho. |
| `GET /inventory/catalog` | Produtos elegíveis paginados, busca e filtros cadastrais do seletor. |
| `GET /inventory/address-groups` | Hierarquia e vínculos de produtos necessários à seleção por grupo. |
| `POST /inventory/scope-preview` | Resolver seleção geral, por grupos ou por IDs e devolver prévia cadastral sem persistir. |

Registrar rotas literais antes de `/{inventory}` e restringir o identificador a número. Não criar endpoints de exclusão ou transição operacional.

### Escrita

Corpo de criação/edição: `description` (campo Nome, máximo de 160 caracteres), `notes` opcional, `due_date` em `Y-m-d`, `type` (`geral` ou `ciclico`) e `product_ids` distintos. Na edição, `version` é obrigatório.

Exigir nome não vazio, prazo válido e pelo menos um produto elegível. Não acrescentar regra de prazo futuro não existente no comportamento aprovado. Converter a modalidade visual `manual` do seletor em `type: ciclico`; o servidor fixa `selection_mode: manual`.

Setor, depósito, número, situação, autoria, endereços, saldos, participantes e rodadas não são campos de escrita do cliente. Proibir esses campos quando enviados; nunca usá-los por mass assignment. O servidor resolve os endereços a partir dos produtos/contexto.

A resposta de detalhe inclui `id`, número/código gerado no servidor, campos do rascunho, situação, contexto, versão, autoria/datas e os IDs selecionados. O número pode ser derivado do identificador incremental, sem contador baseado em quantidade de registros no cliente e sem limite de quatro dígitos.

### Catálogo e prévia

- Identidade por `products.id`, não pelo código de exibição, descrição ou ID composto da fixture.
- Projeção explícita: descrição, códigos reais disponíveis, derivação/empresa quando disponíveis, unidade, família/origem e endereços com ID/nome/hierarquia.
- Usar dados locais de integração já cadastrados no WMS somente como metadados. Não devolver parâmetros de integração completos, credenciais ou saldos.
- `catalog` aceita `search`, `origin_id`, `family_id`, `page` e `per_page`, com ordem estável. Referências de origem/família devem vir do catálogo elegível, não de listas globais presumidas.
- A prévia aceita seletores mutuamente exclusivos: `all`, `groups` com `address_ids`, ou `products` com `product_ids`; admite paginação da apresentação e os filtros cadastrais pertinentes.
- A prévia devolve todos os IDs resolvidos em formato leve, produtos paginados e resumo de produtos/endereços. O total selecionado não depende do tamanho da página.
- Resolver grupos e seus descendentes no servidor. Exibir todos os endereços da Expedição de cada produto resultante, mesmo fora dos grupos/filtros usados para encontrá-lo.
- Na consulta de seleção já salva, sinalizar IDs que perderam elegibilidade. Não remover silenciosamente nem revelar dados de registros alheios ao contexto. Na escrita, recusá-los com erro de revisão.
- A árvore deve permitir estado parcial considerando todos os membros do grupo, não somente produtos da página carregada. Retornar vínculos leves suficientes para esse cálculo; não executar uma consulta por produto/nó.
- Paginação de prévia por POST deve reenviar o seletor; não seguir um link como GET perdendo o corpo da seleção.

### Falhas

`401` segue o tratamento de sessão existente; `403` para setor/nível indevido; `404` para registro fora do contexto/inexistente; `422` para campos ou produtos inválidos; `409` para versão desatualizada ou registro fora de rascunho. Conflitos precisam de códigos distinguíveis e mensagem legível. Configuração ausente deve falhar explicitamente, sem assumir um depósito ou consultar o ERP.

Não repetir automaticamente POST/PUT após falha de comunicação: uma resposta perdida não prova que a escrita falhou. O usuário pode consultar a listagem antes de reenviar uma criação sem confirmação.

## Modelo relacional mínimo

Nova migration para as duas tabelas, com rollback restrito a elas:

- `inventories`: `id`, `description`, `notes`, `type`, `selection_mode`, `status`, `sector`, `depot_code` como string que preserve zeros à esquerda, `due_date`, `version`, `created_by`, `updated_by` e timestamps.
- `inventory_products`: `id`, `inventory_id`, `product_id`, `depot_code` e timestamps; unicidade de inventário + produto + depósito.
- Índices de leitura por contexto/situação e de produto/depósito para evolução posterior, sem criar bloqueios agora.
- FKs não podem apagar silenciosamente seleção/autoria quando um cadastro referenciado for removido. Usar restrição de exclusão para produto/usuários e validar esse impacto; o vínculo ao cabeçalho pode usar cascade para exclusão interna/rollback, sem endpoint de exclusão.
- Não criar tabelas de fotografia de endereços, rodadas, tarefas ou bloqueios nesta issue.

A seleção fica salva; seus endereços são reconsultados ao reabrir e salvar. Novos produtos não entram automaticamente em um geral já revisado. Salvar não muda a situação nem altera quantidades.

## Matriz de reaproveitamento

| Origem em `rex-front/src` | Ação planejada |
| --- | --- |
| `components/PageHeader`, `Button`, `SidePanel` | Manter os usos do protótipo e validar os estados assíncronos. |
| `components/Spinner` | Candidato para carregamento, sem alterar sua API global. |
| `components/Pagination` e `PaginationLink` | Condicional. O código atual usa `li` clicável, exigindo atenção à navegação por teclado. Se não atender, manter controles locais acessíveis. |
| `components/Form/InputField` | O contador automático e o blur ao rolar diferem do input do protótipo. Preferir o input local se não houver composição equivalente. |
| `components/Form/TextArea` | Ausência de `id`/`disabled` e associação de label impede substituição direta sem perda. Preservar textarea local se necessário. |
| `components/DefaultTable` | Avaliar apenas listagem simples; não usar como substituto da tabela de seleção agrupada. Preservar semântica, links e teclado. |
| `components/FamilySearch`, `OriginSearch`, `SearchFilter`, `Filters` | Não substituir automaticamente filtros controlados: comportamento e transporte são diferentes. |
| `pages/Teams/components/OrderAddress/components/AddressTree` | Não acoplar o inventário à árvore de drag-and-drop/ordenação de equipes. |
| `pages/Inventory/DraftPanel.jsx`, `ProductSelection.jsx`, `InventoryKindSelector.jsx` | Adaptar ao recorte de três etapas e dados reais, preservando o comportamento visual/interativo aprovado. |
| `pages/Inventory/ProductIdentity.jsx`, `ProductAddresses.jsx` | Reaproveitar após remover dependências transitivas da fixture. |

A comparação deve cobrir interação, aparência, foco/teclado, acessibilidade, carregamento/erro e preservação da seleção. Não é objetivo maximizar quantidade de componentes reutilizados.

## Roteiro por tarefa

Em cada tarefa: escrever o teste focal → confirmar falha pelo motivo esperado → implementar o mínimo → confirmar sucesso → revisar diff → commit pequeno com prefixo `ENG-3113`. Rodar Pint antes de cada commit do backend. Não corrigir falhas preexistentes ou refatorar módulos alheios sem necessidade demonstrada.

### 1. Persistência e contexto configurável

**Depende de:** autorização para iniciar a execução e preflight seguro.

**Arquivos novos — backend:**
- `database/migrations/<timestamp>_create_inventory_draft_tables.php`
- `config/inventory.php`
- `app/Models/Inventory/Inventory.php`
- `app/Models/Inventory/InventoryProduct.php`
- `database/factories/Inventory/InventoryFactory.php`
- `Domain/Inventory/Enums/InventoryTypeEnum.php`
- `Domain/Inventory/DTOs/InventoryContextDTO.php`
- `Domain/Inventory/Services/InventoryContextService.php`
- `tests/Unit/Inventory/InventorySchemaTest.php`
- `tests/Unit/Inventory/InventoryContextTest.php`

**Editar:** `.env.example`, `tests/Pest.php`.

1. Adicionar os testes de schema, unicidade/FKs, versão inicial e rollback das novas tabelas. Optar explicitamente por `RefreshDatabase` apenas nas novas suítes, preservando o guard existente.
2. Testar que `REX_INVENTORY_EXPEDITION_DEPOT_CODE` é lido como string e que ausência de configuração não usa fallback. Definir `004` na configuração local autorizada; documentar a chave em `.env.example` sem hardcode de instância no serviço.
3. Implementar migration/models/contexto conforme o contrato mínimo. Não usar `HasSectorScope` como única proteção.
4. Rodar `./vendor/bin/pest tests/Unit/Inventory/InventorySchemaTest.php tests/Unit/Inventory/InventoryContextTest.php` depois do preflight. Não alterar o schema oficial nesta tarefa de testes.

**Saída:** relações e configuração verificadas, sem endpoints operacionais ou saldo.

### 2. Autorização por token/contexto ativo

**Depende de:** 1.

**Novos:** `app/Http/Middleware/EnsureInventoryManagementAccess.php`, `app/Policies/InventoryPolicy.php`, `tests/Feature/Inventory/InventoryAccessTest.php`.

**Editar:** `app/Providers/AuthServiceProvider.php`, `routes/api.php`; adicionar controllers mínimos do namespace `app/Http/Controllers/Inventory/` conforme as tarefas seguintes.

1. Cobrir todas as rotas da matriz: Admin/Master na Expedição, usuário sem sessão, outros níveis, System e Admin/Master em outro setor.
2. Usar `$this->authenticateAs(...)` de `tests/TestCase.php`, com abilities reais do token de teste; não simular somente `access_level` no usuário.
3. Aplicar middleware específico além da Policy: `Gate::before` atualmente libera Master globalmente. Não modificar esse comportamento global nem depender dele para o inventário.
4. Restringir também as consultas de cabeçalho/produtos/endereços pelo contexto explícito. Um ID de inventário de outro contexto deve resultar em `404`, sem metadados vazados.
5. Rodar `./vendor/bin/pest tests/Feature/Inventory/InventoryAccessTest.php` e manter os casos cobrindo novos endpoints a cada tarefa.

**Saída:** autorização vale na API inteira e não é limitada ao menu/rota do cliente.

### 3. Catálogo cadastral real e completo

**Depende de:** 1–2.

**Novos:**
- `Domain/Inventory/Queries/InventoryCatalogQuery.php`
- `Domain/Inventory/DTOs/InventoryCatalogSearchDTO.php`
- `Domain/Inventory/Resources/InventoryCatalogProductResource.php`
- `app/Http/Requests/InventoryCatalogRequest.php`
- `app/Http/Controllers/Inventory/InventoryCatalogController.php`
- `tests/Support/InventoryTestData.php`
- `tests/Feature/Inventory/InventoryCatalogTest.php`

**Editar:** `routes/api.php`.

1. Montar dados mínimos com factories existentes de produto, integração, família/origem, unidade, endereço e item. Cobrir vínculo com quantidade zero, produtos sem integração opcional, produtos sem endereço, endereço de outro setor, endereço removido e múltiplas OPs/itens no mesmo endereço.
2. Testar busca por identidade/códigos/descrição e filtros, paginação estável, mais de 100 produtos e deduplicação. Preservar a busca sem diferenciar caixa/acentos nos campos disponíveis, conforme o seletor do protótipo.
3. Consultar vínculo de produto a `Item` cujo `itemable_type` corresponde a `Address`, usando o morph type real, endereços atuais e `SectorEnum::EXPEDITION`. Não filtrar `amount > 0`, nem adicionar restrições de rua, status ou categoria sem justificativa no desenho.
4. Não reutilizar cegamente `ProductLocationService`/Resources genéricos: eles carregam quantidades e podem depender de escopo global. Fazer projeção cadastral explícita e carregar relacionamentos em lote.
5. Testar ausência de campos de saldo/credenciais e ausência de N+1. Não adicionar índices a tabelas de estoque sem medir a consulta primeiro.
6. Rodar `./vendor/bin/pest tests/Feature/Inventory/InventoryCatalogTest.php`.

**Saída:** catálogo real, contextualizado, paginado e independente de ERP/fixture.

### 4. Grupos e resolução autoritativa da abrangência

**Depende de:** 3.

**Novos:** `Domain/Inventory/DTOs/InventoryScopeDTO.php`, `Domain/Inventory/Services/InventoryScopeService.php`, `app/Http/Requests/InventoryScopePreviewRequest.php`, `tests/Feature/Inventory/InventoryScopeTest.php`.

**Editar:** `InventoryCatalogController.php`, `InventoryCatalogQuery.php`, `routes/api.php` e o Resource cadastral conforme necessário.

1. Testar seletores `all`, `groups` e `products`, incluindo geral com mais de 100 IDs, grupos sobrepostos, grupos vazios, hierarquia aninhada e IDs fora do contexto.
2. Criar o caso central: produto em A e B na Expedição e C no Almoxarifado; selecionar somente A/grupo de A deve devolver A+B, nunca C. Repetir com saldo zero e itens duplicados por OP.
3. Resolver descendentes em lote/CTE com filtro de setor em todos os níveis. Separar descoberta dos produtos de expansão de seus endereços completos; o filtro inicial não pode contaminar a segunda consulta.
4. Retornar IDs leves completos, resumo e páginas da prévia sem persistir nada. Tratar produtos que perderam elegibilidade como inconsistências na leitura, não como remoção automática.
5. Retornar uma árvore apta a calcular seleção parcial sem uma chamada por produto/nó e sem depender da página visível.
6. Rodar `./vendor/bin/pest tests/Feature/Inventory/InventoryScopeTest.php tests/Feature/Inventory/InventoryCatalogTest.php`.

**Saída:** a mesma resolução alimenta prévia, escrita e reabertura; não existem listas paralelas de endereços montadas pelo browser.

### 5. Comandos de rascunho, consulta básica e concorrência

**Depende de:** 2–4.

**Novos:**
- `Domain/Inventory/DTOs/InventoryDraftDTO.php`
- `Domain/Inventory/Services/InventoryDraftStoreService.php`
- `Domain/Inventory/Services/InventoryDraftUpdateService.php`
- `Domain/Inventory/Exceptions/InventoryDraftConflictException.php`
- `Domain/Inventory/Resources/InventoryResource.php`
- `Domain/Inventory/Resources/InventorySummaryResource.php`
- `app/Http/Requests/InventoryDraftRequest.php`
- `app/Http/Controllers/Inventory/InventoryController.php`
- `tests/Feature/Inventory/InventoryDraftTest.php`
- `tests/Feature/Inventory/InventoryConflictTest.php`
- `tests/Feature/Inventory/InventorySideEffectsTest.php`

**Editar:** `routes/api.php`.

1. Cobrir criação, edição, listagem e reabertura por dois usuários autorizados, número do servidor, manutenção de autoria original e atualização de `updated_by`.
2. Cobrir campos inválidos/proibidos, IDs duplicados/inelegíveis e erro de sincronização: não pode sobrar cabeçalho ou alteração parcial dos produtos.
3. Criar/atualizar dentro de uma transação. Na edição, ler o cabeçalho contextualizado sob bloqueio curto de banco, comparar versão e situação e só então sincronizar produtos e incrementar versão. A versão enviada pelo cliente não é atribuída diretamente.
4. Testar duas edições partindo da mesma versão: a primeira persiste; a segunda retorna `409` sem modificar dados. Cobrir situação diferente de `rascunho` sem implementar sua transição nesta issue.
5. Reabrir após adicionar/remover endereços do WMS: atualizar endereços da seleção, manter IDs selecionados, sinalizar perda de elegibilidade e não incluir novos produtos automaticamente no geral.
6. Retornar o conflito pelo mecanismo existente de exceções renderizáveis/HTTP, preservando a sanitização de `app/Exceptions/Handler.php`, sem mudanças genéricas de tratamento de erros.
7. Bloquear chamadas HTTP/SOAP/Senior nos testes usando as estratégias existentes, por exemplo `tests/Support/ReclassificationPickingConcurrencyWorker.php`. Verificar estoque/movimentações/filas de integração antes/depois; nenhuma contagem, bloqueio ou ajuste pode ser criado.
8. Rodar `./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory`.

**Saída:** todos os critérios de persistência/compartilhamento/abrangência podem ser comprovados contra o banco de testes, sem o frontend.

### 6. Contrato do frontend e helpers sem dependências simuladas

**Depende de:** contrato das tarefas 3–5; pode começar com respostas sintéticas somente em testes.

**Novos — frontend:**
- `src/domain/Inventory/services/InventoryService.jsx`
- `src/pages/Inventory/wms.mjs`
- `src/pages/Inventory/wms.test.mjs`
- `src/pages/Inventory/draft.mjs`
- `src/pages/Inventory/draft.test.mjs`

**Editar:** `selection.mjs`, `selection.test.mjs`, `isolation.test.mjs`, `ProductIdentity.jsx`, `ProductAddresses.jsx` e `references/context.js`, todos sob `src/pages/Inventory/`.

1. Testar normalização de IDs, derivação/empresa/unidade opcionais, rótulos reais, montagem de payload, validação e mensagens de erro/conflito. Não inventar códigos, empresas, unidades ou saldo para preencher campos ausentes.
2. Criar o serviço sobre `@http/index.jsx`, preservando credenciais e tratamento de sessão existentes. Métodos de escrita retornam a resposta confirmada; leitura aceita cancelamento. Não criar outro cliente HTTP nem armazenar inventários localmente.
3. Separar helpers puros do runtime legado. Hoje `selection → presentation → model → catalog → fixture` e `ProductIdentity → ProductAddresses → identification/model` carregam simulação indiretamente. O novo caminho deve importar somente os helpers WMS, sem apenas esconder um import direto.
4. Remover o limite funcional de 100 em `selection.mjs` e atualizar os testes que hoje o exigem. Seleção inicial geral vem de todos os IDs resolvidos pelo servidor, não da primeira página carregada.
5. Trocar o valor padrão de `ReferenceContext`, hoje preenchido pela fixture, por contexto explícito. Não apresentar um catálogo fictício quando não houver Provider/dados.
6. Substituir o guard antigo de `isolation.test.mjs`, que proíbe qualquer API, por um teste do grafo efetivamente alcançável pela entrada persistida: proibir fixture, `catalog.mjs`, `model.mjs`, `store.mjs`, `seeds.mjs`, `operations.mjs` e chamadas de ajustes/ERP. Não proibir o transporte autorizado do novo serviço nem o storage legítimo de autenticação fora da feature.
7. Manter testes matemáticos legados separados conceitualmente da evidência da entrega persistida; arquivos de protótipo podem permanecer fora do runtime, sem refatorar todo o motor de contagem.

**Saída:** helpers/componentes visuais reutilizáveis não importam dados ou transições de demonstração.

### 7. Carregamento real e seleção por produtos/grupos

**Depende de:** 3–4 e 6.

**Novos:** `src/pages/Inventory/references/InventoryDataProvider.jsx` e componentes locais de árvore/paginação apenas se os existentes não atenderem à matriz.

**Editar:** `ProductSelection.jsx`, `ProductSelection.css`, `selection.mjs` e seus testes; `references/context.js`.

1. Carregar catálogo, referências e árvore pela API. Distinguir loading, vazio e erro; cancelar/ignorar respostas antigas ao trocar busca, contexto ou desmontar.
2. Preservar seleção e metadados necessários fora da página atual. Usar a identidade nativa dos produtos; não misturar IDs numéricos com strings de `<select>` sem normalização.
3. Implementar seleção em lote e estados parcial/completo sobre os membros reais dos grupos. Manter a regra do protótipo de não apagar seleções externas ao filtro e de remover do grupo somente seus membros na ação correspondente.
4. Resolver o geral por `scope-preview: all`, sem truncamento. Alternar tipo/filtrar não deve inserir/remover produtos de uma seleção já revisada sem a ação explícita esperada.
5. Mostrar, no painel dos selecionados, todos os endereços devolvidos pelo servidor; não reconstruir abrangência a partir da página/grupo visível.
6. Reavaliar os candidatos de componentes com a matriz. Se não preservarem o comportamento, usar composição local, sem alterar sua API global.

**Saída:** seleção real conserva todos os endereços e não se perde em filtros/páginas.

### 8. Cadastro assíncrono de três etapas

**Depende de:** 5–7.

**Editar:** `src/pages/Inventory/DraftPanel.jsx`, `DraftModes.css`, `InventoryKindSelector.jsx`; complementar `draft.mjs`/testes.

1. Remover dependências de participantes, distribuição, rodadas e opção de bloqueio. Preservar Dados → Abrangência → Revisão e os componentes visuais compatíveis.
2. Preservar nome, descrição, prazo, navegação por etapas, foco, Escape e teclado no painel, dentro do recorte aprovado. Componentes locais devem respeitar o estado ocupado; não introduzir as diferenças de contador/foco dos inputs compartilhados por conveniência.
3. Fazer `onSave` assíncrono, aguardar a API e só fechar/navegar após sucesso confirmado. Bloquear duplo envio e tratar respostas tardias sem alterar outra sessão/tela.
4. Mostrar validações do servidor e indisponibilidade sem descartar o formulário. Tratar `409` com aviso e recarga explícita, protegendo a edição contra descarte involuntário; não implementar merge.
5. Exigir revisão para produto sem vínculo elegível. Não reintroduzir saldos, atribuições, fotografia ou dados locais para satisfazer validações antigas.

**Saída:** cadastro salva rascunho e permanece editável em caso de erro; não inicia nada automaticamente.

### 9. Listagem/detalhe compartilhados e corte do fluxo simulado

**Depende de:** 5–8.

**Editar — frontend:**
- `src/pages/Inventory/Inventory.jsx`
- `src/pages/Inventory/InventoryList.jsx`
- `src/pages/Inventory/Inventory.css`
- `src/pages/Inventory/permissions.mjs` e `permissions.test.mjs`
- `src/routes/Router/Router.jsx`
- `src/components/Menu/MenuConfig.jsx`, somente se necessário ao vínculo de permissões

1. Substituir a entrada `MockDataProvider`/store/operations por leitura da API e estado de tela em memória.
2. Listar rascunhos reais, com número, nome, tipo, prazo, situação e autoria, de forma paginada e compartilhada. Não implementar os filtros gerenciais ou comparativos antigos.
3. Abrir detalhe persistido e permitir edição. Não renderizar resultados, histórico simulado, configurações, app de contagem, aprovação ou botão de início.
4. Remover uso de `createStarted` e transições locais. Não importar `list.mjs`/`presentation.mjs` legados sem verificar seu grafo de dependências.
5. Restringir permissões a `{2: [1, 2]}` e os caminhos a `/inventarios` e `/inventarios/:inventoryId`. Não expor rotas antigas de aprovação/contagem a drafts reais; acessos antigos não podem montar componentes simulados.
6. Testar menu/rotas/contexto ativo, inclusive Master fora da Expedição. A entrada também deve validar contexto de sessão, sem modificar autenticação ou ajustes de estoque existentes.
7. Recarregar leitura após salvar; não persistir um estado global por criador nem compartilhar dados de uma sessão anterior por cache local.

**Saída:** o fluxo navegável de inventário é integralmente persistido, sem cenários locais misturados.

### 10. E2E do recorte, equivalência visual e integração

**Depende de:** 5–9.

**Novos — frontend:** `e2e/inventory/persisted/setup.mjs`, `fixtures.mjs`, `draft.spec.mjs`, `scope.spec.mjs`, `errors.spec.mjs`, `component-parity.spec.mjs` e `README.md` nessa pasta.

**Editar:** `e2e/inventory/playwright.config.mjs`; atualizar documentação de validação em `docs/validation/inventario/README.md`.

1. Apontar a configuração focal para os novos testes persistidos. A configuração antiga coleta todos os specs de contagem/mock e usa setup que bloqueia API e injeta inventário em storage; isso não pode certificar a entrega nova. Preservar os testes históricos fora da coleta desta entrega, sem ignorar falhas do novo recorte.
2. Manter URLs/portas configuráveis pelo ambiente, sem novos valores de instância hardcoded em arquivos versionados. Preparar sessão somente pelos mecanismos de teste existentes e preservar sentinelas de credenciais/armazenamento alheio.
3. Usar respostas sintéticas da API apenas para testar comportamento de UI: geral >100, cíclico, grupos, seleção parcial, páginas/filtros, dados incompletos, vazio, erro, `422`, `409`, duplo clique e respostas fora de ordem. Essas interceptações não comprovam persistência real entre usuários.
4. Instrumentar o browser para provar que nenhuma chave de inventário é lida/gravada/migrada e que não há chamadas de ajuste/ERP ou fallback com dados de demonstração.
5. Validar o comportamento dos componentes reutilizados e capturar evidências do cadastro/listagem/detalhe em larguras 390, 1280 e 1440: foco, teclado, painel, etapas, estados parciais, carregamento/erro e ausência de overflow. Comparar com a base do protótipo, descontando somente o recorte aprovado.
6. Executar smoke com backend real e dois usuários autorizados em ambiente descartável/de testes: A cria; B abre e altera; A reabre e vê a mudança; duas edições da mesma versão produzem conflito; refresh mantém o registro sem storage de inventário. Preparar contas/dados somente com autorização, sem versionar credenciais ou resetar a base oficial.
7. O teste de duas identidades contra banco real da tarefa 5 é obrigatório. Se não houver ambiente/contas para o smoke no navegador, registrar esse bloqueio e não apresentar mocks como homologação integrada.

**Saída:** evidências distinguem testes de UI, integração real e verificações não executadas.

### 11. Regressão, revisão e entrega

**Depende de:** todas as anteriores.

**Backend, sempre após o preflight:**

```bash
cd rex-back
php artisan --env=testing test:database-safety
./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory
./vendor/bin/pint --dirty
composer test-safe
```

**Frontend:**

```bash
cd rex-front
node --test src/pages/Inventory/*.test.mjs
npm test
# Lint focal nos arquivos JS/JSX alterados, seguido do lint geral se viável:
npm run lint
npm run build
# Iniciar Vite com URLs/portas configuradas para o ambiente de teste antes:
npx playwright test --config=e2e/inventory/playwright.config.mjs
```

1. Verificar a necessidade de cobertura de regressão de `MenuConfig.test.mjs`, permissões/rotas e componentes tocados. Não alterar testes de outros módulos apenas para esconder regressões.
2. Revisar o bundle/grafo da entrada persistida para impedir dependências simuladas, mesmo quando o código da fixture ainda existe no repositório.
3. Confirmar que migrations não mudam estoque, que não há integração nova e que o mapeamento local está configurado como `004`.
4. Executar `git diff --check` e revisar `git diff --stat` em cada repositório. Rodar Pint antes de cada commit do backend e manter commits restritos à issue.
5. Registrar os comandos e resultados reais, capturas e limitações. Falhas preexistentes devem ser identificadas separadamente, não corrigidas sem necessidade.
6. Entregar as alterações em `feature/eng-3113` de cada repositório, com referências cruzadas e links para ENG-3113. Revisar a base da futura PR do frontend: ela precisa conter o protótipo aprovado, não presumir que ele já está na `main`.

## Checklist de aceite da execução

- [x] Criar, editar, salvar e reabrir rascunho compartilhado entre dois usuários autorizados.
- [x] Geral seleciona todo o catálogo elegível, inclusive além da primeira página/100 produtos; seleção continua revisável.
- [x] Cíclico manual monta seleção por produto e grupos.
- [x] Cada produto conserva todos os endereços da Expedição/004, mesmo fora do grupo escolhido.
- [x] Não restringir elegibilidade por saldo; não usar saldos fictícios, ERP ou armazenamento local de inventário.
- [x] Impedir sobrescrita silenciosa por edição concorrente.
- [x] Listagem/detalhe básicos permitem reabertura, sem simular as entregas seguintes.
- [x] Reaproveitamento de componentes foi avaliado e validado sem alterar o comportamento aprovado.
- [x] Migração/constraints, segurança de acesso, testes focais, regressão e evidências de UI revisados.
- [x] Registrar separadamente qualquer smoke integrado ou teste não executado.

## Nota de planejamento

Na etapa de planejamento, este plano foi preparado manualmente porque a skill `writing-plans` não estava instalada. A implementação foi iniciada somente após autorização posterior do usuário. As tarefas 1–11 foram executadas no recorte aprovado; os resultados reais, a integração entre usuários e os gates globais não concluídos estão em [evidências da implementação](../testing/eng-3113-inventario-manual.md).
