# ENG-3116 — Distribuir ou assumir tarefas de contagem

**Status:** desenho aprovado por seções em 2026-11-06; somente planejamento, sem autorização para implementar.
**Issue:** https://linear.app/soelx/issue/ENG-3116/distribuir-ou-assumir-tarefas-de-contagem
**Pré-requisitos:** [desenho da ENG-3113](2026-11-05-eng-3113-inventario-manual-design.md), [plano da ENG-3113](2026-11-05-eng-3113-inventario-manual-implementation-plan.md), [desenho da ENG-3114](2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-design.md) e [plano da ENG-3114](2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-implementation-plan.md).

## Objetivo e limites

Permitir que a gestão selecione usuários existentes por rodada e distribua tarefas por produto e endereço, diretamente ou por sugestão de localização, família ou produto. Uma tarefa sem responsável permanece aberta para assunção exclusiva por um participante elegível no aplicativo nativo Rex-Estoque.

Preservar o contexto aprovado **Expedição ↔ depósito 004**, obtido da configuração da ENG-3113, e a fotografia operacional da ENG-3114. Não resolver novamente a abrangência pelo cadastro vivo, alterar quantidades, consultar saldos ou enviar ajustes ao ERP.

A entrega abrange participantes, duas rodadas iniciais, distribuição, início da participação, consulta e assunção. Modalidades, lançamentos, zeros e correções pertencem à ENG-3117. Recontagens, resultados, conclusão de rodadas e encerramento local pertencem à ENG-3118.

## Decisões confirmadas na conversa

1. Somente participantes selecionados pela gestão **naquela rodada** podem assumir tarefas abertas.
2. Os participantes elegíveis são usuários existentes, não excluídos, com acesso ao Rex-Estoque na Expedição: **Master, Administrador, Armazenador e Separador**. Não criar perfil ou permissão “Inventariante”.
3. A gestão exige Administrador/Master com sessão ativa na Expedição, como nas dependências. Um administrador que queira executar também precisa estar selecionado na rodada.
4. Participantes e distribuição congelam assim que qualquer operador inicia operacionalmente a respectiva rodada. Não permitir ajuste gerencial posterior, mesmo de tarefas ainda sem contagem.
5. Assunções de tarefas que permaneceram abertas continuam permitidas depois desse congelamento. Não são redistribuições gerenciais.
6. Não haverá devolução, expiração, liberação automática ou troca de responsável após o início. Uma interrupção do trabalho não devolve a tarefa à lista aberta.
7. Apenas consultar listas não inicia a rodada. A primeira ação **Iniciar rodada** ou **Assumir tarefa** registra o início operacional.
8. A sugestão preserva o comportamento do protótipo: ordenação pelo critério e divisão em blocos equilibrados pela quantidade de tarefas. Não otimiza rotas nem garante grupos indivisíveis.
9. Alterar critério ou participantes não substitui atribuições silenciosamente. Uma nova distribuição exige ação e confirmação explícitas.
10. Toda ação usa a identidade autenticada. Não transportar a troca de personagem do simulador para o aplicativo real.

## Contexto dos repositórios

A inspeção inicial encontrou documentação, mas nenhuma implementação das ENG-3113/3114. Os nomes novos de tabelas, classes e endpoints são contratos propostos: reconciliar com a entrega efetiva das dependências antes de implementar, sem duplicar o contexto de inventário.

| Repositório | Situação/base para a execução futura |
| --- | --- |
| `rex-back` | Incorporar a implementação da ENG-3114 sobre a ENG-3113. Documentação desta issue em `feature/eng-3116`, worktree `rex-back-eng-3116`, criada de `feature/eng-3114` em `60600299`. |
| `rex-front` | Criar a branch da issue sobre o fluxo persistido da ENG-3114, que depende da ENG-3113 e do protótipo `eng-2966` (`67305ddb`). Não usar uma `main` sem o módulo aprovado. |
| `Rex-Estoque` | Criar a branch da issue sobre a base aprovada do app, inspecionada em `main`, commit `7aec310`. Ainda não existe módulo de inventário nativo. |

