🏠 Início / 📚 Documentação / Implementação / Migracao Modulos Comuns

Migracao Modulos Comuns

🔄 Guia de Migração para Módulos Comuns

Este documento descreve como migrar os apps existentes para usar os módulos comuns do C-Suite.

📋 Índice

  1. Visão Geral
  2. Módulos Disponíveis
  3. Passo a Passo de Migração
  4. Exemplos por App
  5. Checklist de Migração

Visão Geral

Os módulos comuns (common/) fornecem funcionalidades padronizadas para todos os apps do ecossistema C-Suite:

Módulos Disponíveis

1. Logging Centralizado (common_logging)

Uso:

from common.common_logging import setup_logging, create_logging_middleware, get_logger

# No startup do app
setup_logging(
    app_name="meu-app",
    log_level=os.getenv("LOG_LEVEL", "INFO"),
    log_format="json" if os.getenv("ENV") == "production" else "text",
    structured=True
)
app.middleware("http")(create_logging_middleware("meu-app"))

# Em qualquer módulo
logger = get_logger(__name__)
logger.info("Mensagem de log")

2. Tratamento de Erros (common_errors)

Uso:

from common.common_errors import error_handler, CSuiteError, ErrorCode

# Registrar handler global
app.add_exception_handler(Exception, error_handler)

# Lançar erros padronizados
raise CSuiteError(
    error_code=ErrorCode.RESOURCE_NOT_FOUND,
    message="Recurso não encontrado",
    details={"resource_id": 123}
)

3. Health Checks (common_health)

Uso:

from common.common_health import create_health_router

health_router = create_health_router(
    app_name="meu-app",
    dependencies=[
        "database:csuite",
        "external_service:api_externa:http://api.externa.com"
    ]
)
app.include_router(health_router)

4. Métricas Prometheus (common_metrics)

Uso:

from common.common_metrics import create_metrics_router, create_metrics_middleware

metrics_router = create_metrics_router("meu-app")
app.include_router(metrics_router)
app.middleware("http")(create_metrics_middleware("meu-app"))

5. Distributed Tracing (common_tracing)

Uso:

from common.common_tracing import setup_tracing, get_tracer

# No startup do app
setup_tracing(
    app=app,
    service_name="meu-app",
    jaeger_host=os.getenv("JAEGER_HOST", "localhost"),
    jaeger_port=int(os.getenv("JAEGER_PORT", "14250"))
)

# Em funções assíncronas
tracer = get_tracer("meu-modulo")
with tracer.start_as_current_span("operacao_importante") as span:
    span.set_attribute("parametro", valor)
    # ... código ...

6. Circuit Breaker (common_circuit_breaker)

Uso:

from common.common_circuit_breaker import circuit_breaker, CircuitBreakerConfig

@circuit_breaker(
    name="chamada_api_externa",
    config=CircuitBreakerConfig(
        failure_threshold=5,
        recovery_timeout=30,
        expected_successes=1
    )
)
async def chamar_api_externa():
    # ... código ...
    pass

7. Event Sourcing (common_event_sourcing)

Uso:

from common.common_event_sourcing import get_event_store, EventType

event_store = get_event_store("csuite")
event_id = event_store.record_event(
    event_type=EventType.DECISION_CREATED,
    aggregate_id=str(decision_id),
    aggregate_type="decision",
    payload={"decision": decision_data},
    metadata={"user_id": user_id}
)

8. Notificações (common_notifications)

Uso:

from common.common_notifications import get_notification_service, NotificationChannel

notification_service = get_notification_service()
await notification_service.send_slack_message("Alerta importante!")
await notification_service.send_email(
    recipient="admin@example.com",
    subject="Alerta",
    body="Mensagem de alerta"
)

9. Business Metrics (common_business_metrics)

Uso:

from common.common_business_metrics import define_business_counter, get_business_metric

# No startup
define_business_counter(
    "decisions_total",
    "Total number of decisions made",
    ["org_id", "decision_type"]
)

