# Spec: Justificativa do Motorista no Modal Acompanhamento — Edicaorota

**Data:** 2026-05-27  
**Status:** Aprovado

## Contexto

A tela de reordenação de rota (`editar_rota.php`) ganhou um modal de confirmação com campo opcional de justificativa. Quando o motorista preenche esse campo, o texto é enviado via POST como `justificativa_motorista`. Atualmente o campo não é salvo nem exibido em nenhuma view do gestor.

## Objetivo

Salvar a justificativa do motorista no banco e exibi-la no modal "Acompanhamento da rota do motorista" (visão do gestor, `central.php`), abaixo do campo "Código do Motorista" — somente quando preenchida.

## Escopo

- **Visibilidade:** todos os estados pós-envio (`PENDENTE_APROVACAO`, `APROVADA`, `REJEITADA`, `CANCELADA`)
- **Bloco oculto quando vazio:** aparece somente se `justificativa_motorista` não for `null`/vazia
- **Sem limite de tamanho no banco** (`TEXT NULL`) — consistente com `motivo_rejeicao` e `resposta_gestor`

## Fora do escopo

- Validação de tamanho máximo ou obrigatoriedade da justificativa
- Exibição em outras views além do modal Acompanhamento
- Histórico de múltiplas justificativas (a coluna é 1:1 com a edicao)
- i18n: textos somente em pt-br nesta iteração

## Arquivos modificados

| Arquivo | Mudança |
|---|---|
| `migrations/006_justificativa_motorista.sql` | Nova migration `ALTER TABLE` |
| `Laboratorios/SubmeterRotaPropostaLaboratorio.php` | Salva `justificativa_motorista` no `make()`/`save()` |
| `Laboratorios/ConsultarEdicaoRotaLaboratorio.php` | Expõe `justificativa_motorista` no array de retorno |
| `sinais/Central/html/central.php` | HTML do bloco + JS de populate/show/hide |

## 1. Migration

**Arquivo:** `componentes/Missoes/Logistica/sinais/Edicaorota/migrations/006_justificativa_motorista.sql`

```sql
ALTER TABLE edicoes_rota
  ADD COLUMN justificativa_motorista TEXT NULL;
```

- `NULL` quando o motorista não preencheu
- `TEXT` (sem limite) — consistente com `motivo_rejeicao` e `resposta_gestor`
- Sem `DEFAULT` — framework não usa `DEFAULT` em colunas de domínio

## 2. Backend — SubmeterRotaPropostaLaboratorio

Adicionar `justificativa_motorista` ao `make()`, convertendo string vazia para `null`:

```php
$sonda->make([
    'id'                      => (int) $edicao->id,
    'rota_proposta'           => json_encode($proposta),
    'justificativa_motorista' => trim($_POST['justificativa_motorista'] ?? '') ?: null,
    'status'                  => EdicaoRotaStatus::PENDENTE_APROVACAO->value,
])->save();
```

## 3. Backend — ConsultarEdicaoRotaLaboratorio

Adicionar ao array de retorno (junto aos demais campos da edicao):

```php
'justificativa_motorista' => $edicao->justificativa_motorista,
```

O campo é retornado em todos os estados — o frontend decide exibir ou não.

## 4. Frontend — central.php

### HTML

Inserir após o fechamento de `#acompanhar-codigo-bloco`:

```html
<div id="acompanhar-justificativa-bloco" class="hidden">
  <div class="acompanhar-label">Observação do motorista</div>
  <div id="acompanhar-justificativa-texto" class="acompanhar-valor"></div>
</div>
```

Classes `acompanhar-label` e `acompanhar-valor` já existem no modal — sem CSS adicional necessário.

### JavaScript

No handler de polling/populate do modal Acompanhamento, após o bloco do código do motorista:

```js
var just = data.justificativa_motorista;
if (just) {
    $('#acompanhar-justificativa-texto').text(just);
    $('#acompanhar-justificativa-bloco').removeClass('hidden');
} else {
    $('#acompanhar-justificativa-bloco').addClass('hidden');
}
```

O bloco é reavaliado a cada polling — some corretamente se o modal for reaberto para uma edicao sem justificativa.

## Fluxo completo

```
Motorista preenche justificativa no modal de confirmação
  → POST /Edicaorota com justificativa_motorista no body
  → SubmeterRotaPropostaLaboratorio salva em edicoes_rota.justificativa_motorista

Gestor abre modal Acompanhamento
  → polling chama ConsultarEdicaoRotaLaboratorio
  → response inclui justificativa_motorista
  → JS exibe #acompanhar-justificativa-bloco (se preenchido)
    abaixo de #acompanhar-codigo-bloco
```