O documento em `rex-back/docs/plans/` é referência comum aos três repositórios. Não trocar branches ou modificar alterações de outras sessões. Durante a análise, as worktrees principais mudaram para `main` e o app apresentou alteração preexistente em `.easignore`; nada disso integra esta issue.

A ENG-3115 pode fornecer navegação e acompanhamento, mas não é bloqueadora desta entrega. Coordenar os pontos de integração sem duplicar a consulta gerencial ou exigir sua implementação.

## Abordagens consideradas

| Abordagem | Benefícios | Custos ou riscos |
| --- | --- | --- |
| **Tarefas relacionais persistidas por rodada — escolhida** | Integridade dos vínculos, consulta individual, auditoria e assunção concorrente autoritativa no backend. Reaproveita a interface gerencial. | Exige schema, comandos transacionais e integração nativa. |
| Distribuição dinâmica por regras | Menor materialização inicial. | Dificulta ajustes por tarefa, congelamento, reprodução e independência dos cadastros posteriores. |
| Persistir o JSON do protótipo | Menor adaptação inicial do estado local. | Acopla simulação e negócio; dificulta constraints, compartilhamento e concorrência real. |

Reaproveitar os componentes visuais, não o store, a fixture, os atores simulados ou as transições locais.

## 1. Estrutura, abrangência e rodadas

Após o início do inventário, preparar **duas rodadas iniciais**, conforme o aceite da ENG-3118. A preparação não exige participantes. Selecionar participantes e distribuir tarefas nunca são condições para iniciar o inventário ou manter seus bloqueios da ENG-3114.

Cada rodada possui participantes próprios e uma tarefa por **produto + endereço da fotografia operacional**. OPs, lotes e itens repetidos não criam tarefas adicionais. Não limitar a geração à página visível, a endereços com saldo ou ao grupo que originalmente selecionou o produto.

A preparação é transacional e idempotente: não duplicar rodadas ou tarefas quando o comando for repetido. Não criar rodadas por efeito colateral de uma leitura GET. A integração futura pode preparar o par no fluxo de início e usar um comando administrativo explícito/idempotente para inventários já iniciados pela versão anterior.

As tarefas nascem abertas. A mesma pessoa pode participar de ambas as rodadas e assumir o mesmo par produto/endereço em cada uma; não existe exclusividade entre rodadas nem rotação obrigatória de operadores.

### Persistência proposta

- **Rodadas:** inventário, número único dentro dele, situação, versão da configuração e início operacional com autor/horário. Nesta issue, implementar preparação e início, não encerramento ou recontagem operacional.
- **Participantes por rodada:** vínculo único a usuários reais. Seleção gerencial não representa presença online. Se houver marca de primeiro ingresso, preservá-la sem simular sessões conectadas.
- **Tarefas:** vínculo único de rodada com endereço-produto da fotografia; responsável opcional e dados de atribuição/assunção. Um único responsável persistido é a fonte de propriedade.
- **Eventos de auditoria:** configuração, início e assunção, com autoria autenticada, horário e vínculos mínimos para explicar a alteração.

Proteger por constraints a unicidade rodada/número, participante/rodada e tarefa/rodada/endereço-produto. Impedir vínculos de tarefa a fotografia de outro inventário e atribuição a usuário que não seja participante da mesma rodada. Responsável nulo é válido. Exclusões cadastrais não podem apagar tarefas ou autoria em cascata.

Não persistir o estado completo do protótipo como JSON. Uma representação estruturada do detalhe de um evento não substitui o modelo relacional de tarefas e participantes.

## 2. Elegibilidade e autorização

O catálogo de participantes considera o cadastro atual: usuário não excluído, não técnico e com ao menos um dos quatro perfis aprovados **na Expedição**. Um perfil no Almoxarifado e outro na Expedição não podem ser combinados para produzir elegibilidade indevida.