# No código
get_business_metric("decisions_total").labels(
    org_id="1",
    decision_type="offer"
).inc()

Passo a Passo de Migração

Passo 1: Adicionar Imports

Adicione os imports necessários no início do arquivo main.py:

import os
import sys
from pathlib import Path

# Adiciona raiz do projeto ao path
sys.path.insert(0, str(Path(__file__).resolve().parents[N]))  # Ajuste N conforme necessário

# Imports dos módulos comuns
from common.common_logging import setup_logging, create_logging_middleware
from common.common_errors import error_handler
from common.common_health import create_health_router
from common.common_metrics import create_metrics_router, create_metrics_middleware
from common.common_tracing import setup_tracing

Passo 2: Configurar Logging

setup_logging(
    app_name="meu-app",
    log_level=os.getenv("LOG_LEVEL", "INFO"),
    log_format="json" if os.getenv("ENV") == "production" else "text",
    structured=True
)
app.middleware("http")(create_logging_middleware("meu-app"))

Passo 3: Configurar Error Handling

app.add_exception_handler(Exception, error_handler)

Passo 4: Adicionar Health Checks

health_router = create_health_router(
    app_name="meu-app",
    dependencies=["database:csuite"]  # Ajuste conforme necessário
)
app.include_router(health_router)

Passo 5: Adicionar Métricas

metrics_router = create_metrics_router("meu-app")
app.include_router(metrics_router)
app.middleware("http")(create_metrics_middleware("meu-app"))

Passo 6: Adicionar Distributed Tracing

setup_tracing(
    app=app,
    service_name="meu-app",
    jaeger_host=os.getenv("JAEGER_HOST", "localhost"),
    jaeger_port=int(os.getenv("JAEGER_PORT", "14250"))
)

Passo 7: Substituir Chamadas HTTP por Circuit Breaker

from common.common_http_client import get_http_client

async with get_http_client(
    base_url="http://api.externa.com",
    timeout=5.0,
    circuit_breaker_name="api_externa",
    failure_threshold=3,
    timeout_seconds=30.0
) as client:
    response = await client.get("/endpoint")

Passo 8: Adicionar Event Sourcing (se aplicável)

from common.common_event_sourcing import get_event_store, EventType

event_store = get_event_store("csuite")
# Registrar eventos importantes

Exemplos por App

4C Decision API

Arquivo: 4c/api/decision_api/main.py

Mudanças necessárias:
1. ✅ Adicionar logging centralizado
2. ✅ Adicionar error handling padronizado
3. ✅ Adicionar health checks
4. ✅ Adicionar métricas
5. ✅ Adicionar distributed tracing
6. ✅ Adicionar circuit breaker nas chamadas HTTP
7. ✅ Adicionar event sourcing nas decisões
8. ✅ Adicionar business metrics

CSuite Sales Manager APIs

Arquivos:
- csuite-sales-manager/decision-api/app/main.py
- csuite-sales-manager/manager-api/app/main.py

Mudanças necessárias:
1. ✅ Adicionar logging centralizado
2. ✅ Adicionar error handling padronizado
3. ✅ Adicionar health checks
4. ✅ Adicionar métricas
5. ✅ Adicionar distributed tracing
6. ✅ Adicionar business metrics

CSuite Context API

Arquivo: csuite-context/approot/app/main.py

Mudanças necessárias:
1. ✅ Adicionar logging centralizado
2. ✅ Adicionar error handling padronizado
3. ✅ Adicionar health checks
4. ✅ Adicionar métricas
5. ✅ Adicionar distributed tracing

Checklist de Migração

Para cada app, verifique:

Próximos Passos

  1. Migrar apps principais (4c Decision API, Sales Manager APIs, Context API)
  2. Adicionar testes para verificar integração
  3. Configurar monitoramento e alertas
  4. Documentar configurações específicas por app

Última atualização: 2025-12-01

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir