# Playbook de Operação — atualizar e rodar o dashboard

Para um agente (ou humano) que entra neste working folder e precisa **atualizar os dados** e/ou
**rodar o dashboard**. Siga a ordem. Nada aqui escreve no BigQuery (somente leitura).

## Pré-requisitos
- Python 3.10+ com `google-cloud-bigquery` e `openpyxl` instalados.
- Credencial BQ ativa (`GOOGLE_APPLICATION_CREDENTIALS` apontando para a SA, já configurado neste ambiente).
- Acesso de leitura aos datasets `menumind-450015.0_bcb` e `menumind-450015.aiDataset`.

## Ordem correta de atualização

1. **Atualizar a fonte trimestral (Meios de pagamento), se houver trimestre novo.**
   As séries trimestrais e as projeções dependem dela. Atualização da fonte é feita no pipeline próprio:
   `/mnt/c/claude-workspace/bcb/meios_pagamento/` → `python3 pipeline_bcb_mpv.py --mode update`
   (ver o playbook daquele pipeline; respeita o throttle do Olinda). Só precisa rodar quando o BCB
   publica um novo trimestre. As tabelas RF e MDIC são **anuais** e atualizam com defasagem (até 2024 hoje).

2. **Conferir que RF e MDIC estão no BQ.** Sanidade rápida (opcional):
   ```sql
   SELECT MAX(ano) FROM `menumind-450015.aiDataset.rfb_setoriais`;       -- esperado >= 2024
   SELECT MAX(ano) FROM `menumind-450015.aiDataset.mdic_ecommerce_ncm`;  -- esperado >= 2024
   ```
   Quando um novo ano for publicado, basta re-rodar o build — o ano novo entra automaticamente.

3. **Revisar crosswalks se surgiram CNAE/NCM novos.** Em geral não muda. Se um ano novo trouxer
   códigos não mapeados, eles caem em `423 (Outros)`. O build loga a % de receita em "Outros"
   (alerta se > 35%). Para corrigir, edite `crosswalks/cnae_to_segmento.csv` /
   `crosswalks/ncm2_to_segmento.csv` (ver `MODELAGEM.md` para a lógica) e rode o build de novo.

4. **Rodar o build** (BQ → `data/*.json`):
   ```bash
   cd /mnt/c/claude-workspace/dashboards/vendas_setorial
   python3 build/build_data.py
   ```
   - Roda as queries de `sql/`, aplica os crosswalks, trimestraliza RF e MDIC com os shares do BCB,
     projeta até 2026T1 e escreve `data/*.json`.
   - Faz validações e sai com código 0 (OK) ou 2 (falha). Leia o log: deve mostrar
     `OK: trimestral RF 2024 == anual`, `OK: projecao chega a 2026T1`, e a cobertura de "Outros".
   - **Idempotente:** re-rodar regenera tudo do zero; não escreve no BQ.

5. **Abrir/validar o dashboard:**
   ```bash
   python3 -m http.server 8080
   # abra http://localhost:8080/app/
   ```
   (Precisa ser servido por HTTP — `fetch()` de arquivos `file://` é bloqueado pelo navegador.)
   Confira: as 6 visões abrem; filtros e drill-downs respondem; a visão combinada mostra a faixa
   de projeção até T1/26. Critérios objetivos em `VERIFICATION.md`.

6. **Gerar Excel (opcional), sob demanda:**
   ```bash
   python3 build/export_excel.py     # gera exports/*.xlsx
   ```
   Os jobs pré-mapeados estão no topo de `build/export_excel.py`. Para criar uma nova série, ver
   `PLAYBOOK_USO_COMBINADO.md` (seção Excel).

## Como interpretar cada atualização
- **Novo trimestre BCB:** estende a visão 1, recalcula shares e **reprojeta** RF/MDIC (a projeção
  ancora no BCB mais recente). É a única atualização frequente.
- **Novo ano RF/MDIC:** estende as visões 2/3 e vira "realizado" o que antes era projeção naquele ano;
  a projeção avança um ano à frente.
- **Mudança de crosswalk:** re-agrupa o histórico inteiro (não destrói dado; só re-mapeia). Sempre
  re-rodar o build após editar.

## Recuperação de problemas
- Build falha em auth → conferir `GOOGLE_APPLICATION_CREDENTIALS`.
- Query falha → testar o `.sql` isolado no BQ; confirmar que as tabelas existem e os nomes de coluna batem.
- Dashboard abre em branco → verificar no console do navegador se `../data/*.json` carregaram (rodar via http.server, não file://).
- "Outros" (423) muito alto → crosswalk desatualizado; revisar `cnae_to_segmento.csv`/`ncm2_to_segmento.csv`.