Guia de Contribuição

### Descrição
Breve descrição do problema

### Passos para Reproduzir
1. Fazer login como admin
2. Acessar /api/v1/usuarios
3. Tentar criar usuário sem email

### Comportamento Esperado
Retornar erro 422 com mensagem clara

### Comportamento Atual
Retorna erro 500 sem detalhes

### Logs

### Ambiente
- Sinapse: v1.0.0
- Python: 3.11
- OS: Ubuntu 22.04

# Fork o repositório no GitHub

# Clone seu fork
git clone [email protected]:seu-usuario/core_sinapse.git
cd core_sinapse

# Adicione o upstream
git remote add upstream [email protected]:InstitutoTodosPelaSaude/core_sinapse.git

# Configure seu ambiente
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# Imports organizados com isort
from typing import Optional, List, Dict
from datetime import datetime

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

from core.database import get_db
from core.security import get_current_user
from modules.usuarios.schemas import UsuarioSchema
from modules.usuarios.models import UsuarioModel

# Classes com docstrings
class UsuarioService:
    """
    Serviço para operações relacionadas a usuários.
    
    Este serviço centraliza toda a lógica de negócio
    relacionada ao gerenciamento de usuários.
    """
    
    async def criar_usuario(
        self,
        *,
        db: AsyncSession,
        usuario_data: UsuarioSchema,
        current_user: UsuarioModel
    ) -> UsuarioModel:
        """
        Cria um novo usuário no sistema.
        
        Args:
            db: Sessão assíncrona do banco
            usuario_data: Dados do usuário a ser criado
            current_user: Usuário autenticado fazendo a requisição
            
        Returns:
            UsuarioModel: Usuário criado
            
        Raises:
            HTTPException: Se email já existe ou sem permissão
        """
        # Implementação...

modules/novo_modulo/
├── __init__.py          # Exports do módulo
├── module_config.py     # Configurações
├── endpoints.py         # Rotas FastAPI
├── models.py           # Modelos SQLAlchemy
├── schemas.py          # Schemas Pydantic
├── async_services.py   # Lógica de negócio
├── async_repository.py # Acesso a dados
└── tests/              # Testes do módulo
    ├── __init__.py
    ├── test_endpoints.py
    └── test_services.py

from typing import Optional, List, Dict, Union
from datetime import datetime

async def processar_dados(
    dados: List[Dict[str, Union[str, int]]],
    filtro: Optional[str] = None,
    limite: int = 100
) -> Dict[str, List[Dict[str, any]]]:
    """Processa dados com filtro opcional."""
    resultado: Dict[str, List[Dict[str, any]]] = {
        "processados": [],
        "erros": []
    }
    # ...
    return resultado

# tests/test_usuarios.py
import pytest
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession

from main import app
from modules.usuarios.models import UsuarioModel

class TestUsuarios:
    """Testes para o módulo de usuários."""
    
    @pytest.mark.asyncio
    async def test_criar_usuario(
        self,
        client: AsyncClient,
        db: AsyncSession,
        admin_token: str
    ):
        """Testa criação de usuário com sucesso."""
        # Arrange
        usuario_data = {
            "email": "[email protected]",
            "nome": "Novo Usuario",
            "senha": "senha123"
        }
        
        # Act
        response = await client.post(
            "/api/v1/usuarios/",
            json=usuario_data,
            headers={"Authorization": f"Bearer {admin_token}"}
        )
        
        # Assert
        assert response.status_code == 201
        data = response.json()
        assert data["email"] == usuario_data["email"]
        assert "senha" not in data

# conftest.py
import pytest
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession

@pytest.fixture
async def client():
    """Cliente HTTP para testes."""
    async with AsyncClient(app=app, base_url="http://test") as ac:
        yield ac

@pytest.fixture
async def admin_user(db: AsyncSession):
    """Usuário admin para testes."""
    # Criar e retornar usuário admin
    pass

@pytest.fixture
async def admin_token(admin_user):
    """Token JWT de admin."""
    # Gerar e retornar token
    pass

def calcular_estatisticas(
    casos: List[AgravoModel],
    periodo: str = "mensal"
) -> Dict[str, float]:
    """
    Calcula estatísticas de casos de agravos.
    
    Args:
        casos: Lista de casos para análise
        periodo: Tipo de agrupamento (diario, semanal, mensal)
        
    Returns:
        Dict com estatísticas calculadas:
            - total: Total de casos
            - media: Média por período
            - taxa_crescimento: Taxa de crescimento
            
    Raises:
        ValueError: Se período não for válido
        
    Example:
        >>> casos = await get_casos_dengue()
        >>> stats = calcular_estatisticas(casos, "semanal")
        >>> print(f"Total: {stats['total']}")
    """

@router.post(
    "/",
    response_model=UsuarioResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Criar novo usuário",
    description="Cria um novo usuário no sistema. Requer permissão USUARIOS_CRIAR."
)
async def criar_usuario(
    usuario: UsuarioCreate,
    db: AsyncSession = Depends(get_db),
    current_user: UsuarioModel = Depends(requer_permissao("usuarios.criar"))
):
    """
    Cria um novo usuário com os dados fornecidos.
    
    - **email**: Email único do usuário
    - **nome**: Nome completo
    - **senha**: Senha com mínimo 8 caracteres
    - **grupos**: Lista de IDs de grupos (opcional)
    """

## Descrição
Breve descrição do que foi alterado e por quê.

## Tipo de mudança
- [ ] Bug fix
- [ ] Nova feature
- [ ] Breaking change
- [ ] Documentação

## Como testar
1. Passo 1
2. Passo 2
3. Verificar resultado

## Checklist
- [ ] Testes adicionados
- [ ] Documentação atualizada
- [ ] Código revisado
- [ ] CI passando

## Screenshots (se aplicável)
[Adicione screenshots aqui]

## Issues relacionados
Closes #123