# ENG-3116 — Plano de implementação da distribuição e assunção de tarefas

**Status:** implementação backend/web concluída nas worktrees dedicadas; validações focais concluídas. E2E integrado, revisão final, coordenação ENG-3115 e commits ainda pendentes. App nativo separado na ENG-3268 e fora desta etapa.
**Desenho aprovado:** [Distribuir ou assumir tarefas de contagem](2026-11-06-eng-3116-distribuicao-tarefas-contagem-design.md), commit `51f8deda`.
**Pré-requisitos:** implementações da ENG-3113 e ENG-3114, conforme seus desenhos e planos nesta pasta.

## Estado atual da execução — 2026-11-09

- [x] Schema relacional, constraints compostas e models para rodadas, participantes, tarefas e eventos.
- [x] Preparação transacional/idempotente no início e recuperação explícita de inventários já iniciados; configuração/versionamento, prévia determinística, elegibilidade atual e operação de ingresso/assunção.
- [x] Interface web conectada às rotas persistidas, com busca/paginação de pessoas e tarefas, edição independente, sugestão explicitamente aplicada, conflitos e confirmação de descarte local.
- [x] Contratos documentados em [`docs/inventory-rounds-api.md`](../inventory-rounds-api.md); resultados em [`docs/validation/eng-3116/README.md`](../validation/eng-3116/README.md) e no frontend.
- [x] Segurança do banco de testes aprovada; suíte Inventory Feature/Unit: **132 testes, 912 assertions, 0 falhas**. Ocorrem 2 warnings conhecidos porque o container de teste não possui `/app/.env`.
- [x] Frontend: **464 testes Node**, Playwright web focal com mock de API (**1 passou**), ESLint focal e build aprovados. Build conserva aviso de chunk acima de 500 kB.
- [ ] E2E integrado com API real, revisão final e coordenação/reconciliação da ENG-3115 antes de integrar.
- [ ] Preparar commits locais depois da revisão; ainda não há commits desta implementação.
- [ ] A implementação e homologação nativas seguem fora do escopo e serão tratadas pela ENG-3268.

## Objetivo, arquitetura e limites

Entregar no backend Laravel/PostgreSQL e frontend web React/Vite duas rodadas iniciais independentes, distribuição gerencial por produto/endereço e contratos seguros para assunção. A integração e telas do app React Native/Expo pertencem à ENG-3268 e não serão implementadas nesta execução.

Persistir uma tarefa por rodada/endereço-produto da fotografia da ENG-3114. Responsável nulo representa tarefa aberta. Somente participantes selecionados naquela rodada podem executar ou assumir, nos perfis existentes Master, Administrador, Armazenador e Separador, com contexto ativo de Expedição. A gestão continua restrita a Admin/Master nesse contexto.

**Regra central aprovada:** o primeiro ingresso operacional ou assunção congela participantes e distribuição da rodada. Assunções posteriores de tarefas abertas continuam válidas. Não implementar troca de responsável, devolução, expiração ou desbloqueio administrativo após esse início.

A ENG-3268 implementará posteriormente a experiência nativa que consome os contratos operacionais. Não registrar quantidades, concluir tarefas ficticiamente, configurar modalidades, abrir recontagens operacionais, encerrar inventário, alterar estoque ou consultar/enviar ajustes ao ERP. ENG-3117 acrescenta contagens; ENG-3118 acrescenta resultados e encerramento.

## Estado inicial e segurança

- [x] Desenho aprovado por quatro seções e versionado.
- [x] Incorporar ao worktree `rex-back-eng-3116` as implementações ENG-3113/3114 de `feature/inventario` (`c4056323`).
- [x] Criar o worktree frontend `rex-front-eng-3116`, branch `feature/eng-3116`, a partir de `feature/inventario` (`64b2accd`).
- [x] Receber autorização para implementar backend e interface web; a integração móvel da ENG-3268 fica adiada.
- [x] Implementar, testar e documentar a distribuição backend/web nas worktrees ENG-3116.
- [ ] Integrar as alterações atuais da ENG-3115 após reconciliação.

As worktrees dedicadas iniciam de `feature/inventario`; não editar os worktrees principais em uso pela ENG-3115. Não absorver alteração preexistente de `.easignore` nem modificar `Rex-Estoque`. A ENG-3115 não é bloqueadora; reconciliar sua evolução em detalhe/listagem ao integrar, sem duplicá-la.

Seguir `rex-back/AGENTS.md` e `docs/testing-database.md`. O projeto requer PHP `^8.4`; usar runtime compatível, não o PHP 8.2 padrão inspecionado. Não atualizar dependências para adaptar o projeto ao runtime local.

Comandos abaixo orientam as validações futuras em banco descartável e runtime correto; não usar o PostgreSQL compartilhado de outra sessão:

```bash
cd rex-back
# Apenas se a instância descartável configurada ainda precisar ser iniciada:
docker compose --profile test up -d postgres-test
php artisan --env=testing test:database-safety
```

Nunca executar migrations/`migrate:fresh` ou testes com banco oficial. Manter o teste de ENG-3116 em instância PostgreSQL descartável isolada das demais sessões; não executar simultaneamente suítes que recriem o mesmo schema. Workers de concorrência também precisam executar o guard de banco seguro.

