# Playbook de Uso Combinado — como as três fontes interagem

Ensina um agente a **usar as três bases de forma combinada**: uma fonte projetando/transformando a
outra. É a lógica da Visão 4 e a base para análises e exports.

## O eixo comum: 28 segmentos
Todas as fontes são reprojetadas para os **28 segmentos** do agrupamento de meios de pagamento
(`crosswalks/segmentos.json`, códigos 401–428, com nome amigável e cor). Cada fonte chega a esse eixo
por um crosswalk próprio:
- **Meios de pagamento (BCB):** já vem por segmento (campo `segmento`, decodificado por `mpv_dim_segmento_mcc`).
- **Faturamento das empresas (RF):** CNAE → segmento via `cnae_to_segmento.csv` (override por classe → base por divisão).
- **Faturamento e-commerce (MDIC):** capítulo NCM (2 díg) → segmento via `ncm2_to_segmento.csv`.

## Cadência e papéis
| Fonte | Cadência | Papel na combinação |
|---|---|---|
| Meios de pagamento | **trimestral**, até 2026T1 | **régua temporal** — fornece sazonalidade intra-ano e o crescimento recente para projetar |
| Faturamento das empresas | anual, até 2024 | nível absoluto de faturamento total a ser trimestralizado e projetado |
| Faturamento e-commerce | anual, até 2024 | nível absoluto de faturamento online a ser trimestralizado e projetado |

## Transformação 1 — Trimestralizar as séries anuais
Para um segmento `s` e ano `y`:
```
share_BCB(s, y, T)  = valor_BCB(s, y, T) / Σ_T valor_BCB(s, y, T)      (4 trimestres do ano)
RF_trimestral(s,y,T)   = RF_anual(s,y)   × share_BCB_total(s,y,T)       # todas as capturas
MDIC_trimestral(s,y,T) = MDIC_anual(s,y) × share_BCB_naoPresente(s,y,T) # apenas cartão não presente (online)
```
- RF usa o share de **todas as capturas** (faturamento total ≈ atividade total em cartão).
- MDIC usa o share de **cartão não presente** (online), coerente com e-commerce.
- Se o segmento não tem BCB naquele ano (raro), usa split igual (0,25 por trimestre).
- **Garantia:** Σ dos 4 trimestres = o anual (validado no build).

## Transformação 2 — Projetar para frente (até 2026T1)
Do último ano realizado (2024) em diante, encadeando a razão YoY do BCB por segmento:
```
RF_tri(s, t)   = RF_tri(s, t−4 trimestres)   × [ valor_BCB_total(s,t)       / valor_BCB_total(s,t−4) ]
MDIC_tri(s, t) = MDIC_tri(s, t−4 trimestres) × [ valor_BCB_naoPresente(s,t) / valor_BCB_naoPresente(s,t−4) ]
```
- O BCB tem dado **real** até 2026T1, então a projeção é "puxada" pelo crescimento observado em cartão.
- Encadeia sequencialmente: 2025T* usa 2024 (trimestralizado) como base; 2026T1 usa 2025T1 (já projetado).
- Razão YoY indefinida (base zero) → fallback 1,0 (mantém nível).
- A faixa projetada é marcada no chart (tracejado + hachura) a partir de `proj_from_idx`.

## Eixo da cadeia (varejo/atacado/indústria) e modos temporais
- O **filtro de Cadeia** (Todos/Varejo/Atacado/Indústria/Serviços) separa o elo dentro do mesmo segmento
  de produto. Na Combinada ele atua sobre a linha de Faturamento das empresas (`rf[cadeia]`); a linha de
  e-commerce só aparece em Todos/Varejo (e-commerce = varejo online); a de meios de pagamento é a régua e
  não filtra por cadeia. Ver `MODELAGEM.md §2b` (inclui a regra especial de alimentos/atacarejo).
- **Modos temporais:** Trimestral (nativo), **LTM** (soma móvel de 4 trimestres; ticket = valor LTM ÷ qtd
  LTM) e **Ano fechado** (soma por ano-calendário, sem anos incompletos). Ver `MODELAGEM.md §2c`.

## Leituras possíveis da Visão combinada (por segmento)
- **Penetração e-commerce** = Faturamento e-commerce ÷ Faturamento das empresas.
- **Intensidade de cartão** = Meios de pagamento ÷ Faturamento das empresas.
- **Aceleração recente** = inclinação da projeção vs realizado (vinda do BCB).

> As três séries medem coisas diferentes (transacionado em cartão ≠ faturamento declarado ≠ faturamento
> online). Use a combinada para **tendência e composição**, não para igualdade de nível entre fontes.

## Excel — séries para estudo manual
`build/export_excel.py` reaproveita exatamente a lógica do `build_data.py` (mesmos números do dashboard).
Jobs pré-mapeados no topo do arquivo:
1. Pagamentos — valor trimestral, todos os segmentos, **cartão não presente**.
2. Faturamento — Receita Bruta anual por segmento (consolidado + split por regime).
3. E-commerce — Faturamento anual por segmento.
4. Combinada — série trimestral realizada+projetada das 3 fontes para um segmento.

**Adicionar um job:** acrescente um dict em `EXPORT_JOBS` no topo de `export_excel.py`:
- `nome` (arquivo), `visao` (`pagamentos|faturamento|ecommerce|combinada`),
- `segmentos` (`'todos'` ou lista de nomes amigáveis/códigos),
- `metrica` (pagamentos: `valor|qtd|tarifa_x_valor`; faturamento: `receita|n_cnpj|massa|export|arrec`;
  ecommerce: `faturamento`; combinada: as 3 séries), `granularidade` (`anual|trimestral`),
- pagamentos aceita `filtros` `{pres,funcao,pay,tier}` (omita uma chave para somar naquela dimensão).
- faturamento/combinada aceitam `tipo` (`todos|varejo|atacado|industria|servicos`) para filtrar a cadeia.
Rode `python3 build/export_excel.py`. Nunca cite a fonte final em nenhuma célula/aba.