# Modelagem — decisões e justificativas

Registra **por que** o dashboard é como é. Para quem vai manter, auditar ou estender.

## 1. Por que o eixo comum é o agrupamento de meios de pagamento (28 segmentos)
A fonte trimestral (BCB) já agrupa MCC em **28 segmentos econômicos** nomeados (códigos 401–428), com
rótulos legíveis para humanos ("Alimentação", "Roupas, sapatos, acessórios e afins", etc.). É o único
dos três sistemas com um agrupamento setorial pronto **e** com cadência trimestral recente — por isso
vira a régua. Reaproveitamos os **nomes oficiais do dicionário** como rótulos da UI (fonte de verdade:
`crosswalks/segmentos.json`); cores são uma paleta categórica estendida do design system (8 → 28).

## 2. Crosswalks construídos do zero (o BCB não fornece CNAE/NCM)
O dicionário do BCB mapeia **apenas MCC → segmento**. Não há CNAE nem NCM nele. Para trazer RF e MDIC
ao mesmo eixo, construímos dois crosswalks curados, por "maior representatividade / uso mais provável":

- **`cnae_to_segmento.csv`** — resolução **mais específico primeiro**: override por **classe CNAE (4 díg)**
  → base por **divisão (2 díg)**. A base por divisão cobre toda a economia (~87 divisões). Os overrides
  por classe dão **granularidade de varejo** (divisões 45/46/47): supermercado (47.11→414) ≠ vestuário
  (47.81→416) ≠ farmácia (47.71→407) ≠ eletro (47.53→406) ≠ móveis/construção (47.44→413) ≠ autopeças
  (45.30→419), etc. Atacado (div 46) vai a *Grandes Atacadistas* (408), espelhando a própria lógica do
  BCB, com exceções de alto valor (combustível 46.81→415; farma 46.44→407).
- **`ncm2_to_segmento.csv`** — cada **capítulo NCM (2 díg)** ao segmento dominante, permitindo **fundir**
  capítulos afins (ex.: 61+62 vestuário→416; 84+85 eletro→406; 30 farma→407; 87 autopeças→419). Drill do
  e-commerce é por este nível (2 díg), como pedido.
- Códigos sem contrapartida clara caem em **423 (Outros)**. O build loga a % de receita em "Outros" e
  alerta se > 35% (hoje ~17% na RF — saudável).

Por que classe (e não subclasse) na RF: classe (4 díg) existe em **todos** os anos 2016–2024 com
cobertura completa e já separa os nichos de varejo; subclasse só existe 2019+. Anos antigos (2008–2015)
têm só divisão/grupo — aí o varejo (div 47) fica agregado em 421, documentado.

## 2b. Eixo da cadeia (tipo): varejo × atacado × indústria × serviços
Além do segmento de **produto**, cada CNAE recebe um **elo da cadeia** (`tipo`) em
`cnae_to_segmento.csv`: **varejo · atacado · industria · servicos**. Isso permite, dentro de um mesmo
segmento de produto, separar a loja (varejo) da distribuição (atacado) da fabricação (indústria) — o
pedido típico "no vestuário, separar confecção (div 14, indústria) do varejo (47.81)". Por isso o
atacado especializado (div 46) e a indústria (div 10–33) foram **remapeados para o segmento de produto**
(ex.: atacado de vestuário 46.42 → 416 *atacado*; confecção 14 → 416 *industria*; varejo 47.81 → 416
*varejo*), em vez de jogar todo atacado em 408. O 408 "Grandes Atacadistas" guarda só o atacado
**genérico/sem predominância** (46.19/46.89/46.93).

**Regra especial de alimentos:** o varejo de alimentos **inclui o atacarejo** (46.91 atacado com
predominância alimentícia → tipo=*varejo*, junto da loja); a **fabricação** de alimentos/bebidas
(div 10/11) fica *industria*; e o **atacado de commodities agrícolas** (café 46.21, soja 46.22, cereais
46.32, carnes 46.34…) fica *atacado*, separado do atacarejo. Serviços (div 49+) e segmentos sem cadeia
de bens ficam *servicos*.

O e-commerce (MDIC/NCM) é, por natureza, **varejo online** — não tem eixo de cadeia. Na Visão combinada,
o filtro de cadeia atua só sobre a linha de Faturamento das empresas; a linha de e-commerce aparece
apenas em *Todos*/*Varejo*; a de meios de pagamento é sempre cheia (régua).

## 2c. Modos temporais: Trimestral · LTM · Ano fechado
A série nativa de meios de pagamento é **trimestral**. O dashboard oferece dois modos derivados,
calculados no cliente: **LTM** (últimos 12 meses = soma móvel dos 4 trimestres em cada ponto; ticket =
valor LTM ÷ unidades LTM, nunca média de ticket) e **Ano fechado** (somas por ano-calendário, descartando
anos incompletos). Disponíveis nas visões com base trimestral (Meios de pagamento e Combinada).

## 3. Granularidade RF: escolher a mais fina por ano (sem dupla contagem)
A tabela RF traz **vários níveis simultâneos** (seção/divisão/grupo/classe/subclasse) — somá-los
duplicaria. O build escolhe, **por ano**, a granularidade mais fina presente (classe > grupo > divisão):
2008–2010 divisão, 2011–2015 grupo, 2016–2024 classe. Nos níveis finos as colunas de nível superior vêm
**nulas** — por isso a divisão é derivada do prefixo do código da classe/grupo.

## 4. Métricas da RF: só o que existe de verdade
A RF de estudos setoriais **não publica DRE** — não há Lucro Bruto, Lucro Líquido nem Despesas
Operacionais. Entregamos **Receita Bruta** (faturamento) + métricas reais complementares: nº de empresas
(CNPJs), massa salarial/empregados, exportações/importações e arrecadação total. **Nunca** inventamos
lucro/despesas (regra do workspace: não fabricar dado).

## 5. Regime tributário
`is_simples_nacional` separa **Simples** de **regime normal** (Lucro Real/Presumido/Arbitrado/Imune/
Isento). As visões 2 e 3 dão o **consolidado** (normal+Simples) e a **quebra**. RF publica arquivos
complementares (normal vs Simples) não sobrepostos — a união dá cobertura completa.

## 6. Trimestralização e projeção (Visão 4)
Detalhe das fórmulas em `PLAYBOOK_USO_COMBINADO.md`. Princípios:
- RF/MDIC anuais → trimestrais via **share intra-ano do BCB** (RF: todas as capturas; MDIC: só online).
- Projeção até 2026T1 encadeando a **razão YoY do BCB** por segmento (real até 2026T1).
- Σ trimestres = anual (garantido); nível absoluto vem da fonte anual, forma temporal vem do BCB.

## 7. Arquitetura técnica
- **Build em Python** roda SQL no BQ (somente leitura), aplica crosswalks e matemática em Python e
  emite `data/*.json`. O cubo de pagamentos (~63k combos não-zero) é emitido em **colunas paralelas**
  compactas; o app filtra/soma no cliente — suporta qualquer combinação de filtros sem novas queries.
- **App estático** (HTML/CSS/JS vanilla, sem build) porta o design system (IBM Plex Sans/Mono, light
  mode, charts SVG com banda de projeção). Roda local via `http.server`.
- Sem escrita no BQ; nenhum `TRUNCATE`/`DELETE`. Re-rodar é seguro e idempotente.

## 8. Valores nominais
Séries em R$ **nominais** (sem deflação). O dashboard é descritivo (tendência/composição). Se um estudo
exigir valores reais, deflacionar a jusante (no Excel) — não embutido para não distorcer a leitura bruta.

## 9. Confidencialidade
A UI usa apenas rótulos públicos (Meios de pagamento / Faturamento das empresas / Faturamento e-commerce)
e fonte "AltWise". Fontes finais aparecem só nesta documentação técnica.

## 9b. Penetração de cartões (Visões 5 e 6)
Duas visões anuais que combinam as bases pela mesma classificação de segmento, **sem projeção**, até o
último ano com denominador disponível (RF/MDIC = 2024 hoje; dinâmico).
- **Cartões — mercado:** numerador = transações em cartão (**todas as capturas**, presente + não
  presente); denominador = **faturamento de VAREJO** do segmento (RF, `tipo=varejo`, consolidado
  normal+simples — inclui atacarejo/supermercados, que já são `varejo` no crosswalk). Métrica central =
  **penetração** = cartão ÷ faturamento de varejo, por segmento. **Por que varejo e não total:** cartão é
  atividade de consumo/varejo; dividir pelo faturamento total (incluindo indústria/atacado/serviços)
  distorce a razão. Além disso, a **janela é limitada aos anos com granularidade `classe`** (filtro fino
  de varejo disponível, hoje 2016+) — antes disso o varejo fica agregado em segmentos genéricos e a razão
  **quebra** na virada de granularidade (ex.: vestuário 2015→2016). Restringir a janela elimina a quebra.
- **Cartões — e-commerce:** numerador = cartão **não presente** (online); denominador = **faturamento
  e-commerce** (MDIC). Mesma estrutura de decomposição.
- **Drills** (frações do numerador): % crédito e % débito+outros (sobre o faturamento); e, dentro do
  crédito (como fração do crédito): **Premium + Empresarial** (premium/platinum + corporativo/
  empresarial), **à vista × parcelado** (parcelado = soma de todas as parcelas) e **nº de parcelas**
  (1 / 2-3 / 4-6 / 7+). Identidades garantidas no build: crédito+débito=cartão; à vista+parcelado=
  crédito; soma das parcelas=crédito.
- Insumo: `sql/v5_cartao_anual.sql` (BCB agregado por ano×segmento×função×presença×tier×parcelas) →
  `build_mercado()` → `data/mercado.json`. As frações são razões nominais entre fontes diferentes —
  ler como **mix/penetração**, não como igualdade contábil.

## 10. Aprendizados de construção (gotchas para quem mantém)
Itens não-óbvios descobertos ao construir — leia antes de mexer:
- **RF não tem DRE.** `rfb_setoriais` só publica `receita_bruta` + arrecadação/folha/comércio exterior. Não
  existe lucro/despesa. Nunca fabricar — usar as métricas reais complementares.
- **Granularidades CNAE coexistem na mesma tabela** (secao/divisao/grupo/classe/subclasse) — somá-las
  duplica. O build escolhe a **mais fina por ano**. E, no nível fino, **as colunas de nível superior vêm
  NULL** (uma linha de `classe` "47.11-3" tem `cnae_divisao` NULL) — por isso a divisão é derivada do
  prefixo do código, não da coluna pai.
- **MDIC:** usar só `source_type='csv_archive'` (senão dupla contagem entre as 3 origens); excluir
  `'########'` (LGPD) e `'Erro de Classificação'`; **quantidade só existe nas fontes xlsx** — por isso a
  métrica de e-commerce é apenas faturamento (sem ticket/contagem confiável).
- **BCB:** `formacaptura='Não presencial (online)'` = cartão **não presente** (e-commerce); todo o resto
  (incl. `Recorrente`) = presente. Cubo de ~63k combos não-zero → emitido em colunas paralelas (filtro no
  cliente). `qtdTransacoes`/`valorTransacoes` em **absoluto** (não escalar).
- **Crosswalks são curados e construídos do zero** (o BCB só dá MCC→segmento). O eixo de **cadeia**
  (varejo/atacado/indústria) exigiu re-mapear atacado especializado e indústria para o segmento de
  **produto** (não jogar tudo em 408). Revisar `cnae_to_segmento.csv` quando surgirem CNAE novos.
- **BigQuery:** `desc` é palavra reservada — sempre dar alias (`AS dsc`). Todas as queries são
  **somente leitura**; o build nunca escreve no BQ e é idempotente.
- **`build/` é ignorado pelo `.gitignore` raiz** do workspace (artefatos). Este projeto re-inclui `build/`
  no `.gitignore` local porque ali ficam os SCRIPTS do pipeline — não remover essa re-inclusão.
- **Verificação de UI sem navegador:** o WSL não tem libs do Chromium; a checagem de cliques/estado roda
  via harness **jsdom** (carrega o `index.html`/`app.js`/JSON reais e clica nos controles). Valida lógica
  e estrutura, não pixels — a conferência visual final é humana.