## Contrato proposto da API

Reconciliar nomes com as dependências sem alterar o comportamento. Prefixo comum `/api/v1/inventory`; os caminhos abaixo são relativos a ele.

### Gestão — autenticação e Admin/Master ativos na Expedição

| Método/caminho | Contrato |
| --- | --- |
| `GET /participants` | Catálogo mínimo de usuários elegíveis, com busca e paginação. Validar nível dentro do setor, não em qualquer setor do cadastro. |
| `POST /{inventory}/rounds/initialize` | Preparar idempotentemente as duas rodadas e todas as tarefas de inventário já iniciado, sem exigir participantes. Não reiniciar nem recalcular uma abrangência existente. |
| `GET /{inventory}/rounds` | Resumo persistido das rodadas, situação, início e capacidade de configurar. |
| `GET /{inventory}/rounds/{round}` | Configuração, participantes e mapa leve completo de atribuições, com metadados de tarefas paginados e totais reais. |
| `POST /{inventory}/rounds/{round}/distribution-preview` | Receber versão, critério e participantes da edição; devolver sugestão completa sem gravar ou iniciar a rodada. |
| `PUT /{inventory}/rounds/{round}/configuration` | Salvar participantes e atribuições completos atomicamente, exigindo versão e rodada ainda não iniciada. |

Payload proposto de configuração: `version`, `participant_ids`, `strategy` (`location`, `family`, `product`) e `assignments` com `{task_id, operator_id}`; `operator_id: null` deixa aberta. Usar somente IDs reais e distintos. O servidor exige exatamente as tarefas daquela rodada, sem duplicatas, omissões ou tarefas externas.

Não aceitar produto/endereço/depósito/setor como substituição da fotografia, autoria, situação ou início operacional enviados pelo cliente. Acrescentar/remover produtos e tarefas não é uma operação de configuração. Remover participante sem resolver suas atribuições retorna validação; não limpar ou redistribuir silenciosamente.

A prévia valida participantes/contexto e deriva todas as tarefas no servidor. Ordenar participantes e tarefas de forma determinística e explicitar a ordem usada; não depender de ordem incidental de consulta. O mapa leve completo permite salvar uma edição com tarefas fora da página atual. A paginação limita metadados de exibição, nunca a abrangência.

### Operação — sessão nativa no contexto/perfil aprovado e participação na rodada

| Método/caminho | Contrato |
| --- | --- |
| `GET /available-rounds` | Inventários/rodadas operáveis em que o usuário autenticado foi selecionado; identificação e totais de tarefas próprias/abertas, sem resultados. |
| `GET /rounds/{round}/tasks` | `scope=mine` ou `scope=open`, busca e paginação estável, sempre filtrados no servidor. |
| `GET /rounds/{round}/tasks/{task}` | Reconsulta cega de tarefa própria/aberta para recuperar uma resposta perdida; se já indisponível, informar isso sem revelar dados do novo responsável. |
| `POST /rounds/{round}/enter` | Ingressar/iniciar explicitamente, de forma idempotente para o participante. Corpo sem identidade de operador. |
| `POST /rounds/{round}/tasks/{task}/claim` | Assumir exclusivamente para a identidade autenticada, recuperando repetição própria sem duplicar evento. Corpo sem identidade de operador. |

As rotas operacionais não herdam a restrição administrativa. Master/Admin não selecionados também são recusados. Autorização considera o token ativo e o acesso cadastral atual, sem bypass global de Master e sem aceitar a troca de ator do simulador.

Usar Resources distintos para gestão e operação. Projetar apenas identificação do inventário/rodada, produto/endereço/unidade/contexto e propriedade necessária. Não devolver saldos, lançamentos, resultados de outras rodadas, credenciais ou parâmetros de integração completos.

Registrar rotas literais antes de `/{inventory}` e limitar identificadores conforme a convenção das dependências. Aplicar scoping de rodada/tarefa ao inventário/contexto real; um ID aninhado não prova esse vínculo.

### Falhas e repetição

- `401/403/404`: sessão, permissão e registro fora do contexto, conforme as dependências; sem vazamento de dados.
- `422`: campos proibidos, participante inelegível, destinatário fora da rodada, configuração incompleta ou ID de tarefa inválido.
- `409`: versão desatualizada, rodada congelada/fechada, inventário não operável ou tarefa de outro responsável. Usar códigos estáveis distinguíveis, por exemplo `inventory_round_frozen` e `inventory_task_unavailable`.
- Repetir preparação não duplica rodadas/tarefas. Repetir ingresso próprio não duplica ingresso/início. Repetir assunção própria não duplica assunção/evento. Revalidar acesso antes de recuperar sucesso anterior.
- Perda de resposta exige reconsulta. Não repetir automaticamente um salvamento com versão antiga nem afirmar que uma falha de rede desfez a escrita.

## Modelo e protocolo transacional

### Persistência mínima proposta

- `inventory_rounds`: inventário, número, situação, `configuration_version`, critério, autor/horário de preparação e início operacional. Unicidade inventário/número.
- `inventory_round_participants`: rodada/usuário únicos, autoria da seleção e marca opcional de primeiro ingresso, sem presença online fictícia.
- `inventory_count_tasks`: rodada, vínculo ao endereço-produto congelado e responsável opcional, com metadados de atribuição/assunção. Unicidade rodada/endereço-produto.
- Eventos próprios de inventário para configuração, início/ingresso e assunção; reutilizar estrutura compatível caso exista nas dependências, sem misturar com movimentações de estoque.

Usar FKs/constraints que impeçam tarefa com fotografia de outro inventário e responsável não participante da mesma rodada, inclusive por acesso direto ao banco de testes. Uma FK composta é uma alternativa para participação e scoping. Responsável nulo deve continuar válido. Não criar cascatas de exclusão de usuários/cadastros que apaguem histórico.

### Ordem de locks a implementar e comprovar

1. Proteger a situação do cabeçalho do inventário antes das leituras decisivas: lock compatível com outras operações da mesma atividade e com futuro encerramento exclusivo. A preparação inicial exige exclusão para não criar duas vezes.
2. Obter lock exclusivo curto na rodada para salvar configuração, ingressar ou assumir. Se envolver várias rodadas, usar ordem por ID.
3. Obter os locks das tarefas necessárias em ordem por ID; revalidar participação, situação e propriedade sob as travas.
4. Escrever estado e auditoria na mesma transação; só responder sucesso depois do commit externo.

A ordem concreta deve ser reconciliada com a ENG-3114 e documentada para a ENG-3118: cabeçalho → rodada → tarefa. Não adquirir locks em ordem inversa no futuro registro de contagem. Preferir lock compartilhado do cabeçalho nas operações independentes das rodadas para não serializá-las desnecessariamente; o encerramento precisará de lock incompatível antes de invalidar as ações.

Travar a rodada coordena a primeira ação operacional com a última edição administrativa. Se a edição confirma primeiro, o operador revalida o novo estado. Se o operador confirma primeiro, a configuração é recusada integralmente. Incrementar a versão de configuração no salvamento e na transição de congelamento; assunções posteriores não exigem versão global da lista e não devem conflitar artificialmente entre tarefas distintas.

Assunção verifica propriedade antes de produzir efeitos: aberta → atribuir a si; própria → recuperar estado, iniciando participação apenas se necessário; de terceiro → conflito sem evento/início parcial. O guard de bloqueio de movimentação da ENG-3114 não é autorização de contagem e não deve ser chamado para impedir estas ações não quantitativas.

## Roteiro por tarefa

A implementação foi feita em passos focais com testes e revisão; Pint passou nos 30 arquivos PHP focalizados. Resultados e limitações estão registrados nos READMEs de validação. A integração final e os commits locais permanecem pendentes. Os caminhos marcados como candidatos abaixo descrevem o desenho do plano; consulte o estado da execução para os artefatos efetivamente entregues.

### 1. Reconciliar dependências e fechar os contratos — concluída; contratos e API documentados

**Depende de:** implementações ENG-3113/3114 disponíveis em `feature/inventario`; incorporadas às worktrees ENG-3116.

**Ler:** contexto configurável, middleware/Policy, `Inventory`, `InventoryProductAddress`, início, Resources, transporte web e guard de isolamento das dependências; `Domain/User/QueryBuilders/UserQueryBuilder.php`. O app/ENG-3268 consumirá os contratos operacionais em outra execução; não inspecionar nem alterar sua navegação/transporte nesta entrega.

**Artefatos entregues:** `docs/inventory-rounds-api.md` e `docs/validation/eng-3116/README.md` no backend.

1. Confirmar nomes/estados reais e presença da fotografia imutável; documentar a correspondência com os contratos deste plano.
2. Confirmar níveis 1/2/3/4 dentro de Expedição e configuração local do depósito como string. Não consultar ERP nem usar IDs compostos da fixture.
3. Mapear o ponto de preparação do par inicial: após a fotografia no início transacional e comando idempotente para inventários previamente iniciados, sem efeito de leitura GET.
4. Registrar as projeções mínimas administrativas/nativas, eventos disponíveis e estratégia de exclusão histórica; não duplicar eventos/contexto já entregues.
5. Documentar ordem de locks e contrato com ENG-3117/3118, inclusive encerramento futuro concorrente e início de contagem sem atalho de autorização.
6. Preparar branches/worktrees de execução sem interferir em outras sessões e listar testes de regressão realmente existentes.

**Saída:** contrato reconciliado e aprovado pelo desenho, sem bloqueador técnico implícito ou implementação da dependência dentro desta issue.

### 2. Schema de rodadas, participantes, tarefas e eventos — implementado e validado

**Depende de:** 1 e preflight seguro.

**Novos propostos — backend:**
- `database/migrations/<timestamp>_create_inventory_round_task_tables.php`
- `app/Models/Inventory/InventoryRound.php`, `InventoryRoundParticipant.php`, `InventoryCountTask.php`
- `app/Models/Inventory/InventoryEvent.php`, somente se não existir estrutura compatível
- Factories correspondentes em `database/factories/Inventory/`
- `Domain/Inventory/Enums/InventoryRoundStatusEnum.php`
- `tests/Unit/Inventory/InventoryRoundTaskSchemaTest.php`

**Editar:** relações dos models de inventário/fotografia e opt-in seguro das suítes em `tests/Pest.php`, quando necessário.

