# Reset de Item da Missão (gestor) — Spec

## Contexto e problema

Quando um operador comete um erro durante a execução de um item de missão (ex.: pesa errado em uma missão de pesagem, bipa quantidade incorreta na separação, conclui um item por engano), hoje **não há caminho para o gestor desfazer aquele item específico** sem afetar a missão inteira.

Existe no painel de gestão (`Logistica/sinais/Designacoes/html/designacao_painel.php:1245`) um botão "Reiniciar" que chama `MissoesItensEdicao::voltarItemPendente`, mas ele:

1. **Não zera os dados de execução do item** (`quantidade_bipada`, `dados_adicionais`, `concluido_em`, `concluido_por`) — só troca o `status` para `pendente` e appenda uma observação. Os dados antigos continuam fantasmas na linha.
2. **Não rebota o status da missão** quando ela está em `aguardando_aprovacao`. Resultado: depois do reset o item está pendente, mas a missão continua "aguardando aprovação" do gestor — estado inconsistente.

A feature corrige esses dois gaps para que o reset do item realmente devolva o item ao estado pré-execução e, quando aplicável, recoloque a missão em andamento.

## Escopo

- ✅ Faz parte:
  - Estender `MissoesItensEdicao::voltarItemPendente` para zerar todos os campos de execução do item (não só o status).
  - Quando a missão estiver em `aguardando_aprovacao` no momento do reset, atualizar seu status para `em_andamento` na mesma operação.
  - Registrar no extrato a reabertura da missão (em adição ao `ITEM_REINICIADO` já existente).
  - Ajustar o `data-confirm-msg` do botão "Reiniciar" no `designacao_painel.php` para mencionar que a missão pode voltar a `em_andamento`.
  - Funcionar para qualquer tipo de missão logística (pesagem, separação, conferência, carregamento) — comportamento consistente.
- ❌ Fora de escopo:
  - Criar um Laboratório novo ou mover o handler para outro lugar (mantém-se no `MissoesItensEdicao` atual).
  - Alterar a UI do botão (ícone, posição, condições de exibição já existentes).
  - Alterar `recomecarItem`, `pularItem`, `duplicarItem`, `remover` ou outros handlers do mesmo arquivo.
  - Reset de itens em missões `concluida` (já bloqueado pela validação de status atual e deve continuar bloqueado).
  - Reset em massa (vários itens de uma vez) — fluxo permanece item-a-item.
  - Mudar regras de quem pode resetar (segue `isGestorLogistico` da view).
  - Notificações ao operador que executou o item original.
  - Schema: nenhuma migration nova, todos os campos a zerar já existem.

## User stories

### US1 — Resetar item com limpeza completa
**Como** gestor logístico **eu quero** que o reset de um item zere de fato os dados de execução **para** que o operador, ao retomar o item pendente, comece do zero sem ver dados antigos fantasmas.

**Critérios de aceite:**
- AC1.1: Após o reset, o item tem `status = pendente`, `quantidade_bipada = 0`, `concluido_em = null`, `concluido_por = null`.
- AC1.2: O campo `dados_adicionais` é limpo (vazio `{}` ou `null`, conforme padrão da coluna no banco).
- AC1.3: Se o item tinha campos de ocorrência preenchidos (`ocorrencia_separacao` ou similar), eles também são limpos — um item "pendente" não pode carregar justificativa de execução anterior.
- AC1.4: O reset aparece no extrato como `ITEM_REINICIADO` (mantém o registro atual).
- AC1.5: A observação do reset continua sendo appendada ao campo `observacoes` no formato atual: `[Resetado p/ pendente por <nome>]`.
- AC1.6: O fluxo continua bloqueado quando a missão está em `concluida`, `cancelada` ou status finalizado equivalente — comportamento atual preservado.

### US2 — Rebote automático da missão
**Como** gestor logístico **eu quero** que, ao resetar um item de uma missão que está em `aguardando_aprovacao`, a missão volte para `em_andamento` automaticamente **para** não ter de aprovar uma missão que sabidamente tem item pendente, nem precisar fazer uma segunda ação manual.

**Critérios de aceite:**
- AC2.1: Se `missao.status == aguardando_aprovacao` no momento do reset bem-sucedido, a missão é atualizada para `em_andamento` na mesma operação.
- AC2.2: Para missões em `em_andamento`, `pausada`, `pendente` ou `rascunho`, o status da missão **não** é alterado pelo reset (permanece como estava).
- AC2.3: A mudança de status da missão é registrada no extrato como uma ação dedicada (nome a ser confirmado pelo TL — sugestão: `MISSAO_REABERTA` ou `MISSAO_VOLTADA_EM_ANDAMENTO`).
- AC2.4: Se a atualização do status da missão falhar, o reset do item falha como um todo (atomicidade) — não pode haver item resetado com missão num status inconsistente.
- AC2.5: A `Message` de retorno informa ao usuário o que aconteceu, ex.: "Item voltado para pendente. Missão reaberta para Em Andamento."

