# Registro de divergências — golden master

Linha de base capturada do sistema legado por `php artisan golden:capturar`.
Primeira captura em **2026-08-03**; recapturada em **2026-09-15**, depois da
importação de agosto/2026 e da remoção das 6 duplicatas reais de abril/2026.

Há duas naturezas de arquivo nesta pasta:

- **O que o legado mostra** — `veiculos-mensal`, `financeiro-mensal`,
  `cards-custo`. Fotografia do sistema antigo, não o que está certo. Prova que
  o ETL não mudou nenhum total.
- **O que as regras mandam** — `resultado-regras`. O resultado mês a mês pelas
  regras decididas pelo dono em 15/09/2026, calculado sobre as linhas cruas do
  legado por um SQL escrito à parte das consultas do sistema novo. É o
  gabarito dos relatórios.

Quando um relatório divergir de um destes arquivos, a diferença tem que cair
numa destas duas classificações, e ser anotada abaixo:

- **bug antigo corrigido** — o legado estava errado e o número novo é o certo.
- **regressão minha** — o legado estava certo e eu quebrei.

Sem isso não há como responder ao gestor quando ele perguntar por que o número
mudou.

## Arquivos

| Arquivo | Linhas | Conteúdo |
|---|---|---|
| `veiculos-mensal.csv` | 200 | quantidade, faturamento, lucro, retorno e dias de pátio por mês e loja, sobre `data_venda` |
| `financeiro-mensal.csv` | 791 | linhas e total por mês, operação e marcador, sobre `data_quitacao` |
| `cards-custo.csv` | 552 | os cards "custo total de venda" e "custo total de operação", com e sem os defeitos |
| `resultado-regras.csv` | 380 | por mês e destino (cada loja, GERAL, TOTAL LOJAS): vendas, faturamento, lucro dos veículos, custo direto, rateio, custo total, outras receitas e resultado |

Toda métrica de dinheiro da fotografia tem coluna `_decimal` e `_float`. A
primeira é soma exata; a segunda reproduz a acumulação em ponto flutuante que o
legado faz.

---

## As regras do gabarito (15/09/2026)

Estão como literais no SQL `CapturarGoldenMaster::RESULTADO_PELAS_REGRAS`, que
não lê nenhuma tabela do sistema novo:

- **Venda**: uma por placa + data + valor (a origem emite uma linha por
  financiamento). Linha sem placa fica fora — é a que o ETL põe em quarentena.
- **Lucro do veículo** = venda − total − comissão + retorno, com as correções de
  dado decididas: comissão de R$ 0,01 conta zero; os 7 retornos truncados valem
  o que diz o CSV de origem.
- **Lojas**: Joaçaba e Catanduvas desde 2019; Concórdia desde setembro/2025.
  Herval não é loja, nem no histórico. O custo GERAL é dividido pelo número de
  lojas do mês, cada parte arredondada ao centavo.
- **Custo**: comissão nunca; pró-labore sempre; no centro 1, menos empréstimos,
  reembolsos e acerto de saldo; do centro 5, só garantia; centros 2, 3, 4, 8 e
  9 inteiros; centros 0 (baixa agrupada), 6 (investimentos) e 7 (retirada de
  sócios) não.
- **Outras receitas**: toda entrada, menos venda de veículo, retorno sobre
  financiamento, empréstimos e oficina. Somam no GERAL e no TOTAL LOJAS.
- **TOTAL LOJAS** usa o GERAL inteiro, não a soma das partes arredondadas.

### Mês âncora: agosto/2026

| Destino | Lucro nos veículos | Despesa própria | Rateio | Outras receitas | Resultado |
|---|---:|---:|---:|---:|---:|
| JOAÇABA | 137.926,29 | 75.113,34 | 53.238,26 | | 9.574,69 |
| CATANDUVAS | 122.771,88 | 47.282,24 | 53.238,26 | | 22.251,38 |
| CONCÓRDIA | 182.789,53 | 35.460,09 | 53.238,26 | | 94.091,18 |
| GERAL | | 159.714,77 | | 4.509,64 | |
| **TOTAL LOJAS** | **443.487,70** | 157.855,67 | 159.714,77 | 4.509,64 | **130.426,90** |

---

## Divergências já conhecidas, classificadas antes de existir código novo

### 1. Comparativo ano-a-ano lê o mês corrente — **bug antigo corrigido**

`Dashboard.class.php:128` e `:145` compõem `$custo['anoAnterior']` lendo
`['mesAtual']` de uma das parcelas. O mesmo erro está em `Dashboard-v2.class.php`.
Esses métodos não são chamados por nenhuma tela do legado hoje; o erro aparece
só nos cards capturados aqui.

### 2. Nove de treze literais de categoria não existem no banco — **bug antigo corrigido**