1. Testar unicidade do número da rodada, participação e tarefa, com duas rodadas contendo o mesmo produto/endereço sem colisão.
2. Testar responsável nulo, participante da mesma rodada, fotografia do mesmo inventário e recusa de referências cruzadas por constraints, não só validação PHP.
3. Testar que usuário/produto/endereço não apaga tarefas, participantes ou autoria por cascade; preservar o soft delete existente.
4. Implementar migrations/relações e índices de consulta por rodada/responsável, sem alterar tabelas de quantidades ou criar saldos de referência.
5. Testar rollback restrito às estruturas novas no banco descartável. Não apresentar o rollback como procedimento de produção com inventários ativos.

**Validar:** `./vendor/bin/pest tests/Unit/Inventory/InventoryRoundTaskSchemaTest.php` após preflight.

### 3. Elegibilidade e autorização administrativa/operacional — implementada e validada

**Depende de:** 1–2.

**Novos propostos:**
- `Domain/Inventory/Queries/InventoryEligibleParticipantQuery.php`
- `Domain/Inventory/Services/InventoryExecutionAccessService.php`
- `Domain/Inventory/Resources/InventoryParticipantResource.php`
- `app/Http/Controllers/Inventory/InventoryParticipantController.php`
- `app/Http/Middleware/EnsureInventoryExecutionAccess.php`, se necessário à composição existente
- `tests/Feature/Inventory/InventoryParticipantEligibilityTest.php`, `InventoryExecutionAccessTest.php`

**Editar:** `routes/api.php`, Policy do inventário e middleware administrativo apenas para compor as rotas, sem mudar o bypass global de outros módulos.

1. Testar catálogo com usuários não excluídos dos quatro perfis na Expedição; excluir System, usuários de outros setores e perfis nativos não aprovados.
2. Criar o caso de perfil elegível apenas no Almoxarifado e perfil não elegível na Expedição. Ele não entra no catálogo por combinação indevida dos filtros genéricos.
3. Autenticar com abilities reais de teste. Cobrir sessão ativa em outro setor, perfil ativo não aprovado, acesso revogado e usuário excluído mesmo com token anterior.
4. Cobrir Master/Admin selecionados e não selecionados; não deixar o bypass administrativo substituir a participação operacional.
5. Proibir autoria/operador-alvo no corpo de ingresso/assunção. Destinatários da configuração continuam permitidos, validados separadamente.
6. Confirmar que ID de rodada/tarefa de outro contexto não vaza dados e que os quatro perfis conseguem usar as rotas operacionais sem middleware administrativo indevido.

**Validar:** testes focais de elegibilidade/acesso e regressão de acesso da ENG-3113.

### 4. Preparação idempotente das duas rodadas iniciais — implementada e validada

**Depende de:** 2–3.

**Novos propostos:**
- `Domain/Inventory/Services/InventoryInitialRoundsService.php`
- `app/Http/Controllers/Inventory/InventoryRoundController.php`
- `Domain/Inventory/Resources/InventoryRoundSummaryResource.php`
- `tests/Feature/Inventory/InventoryInitialRoundsTest.php`

**Editar:** serviço transacional de início da ENG-3114, suas factories/testes e `routes/api.php`.

1. Testar preparação somente de inventário iniciado/operável, sem participantes, produzindo exatamente as rodadas 1 e 2 e tarefas abertas completas.
2. Usar a fotografia, não o cadastro vivo ou a página atual. Cobrir produto em vários endereços, endereços sem saldo, itens/OPs repetidos e volume maior que uma página.
3. Repetir comando/início e verificar mesmos IDs, ausência de tarefas/rodadas duplicadas e preservação de configurações já salvas. Não criar terceira rodada por repetição.
4. Integrar a preparação no início após a fotografia, na mesma transação, sem exigir participantes e sem alterar os bloqueios. Falha injetada deve reverter todo o início integrado.
5. Manter o comando administrativo idempotente para registros já iniciados pela ENG-3114; abrir gestão pode acioná-lo explicitamente pela API, nunca por GET ou reinício artificial.
6. Reler após falha e provar ausência de par parcial, tarefas órfãs, resolução de abrangência pelo catálogo vivo ou nova integração ERP.

**Validar:** `InventoryInitialRoundsTest` e testes de atomicidade/repetição do início da ENG-3114.

### 5. Consultas gerenciais/nativas e sugestão completa — implementadas e validadas

**Depende de:** 3–4.

**Novos propostos:**
- `Domain/Inventory/Queries/InventoryRoundTaskQuery.php`
- `Domain/Inventory/Services/InventoryDistributionPreviewService.php`
- `Domain/Inventory/Resources/InventoryRoundConfigurationResource.php`, `InventoryOperatorRoundResource.php`, `InventoryOperatorTaskResource.php`
- `app/Http/Requests/InventoryDistributionPreviewRequest.php`, `InventoryTaskSearchRequest.php`
- `app/Http/Controllers/Inventory/InventoryOperatorTaskController.php`
- `tests/Feature/Inventory/InventoryRoundQueriesTest.php`
- `tests/Unit/Inventory/InventoryDistributionPreviewTest.php`

**Editar:** controller de rodadas e `routes/api.php`.