A consulta genérica de usuários inspecionada filtra nível e setor separadamente. Não presumir que adicionar os dois filtros garante que o nível pertença ao setor desejado. Usar uma consulta contextual específica ou composição que valide o par exato.

Validar a elegibilidade ao sugerir e salvar a configuração. Para as ações operacionais, exigir sessão ativa na Expedição com nível aprovado, acesso cadastral atual e participação na rodada. Revalidar também a situação operacional do inventário e da rodada. Revogar acesso não transforma a tarefa em aberta nem apaga sua atribuição/histórico.

Não aplicar o middleware administrativo indiscriminadamente às rotas do aplicativo. Não depender de bypass global de Master nas Policies: Master fora do contexto ou não selecionado não executa a rodada.

O cliente pode indicar **destinatários** ao configurar atribuições; nunca indica a **autoria** da configuração, início ou assunção. Essa autoria vem exclusivamente da autenticação do servidor.

## 3. Distribuição pela gestão

No detalhe persistido, disponibilizar **Gerenciar contagens**, com visualização e configuração separadas para cada rodada.

Reaproveitar `OperatorPicker.jsx`, `Distribution.jsx` e a composição visual de `Management.jsx`, removendo dependências simuladas. Manter busca, seleção provisória no diálogo, cancelamento, foco e seleção preservada fora do filtro.

### Sugestão e ajustes

1. Selecionar participantes da rodada, sem alterar a identidade da sessão.
2. Consultar todas as tarefas da fotografia, com paginação apenas da apresentação.
3. Atribuir individualmente, em lote ou acionar **Distribuir** por localização, família ou produto.
4. A sugestão ordena as tarefas pelo critério, com desempate estável por identidades, e divide blocos contíguos entre participantes em ordem explícita e determinística. O número de tarefas por pessoa difere no máximo em uma; mais participantes que tarefas é permitido.
5. Localização usa a hierarquia/metadados preservados da fotografia; família e produto também usam os dados dessa abrangência, sem reavaliar vínculos de estoque atuais. Ausência de família é um caso cadastral real, sem criar família fictícia.
6. A sugestão pode dividir tarefas de um produto ou família entre pessoas. Não prometer proximidade física, carga por quantidade de estoque ou rota otimizada.
7. Mudar o critério apenas reorganiza a visualização. Substituir atribuições existentes por uma sugestão exige confirmação explícita.
8. Disponibilizar **Atribuir** e **Deixar aberta**, inclusive em lote. Tarefas abertas são um resultado válido, não erro de configuração.
9. Remover participante exige revisar suas atribuições, reatribuindo-as ou deixando-as abertas. Não recalcular ou apagar essas atribuições silenciosamente.
10. Salvar participantes e atribuições juntos, com a versão lida da configuração, em uma única transação.

A sugestão deve ser autoritativa no backend e pode ser pré-visualizada sem persistir. O servidor deriva o universo de tarefas da rodada, não de IDs de produtos/endereços arbitrários enviados pelo navegador. Salvar exige uma configuração completa e válida, independentemente das páginas carregadas.

Enquanto a rodada não iniciou, pode ser salva sem participantes se todas as tarefas permanecerem abertas. Ela só estará acessível no app a quem for selecionado; nenhum usuário pode se incluir por conta própria.

## 4. Início operacional e congelamento

Consultar inventários, rodadas ou listas de tarefas não registra início. O operador selecionado inicia explicitamente por **Iniciar rodada** ou implicitamente ao confirmar **Assumir tarefa**.

A primeira ação válida registra autor/horário do início operacional. A partir daí:

- participantes, critério gerencial e distribuição ficam congelados;
- tarefas diretamente atribuídas mantêm o responsável;
- tarefas abertas continuam abertas até uma assunção válida;
- novas assunções não autorizam ajuste gerencial, entrada de novos participantes, devolução ou troca de proprietário;
- sair da tela, trocar de sessão, perder conexão ou passar um prazo não libera tarefas;
- o início da rodada 1 não congela a rodada 2.

Coordenar salvamento gerencial, ingresso e assunção com a mesma trava curta da rodada. Validar situação e versão depois da trava, não apenas antes. Se a edição vence, a operação relê participantes e tarefas atualizados; se o início vence, a edição retorna conflito sem persistência parcial.

O congelamento é uma regra de domínio, não apenas controles desabilitados na tela. O registro de contagem da ENG-3117 deve usar o mesmo contrato de ingresso/validação, sem criar um atalho que permita lançar antes do congelamento ou em tarefa de outra pessoa.

## 5. App nativo e assunção exclusiva

Adicionar **Inventários** à navegação do Rex-Estoque para o contexto/perfis aprovados. Consultar somente rodadas em que a identidade autenticada foi selecionada.

O fluxo permite escolher inventário e rodada e alternar entre **Minhas tarefas** e **Tarefas abertas**. Mostrar identidade do produto, endereço, unidade e contexto necessários ao trabalho. Não usar o Resource administrativo completo: omitir saldos, resultados de outras rodadas e dados gerenciais desnecessários.

Não portar `MobileApp.jsx` como WebView ou simulador. Aproveitar sua organização visual como referência, usando componentes e transporte nativos existentes. Não incluir seletor de operador.

### Comando de assunção

1. Autenticar e autorizar a identidade real e o contexto ativo.
2. Na transação, proteger a situação do inventário e obter as travas da rodada e tarefa em ordem consistente com os demais comandos.
3. Reler rodada, participação, situação e propriedade. Aceitar somente tarefa da rodada solicitada e de sua fotografia.
4. Se aberta, atribuir à identidade autenticada; registrar início operacional se ainda não ocorreu e persistir a auditoria na mesma transação.
5. Se já pertence ao mesmo operador, recuperar o estado confirmado sem nova atribuição ou evento duplicado, mantendo as verificações de acesso.
6. Se pertence a outra pessoa, retornar `409` sem alterar dados.

Duas tentativas concorrentes pela mesma tarefa resultam em um único proprietário e um único evento de assunção. Uma consulta prévia `exists` seguida de escrita desprotegida não atende ao aceite.

Assunção exige conexão. A tarefa só migra para **Minhas tarefas** após confirmação do servidor; uma falha de comunicação não comprova que o comando falhou. Reconsultar antes de tentar de novo. Descartar respostas antigas e dados de tela ao trocar usuário, setor ou sessão.

Nesta issue não há formulário de quantidade, leitura unitária, correção, conclusão fictícia de tarefa ou botão que simule encerramento global. A ENG-3117 acrescentará execução de contagem sobre os mesmos identificadores de tarefa.

## 6. Fluxo de dados, falhas e auditoria

**Gestão:** inventário iniciado/fotografia → preparação idempotente → configuração em memória → prévia opcional → confirmação e salvamento na API → reconsulta do estado persistido.

**Operador:** sessão → rodadas elegíveis → tarefas próprias/abertas → início ou assunção → confirmação do servidor → atualização das listas.

| Situação | Comportamento |
| --- | --- |
| Sem sessão ou sem permissão | Fluxo existente de `401/403`; não revelar dados de outras rodadas/contextos. |
| Registro fora do contexto/inexistente | `404`, sem metadados operacionais vazados. |
| Campos/vínculos inválidos | `422`, indicando revisão, sem alteração parcial. |
| Versão desatualizada, rodada congelada/fechada ou tarefa de outro operador | `409` com códigos distinguíveis e mensagem legível; atualizar dados explicitamente. |
| Falha de leitura | Estado de erro e nova tentativa, nunca fixture como fallback. |
| Falha ao salvar | Preservar a edição gerencial em memória; não sobrescrever outra versão silenciosamente. |
| Resposta de escrita perdida | Reconsultar estado autoritativo antes de reenviar; recuperar assunção própria de forma idempotente. |
| Listas vazias | Estado vazio real, sem inserir operadores ou tarefas de demonstração. |

