Skip to content

Navigation Menu

Sign in
Sign up

Repository files navigation

🏗️ AutoINCC API

Python FastAPI PostgreSQL Redis Celery Docker License: GPL v3 Portal

AutoINCC é uma plataforma open-source e API RESTful de alta performance projetada para automatizar a extração, transformação, cálculo econômico e disponibilização do Índice Nacional de Custo da Construção (INCC).

Concebido como projeto irmão do AutoSINAPI e do AutoCUB, o AutoINCC integra o ecossistema de dados abertos para a construção civil (Mundo AEC). Todas as ferramentas interativas, simuladores de custos e acesso centralizado às APIs estão disponíveis no portal oficial:

👉 mundoaec.com | mundoaec.com/autoincc

O AutoINCC adota arquitetura de microsserviços distribuídos de alta disponibilidade: FastAPI + Redis + Celery + PostgreSQL (Star Schema).

🏛️ Arquitetura de Microsserviços & Resiliência

 ┌───────────────────────────────────┐
 │ FastAPI (REST API) │
 └─────────┬───────────────▲さんかく─────────┘
 │ │
 1. Dispara │ │ 3. Consulta Cache L2
 task │ │ (< 3ms)
 ▼ │
 ┌─────────────────────────┴─────────┐
 │ REDIS │
 │ (Broker Celery + Cache L2) │
 └─────────┬─────────────────────────┘
 │
 2. Consome │ Invalida / Aquece
 tarefas │ cache pós-ETL
 ▼
 ┌───────────────────────────────────┐
 │ Celery ETL Worker │
 │ (Worker Assíncrono) │
 └─────────┬─────────────────────────┘
 │
 │ 4. UPSERT Idempotente
 ▼
 ┌───────────────────────────────────┐
 │ PostgreSQL │
 │ (Star Schema DW) │
 └───────────────────────────────────┘
 Orquestrador de Inicialização (Container 'init'):
 Postgres & Redis Saudáveis ──▶ Init Executa DDL/Seed ──▶ Encerra com Sucesso (0)
 │
 ┌─────────────────────────────────────┴─────────────────────────────────────┐
 ▼ ▼
 API inicia com DB 100% pronto Worker inicia pronto para tarefas

🚀 Funcionalidades Principais

  • ETL com Celery Worker Assíncrono: Extração desacoplada com tolerância a falhas, retentativas e persistência de mensagens no Redis.
  • Cache L2 de Alta Performance (Redis): Latência de leitura inferior a 3ms para consultas aos índices consolidados (/latest) e séries históricas (/history), com invalidação automática orientada a eventos pós-carga.
  • Polite Crawling & Request Pacer: Limitação de taxa ética com jitter estocástico uniforme entre requisições externas ao Banco Central e FGV, evitando bloqueios (HTTP 429) e sobrecargas.
  • Container Init Orquestrador: Garante inicialização determinística do banco e seed de dimensões via service_completed_successfully antes da inicialização da API e dos workers.
  • Rigor Matemático:
    • Normalização de taxas percentuais ($v_m = \text{valor} / 100$).
    • Número-Índice Contínuo (Base 100): Encadeamento de taxas via produtório acumulado histórico (100ドル \times \prod (1 + v_m)$).
    • Variação Acumulada no Ano (YTD - Year to Date).
    • Variação Acumulada nos Últimos 12 Meses (janela móvel).
  • Modelo Dimensional (Star Schema): PostgreSQL com tabelas dim_tempo, dim_categoria, dim_geografia, dim_tipo_indice e a tabela fato_incc com UPSERT nativo (ON CONFLICT DO UPDATE).
  • Calculadora de Correção Monetária: Reajuste de contratos e parcelas pelo fator acumulado do período ($Valor \times \frac{I_{fim}}{I_{inicio}}$).

⚡ Inicialização Rápida com Docker Compose

Suba todo o ecossistema (Postgres, Redis, Init, API e Celery Worker) com um único comando:

docker compose up -d --build

Verificação do Status dos Containers

docker compose ps

Você verá o container autoincc_init executado com código de saída 0 e todos os serviços saudáveis:

NAME IMAGE STATUS PORTS
autoincc_api autoincc_api-api Up (healthy) 0.0.0.0:8000->8000/tcp
autoincc_celery_worker autoincc_api-celery_worker Up 
autoincc_init autoincc_api-init Exited (0) 
autoincc_postgres postgres:15-alpine Up (healthy) 0.0.0.0:5432->5432/tcp
autoincc_redis redis:7-alpine Up (healthy) 0.0.0.0:6379->6379/tcp

📚 Endpoints da API (/api/v1)

1. Raio-X do Mercado & Visão Geral (/overview)

Retorna um snapshot consolidado do último mês de referência disponível, com as taxas de ambas as variantes (INCC-M e INCC-DI), spread pontual, variações acumuladas em múltiplas janelas (YTD, 12M, 24M, 36M) e dinâmica de aceleração/momentum.

GET /api/v1/incc/overview

Cache L2 no Redis (incc:overview, TTL 3600s).

Exemplo de Resposta:

{
 "data_referencia": "2026年07月01日",
 "incc_m": {
 "sigla": "INCC-M",
 "data_id": "2026年07月01日",
 "variacao_mensal_percentual": "0.6100",
 "numero_indice": "118.406632",
 "variacao_ytd_percentual": "4.9085",
 "variacao_12m_percentual": "6.4594",
 "variacao_24m_percentual": "14.3580",
 "variacao_36m_percentual": "-100.0000"
 },
 "incc_di": {
 "sigla": "INCC-DI",
 "data_id": "2026年08月01日",
 "variacao_mensal_percentual": "0.8500",
 "numero_indice": "119.115357",
 "variacao_ytd_percentual": "5.5900",
 "variacao_12m_percentual": "6.5542",
 "variacao_24m_percentual": null,
 "variacao_36m_percentual": null
 },
 "spread_mensal_pontos": "-0.2400",
 "aceleracao_incc_m": {
 "delta_mes_anterior_pontos": "-0.1700",
 "delta_ano_anterior_pontos": "-0.3000",
 "tendencia": "desacelerando"
 }
}

2. Comparativo Unificado Lado a Lado (/compare)

Série temporal unificada e alinhada mês a mês entre INCC-M e INCC-DI, com cálculo automatizado de spread ponto a ponto ($v_{\text{INCC-M}} - v_{\text{INCC-DI}}$) e detecção da variante dominante (INCC-M, INCC-DI ou EMPATE).

GET /api/v1/incc/compare?data_inicio=2024年01月01日&data_fim=2024年12月01日&skip=0&limit=100

Cache L2 no Redis (incc:compare:*, TTL 3600s).

3. Matriz de Sazonalidade dos 12 Meses (/analytics/seasonality)

Decomposição estatística histórica de longo prazo (1944 até o presente) agregada para cada um dos 12 meses do ano civil (Janeiro a Dezembro), contendo média, mediana, desvio padrão amostral, mínimos, máximos e probabilidade histórica de alta inflacionária.

GET /api/v1/incc/analytics/seasonality?sigla=INCC-M

Cache L2 no Redis (incc:seasonality:*, TTL 86400s).

4. Estatísticas Agregadas da Série (/analytics/stats)

Resumo estatístico da série histórica com volatilidade anualizada ($\sigma \times \sqrt{12}$), média, mediana e identificação dos recordes históricos de alta e baixa com data exata.

GET /api/v1/incc/analytics/stats?sigla=INCC-M

Cache L2 no Redis (incc:stats:*, TTL 86400s).

Exemplo de Resposta:

{
 "sigla": "INCC-M",
 "total_observacoes": 990,
 "data_inicio": "1944年02月01日",
 "data_fim": "2026年07月01日",
 "media_mensal_percentual": "4.0950",
 "mediana_mensal_percentual": "1.0000",
 "desvio_padrao_mensal_pontos": "8.5623",
 "volatilidade_anualizada_percentual": "29.6608",
 "recorde_alta_percentual": "78.4100",
 "recorde_alta_data": "1990年03月01日",
 "recorde_baixa_percentual": "-4.4200",
 "recorde_baixa_data": "1945年01月01日"
}

5. Catálogo Técnico e Governança Metodológica (/metadata)

Exposição dos metadados oficiais das séries (código BCB SGS, instituto responsável, janelas de coleta do mês civil vs período 21 a 20 e histórico de revisões metodológicas do FGV IBRE).

GET /api/v1/incc/metadata

Cache L2 no Redis (incc:metadata, TTL 86400s).

6. Último Índice Consolidado (/latest)

GET /api/v1/incc/latest?sigla=INCC-M

7. Série Histórica Filtrada (/history)

GET /api/v1/incc/history?data_inicio=2024年01月01日&data_fim=2024年12月01日&sigla=INCC-M&skip=0&limit=100

8. Calculadora de Reajuste Contratual (/correction)

POST /api/v1/incc/correction
Content-Type: application/json
{
 "valor_inicial": 100000.00,
 "data_inicio": "2024年01月01日",
 "data_fim": "2024年06月01日",
 "sigla": "INCC-M"
}

9. Disparo Manual do ETL via Celery Worker (Protegido)

POST /api/v1/etl/trigger
X-API-Key: autoincc_secret_token_dev_123
Content-Type: application/json
{
 "series_codes": [192, 7456],
 "data_inicial": "2024年01月01日"
}

🧪 Testes Automatizados (TDD)

A suíte completa conta com 37 testes automatizados cobrindo domínio (DDD), modelos matemáticos, resiliência do cache Redis, limitação ética (pacing) e adaptadores HTTP FastAPI:

pytest -v

📄 Licença

Distribuído sob a licença GNU General Public License v3.0 (GPLv3). Consulte o arquivo LICENSE para os termos completos de uso, modificação e distribuição de código aberto.

About

🏗️ API RESTful aberta e pipeline ETL para dados do INCC (FGV IBRE / BCB SGS) com Star Schema DW, Celery, Redis e análises estatísticas. Integrado ao ecossistema Mundo AEC.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

AltStyle によって変換されたページ (->オリジナル) /