### US3 — Comunicar a consequência ao gestor
**Como** gestor **eu quero** que o modal de confirmação me avise que resetar um item pode reabrir a missão **para** não ser pego de surpresa quando uma missão em aprovação some da minha fila.

**Critérios de aceite:**
- AC3.1: O `data-confirm-msg` do botão Reiniciar no `designacao_painel.php` menciona explicitamente que, se a missão estiver aguardando aprovação, ela voltará para Em Andamento.
- AC3.2: A mensagem continua na mesma linha de tom/tamanho do confirm atual (não vira texto longo).

## Personas envolvidas

| Persona | Papel | Ponto de contato |
|---|---|---|
| Gestor logístico | Decisor operacional | Aciona o reset pelo `designacao_painel` quando identifica erro de operador |
| Operador (separador / conferente / pesador) | Executor | Volta a executar o item pendente após o reset, do zero |
| Time de devs Genesis | Mantenedor | Implementa/mantém `MissoesItensEdicao` |

## Dados / entidades-chave (alto nível)

- **MissaoLogisticaItem** — linha resetada. Campos afetados: `status`, `quantidade_bipada`, `dados_adicionais`, `concluido_em`, `concluido_por`, `observacoes`, e ocorrências eventualmente preenchidas.
- **MissaoLogistica** — entidade pai. Campo afetado: `status` (apenas quando estava em `aguardando_aprovacao`).
- **Extrato da missão** — recebe registro `ITEM_REINICIADO` (já existente) e, quando aplicável, registro de reabertura da missão.

## Regras de negócio

1. O reset só pode ser feito por gestor logístico (regra de UI já existente; backend não muda permissões).
2. O reset só é permitido para missões em `em_andamento`, `aguardando_aprovacao`, `pausada`, `pendente` ou `rascunho` — validação de status atual no handler é mantida.
3. Item já pendente é no-op: retorna `info`, não escreve nada.
4. Reset zera **todos** os campos de execução do item, não apenas o status — não há campo de execução que sobreviva ao reset.
5. Atomicidade: update do item + (eventual) update da missão + extratos formam uma unidade lógica. Falha em qualquer passo aborta a operação inteira.
6. Apenas o status `aguardando_aprovacao` é "rebotado" para `em_andamento`. Outros estados intermediários permanecem como estão (gestor é quem decide reativá-los).
7. O extrato da reabertura da missão referencia o item que disparou o reset (rastreabilidade).
8. Mensagens ao usuário (`Message`) não são hardcoded em PT — passam pelo padrão de i18n já adotado em `MissoesItensEdicao` (se aplicável; conferir convenção atual).

## Métricas de sucesso

- Após o reset de um item de pesagem, abrir o app na tela de pesagem do mesmo item exibe estado pré-execução (sem peso fantasma, sem operador anterior).
- Missão que estava em `aguardando_aprovacao` some da fila de aprovação após reset e reaparece em "em andamento".
- Zero registros de extrato órfãos (item resetado mas missão num status inconsistente — isso simplesmente não pode existir após esta feature).
- Feedback do gestor: o modal de confirmação descreve o que vai acontecer antes de acontecer (não há surpresa).

## Dúvidas em aberto

- [ ] Nome exato da nova ação de extrato para reabertura da missão (`AcaoExtrato::MISSAO_REABERTA` vs. `MISSAO_VOLTADA_EM_ANDAMENTO` vs. reutilizar enum existente). TL confirma na fase de tech plan.
- [ ] Atomicidade transacional: o `MissaoLogisticaItem` e a `MissaoLogistica` são tabelas separadas. Verificar se o framework Genesis (Sondas/`atualizar`) oferece transação explícita ou se o handler precisa orquestrar `BEGIN/COMMIT`. TL define o approach.
- [ ] Lista completa dos campos de "execução" a zerar — esta spec lista os principais (`quantidade_bipada`, `dados_adicionais`, `concluido_em`, `concluido_por`, ocorrências). TL audita o schema de `missao_logistica_item` e confirma se há outros (ex.: `peso_real`, `tempo_execucao_seg`) que precisam ser limpos.
- [ ] Mensagem do `Message` de retorno: copiar exata em PT (e i18n se aplicável). Definir junto com o time de produto se "Missão reaberta para Em Andamento" é o texto certo.