# Guía del Desarrollador — API Model v2

Esta API está construida siguiendo principios de **Clean Architecture** y **Separación de Responsabilidades**. El objetivo es que el código sea testeable, mantenible y fácil de ampliar.

---

## 1. Estructura de Carpetas (src/)

El código fuente se divide en capas lógicas:

| Capa | Responsabilidad |
| :--- | :--- |
| **Route/** | Define las URLs y qué Action las maneja. No tiene lógica. |
| **Action/** | Capa HTTP. Lee el Request, valida la forma, llama a un Service y devuelve el JSON. |
| **Service/** | Casos de uso y lógica de negocio. Orquesta entidades y repositorios. |
| **Domain/** | El núcleo. Contiene las **Entities** (objetos de negocio) e **Interfaces** de repositorios. |
| **Infrastructure/** | Implementaciones técnicas (PDO, Redis, Mail). Aquí vive el SQL real. |
| **Shared/** | Código común: DTOs, Excepciones, Helpers de HTTP y Validación. |
| **Middleware/** | Filtros globales (CORS, Auth, Logs de acceso, Errores). |

---

## 2. Flujo de una Petición

Para entender cómo funciona, sigue este camino:
1. **Cliente** envía petición → `public/index.php`
2. **Slim** hace match en `src/Route/` → Ejecuta un **Action**.
3. **Action** valida entrada → Llama a un **Service**.
4. **Service** ejecuta lógica → Llama a un **Repository** (interfaz).
5. **Infrastructure** ejecuta el SQL → Devuelve datos al **Service**.
6. **Action** recibe respuesta → Retorna JSON al **Cliente**.

---

## 3. Cómo añadir un nuevo Endpoint (Checklist)

Si necesitas añadir, por ejemplo, `GET /productos`:

1. [ ] **Dominio**: Crea `src/Domain/Repository/ProductoRepositoryInterface.php`.
2. [ ] **Infraestructura**: Crea `src/Infrastructure/Persistence/Repositories/PdoProductoRepository.php`.
3. [ ] **DI**: Registra ambos en `config/container.php`.
4. [ ] **Servicio**: Crea `src/Service/ProductoService.php` (inyecta la interfaz).
5. [ ] **Acción**: Crea `src/Action/ProductoAction.php` (inyecta el servicio).
6. [ ] **Ruta**: Registra la ruta en un archivo en `src/Route/` y asegúrate que se cargue en `public/index.php`.

---

## 4. Reglas de Oro para el Programador

*   **Sin SQL en Servicios**: El SQL vive únicamente en `Infrastructure/Persistence/Repositories`. El Service solo habla con interfaces.
*   **Actions Delgadas**: Una Action no debería tener más de 15-20 líneas. Su trabajo es solo mapear HTTP a Negocio.
*   **Tipado Estricto**: Usa siempre `declare(strict_types=1);` y tipa todos los parámetros y retornos.
*   **Excepciones de Dominio**: Si algo falla en el negocio, lanza una excepción de `src/Shared/Exceptions`. El Middleware de errores se encargará de convertirla en un JSON bonito.
*   **Documentación**: No necesitas escribir manuales de API. Simplemente registra la ruta y aparecerá automáticamente en `/docs`.

---

## 5. Comandos Útiles

*   **Servidor Local**: `php -S localhost:8080 -t public`
*   **Tests**: `composer test`
*   **Análisis Estático**: `composer phpstan`
*   **Documentación**: Accede a `/docs` en tu navegador.