# ENG-3116 — Rodadas, participantes, distribuição e assunção

Esta API estende a fotografia operacional da ENG-3114. O inventário e cada tarefa continuam vinculados à Expedição e ao depósito configurado; nenhuma rota desta entrega lê saldos, grava contagens, envia ajustes ao ERP ou libera bloqueios.

## Gestão

Todas as rotas abaixo exigem `auth:sanctum` e sessão ativa de Master/Administrador na Expedição.

| Método e caminho | Contrato |
| --- | --- |
| `GET /api/v1/inventory/participants?search=&page=1&per_page=30` | Catálogo mínimo paginado (`id`, `name`). A elegibilidade consulta o nível dentro do JSON da Expedição; não combina perfis de setores diferentes. |
| `POST /api/v1/inventory/{inventory}/rounds/initialize` | Inicializa idempotentemente as duas rodadas e uma tarefa por endereço-produto fotografado. Exige inventário iniciado. Usado também para inventários iniciados antes da ENG-3116. |
| `GET /api/v1/inventory/{inventory}/rounds` | Resumo das rodadas, participantes e totais. É somente leitura e não inicia a rodada. |
| `GET /api/v1/inventory/{inventory}/rounds/{round}?page=1&per_page=50&search=` | Configuração persistida, mapa integral e leve `{task_id, operator_id}`, mais metadados da página filtrável. A paginação limita somente a exibição. |
| `POST /api/v1/inventory/{inventory}/rounds/{round}/distribution-preview` | Cálculo completo da distribuição, sem persistir. Corpo: `{version, participant_ids, strategy}`; estratégia `location`, `family` ou `product`. |
| `PUT /api/v1/inventory/{inventory}/rounds/{round}/configuration` | Salva atomicamente participantes e atribuições completas. Corpo: `{version, participant_ids, strategy, assignments:[{task_id, operator_id}]}`; `operator_id: null` deixa a tarefa aberta. |

Nas consultas de participantes e de configuração da rodada, `search` é opcional: ausente, nulo, vazio (`search=`) ou composto apenas por espaços significa **sem filtro de busca**. Quando preenchido, deve ser string de até 150 caracteres; arrays e valores acima do limite retornam `422`. A busca continua aplicada no servidor antes da paginação, sem reduzir o mapa integral de atribuições nem alterar a configuração da rodada.

A atribuição deve conter exatamente uma linha por tarefa da rodada, inclusive tarefas fora da página visível. IDs duplicados, omissões, participantes inelegíveis e destinatários não selecionados retornam `422`. Campos desconhecidos/autoria são recusados. A autoria sempre vem da sessão.

O cálculo em `distribution-preview` ordena tarefas pelo critério e desempata por identidades persistidas. Participantes são ordenados por ID e a resposta explicita `participant_order`; blocos contíguos diferem no máximo por uma tarefa. O endpoint não persiste a configuração. Na interface, **Distribuir** consulta esse cálculo e substitui imediatamente o mapa completo **somente na edição local**, sem uma segunda confirmação de prévia. Trocar participantes ou critério não redistribui automaticamente. Apenas **Salvar distribuição** envia `PUT .../configuration` e persiste participantes, critério e atribuições; descartar a edição mantém a configuração salva anterior.

## Operação — contratos nativos das ENG-3268/3269/3270

Estas rotas exigem autenticação, acesso cadastral ativo na Expedição como Master, Administrador, Armazenador ou Separador e participação selecionada na rodada. Master/Admin não têm bypass de participação. Nenhum corpo aceita ator/operador; a identidade é sempre autenticada.

| Método e caminho | Contrato |
| --- | --- |
| `GET /api/v1/inventory/available-rounds` | Rodadas de inventários iniciados, com totais próprios/abertos, status do inventário, ingresso individual e capacidades; sem resultados. |
| `GET /api/v1/inventory/rounds/{round}/context` | Contexto cego autorizado, incluindo após fechamento: situação do inventário/rodada, ingresso individual e capacidades. |
| `GET /api/v1/inventory/rounds/{round}/tasks?scope=mine\|open&page=1&per_page=50&search=` | Lista paginada, filtrada no servidor, com contexto e capacidades por tarefa; legível após fechamento para participante autorizado. |
| `GET /api/v1/inventory/rounds/{round}/tasks/{task}` | Recuperação cega de tarefa aberta/própria, contexto e capacidades; permite consultar a própria contagem vigente após fechamento sem revelar terceiros. |
| `POST /api/v1/inventory/rounds/{round}/enter` | Ingresso operacional idempotente. Corpo vazio. |
| `POST /api/v1/inventory/rounds/{round}/tasks/{task}/claim` | Assunção exclusiva; corpo vazio. Repetir tarefa própria recupera o estado sem evento duplicado. |

A lista operacional aceita `search` opcional/anulável, string de até 150 caracteres. Ausente, nulo, vazio ou somente espaços não filtra. Quando preenchido, pesquisa parcialmente código/descrição do produto e nome/hierarquia do endereço **fotografados**, sem distinguir maiúsculas/minúsculas e ignorando espaços externos. O filtro é aplicado no servidor dentro de `mine`/`open` antes da paginação; `data.meta.total` e `last_page` refletem os resultados filtrados. Arrays/outros tipos não string e texto acima do limite retornam `422`. A resposta operacional e as regras de autorização/ingresso permanecem iguais.

O contrato completo dos campos novos, situações legíveis, capacidades, conflitos de fechamento e recuperação está em [inventory-operational-api.md](inventory-operational-api.md). `available-rounds` continua sendo descoberta, não histórico: para revalidar contexto já aberto após fechamento, usar `context` ou a consulta operacional de tarefas.

Leituras não iniciam a rodada. A primeira entrada ou assunção válida registra início/autor/data e congela configuração somente daquela rodada. Tarefas ainda abertas podem continuar sendo assumidas por participantes selecionados. Não existe troca de responsável, devolução, expiração ou liberação administrativa após o início.

As projeções operacionais incluem identidade do inventário, rodada, produto, unidade e endereço; omitem saldos, outras rodadas e dados gerenciais. Uma tarefa já assumida por outra pessoa retorna `409 inventory_task_unavailable` sem identificar seu responsável. Edições após início retornam `409 inventory_round_frozen`; versões concorrentes usam `409 inventory_configuration_conflict`.

## Persistência e concorrência

`inventory_rounds`, `inventory_round_participants`, `inventory_count_tasks` e `inventory_round_events` mantêm a configuração relacional. Constraints compostas prendem a rodada ao inventário, a tarefa à fotografia correspondente e o responsável a um participante da mesma rodada. Exclusões de usuário/inventário não apagam histórico.

As operações de configuração, ingresso e assunção obtêm locks nesta ordem: cabeçalho do inventário → rodada → usuário/participante → tarefa. A preparação executa sob o lock do cabeçalho e na mesma transação do início do inventário. Alteração de propriedade, primeiro ingresso/início e eventos confirmam ou revertem juntos. Repetições não criam eventos de assunção duplicados.

Para contagens da ENG-3117, usar o mesmo `round_id`/`task_id`, autorização/participação e ordem de locks. Um endpoint de contagem não deve iniciar a tarefa de um participante diferente nem aceitar IDs de usuário no corpo.
