🏠 Início / 📚 Documentação / Guias De Uso / Development Setup

Development Setup

💻 Guia de Setup de Desenvolvimento - CSuite

Versão: 1.0
Última Atualização: 2025-01-02
Responsável: Equipe de Desenvolvimento

📋 Índice

  1. Pré-requisitos
  2. Setup Inicial
  3. Configuração do Ambiente
  4. Executando Serviços Localmente
  5. Desenvolvimento
  6. Testes
  7. Debugging
  8. Troubleshooting

🎯 Pré-requisitos

Software Necessário

Obrigatório:
- Python 3.11+ - Download
- Docker 20.10+ - Installation Guide
- Docker Compose 2.0+ - Incluído no Docker Desktop
- Git - Download
- Editor de código - VS Code, PyCharm, etc.

Recomendado:
- Make - Para facilitar comandos
- Postman/Insomnia - Para testar APIs
- MySQL Client - Para acessar banco diretamente

Contas e Acessos

Necessário:
- Acesso ao repositório Git
- Acesso ao Docker Hub/Registry (se privado)
- Credenciais de banco de dados (desenvolvimento)

🚀 Setup Inicial

1. Clonar Repositório

# Clonar repositório
git clone <repository-url>
cd c-suite

# Verificar branch
git branch

2. Configurar Ambiente Python

# Criar virtual environment
python3 -m venv venv

# Ativar virtual environment
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Instalar dependências
pip install -r requirements.txt

3. Configurar Variáveis de Ambiente

Criar arquivo .env na raiz:

# .env
# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=dev_password
DB_NAME=csuite_dev

# API
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=True

# Secrets (desenvolvimento)
JWT_SECRET_KEY=dev_secret_key_change_in_production
ENCRYPTION_KEY=dev_encryption_key

# Services
CONTEXT_API_URL=http://localhost:8001
EXECUTIVE_API_URL=http://localhost:8002

⚠️ Importante: Não commitar arquivo .env com credenciais reais.

⚙️ Configuração do Ambiente

1. Setup do Banco de Dados

Opção 1: Docker Compose (Recomendado)

# Iniciar MySQL via Docker Compose
docker-compose up -d mysql

# Aguardar MySQL estar pronto
docker-compose logs -f mysql
# Aguardar mensagem: "ready for connections"

Opção 2: MySQL Local

# Instalar MySQL (depende do OS)
# Ubuntu/Debian:
sudo apt-get install mysql-server

# Mac:
brew install mysql

# Iniciar MySQL
sudo systemctl start mysql  # Linux
brew services start mysql   # Mac

Criar banco de dados:

# Conectar ao MySQL
mysql -u root -p

# Criar banco
CREATE DATABASE csuite_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Criar usuário (opcional)
CREATE USER 'csuite_dev'@'localhost' IDENTIFIED BY 'dev_password';
GRANT ALL PRIVILEGES ON csuite_dev.* TO 'csuite_dev'@'localhost';
FLUSH PRIVILEGES;

2. Executar Migrações

# Executar migrações
# (depende da ferramenta de migração usada)
# Exemplo com Alembic:
alembic upgrade head

# Ou executar scripts SQL diretamente:
mysql -u root -p csuite_dev < sql/schema.sql
mysql -u root -p csuite_dev < sql/seed.sql

3. Configurar Docker (Opcional)

Para desenvolvimento com Docker:

# Build das imagens
docker-compose build

# Iniciar serviços
docker-compose up -d

# Ver logs
docker-compose logs -f

🏃 Executando Serviços Localmente

Gateway (csuite-gateway)

cd csuite-gateway

# Instalar dependências
pip install -r requirements.txt

# Executar
uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

# Ou com Python
python -m uvicorn app.main:app --reload

Acessar:
- API: http://localhost:8080
- Docs: http://localhost:8080/docs
- Health: http://localhost:8080/health

Context API (csuite-context)

cd csuite-context

# Instalar dependências
pip install -r requirements.txt

# Executar
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

Acessar:
- API: http://localhost:8001
- Docs: http://localhost:8001/docs

Executive API (csuite-executive)

cd csuite-executive

# Instalar dependências
pip install -r requirements.txt

