Setup Local para Desenvolvimento

Este guia ajudará você a configurar um ambiente de desenvolvimento completo para o Sinapse.

Pré-requisitos

Software Necessário

Python 3.11+ (recomendado: usar pyenv ou conda)
PostgreSQL 15+
Redis 7+ (opcional, mas recomendado)
Git
Docker (opcional, mas facilita muito)

Ferramentas Recomendadas

IDE: VS Code com extensões Python
API Client: Postman, Insomnia ou Thunder Client
DB Client: DBeaver, pgAdmin ou TablePlus
Terminal: iTerm2 (macOS), Windows Terminal ou Hyper

Configuração Passo a Passo

1. Clone o Repositório

# Clone via HTTPS
git clone https://github.com/InstitutoTodosPelaSaude/core_sinapse.git

# ou via SSH
git clone [email protected]:InstitutoTodosPelaSaude/core_sinapse.git

cd core_sinapse

2. Configure o Python

# Criar ambiente conda
conda create -n api_sinapse python=3.11

# Ativar ambiente
conda activate api_sinapse

# Verificar versão
python --version

# Criar ambiente virtual
python3.11 -m venv venv

# Ativar ambiente
# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

# Verificar versão
python --version

# Instalar Python 3.11
pyenv install 3.11.7

# Definir versão local
pyenv local 3.11.7

# Criar ambiente virtual
python -m venv venv
source venv/bin/activate

3. Instale as Dependências

# Atualizar pip
pip install --upgrade pip setuptools wheel

# Instalar dependências de produção
pip install -r requirements.txt

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

4. Configure o Banco de Dados

# Iniciar PostgreSQL via Docker
docker run -d \
  --name sinapse-postgres \
  -e POSTGRES_USER=sinapse_user \
  -e POSTGRES_PASSWORD=sinapse123 \
  -e POSTGRES_DB=sinapse_db \
  -p 5432:5432 \
  -v sinapse_pgdata:/var/lib/postgresql/data \
  postgres:15-alpine

# Verificar se está rodando
docker ps

# Criar usuário e banco (conecte como superuser)
sudo -u postgres psql

CREATE USER sinapse_user WITH PASSWORD 'sinapse123';
CREATE DATABASE sinapse_db OWNER sinapse_user;
GRANT ALL PRIVILEGES ON DATABASE sinapse_db TO sinapse_user;
\q

5. Configure Redis (Opcional)

# Iniciar Redis via Docker
docker run -d \
  --name sinapse-redis \
  -p 6379:6379 \
  redis:7-alpine

# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis-server

# macOS
brew install redis
brew services start redis

6. Configure as Variáveis de Ambiente

# Copiar arquivo de exemplo
cp .env.example .env

# Editar com seu editor favorito
nano .env  # ou vim, code, etc.

Configurações essenciais para desenvolvimento:

# API
API_HOST=0.0.0.0
API_PORT=8000
API_RELOAD=true
API_WORKERS=1
API_ENV=development

# Banco de Dados
DATABASE_URL=postgresql+asyncpg://sinapse_user:sinapse123@localhost:5432/sinapse_db
DB_ECHO=true

# Redis (se estiver usando)
REDIS_URL=redis://localhost:6379/0

# Segurança
SECRET_KEY=dev-secret-key-apenas-para-desenvolvimento
MASTER_KEY=dev-master-key

# JWT
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7

# Inicialização
INIT_ADMIN_EMAIL=[email protected]
INIT_ADMIN_PASSWORD=admin123
INIT_ADMIN_NAME=Admin Dev

# Logs
LOG_LEVEL=DEBUG
LOG_FORMAT=json

7. Execute as Migrações

# Verificar status das migrações
alembic current

# Executar todas as migrações
alembic upgrade head

# Verificar se foi aplicado
alembic history

8. Crie os Dados Iniciais

# Executar script de inicialização
python scripts/create_initial_data.py

Isso criará:

Usuário admin inicial
Grupos padrão (admin, gestor, analista, usuario, visualizador)
Permissões básicas
Dados de exemplo (se em modo desenvolvimento)

9. Inicie o Servidor

# Modo desenvolvimento com reload automático
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# ou usando o comando make (se disponível)
make run-dev

Verificação da Instalação

1. Acesse a Documentação Interativa

Abra seu navegador em:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
Scalar: http://localhost:8000/documentation

2. Teste o Health Check

curl http://localhost:8000/api/v1/health

Resposta esperada:

{
  "status": "healthy",
  "version": "1.0.0",
  "environment": "development",
  "timestamp": "2025-07-29T10:00:00Z"
}

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "senha": "admin123"
  }'

Configuração do VS Code

Extensions Recomendadas

Crie o arquivo .vscode/extensions.json:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-python.black-formatter",
    "charliermarsh.ruff",
    "tamasfe.even-better-toml",
    "redhat.vscode-yaml",
    "ms-azuretools.vscode-docker",
    "eamodio.gitlens",
    "usernamehw.errorlens"
  ]
}

Settings do Projeto

Crie o arquivo .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true,
    ".pytest_cache": true,
    ".ruff_cache": true
  }
}

Debug Configuration

Crie o arquivo .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Sinapse API",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "main:app",
        "--reload",
        "--host", "0.0.0.0",
        "--port", "8000"
      ],
      "jinja": true,
      "justMyCode": false,
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}

Scripts Úteis

Makefile

Se você tem make instalado, pode usar:

# Ver comandos disponíveis
make help

# Instalar dependências
make install

# Executar migrações
make migrate

# Iniciar servidor dev
make run-dev

# Executar testes
make test

# Limpar arquivos temporários
make clean

Scripts Python

# Criar novo usuário admin
python scripts/create_admin.py --email [email protected] --senha senha123

# Importar dados de exemplo
python scripts/import_sample_data.py

# Verificar integridade do banco
python scripts/check_db_health.py

Troubleshooting

Problemas Comuns

ImportError: No module named 'asyncpg'

Solução:

pip install asyncpg

psycopg2.OperationalError: FATAL: password authentication failed

Verificar:

Senha no .env está correta
Usuário existe no PostgreSQL
pg_hba.conf permite conexão local

RuntimeError: asyncio.run() cannot be called from a running event loop