👋 Guia de Onboarding - C-Suite Ecosystem

Bem-vindo ao ecossistema C-Suite!

Este guia ajudará você a começar rapidamente.

📋 Índice

Visão Geral
Pré-requisitos
Configuração Inicial
Estrutura do Projeto
Módulos Comuns
Primeiros Passos
Desenvolvimento
Testes
Deploy
Recursos

🎯 Visão Geral

O C-Suite é um ecossistema de 11 microserviços interconectados que trabalham juntos para fornecer:

Decisões Inteligentes - Sistema de decisões baseado em ML
Gestão Executiva - Automação e agentes executivos
Contexto Temporal - Análise de tendências e mudanças de contexto
Gerenciamento de Vendas - Automação de processos de vendas

✅ Pré-requisitos

Conhecimentos Recomendados

Python 3.9+
FastAPI
MySQL
Redis
Docker (opcional)
Conceitos de microserviços

Ferramentas Necessárias

# Python
python --version  # 3.9+

# MySQL
mysql --version  # 8.0+

# Redis
redis-cli --version

# Docker (opcional)
docker --version
docker-compose --version

# Git
git --version

⚙️ Configuração Inicial

1. Clone o Repositório

git clone <repo-url>
cd c-suite

2. Configure Ambiente Virtual

python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

3. Instale Dependências

# Dependências comuns
pip install -r requirements-common.txt

# Dependências específicas do app (exemplo)
cd 4c/api/decision_api
pip install -r requirements.txt

4. Configure Variáveis de Ambiente

# Copie o exemplo
cp .env.example .env

# Edite com suas configurações
nano .env  # ou seu editor preferido

Variáveis principais:

ENV=development
LOG_LEVEL=INFO

# Banco de Dados
CSUITE_DB_HOST=localhost
CSUITE_DB_PORT=3306
CSUITE_DB_USER=user
CSUITE_DB_PASSWORD=password
CSUITE_DB_NAME=csuite

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Jaeger (Tracing)
JAEGER_ENABLED=false
JAEGER_HOST=localhost
JAEGER_PORT=14250

5. Configure Banco de Dados

# Execute migrações (se necessário)
mysql -u user -p < schema.sql

📁 Estrutura do Projeto

c-suite/
├── common/              # Módulos comuns (26 módulos)
│   ├── common_logging.py
│   ├── common_errors.py
│   ├── common_health.py
│   └── ...
├── 4c/                  # Serviços 4C
│   ├── api/
│   │   ├── decision_api/
│   │   ├── feature_service/
│   │   ├── scoring_service/
│   │   └── ...
│   └── ...
├── 4c-suite/            # App de orquestração
├── csuite-executive/    # Agentes executivos
├── csuite-sales-manager/ # Gerenciamento de vendas
├── csuite-context/      # API de contexto
├── docs/                # Documentação (59 docs)
├── tests/               # Testes
│   └── common/          # Testes dos módulos comuns
├── scripts/             # Scripts utilitários
└── README.md

📦 Módulos Comuns

O ecossistema utiliza 26 módulos comuns em common/ para garantir consistência.

Uso Básico

import sys
from pathlib import Path

# Adiciona common ao path
COMMON_PATH = str(Path(__file__).resolve().parents[N])  # Ajuste N
sys.path.insert(0, COMMON_PATH)

# Importa módulos com fallback
try:
    from common.common_logging import setup_logging, get_logger
    LOGGING_ENABLED = True
except ImportError:
    LOGGING_ENABLED = False
    import logging
    logger = logging.getLogger(__name__)

# Configura logging
if LOGGING_ENABLED:
    setup_logging(app_name="meu-app")
    logger = get_logger(__name__)

📚 Consulte docs/GUIA_RAPIDO_REFERENCIA.md para exemplos completos.

Módulos Principais

Logging - common_logging
Error Handling - common_errors
Health Checks - common_health
Métricas - common_metrics
Tracing - common_tracing
Circuit Breaker - common_circuit_breaker
Event Sourcing - common_event_sourcing
Business Metrics - common_business_metrics