1. Testar que a gestão lê os participantes e mapa completo, enquanto o app recebe somente rodadas selecionadas e tarefas próprias/abertas autorizadas.
2. Testar ausência de saldo, lançamentos/resultados de outras rodadas, credenciais e fallback cadastral fictício nos Resources nativos, inclusive no detalhe de recuperação.
3. Testar paginação/busca estáveis e totais sobre o conjunto real. Consultar não altera início, versão, participantes ou eventos.
4. Para os três critérios, ordenar por metadados da fotografia e desempates estáveis; dividir em blocos balanceados pela quantidade. Testar mais participantes que tarefas, ausência real de família e divisão permitida de um produto/família.
5. Prévia considera a edição de participantes enviada, validada no servidor, mas não salva nada. Cobrir tarefa fora da página, mais de 100 tarefas, repetição determinística e troca da ordem incidental das consultas.
6. Mostrar indisponibilidade na reconsulta de tarefa assumida por terceiro sem expor o novo responsável; registros externos continuam inacessíveis.
7. Carregar relações em lote e verificar ausência de N+1 relevante. Não alterar índices de estoque ou Resources globais sem necessidade demonstrada.

**Validar:** consultas e sugestão focais; regressão de acesso.

### 6. Salvamento atômico da configuração antes do início — implementado e validado

**Depende de:** 3–5.

**Novos propostos:**
- `Domain/Inventory/DTOs/InventoryRoundConfigurationDTO.php`
- `Domain/Inventory/Services/InventoryRoundConfigurationService.php`
- `Domain/Inventory/Services/InventoryEventRecorder.php`, se necessário
- `Domain/Inventory/Exceptions/InventoryRoundConflictException.php`
- `app/Http/Requests/InventoryRoundConfigurationRequest.php`
- `tests/Feature/Inventory/InventoryRoundConfigurationTest.php`

**Editar:** controller de rodadas, Resources e rotas.

1. Testar atribuição direta, ajustes individuais/em lote, tarefas abertas e edição independente em cada rodada.
2. Exigir participantes e tarefas distintos, configuração completa e destinatários selecionados/elegíveis. Recusar omissões, duplicações, fotografia externa, campos proibidos e remoção de participante ainda responsável.
3. Salvar sob a ordem de locks definida, comparando versão e ausência de início depois da trava. Incrementar versão no servidor e registrar autor real/diferenças relevantes.
4. Atualizar participantes/atribuições na ordem compatível com as FKs: incluir destinatários novos, ajustar tarefas e só então retirar vínculos dispensados. Nenhuma fase intermediária pode confirmar sozinha.
5. Injetar falha na atualização ou auditoria: nada persiste parcialmente. Testar duas edições da mesma versão, repetição com versão antiga e versão não atribuível pelo cliente.
6. Aceitar configuração sem participantes somente se todas as tarefas estiverem abertas; não habilitar assunção por usuário não selecionado.
7. Não refazer sugestão implicitamente ao trocar critério/participantes. Não criar comando de ajuste após início.

**Validar:** `InventoryRoundConfigurationTest`, constraints e testes de consultas.

### 7. Ingresso, congelamento e assunção exclusiva — implementados e validados

**Depende de:** 3–6.

**Novos propostos:**
- `Domain/Inventory/Services/InventoryRoundEnterService.php`
- `Domain/Inventory/Services/InventoryTaskClaimService.php`
- `Domain/Inventory/Exceptions/InventoryTaskUnavailableException.php`
- `app/Http/Controllers/Inventory/InventoryRoundExecutionController.php`
- `tests/Feature/Inventory/InventoryRoundEnterTest.php`, `InventoryTaskClaimTest.php`

**Editar:** Resources/rotas operacionais e helper compartilhado de proteção transacional, somente se necessário.

1. Testar ingresso explícito, primeira assunção implícita e repetição: registrar primeiro início/ingresso sem duplicar evento e congelar somente aquela rodada.
2. Reler identidade/acesso, cabeçalho, rodada, participação e tarefa sob as travas antes de alterar propriedade. Não confiar em modelos carregados antes da disputa.
3. Assumir tarefa aberta para o usuário autenticado; recuperar tarefa própria sem novo evento de assunção; recusar tarefa de outro usuário sem alteração/início parcial.
4. Testar novas assunções após congelamento e recusa de qualquer configuração, entrada gerencial de novo participante, devolução ou troca de proprietário posterior.
5. Cobrir usuário presente em ambas as rodadas e mesma tarefa lógica assumida independentemente nelas; não criar exclusividade por produto/endereço fora da rodada.
6. Simular falha de auditoria: atribuição, ingresso e congelamento revertem juntos. Passagem de tempo, saída da tela, perda de sessão e revogação de acesso não limpam responsável.
7. Manter a extensão para ENG-3117: antes de registrar contagem, usar autorização/propriedade e o mesmo contrato de ingresso. Não adicionar quantidade, conclusão de tarefa ou encerramento nesta tarefa.
8. Preparar a recusa de ações em rodada/inventário fechados por estados simulados nos testes, sem implementar o encerramento da ENG-3118.

**Validar:** ingresso/assunção/configuração e testes de ausência de efeitos quantitativos.

### 8. Concorrência PostgreSQL real e efeitos externos — concorrência focal validada; integração E2E pendente

