# Instrucciones de Copilot para Proyectos Python FastAPI

## Requisitos de Proceso Importantes
- SIEMPRE presenta un plan detallado y espera aprobación explícita antes de implementar cualquier cambio de código
- No proceder con la implementación hasta recibir confirmación del usuario
- Al presentar el plan, proporciona un desglose paso a paso de todos los archivos a crear o modificar
- Pregunta directamente: "¿Apruebas este plan antes de proceder con la implementación?"

## Convenciones de Nomenclatura Python

### Patrones Generales de Nomenclatura (PEP 8)

| Tipo de Elemento | Patrón/Estilo | Ejemplo(s) |
|------------------|---------------|------------|
| **Variables/Funciones** | `snake_case` | `user_name`, `get_user_by_id()` |
| **Constantes** | `SCREAMING_SNAKE_CASE` | `MAX_RETRY_ATTEMPTS`, `API_BASE_URL` |
| **Clases** | `PascalCase` | `UserService`, `DatabaseConnection` |
| **Módulos/Archivos** | `snake_case` | `user_service.py`, `auth_middleware.py` |
| **Packages** | `snake_case` | `user_management/`, `api_routes/` |

## Estructura de Proyecto FastAPI

```
src/
├── main.py                    # Punto de entrada FastAPI
├── app/
│   ├── __init__.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── deps.py           # Dependencies
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── endpoints/
│   │       │   ├── users.py
│   │       │   └── auth.py
│   │       └── api.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py
│   │   ├── security.py
│   │   └── database.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── user.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   └── user.py
│   ├── services/
│   │   ├── __init__.py
│   │   └── user_service.py
│   └── utils/
│       ├── __init__.py
│       └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   └── test_users.py
└── requirements.txt
```

## Configuración FastAPI Básica

### main.py Principal
```python
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.api.v1.api import api_router
from app.core.config import settings

app = FastAPI(
    title=settings.PROJECT_NAME,
    version=settings.VERSION,
    openapi_url=f"{settings.API_V1_STR}/openapi.json"
)

# CORS middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.ALLOWED_HOSTS,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.include_router(api_router, prefix=settings.API_V1_STR)
```

## Mejores Prácticas

### Desarrollo con FastAPI
- Usar **Pydantic models** para validación automática
- Implementar **dependency injection** para servicios
- Usar **async/await** para operaciones I/O
- Configurar **middleware** para CORS, autenticación, etc.
- Implementar **background tasks** para operaciones pesadas

### Código Python
- Seguir **PEP 8** estrictamente
- Usar **type hints** en todas las funciones
- Implementar **exception handling** consistente
- Usar **dataclasses** o **Pydantic** para modelos
- Aplicar **list comprehensions** cuando sea apropiado

### Testing y Quality
- Usar **pytest** para pruebas unitarias
- Implementar **pytest-asyncio** para pruebas async
- Configurar **black**, **isort**, **flake8** para código limpio
- Usar **mypy** para validación de tipos
- Cobertura mínima del 80% con **pytest-cov**