🚀 Primeiros Passos

1. Execute um App Localmente

# Exemplo: 4C Decision API
cd 4c/api/decision_api
uvicorn main:app --reload --port 8000

2. Verifique Health Check

curl http://localhost:8000/health

3. Veja Métricas

curl http://localhost:8000/metrics

4. Teste um Endpoint

curl http://localhost:8000/docs  # Swagger UI

💻 Desenvolvimento

Padrão de Código

# Formatação
make format  # ou: black . && isort .

# Linting
make lint  # ou: flake8 . && mypy .

# Testes
make test  # ou: pytest

Estrutura de um App

from fastapi import FastAPI
import sys
from pathlib import Path

# Adiciona common ao path
COMMON_PATH = str(Path(__file__).resolve().parents[N])
sys.path.insert(0, COMMON_PATH)

# Imports com fallback
try:
    from common.common_logging import setup_logging, get_logger
    from common.common_errors import error_handler
    from common.common_health import create_health_router
    from common.common_metrics import create_metrics_router
    from common.common_tracing import setup_tracing
    ENABLED = True
except ImportError:
    ENABLED = False

app = FastAPI(title="Meu App")

# Configuração
if ENABLED:
    setup_logging(app_name="meu-app")
    logger = get_logger(__name__)
    app.add_exception_handler(Exception, error_handler)
    app.include_router(create_health_router("meu-app"))
    app.include_router(create_metrics_router("meu-app"))
    setup_tracing(app, "meu-app")

@app.get("/")
def root():
    return {"message": "Hello World"}

🧪 Testes

Executar Testes

# Todos os testes
pytest

# Testes dos módulos comuns
pytest tests/common/

# Teste específico
pytest tests/common/test_common_errors.py

# Com cobertura
pytest --cov=common --cov-report=html

Escrever Testes

import pytest
from common.common_errors import CSuiteError, ErrorCode

def test_error_creation():
    error = CSuiteError(
        error_code=ErrorCode.RESOURCE_NOT_FOUND,
        message="Not found"
    )
    assert error.error_code == ErrorCode.RESOURCE_NOT_FOUND

🚀 Deploy

Checklist de Deploy

Consulte docs/DEPLOY_CHECKLIST.md para checklist completo.

Básico:

[ ] Variáveis de ambiente configuradas
[ ] Migrações executadas
[ ] Health checks validados
[ ] Métricas configuradas
[ ] Tracing configurado
[ ] Logs centralizados

📚 Recursos

Documentação Essencial

docs/GUIA_RAPIDO_REFERENCIA.md - Referência rápida dos módulos
docs/MIGRACAO_MODULOS_COMUNS.md - Como migrar apps
docs/STATUS_FINAL.md - Status geral do ecossistema
docs/TROUBLESHOOTING.md - Solução de problemas

Documentação Técnica

docs/DISTRIBUTED_TRACING.md - Distributed tracing
docs/CIRCUIT_BREAKER.md - Circuit breaker
docs/EVENT_SOURCING.md - Event sourcing
E mais em docs/

Comandos Úteis

# Ver logs
docker-compose logs -f <service>

# Health check
curl http://localhost:8000/health

# Métricas
curl http://localhost:8000/metrics

# Swagger UI
open http://localhost:8000/docs

❓ Dúvidas Frequentes

Como adicionar um novo módulo comum?

Crie o módulo em common/common_nome.py
Documente em docs/NOME.md
Adicione testes em tests/common/test_common_nome.py
Atualize docs/GUIA_RAPIDO_REFERENCIA.md

Como migrar um app para módulos comuns?

Consulte docs/MIGRACAO_MODULOS_COMUNS.md para guia completo.

Como adicionar um novo app?

Crie estrutura do app
Configure módulos comuns (veja padrão acima)
Adicione health checks e métricas
Documente em docs/

🆘 Suporte

Documentação: docs/
Troubleshooting: docs/TROUBLESHOOTING.md
Status: docs/STATUS_FINAL.md
Pendências: docs/PENDENCIAS.md

Bem-vindo ao time! 🎉

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