# Executar
uvicorn app.main:app --reload --host 0.0.0.0 --port 8002

Acessar:
- API: http://localhost:8002
- Docs: http://localhost:8002/docs

Outros Serviços

Cada serviço segue o mesmo padrão:
1. Entrar no diretório do serviço
2. Instalar dependências: pip install -r requirements.txt
3. Executar: uvicorn app.main:app --reload --port <porta>

Portas padrão:
- Gateway: 8080
- Context: 8001
- Executive: 8002
- Operations: 8003
- (verificar cada serviço)

💻 Desenvolvimento

Estrutura de Projeto

c-suite/
├── csuite-gateway/      # Gateway principal
├── csuite-context/      # Context API
├── csuite-executive/    # Executive API
├── csuite-operations/  # Operations API
├── common/             # Código compartilhado
├── docs/               # Documentação
├── sql/                # Scripts SQL
└── tests/              # Testes

Convenções de Código

Python:
- PEP 8 style guide
- Type hints quando possível
- Docstrings para funções/classes
- Black para formatação (se configurado)

Estrutura de arquivo:

# app/main.py
"""
Módulo principal da aplicação.
"""
from fastapi import FastAPI

app = FastAPI(title="CSuite Service")

@app.get("/health")
async def health():
    """Health check endpoint."""
    return {"status": "ok"}

Hot Reload

FastAPI com uvicorn:

# --reload habilita hot reload
uvicorn app.main:app --reload

Mudanças no código são refletidas automaticamente.

🧪 Testes

Executar Testes

# Todos os testes
pytest

# Testes específicos
pytest tests/test_api.py

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

# Verbose
pytest -v

Estrutura de Testes

tests/
├── unit/           # Testes unitários
├── integration/    # Testes de integração
└── fixtures/       # Fixtures compartilhadas

Exemplo de Teste

# tests/test_api.py
import pytest
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_health():
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json() == {"status": "ok"}

🐛 Debugging

Debug no VS Code

Criar .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: FastAPI",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/csuite-gateway/app/main.py",
            "module": "uvicorn",
            "args": [
                "app.main:app",
                "--reload",
                "--host",
                "0.0.0.0",
                "--port",
                "8080"
            ],
            "jinja": true,
            "justMyCode": false
        }
    ]
}

Debug com print/logging

import logging

logger = logging.getLogger(__name__)

def minha_funcao():
    logger.debug("Debug message")
    logger.info("Info message")
    logger.warning("Warning message")
    logger.error("Error message")

Debug no Docker

# Executar container em modo interativo
docker run -it --rm csuite-gateway:latest /bin/bash

# Ver logs
docker logs <container-id>

# Executar com debug
docker run -e DEBUG=True csuite-gateway:latest

🔧 Troubleshooting

Problema: Porta já em uso

Solução:

# Verificar processo usando porta
lsof -i :8080  # Mac/Linux
netstat -ano | findstr :8080  # Windows

# Matar processo
kill -9 <PID>  # Mac/Linux
taskkill /PID <PID> /F  # Windows

# Ou usar outra porta
uvicorn app.main:app --reload --port 8081

Problema: Dependências não instalam

Solução:

# Atualizar pip
pip install --upgrade pip

# Limpar cache
pip cache purge

# Reinstalar
pip install -r requirements.txt --force-reinstall

Problema: Banco de dados não conecta

Solução:

# Verificar se MySQL está rodando
docker ps | grep mysql
# ou
sudo systemctl status mysql

# Testar conexão
mysql -u root -p -h localhost

# Verificar variáveis de ambiente
echo $DB_HOST
echo $DB_PORT

Problema: Import errors

Solução:

# Verificar PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# Instalar em modo desenvolvimento
pip install -e .

# Verificar imports
python -c "import app.main"

📚 Recursos Adicionais

Documentação

Ferramentas Úteis

Desenvolvimento:
- Postman - Testar APIs
- DBeaver - Cliente de banco de dados
- VS Code - Editor recomendado

Debugging:
- pdb - Python debugger
- ipdb - IPython debugger
- pytest - Framework de testes

🔗 Documentos Relacionados

Última Revisão: 2025-01-02
Próxima Revisão: 2025-04-02 (trimestral)

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir