# Vendas Setorial — Ponto de entrada

Dashboard analítico interno da AltWise que cruza **três fontes de vendas/faturamento** sob um eixo
comum de **28 segmentos da economia**, com drill-downs e uma visão combinada que projeta as séries
anuais para frente usando os dados trimestrais mais recentes.

> **Confidencialidade:** o dashboard pode ser exibido a terceiros. A UI **nunca** cita a fonte final
> dos dados. Rótulos públicos: *Meios de pagamento*, *Faturamento das empresas*, *Faturamento e-commerce*;
> fonte exibida = **AltWise**. Esta regra vale para todo artefato renderizado (telas, charts, Excel).
> A documentação técnica interna (esta pasta) pode nomear as fontes.

---

## As três fontes (internamente)

| View | Rótulo público | Fonte real (interno) | Tabela BQ | Grão | Cobertura |
|---|---|---|---|---|---|
| 1 | Meios de pagamento | BCB Meios de Pagamento (tarifas de intercâmbio) | `0_bcb.mpv_intercambio_tic` (+ `mpv_dim_segmento_mcc`) | trimestral | 1999T1–2026T1 |
| 2 | Faturamento das empresas | RF Estudos Setoriais (IRPJ por CNAE) | `aiDataset.rfb_setoriais` | anual | 2008–2024 |
| 3 | Faturamento e-commerce | MDIC e-commerce por NCM | `aiDataset.mdic_ecommerce_ncm` | anual | 2016–2024 |
| 4 | Visão combinada | — (derivada das 3) | — | anual + trimestral projetada | até 2026T1 |
| 5 | Cartões — mercado | meios de pagamento ÷ faturamento das empresas | `mpv_intercambio_tic` ÷ `rfb_setoriais` | anual | até último ano RF (2024) |
| 6 | Cartões — e-commerce | cartão não presente ÷ faturamento e-commerce | `mpv_intercambio_tic` (online) ÷ `mdic_ecommerce_ncm` | anual | até último ano MDIC (2024) |

Documentação de origem de cada fonte (interno):
- BCB: `/mnt/c/claude-workspace/bcb/meios_pagamento/docs/` (ENTRYPOINT, DATA_DICTIONARY, PLAYBOOK, RESUMO_DOC6334)
- RF: `/mnt/c/claude-workspace/dados_rfBR/pipelines/estudos_setoriais/docs/`
- MDIC: `/mnt/c/claude-workspace/dados_rfBR/pipelines/ecommerce_ncm/docs/`

---

## Mapa de navegação — "quero fazer X → vá para Y"

| Quero… | Vá para |
|---|---|
| Entender o que o dashboard mostra e abrir | este arquivo + `PLAYBOOK_OPERACAO.md` (seção "Rodar o dashboard") |
| **Atualizar os dados / regenerar o dashboard** | `PLAYBOOK_OPERACAO.md` (ordem correta de execução) |
| Entender **como as fontes se combinam** (trimestralização, projeção) | `PLAYBOOK_USO_COMBINADO.md` |
| Entender **por que** as decisões de modelagem foram tomadas | `MODELAGEM.md` |
| **Acrescentar** nova fonte / nova visão / novo cruzamento | `PREFLIGHT_NOVA_FONTE.md` |
| Gerar um **Excel** de uma série específica | `PLAYBOOK_USO_COMBINADO.md` (seção Excel) + `build/export_excel.py` |
| Saber **o que validar** / critérios de qualidade | `VERIFICATION.md` |
| Mudar **nomes amigáveis ou cores** dos segmentos | edite `crosswalks/segmentos.json` e rode o build |
| Corrigir o **mapeamento** de um CNAE/NCM a um segmento ou seu **elo de cadeia** (varejo/atacado/indústria) | edite `crosswalks/cnae_to_segmento.csv` (col. `tipo`) / `ncm2_to_segmento.csv` e rode o build |
| Entender **cadeia** (varejo/atacado/indústria) e **modos temporais** (LTM/ano fechado) | `MODELAGEM.md` §2b/§2c |

---

## Estrutura do projeto

```
vendas_setorial/
  crosswalks/      segmentos.json (28 seg + cores) · cnae_to_segmento.csv · ncm2_to_segmento.csv
  sql/             v1_pagamentos_cube · v2_faturamento · v3_ecommerce · v4_bcb_shares  (.sql testados no BQ)
  build/           config.py · build_data.py (BQ -> data/*.json) · export_excel.py
  data/            JSONs gerados (gitignored), consumidos pelo app
  app/             index.html + css/ + js/  (dashboard estático, abre no navegador)
  design/          design system (.zip) + ref/ (extraído)
  docs/            esta documentação
```

## Início rápido (30s)

```bash
cd /mnt/c/claude-workspace/dashboards/vendas_setorial
python3 build/build_data.py          # gera data/*.json a partir do BQ
python3 -m http.server 8080          # serve localmente
# abra http://localhost:8080/app/
```

O eixo comum, os filtros e a navegação são idênticos nas quatro visões; o sistema foi desenhado para
receber **novas fontes** sem reescrever a camada de design (ver `PREFLIGHT_NOVA_FONTE.md`).