# ENG-3270 — Contexto operacional, capacidades e recuperação

Contrato de backend para o fluxo nativo cego. Complementa [rodadas/assunção](inventory-rounds-api.md) e [registro/correção de contagens](inventory-counts-api.md). Não consumir o Resource ou os endpoints gerenciais para obter o ciclo de vida no app.

## Autorização e leitura após fechamento

Todas as rotas operacionais exigem Sanctum, acesso cadastral atual na Expedição com o nível ativo Master/Admin/Armazenador/Separador e participação selecionada na rodada. O contexto de depósito/setor vem do servidor; nenhum campo enviado pelo cliente amplia esse escopo. Admin/Master não têm bypass.

Contexto, lista e detalhe de tarefas são legíveis nos estados pós-início `iniciado`, `conferencia`, `aguardando`, `aprovado` e `reprovado`. A fotografia precisa ter `started_at`. Leitura autorizada não significa escrita autorizada: os estados de fechamento continuam sem novos ingressos, assunções, contagens ou correções.

Rascunho, fotografia não iniciada, situação desconhecida e inventário fora do contexto retornam 404. Usuário sem acesso atual ou não participante recebe 403. Tarefa assumida por outra pessoa retorna `409 inventory_task_unavailable`, sem identificar o proprietário.

## Consulta dedicada

`GET /api/v1/inventory/rounds/{round}/context`

Exemplo de uma rodada concluída em inventário aguardando aprovação:

```json
{
  "data": {
    "inventory": {
      "id": 12,
      "code": "INV-0012",
      "description": "Conferência manual",
      "status": "aguardando"
    },
    "round": {
      "id": 31,
      "number": 1,
      "status": "concluida",
      "started_at": "2026-11-13T10:00:00.000000Z",
      "ended_at": "2026-11-13T11:00:00.000000Z"
    },
    "participant": {
      "has_entered": true,
      "first_entered_at": "2026-11-13T10:05:00.000000Z"
    },
    "capabilities": {
      "can_enter": false,
      "can_claim": false
    }
  }
}
```

`participant` descreve exclusivamente o operador autenticado. `round.started_at` é global e **não substitui** `participant.has_entered`.

A resposta não contém saldo, comparação, resultados oficiais, consolidação, contagens/participantes alheios ou motivos gerenciais. GETs não iniciam rodada, registram ingresso, assumem tarefas ou produzem eventos.

## Consultas existentes: extensões aditivas

### Descoberta de trabalho

`GET /api/v1/inventory/available-rounds`

Mantém filtro de inventário `iniciado`, participação atual, ordenação e campos anteriores. Acrescenta a cada rodada:

- `inventory.status`;
- `ended_at`;
- `participant.has_entered` e `participant.first_entered_at`;
- `capabilities.can_enter` e `capabilities.can_claim`.

Não é um histórico. Quando o inventário sai de `iniciado`, suas rodadas deixam essa listagem. Para revalidar um contexto já aberto ou recuperar confirmação, usar a consulta dedicada ou o contexto incluído na leitura de tarefas; não interpretar ausência na listagem como prova de exclusão/acesso revogado.

Uma rodada concluída/desconsiderada ainda pode aparecer enquanto outra rodada do inventário permanece aberta. Suas capacidades ficam falsas, sem bloquear a rodada ainda operacional. Recontagens configuradas para o participante aparecem como novas rodadas independentes, sem copiar confirmações/rascunhos anteriores.

### Lista e detalhe de tarefas

- `GET /api/v1/inventory/rounds/{round}/tasks?scope=mine|open&page=1&per_page=50&search=`
- `GET /api/v1/inventory/rounds/{round}/tasks/{task}`

A lista aceita `search` opcional/anulável, string de até **150 caracteres**. Ausência, `null`, vazio (`search=`) e somente espaços significam sem filtro. Texto preenchido pesquisa parcialmente código/descrição do produto e nome/hierarquia do endereço na **fotografia congelada**, ignorando caixa e espaços externos. O cadastro atual, saldos e ERP não participam da busca. Tipo não string e texto acima do limite retornam `422`.

Exemplo: `GET /api/v1/inventory/rounds/{round}/tasks?scope=mine&search=parafuso&page=1&per_page=50`. O filtro é aplicado somente nas tarefas próprias ou abertas do escopo/rodada autorizados, antes de contar/paginar. `data.meta.total` é o total filtrado, `last_page` é pelo menos 1 e uma página além do intervalo pode ter `data.data: []` com `total > 0`; só `total: 0` representa ausência total de correspondências.

O consumidor nativo pode enviar a busca em cada página e remover a varredura de todas as páginas com filtro local. Ao trocar busca ou escopo, reiniciar em `page=1` e preservar cancelamento/invalidação das respostas antigas. Essa adaptação pertence à ENG-3268; não foi implementada no app nesta alteração de backend. GET continua sem registrar ingresso ou alterar tarefas, inclusive após fechamento.

Preservam campos e paginação. Acrescentam `data.context`, com exatamente a projeção da consulta dedicada. Cada tarefa acrescenta `capabilities`:

```json
{
  "can_claim": true,
  "can_count": false,
  "can_correct": true
}
```

O exemplo representa tarefa própria já confirmada e ainda corrigível. A resposta do detalhe continua em `data.task`; na lista, em `data.data[]`.

`task.count` é a contagem **vigente** de tarefa própria, de autoria do operador. Contagens incompatíveis com propriedade/autoria não expõem quantidade. Tarefa sem confirmação continua com `count: null`: isso não representa zero nem conclusão. Metadados de produto/endereço/modalidade continuam vindo da fotografia congelada.

## Semântica das capacidades

| Campo | Condições |
| --- | --- |
| Contexto `can_enter` | Inventário iniciado com fotografia e rodada pendente/em andamento. Repetição de ingresso já realizado continua idempotente. |
| Contexto `can_claim` | Rodada operacional. A autorização de uma tarefa específica depende também da propriedade. Não garante que existam tarefas abertas. |
| Tarefa `can_claim` | Rodada operacional e tarefa aberta ou já própria. O segundo caso permite recuperar/repetir assunção idempotente. |
| Tarefa `can_count` | Tarefa própria sem confirmação, inventário iniciado, rodada em andamento/iniciada, ingresso individual confirmado e modalidade congelada válida. |
| Tarefa `can_correct` | Mesmas condições de escrita, confirmação existente e autoria do operador. Justificativa/versão ainda são obrigatórias no comando. |

Capacidades são uma fotografia do servidor, não uma promessa de sucesso futuro. O comando revalida as regras sob os locks transacionais. O app deve reconsultar ao retomar e após conflitos, preservar rascunho em memória e não converter recusa ou falha de rede em sucesso local.

As consultas dedicadas/lista/detalhe usam shared locks na ordem inventário → rodada. Gravação, configuração e fechamento usam o cabeçalho exclusivamente; assim, contexto, confirmação e capacidades são projetados de maneira coerente em relação a esses comandos. Essas leituras não persistem dados.

## Recuperação de confirmação após fechamento

1. Manter a identificação e o payload do comando original quando a resposta for desconhecida.
2. Reconsultar contexto/tarefa quando cabível. Uma falha de leitura não prova que a gravação falhou.
3. Repetir `PUT .../tasks/{task}/count` com **a mesma chave e o mesmo payload** para recuperar o recibo. O servidor revalida acesso, participação, propriedade e autor; um comando persistido retorna `replayed: true`, inclusive após fechamento, sem nova revisão/evento.
4. Reconsultar o detalhe da tarefa. `task.count` contém a versão vigente e o contexto informa se ainda existe capacidade de escrita.

O recibo identifica a revisão daquele comando. Se houve correção posterior, o replay da versão 1 continua devolvendo a versão 1, enquanto o GET pode devolver a versão 2. Não substituir o estado vigente pelo recibo antigo nem interpretar recuperação como nova correção.

Se o fechamento venceu antes de a gravação persistir, o comando não possui recibo e é recusado, sem fabricar confirmação ou reabrir a rodada. Acesso revogado não é restaurado por possuir uma chave antiga. Não gerar outra chave para tentar recuperar a mesma intenção.

## Conflitos

Respostas de conflito mantêm `{ "message": "...", "code": "..." }` com HTTP 409.

| Código | Significado / orientação |
| --- | --- |
| `inventory_round_not_started` | Rodada ainda não iniciada para contagem; não significa rodada encerrada. |
| `inventory_round_completed` | Rodada concluída em inventário ainda iniciado; reconsultar contexto e desabilitar novas operações dessa rodada. |
| `inventory_round_discarded` | Rodada desconsiderada em inventário ainda iniciado; reconsultar contexto e desabilitar novas operações dessa rodada. |
| `inventory_not_operable` | Inventário não aceita escrita. Reconsultar contexto para distinguir conferência, aprovação pendente e decisão final. A indisponibilidade do inventário tem precedência sobre a situação da rodada em novas escritas. |
| `inventory_participant_not_entered` | Operador ainda não ingressou, mesmo que outra pessoa já tenha iniciado a rodada. |
| `inventory_task_unavailable` | Tarefa não pertence ao operador; não tentar assumir/corrigir terceiros. |
| `inventory_count_version_conflict` | Versão mudou; consultar a versão vigente sem sobrescrita automática. |
| `inventory_count_command_reused` | Mesma identificação reutilizada com outro payload/autor. Não reenviar com dados alterados para recuperar um comando. |
| `inventory_reading_mode_missing` | Modalidade congelada ausente/inválida. Não inferir modalidade localmente. |

Conflitos específicos de rodada valem para ingresso, assunção e novas contagens/correções. Payload inválido continua retornando 422; identidade/autoria/acesso continuam sujeitos às validações existentes. Não interpretar qualquer 409, 404 ou falha de rede como fechamento.

## Limites de entrega

Sem alteração de schema, estoque, ERP, desbloqueio, aprovação, criação de recontagem pelo app, offline ou push. Nenhum endpoint de gestão deve ser consumido como fallback, inclusive quando o operador é Admin/Master. A adaptação das telas/hooks nativos permanece na ENG-3270 mobile.