Registrar configuração, primeiro ingresso/início e assunções com identidade autenticada, horário e vínculos da rodada/tarefa. Preservar as alterações relevantes de destinatários. Auditoria de sucesso e alteração devem confirmar ou reverter juntas; não anunciar sucesso se a persistência do evento falhar. Repetições sem nova ação não produzem eventos de sucesso duplicados.

Não registrar tokens, credenciais ou payloads integrais da sessão. Não criar presença em tempo real, notificações push, painel de auditoria ou trilha de tentativas recusadas como ampliação implícita desta entrega.

## 7. Validação planejada

### Backend

- Preparar duas rodadas/tarefas idempotentemente, a partir da fotografia completa, inclusive endereços sem saldo e OPs repetidas; falha não deixa preparação parcial.
- Cobrir constraints, responsável nulo, vínculo à fotografia correta, participação na mesma rodada e preservação histórica.
- Autorizar gestão e execução separadamente; cobrir os quatro perfis aprovados, Master fora do contexto, não selecionados, usuários excluídos e nível elegível em setor diferente.
- Testar sugestão determinística por três critérios, balanceamento, mais participantes que tarefas e volume maior que uma página.
- Salvar ajustes individuais/em lote e tarefas abertas; remover participante exige resolver suas atribuições; versões concorrentes não sobrescrevem dados.
- Verificar independência entre rodadas, inclusive mesma pessoa e mesmo produto/endereço em ambas.
- Consultas não iniciam; ingresso e assunção iniciam e congelam somente sua rodada; assunções posteriores continuam permitidas.
- Com processos/conexões PostgreSQL independentes, disputar a mesma tarefa entre operadores e disputar salvamento com ingresso/assunção. Não certificar concorrência com mocks ou chamadas sequenciais.
- Testar repetição, resposta perdida, auditoria atômica e falha injetada; ausência de devolução, expiração e troca de proprietário.
- Confirmar que nenhuma operação altera quantidades, libera bloqueios, envia integração ou consulta o ERP.

### Web, aplicativo e integração

- Validar seleção de participantes, confirmação de redistribuição, seleção em massa, preservação entre filtros/páginas e estados somente leitura após início.
- Testar no app navegação, separação de rodadas, tarefas próprias/abertas, assunção confirmada/conflitante, início explícito e ausência de seletor de identidade.
- Cobrir carregamento, vazio, falhas, duplo envio, perda de resposta, troca de sessão/contexto e respostas antigas.
- Conferir acessibilidade, foco/teclado na web, interação nativa e layouts estreitos, sem importar fixture/store ou exibir saldos/resultados alheios.
- Integrar gestão e dois operadores contra backend e PostgreSQL reais de testes. Distinguir essa evidência dos testes de UI com respostas sintéticas.

Seguir `AGENTS.md` e `docs/testing-database.md`. Usar runtime PHP compatível com o projeto e somente PostgreSQL descartável após o preflight. Não executar suítes que recriem o mesmo schema simultaneamente. Nenhuma migration, teste funcional ou chamada ao banco/ERP integra esta etapa de planejamento.

## Dependências e próximos artefatos

| Issue | Responsabilidade |
| --- | --- |
| ENG-3113 | Cadastro, catálogo e seleção persistida no contexto WMS. |
| ENG-3114 | Início, fotografia operacional e bloqueios de movimentação. |
| ENG-3115 | Consulta/filtros gerenciais, sem redefinir propriedade ou participação. |
| **ENG-3116** | Participantes, duas rodadas iniciais, tarefas, distribuição, ingresso e assunção. |
| ENG-3117 | Modalidades e registro/correção de contagens nas tarefas. |
| ENG-3118 | Recontagens, resultados, conclusão e encerramento local com liberação dos bloqueios. |

O [plano detalhado de implementação](2026-11-06-eng-3116-distribuicao-tarefas-contagem-implementation-plan.md) organiza 13 tarefas com arquivos, dependências, validações e matriz de aceite. A existência dos planos das dependências não significa que suas funcionalidades estejam implementadas. Toda execução permanece pendente de entrega das dependências e autorização posterior.
