# Cubagem da Carga no Carregamento App

**Data:** 2026-06-08  
**Escopo:** Exibir a cubagem total da carga e o progresso bipado em relação à capacidade do caminhão vinculado, no app de carregamento mobile.

---

## Contexto

O badge do veículo no carregamento (`carga-badge-veiculo`) já exibe placa e capacidade total do caminhão (`cubagem_total` do `veiculo_snapshot`). Os itens da missão já possuem cubagem unitária em `dados_adicionais['cubagem']`. Falta mostrar quanto do caminhão a carga ocupa e atualizar esse valor em tempo real conforme o operador bipa.

---

## Visual

O badge do veículo ganha duas novas linhas abaixo das existentes:

```
[truck] ABC-1234            20,00m³   ← existente
CAMINHÃO GRANDE                       ← existente
[████████░░░░░░░░░░░]  42%           ← NOVO: barra de ocupação
8,5 / 20,0m³                         ← NOVO: fração
```

**Regras de cor da barra:**
- Verde (`--app-sucesso`) — ocupação < 80%
- Amarelo (`--app-aviso`) — ocupação 80–95%
- Vermelho (`--app-perigo`) — ocupação > 95%

**Ocultação:** se `cubagem_carga_total == 0` (nenhum produto tem cubagem cadastrada) ou se não há veículo vinculado, a barra e a fração ficam ocultas.

---

## Fluxo de Dados

### PHP — sem query extra

`execucao_bipagem.php` itera `$todosItens` e acumula:

```php
$cubagemCargaTotal = 0;
$cubagemBipadaInicial = 0;
foreach ($todosItens as $item) {
    $da = is_string($item->dados_adicionais ?? '') 
        ? json_decode($item->dados_adicionais, true) 
        : (array)($item->dados_adicionais ?? []);
    $unit = floatval($da['cubagem'] ?? 0);
    $cubagemCargaTotal    += $unit * floatval($item->quantidade ?? 0);
    $cubagemBipadaInicial += $unit * floatval($item->quantidade_bipada ?? 0);
}
```

Dois `<input hidden>` emitidos para o JS:
- `id="data-cubagem-carga-total"` — volume total da carga (m³)
- `id="data-cubagem-veiculo"` — capacidade do caminhão (m³), lido de `$veiculo['cubagem_total']` (0 se sem veículo)

### CarregamentoPresenter.php — 1 campo novo

No loop de montagem de `$jsItensData`, adiciona:

```php
'cubagem_unit' => floatval($dadosAdicionaisDecodificados['cubagem'] ?? 0),
```

Permite ao JS recalcular cubagem bipada por item sem consultar o PHP.

### JS — CarregamentoV2 (`item.js`)

**`inicializarStatsFixos()`:** soma `cubagem_unit * qtd_bipada` → `statsIncremental.cubagemBipada`

**Bloco de atualização incremental** (onde `totalBipado += ultimoDelta`):
```js
this.statsIncremental.cubagemBipada += ultimoDelta * (item.cubagem_unit || 0);
```

**`atualizarBadges()`:** lê `data-cubagem-veiculo` e `data-cubagem-carga-total`, recalcula percentual, atualiza:
- `#veiculo-cubagem-bar-fill` → largura e cor
- `#veiculo-cubagem-frac` → texto `"X,X / Y,Ym³"`

### CSS — `carregamento_v2.css`

Novas classes:
- `.veiculo-cubagem-row` — linha contendo barra + fração
- `.veiculo-cubagem-bar` — container da barra (fundo)
- `.veiculo-cubagem-bar-fill` — fill animado
- `.veiculo-cubagem-frac` — texto da fração

---

## Arquivos Tocados

| Arquivo | Mudança |
|---|---|
| `Presenters/CarregamentoPresenter.php` | Adiciona `cubagem_unit` por item em `$jsItensData` |
| `html/shared/components/v2/execucao_bipagem.php` | Calcula totais PHP, emite hidden inputs, expande HTML do badge |
| `html/carregamento/item.js` (CarregamentoV2) | Init + delta incremental + `atualizarBadges()` para cubagem |
| `html/carregamento/carregamento_v2.css` | Estilos da barra e fração |

**Sem novos Laboratorios, Sondas, migrations ou endpoints.**

---

## Critérios de Aceitação

1. Com caminhão vinculado e produtos com cubagem, o badge mostra fração e barra.
2. A barra atualiza em tempo real após cada bipagem (sem reload).
3. A cor da barra muda corretamente nos thresholds 80% e 95%.
4. Sem caminhão vinculado ou cubagem total = 0, o novo elemento fica oculto — sem impacto visual.
5. O retorno app (que usa o mesmo `execucao_bipagem.php`) não é afetado — a lógica nova é condicional a `$veiculo` e `$cubagemCargaTotal > 0`.