O código escreve `VEICULOS -` (sem acento) onde o dado tem `VEÍCULOS -`.
Essas categorias contribuem exatamente zero para os cards de custo, desde
sempre. Conferido com `COLLATE utf8mb4_bin`:

| Literal no código | Linhas que casam | Grafia real | Total oculto (Pagar, histórico) |
|---|---|---|---|
| `VEICULOS - COMPRA` | 0 | `VEÍCULOS - COMPRA` | R$ 38.857.380,56 |
| `VEICULOS - QUITAÇÕES` | 0 | `VEÍCULOS - QUITAÇÕES` | R$ 11.903.983,26 |
| `VEICULOS - OFICINA` | 0 | `VEÍCULOS - OFICINA` | R$ 1.748.960,87 |
| `VEICULOS - GARANTIA` | 0 | `VEÍCULOS - GARANTIA` | R$ 1.043.379,99 |
| `VEICULOS - PEÇAS` | 0 | `VEÍCULOS - PEÇAS` | R$ 872.829,35 |
| `VEICULOS - TRANSPORTE` | 0 | `VEÍCULOS - TRANSPORTE` | R$ 311.758,66 |
| `VEICULOS - DESPACHANTE` | 0 | `VEÍCULOS - DESPACHANTE` | R$ 125.976,35 |
| `VEICULOS - CARTÓRIO` | 0 | `VEÍCULOS - CARTÓRIO` | R$ 92.884,07 |
| `VEICULOS - VIAGEM` | 0 | `VEÍCULOS - VIAGENS` | R$ 8.814,86 |
| `ADMINISTRATIVA - CORREIOS` | 0 | `ADMINISTRATIVAS - CORREIOS` | — |

Casam de fato: `VEÍCULOS - IPVA/LICENC/SEG OBRIG/MULTA SAIDA`,
`MANUTENÇÃO - VEICULOS`, `VEÍCULOS - LAVAGEM`.

A coluna `valor_corrigido` do CSV já traz o cálculo sem os dois defeitos. É
contra ela que a consulta dos cards deve bater.

### 3. Soma em ponto flutuante — **sem efeito observável**

Medido: zero diferença entre `_decimal` e `_float` em todas as linhas agregadas.
`decimal(15,2)` segue sendo a decisão certa, mas não corrige um erro medido
neste dataset.

### 4. Linhas fora do golden master

A captura filtra `tipo IN ('Pagar','Receber')` e `YEAR(data_quitacao) > 0`,
então as 20 linhas quebradas pelo parser de CSV do legado não entram. A linha
`Receber` de R$ 2.000,00 com marcador vazio (legado #27666, `2022-08-30`)
**entra** na fotografia mas está em quarentena no modelo novo; `GoldenMasterTest`
a desconta, e o gabarito pelas regras a exclui.

### 5. Uma venda por financiamento — **bug antigo corrigido**

A fotografia `veiculos-mensal` conta cada linha do legado como venda. O legado
tem 12 linhas que são o segundo, terceiro ou quarto financiamento da mesma venda
(2019–2020, R$ 390.578,96 de faturamento a mais). O modelo novo conta uma venda
só; `GoldenMasterTest` desconta as linhas extras.

---

## Divergências encontradas depois

| Data | Relatório | Golden | Novo | Classificação | Justificativa |
|---|---|---|---|---|---|
| 2026-08-03 | `custo_total_venda` e `custo_total_operacao`, todos os meses | `valor_legado` | bate com `valor_corrigido` | **bug antigo corrigido** | `App\Consultas\CustoTotal` compõe o card por `categorias.grupo_custo` e lê o ano anterior no ano anterior. `ConsultasTest` também assere que a consulta **não** reproduz `valor_legado` onde o legado erra. |
| 2026-09-15 | lucro dos veículos | `lucro_decimal` (sem retorno) | venda − total − comissão + retorno | **bug antigo corrigido** | Regra de 15/09/2026. O legado gravava o lucro sem o retorno, e duas telas dele somavam o retorno e três não. |
| 2026-09-15 | resultado por loja e total | telas "Mensal" do legado: R$ 153.176 (`ledir.php`) e R$ 116.717 (`ledir-new.php`) em ago/2026 | R$ 130.426,90, idêntico a `resultado-regras` em todos os meses | **bug antigo corrigido** | `ledir.php` não contava pró-labore nem outras receitas; `ledir-new.php` descontava a comissão duas vezes e não somava outras receitas. `ConsultasTest` confere `ResultadoMensal` contra o gabarito em todos os 380 pares mês × destino. |
| 2026-09-15 | rateio do GERAL | acompanhamentos do legado: ÷2 fixo; mensal: ÷3 fixo | ÷2 até ago/2025, ÷3 desde set/2025 | **bug antigo corrigido** | Regra de 15/09/2026. O rateio anterior do sistema novo (`RateioDoGeral`, que dividia pelas unidades abertas no dia e rateava todas as categorias) foi removido. |