**Depende de:** 4–7. Executar apenas no banco descartável, sem reset paralelo de schema.

**Novos propostos:**
- `tests/Feature/Inventory/InventoryTaskClaimConcurrencyTest.php`
- `tests/Feature/Inventory/InventoryRoundFreezeConcurrencyTest.php`
- `tests/Support/InventoryTaskConcurrencyWorker.php`
- `tests/Feature/Inventory/InventoryAssignmentSideEffectsTest.php`

**Referências existentes:** `tests/Support/ReclassificationPickingConcurrencyWorker.php` e testes de concorrência em `tests/Feature/PickingOrder/`.

1. Usar processos/conexões independentes, guard de banco em todos e dados confirmados visíveis aos workers. Não manter a fixture em transação invisível de `RefreshDatabase` durante a disputa.
2. Sincronizar com barreiras/locks e comprovar a espera; não usar somente chamadas sequenciais ou `sleep`. Limitar timeouts e limpar processos em falha.
3. Dois operadores assumem a mesma tarefa: um único proprietário/evento; perdedor recebe conflito. Repetição própria retorna o mesmo estado.
4. Disputar configuração com assunção/ingresso nas duas ordens: edição primeiro obriga revalidação; início primeiro recusa a edição integralmente, sem destinatário removido assumindo por estado antigo.
5. Disputar duas preparações iniciais, a mesma ação pelo mesmo operador e tarefas distintas nas duas rodadas; não duplicar IDs/eventos nem impor exclusividade global indevida.
6. Exercitar o contrato de lock do cabeçalho com uma mudança de situação terminal simulada em teste, sem implementar endpoint de encerramento. Provar que ação não confirma após encerramento já confirmado.
7. Bloquear HTTP/SOAP/Senior e qualquer integração externa nos workers/testes. Comparar estoque, movimentações, bloqueios e filas antes/depois: preparação, distribuição e assunção não alteram quantidades nem liberam bloqueios.
8. Repetir os testes de disputa e registrar resultados reais. Distinguir ausência de efeito externo de uma chamada externa apenas mockada permissivamente.

**Saída:** prova de exclusividade e congelamento sem janela de corrida, com auditoria atômica.

### 9. Transporte e estado de edição gerencial na web — implementados e validados

**Depende de:** contratos 4–7 e transporte persistido das dependências.

**Novos propostos — `rex-front`:**
- `src/pages/Inventory/distribution.mjs`, `distribution.test.mjs`
- `src/pages/Inventory/rounds.mjs`, `rounds.test.mjs`

**Editar:** `src/domain/Inventory/services/InventoryService.jsx` e `src/pages/Inventory/isolation.test.mjs`.

1. Testar normalização de IDs, mapa completo de tarefas, responsáveis nulos, configuração por rodada, pendências de remoção de participante e payload sem autoria/contexto arbitrários.
2. Acrescentar métodos de participantes, preparação, consultas, prévia e salvamento ao transporte autenticado existente. Não criar outro cliente HTTP ou usar `operations.mjs`/store local.
3. Manter edição em memória separada do confirmado, com versão. Mudar critério/participantes não aplica sugestão automaticamente; cancelar prévia preserva ajustes manuais.
4. Preservar alterações fora da página/filtro e não salvar somente tarefas visíveis. Preservar seleção de pessoas fora da busca/página do diálogo.
5. Tratar cancelamento, respostas fora de ordem e troca de sessão/contexto; a consulta de uma rodada não sobrescreve a edição da outra.
6. Ampliar teste do grafo de runtime: nenhum import transitivo de fixture, catálogo demonstrativo, `model.mjs`, `store.mjs`, `operations.mjs` ou simulador.

**Validar:** `node --test src/pages/Inventory/distribution.test.mjs src/pages/Inventory/rounds.test.mjs src/pages/Inventory/isolation.test.mjs` e testes existentes de helpers/permissões.

### 10. Interface gerencial conectada à API — implementada; E2E focal com mock aprovado

**Depende de:** 9 e backend funcional 4–7.

**Editar — `rex-front/src/pages/Inventory/`:** `Management.jsx`, `Distribution.jsx`, `Distribution.css`, `OperatorPicker.jsx`, `OperatorPicker.css`, entrada/detalhe persistido e permissões quando necessário.

**Novos candidatos:** `InventoryRoundPanel.jsx` e estilos locais, somente se a composição existente não atender ao contrato sem acoplamento simulado.

1. Disponibilizar Gerenciar contagens em inventário iniciado; carregar/preparar as rodadas pela API conforme contrato. Não trazer as ações simuladas de `Decisions.jsx` ou o painel web do app para o runtime.
2. Exibir configuração separada das duas rodadas, participantes, resumo de tarefas por responsável e abertas. Reaproveitar aparência e interação dos componentes compatíveis.
3. Integrar busca de pessoas com seleção provisória, Aplicar/Cancelar, busca/paginação e nomes preservados fora da página. Não oferecer novo cadastro/perfil ou trocar sessão para simular o selecionado.
4. Implementar Atribuir/Deixar aberta individualmente e em lote, inclusive seleção visível/parcial, e confirmação antes de substituir atribuições por sugestão.
5. Ao remover pessoa com tarefas, indicar o que precisa ser resolvido antes de salvar; não recalcular automaticamente.
6. Aguardar sucesso do salvamento antes de confirmar/fechar. Em `409`, preservar a edição e oferecer reconsulta explícita, sem merge/sobrescrita silenciosos. Após início confirmado, mostrar somente leitura na rodada afetada.
7. Validar foco, teclado, Escape, diálogo dentro do painel, busy state, erro/vazio e layouts 390/1280/1440. Não refatorar componentes globais por conveniência.

**Validar:** testes de helpers, lint focal, build e E2E web da tarefa 13.

### 11. Transporte tipado e entrada de inventários no app — adiada para ENG-3268; não executar nesta etapa

**Depende de:** contratos operacionais 3, 5 e 7. Pode iniciar com respostas sintéticas apenas nos testes.

**Novos propostos — `Rex-Estoque`:**
- `src/domain/erp/entities/InventoryTask.ts`
- `src/domain/erp/services/InventoryTaskService.ts`, `InventoryTaskService.test.ts`
- `src/routes/inventoryAccess.ts`, `inventoryAccess.test.ts`
- `src/pages/Inventarios/InventariosRouter.tsx`
- `src/routes/inventory.navigation.test.tsx`

**Editar:** `src/routes/drawer.routes.tsx`. Não modificar `bottomTab.routes.tsx` ou preferências globais sem necessidade da navegação escolhida.

1. Testar serviços tipados para rodadas, tarefas, detalhe de recuperação, ingresso e assunção. Reutilizar `getApi`, token de `getUserPrefs` e mensagens de `userMessage`; não criar outra autenticação ou URL fixa de instância.
2. Garantir que ingresso/assunção não enviam ator/operador. Não copiar os payloads de destinos gerenciais para o comando nativo.
3. Expor Inventários no drawer somente para sessão ativa da Expedição nos níveis 1/2/3/4. Manter as rotas internas protegidas e deixar a API decidir participação real.
4. Testar navegação real aninhada com o padrão de `outputTasks.navigation.test.tsx`, incluindo primeiro acesso, escolha de outra rodada e saída de contexto sem manter tela anterior.
5. Não compartilhar cache de tarefas entre usuários/setores. Se houver cache em memória, chavear por identidade/contexto e descartar no logout/troca; não gravar tarefas em SQLite/AsyncStorage.
6. Não alterar permissões dos perfis 5/6, enum global de usuários, EAS, leitor ou sincronização de outros módulos.

**Validar:** Jest focal de serviço, acesso e navegação; TypeScript no contexto da base existente.

### 12. Telas nativas, início e recuperação de assunção — adiada para ENG-3268; não executar nesta etapa

**Depende de:** 11 e backend operacional funcional.

**Novos propostos — `Rex-Estoque/src/pages/Inventarios/`:**
- `Inventarios.tsx`, `InventoryRoundTasks.tsx`, `styles.ts`
- `useInventoryTasks.ts`, `useInventoryTasks.test.ts`
- `InventoryRoundTasks.test.tsx`

1. Listar somente rodadas elegíveis e permitir escolher inventário/rodada sem iniciar por mera navegação.
2. Exibir Minhas tarefas/Tarefas abertas com busca/paginação, produto, endereço, unidade e contexto. Não portar `MobileApp.jsx`, WebView, seletor de operador ou dados demonstrativos.
3. Implementar Iniciar rodada e Assumir tarefa aguardando confirmação, bloqueando duplo envio e informando que iniciar congela a configuração da rodada.
4. Após sucesso, atualizar ambas as listas/totais pelo servidor. Não permitir assumir tarefa pelo simples toque de seleção ou por confirmação otimista local.
5. Em conflito, mostrar mensagem legível e atualizar disponibilidade. Em perda de resposta, reconsultar a tarefa: própria confirma sucesso, aberta permite nova tentativa explícita, indisponível informa conflito sem fingir que nada ocorreu.
6. Em navegação/contexto alterados, cancelar/ignorar respostas antigas; no retorno à tela, revalidar os dados. Uma tarefa não desaparece da responsabilidade por sair da tela ou perder conexão.
7. Cobrir `401/403/409/422`, loading, vazio, erro de leitura, retry, acessibilidade nativa e preservação da rodada escolhida. Não tratar página vazia como ausência total de tarefas.
8. Não criar formulário de quantidade, leitura unitária, barra de progresso baseada em resultados fictícios, devolução ou conclusão global. A ENG-3117 acrescentará a execução sobre o mesmo task ID.

**Validar:** Jest dos hooks/telas, navegação e serviço; smoke nativo previsto na tarefa 13.

### 13. E2E web/backend e regressão — pendente

**Depende de:** tarefas backend/web 1–10 e concorrência backend da tarefa 8. A integração e o smoke do app são responsabilidade posterior da ENG-3268.

**Novos propostos — web:** `e2e/inventory/persisted/distribution.spec.mjs`, `distribution-errors.spec.mjs`.

**Evidências:** `docs/validation/eng-3116/README.md` no backend e no frontend.

1. Cobrir web com participantes, sugestão por critérios, ajustes, tarefas abertas, cancelamento de redistribuição e paginação. Testar o conflito/freeze de início pelos contratos reais do backend; não depender do app.
2. Reutilizar setup persistido das dependências. Testes web históricos que injetam inventários em localStorage ou bloqueiam qualquer API não certificam esta entrega.
3. Em ambiente descartável, usar gestor e dois operadores reais: gestor seleciona equipe; um vê tarefas próprias; ambos veem a mesma aberta; assunção concorrente deixa um proprietário; o outro recebe conflito; gestão passa a somente leitura somente nessa rodada; a outra continua editável.
4. Confirmar refresh/reabertura compartilhados, mesma pessoa nas duas rodadas, participante não selecionado recusado e operador sem tarefas próprias conseguindo assumir uma aberta elegível.
5. Testar repetição, conflitos e recuperação dos comandos backend por HTTP/API. Repetir ações pelo API client para provar que a UI não é a única proteção; recuperação de resposta nativa fica para a ENG-3268.
6. Usar respostas sintéticas somente para comportamento da UI. Concorrência PostgreSQL da tarefa 8 é obrigatória; não substituí-la por chamadas sequenciais ou telas mockadas. Não declarar o aceite nativo homologado: ele está fora desta etapa e pertence à ENG-3268.
7. Revisar ausência de ERP, alteração de quantidades/liberação de bloqueios, perfis novos, devolução/expiração e código das issues seguintes. Não alterar o app; a regressão nativa será executada ao implementar a ENG-3268.
8. Rodar validações abaixo no runtime/ambiente apropriado, revisar diffs e registrar comandos, resultados, capturas e bloqueios reais. Não corrigir falhas preexistentes sem necessidade da issue.

**Comandos futuros — backend, após preflight:**

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

**Comandos futuros — web:**

```bash
node --test src/pages/Inventory/*.test.mjs
npm test
npm run lint
npm run build
# Com Vite/URLs configurados para a instância de testes:
npx playwright test --config=e2e/inventory/playwright.config.mjs
```


Adequar os comandos à entrega real das dependências e à configuração do runner; não versionar credenciais/hosts/portas de instância. Falhas preexistentes devem ser identificadas separadamente. Não executar comandos nem alterar dependências de `Rex-Estoque`. Revisar `git diff --check`, `git diff --stat` e escopo dos dois repositórios antes dos commits/PRs.

## Matriz de aceite da execução

| Critério | Tarefas/evidências obrigatórias |
| --- | --- |
| Gestão escolhe operadores existentes e distribui por localização/família/produto, com ajuste manual | 3, 5–6 e 9–10: elegibilidade contextual, prévia completa/determinística, ajustes, abertas, paginação e UI. |
| Atribuições independentes por rodada | 2, 4, 6–8 e 13: mesmas identidades de produto/endereço/operador nas duas rodadas sem contaminação; congelamento separado. |
| Operador vê tarefas nativas e assume abertas | Adiado para ENG-3268. Esta execução entrega os contratos backend necessários, sem implementação ou teste nativo. |
| Uma aberta só pode ser assumida por uma pessoa, inclusive concorrentemente | 2, 7–8 e 13: proprietário único, disputa PostgreSQL independente, repetição própria, conflito e recuperação por API. |
| Autoria autenticada, sem perfil Inventariante | 3, 6–7 e 13: token/contexto reais, payload sem ator, auditoria atômica e ausência de enum/permissão nova. O app sem seletor será validado pela ENG-3268. |
| Regra adicional aprovada: congelar gestão após primeiro início | 6–8, 10 e 13: corrida com configuração e recusa integral; sem devolução, troca ou expiração posterior. |
| Sem ERP, quantidades, saldos ou runtime simulado | 5, 8–10 e 13: Resources mínimos, dependências externas bloqueadas, grafo de imports web, estoque/bloqueios preservados e sem storage de inventário. |

## Checklist final e transição para as próximas issues

- [ ] Todos os critérios de backend/web possuem evidência real, e testes mockados estão identificados como tais. O aceite nativo e a conclusão integral do aceite original dependem da ENG-3268.
- [x] Schema/constraints, scoping e acesso ativo foram testados, inclusive Master e nível em setor diferente.
- [x] Nenhuma leitura inicia rodada; primeiro ingresso/assunção e congelamento são atômicos.
- [x] Não existem comandos de devolver, expirar, trocar responsável ou editar participantes depois do início.
- [ ] Documentado para ENG-3117: task ID, propriedade, ingresso, autorização, projeção cega e ordem de locks; contagem não pode assumir tarefa implicitamente por payload de outro ator.
- [ ] Documentado para ENG-3118: estrutura reutilizável de rodada, duas rodadas iniciais independentes, tarefas ligadas à fotografia e contrato de encerramento que invalida ações sem apagar histórico.
- [x] Validado que atribuir/assumir não toca bloqueios ou quantidades e não chama ERP.
- [ ] Evidências, limitações, commits e referências cruzadas do backend e frontend registrados, sem segredos ou mudanças alheias; `Rex-Estoque` permanece intocado.

## Nota de planejamento

A skill `writing-plans` não estava instalada quando este plano foi criado. A execução agora autorizada abrange backend e interface web nas worktrees ENG-3116, com base em `feature/inventario`; o app nativo continua separado na ENG-3268. O código e as validações desta etapa são registrados nos commits de desenvolvimento. Nenhum arquivo de `Rex-Estoque` integra o escopo.
