# Pré-flight — acrescentar nova fonte, visão ou cruzamento

O sistema foi desenhado para receber novas fontes **sem reescrever a camada de design**. Checklist
pronto para três tipos de extensão.

## A. Nova fonte de dados (que vira uma nova visão por segmento)

1. **Origem & doc.** Identifique a tabela BQ, o grão, a cadência e a coluna setorial (CNAE? NCM? CNPJ?
   código próprio?). Anote a doc de origem em `ENTRYPOINT.md` (tabela das fontes).
2. **Crosswalk para o eixo de 28 segmentos.** Se a fonte não vier por segmento BCB, crie
   `crosswalks/<x>_to_segmento.csv` no nível mais representativo (curado por "uso mais provável";
   sobras → 423). Reaproveite o padrão de `cnae_to_segmento.csv` (override → base) ou
   `ncm2_to_segmento.csv` (mapa direto). Drill = o nível do crosswalk.
3. **SQL.** Crie `sql/v5_<x>.sql` que agrega ao grão (período × código_setorial × [regime…]) com as
   métricas. **Teste no BQ antes** (regra do workspace).
4. **Build.** Em `build/build_data.py`: adicione `load_<x>_xwalk()`, `run_sql("v5_<x>.sql")` e um
   `build_<x>(...)` que mapeia para segmento e emite `data/<x>.json` (siga o schema das views existentes:
   `{anos|quarters, series:{seg:{…}}, drill:{seg:[…]}}`). Some uma validação em `validate()`.
5. **App.** Em `app/js/app.js`: registre a view na lista de nav (`viewsDef`), adicione um ícone, e um
   bloco `buildView` que lê `data/<x>.json` e reusa `chart()`, `spark()`, KPIs, chips de segmento e a
   tabela de drill já existentes. A navegação/filtros/cores vêm de graça.
6. **Cor/rótulo.** Se a fonte precisar de rótulo público, adicione em `meta.rotulos` (no build) e use só
   ele na UI (nunca a fonte final).
7. **Excel.** Adicione `visao:'<x>'` ao vocabulário de `export_excel.py` e um job pré-mapeado.
8. **Docs.** Atualize `ENTRYPOINT.md`, `MODELAGEM.md` (decisão do crosswalk) e `VERIFICATION.md` (checks).

## B. Novo cruzamento na Visão combinada (uma fonte transformando outra)
1. Defina a relação (qual fonte é régua temporal, qual é nível absoluto).
2. Em `build_combinada()`: adicione a nova série como mais uma linha (`bcb/rf/mdic/<novo>`), reusando os
   helpers `bcb_share()` (trimestralização) e `bcb_ratio()` (projeção) se a régua for o BCB — ou crie um
   helper análogo se a régua for outra fonte.
3. No app, a Visão combinada já desenha N séries — basta incluir a nova no array de séries + KPI.
4. Documente a fórmula em `PLAYBOOK_USO_COMBINADO.md`.

## C. Nova métrica numa visão existente
1. Adicione a coluna no `.sql` da visão e no `build_<view>` (lista `metricas`).
2. Exponha como KPI/chart no `buildView` correspondente. Sem mudança estrutural.

## Regras invioláveis em qualquer extensão
- **Testar todo SQL no BQ** antes de plugar; nunca entregar query não testada.
- **Somente leitura no BQ** (sem TRUNCATE/DELETE/WRITE).
- **Confidencialidade:** nenhum rótulo de fonte final na UI/Excel — só rótulos públicos + "AltWise".
- **Não inventar dado:** métrica inexistente fica de fora (não fabricar).
- **Idempotência:** re-rodar o build regenera tudo; sem efeitos colaterais.
- Rodar `build_data.py` e abrir o dashboard ao final; conferir `VERIFICATION.md`.