# 📝 Guía de Convenciones para Nombres de Schemas

Esta guía define cómo nombrar los Schemas de **Requests** y **Responses** según el tipo de operación y el contexto (recurso único o colección).

---

## 1️⃣ Operaciones sobre recurso único

**Patrón**  
<Verbo><Entidad><Condición><TipoDeSchema>


- **Verbo**: describe la acción (`Get`, `Delete`, `Update`, `Patch`, `Create`).
- **Entidad**: en singular (`Product`, `Customer`, `Invoice`).
- **Condición**: criterio de selección (`ById`, `BySlug`, `ByEmail`).
- **TipoDeSchema**: origen o propósito (`ParamsSchema`, `CommandSchema`, `QuerySchema`).

**Ejemplos ✅**
- `GetProductByIdParamsSchema`
- `DeleteCustomerByIdParamsSchema`
- `UpdateInvoiceByIdCommandSchema`

**Ejemplos ❌**
- `ProductGetByIdParamsSchema` (orden invertido, menos natural).
- `GetProductsByIdParamsSchema` (plural innecesario en recurso único).

**Lectura natural**: *"Esquema de parámetros para obtener un producto por id"*.

---

## 2️⃣ Operaciones sobre colecciones

**Patrón**  
<Entidad>List<Criterio/Filtro><TipoDeSchema>

- **Entidad**: en singular (`Product`, `Customer`).
- **List**: indica conjunto/listado.
- **Criterio/Filtro**: tipo de filtrado (`Criteria`, `Query`).
- **TipoDeSchema**: `Schema` o `ResponseSchema` según corresponda.

**Ejemplos ✅**
- `ProductListCriteriaSchema`
- `CustomerListResponseSchema`
- `InvoiceListQuerySchema`

**Ejemplos ❌**
- `ListProductCriteriaSchema` (el orden “ListProduct” suena a verbo y no a colección).
- `ProductsListCriteriaSchema` (plural innecesario en el nombre base).

**Lectura natural**: *"Esquema de criterios para una lista de productos"*.

---

## 3️⃣ Reglas generales

1. **Singular siempre** para el nombre base de la entidad.
2. El **verbo solo** en operaciones sobre un recurso único o mutaciones.
3. En listados, el **sustantivo principal primero** (`ProductList`, `CustomerList`), nunca `ListProduct`.
4. Sufijos estándar:
   - `CommandSchema` → body de mutaciones (create/update/patch).
   - `ParamsSchema` → route params (`/:id`).
   - `QuerySchema` → query string no normalizada.
   - `CriteriaSchema` → query normalizada con patrón Criteria.
   - `ResponseSchema` → respuesta de la API.
5. Mantener **consistencia**: si usas `ProductListCriteriaSchema`, no alternes con `ProductsCriteriaSchema`.

---

## 4️⃣ Ejemplos positivos y negativos

| ✅ Correcto                              | ❌ Incorrecto                               | Motivo del error                             |
|------------------------------------------|---------------------------------------------|----------------------------------------------|
| `GetCustomerByIdParamsSchema`            | `CustomerGetByIdParamsSchema`               | Orden invertido.                             |
| `ProductListCriteriaSchema`              | `ListProductCriteriaSchema`                 | Orden “ListProduct” no natural en inglés.    |
| `CustomerListResponseSchema`             | `CustomersListResponseSchema`               | Plural innecesario.                          |
| `DeleteInvoiceByIdParamsSchema`          | `DeleteInvoicesByIdParamsSchema`            | Plural innecesario en recurso único.         |
| `UpdateProductByIdCommandSchema`         | `UpdateProductCommandByIdSchema`            | `ById` debe ir antes del tipo de esquema.    |

---


# Convenciones de nombres para Schemas (Requests y Responses)

## Tabla de rutas ↔ Schemas

| **Método** | **Ruta**            | **Caso de uso**                                  | **Request Schema (validación)**            | **Response Schema (DTO)**                 | **Notas** |
|-----------:|---------------------|--------------------------------------------------|--------------------------------------------|-------------------------------------------|-----------|
| GET        | `/entities`         | Listado con criterios (Criteria normalizado)     | `EntityListCriteriaSchema`                 | `EntityListResponseSchema`                | `data: EntitySummary[]`, `pageNumber`, `pageSize`, `totalItems`. |
| GET        | `/entities`         | Búsqueda/filtrado por query params “raw”         | `SearchEntityQuerySchema`                  | `EntityListResponseSchema`                | Úsalo si **no** aplicas patrón Criteria. |
| GET        | `/entities/:id`     | Obtener por ID                                   | `GetEntityByIdParamsSchema`                | `EntityDetailResponseSchema`              | Si devuelves el recurso “puro”, puedes usar `EntityResourceSchema`. |
| POST       | `/entities`         | Crear recurso                                    | `CreateEntityCommandSchema`                | `EntityCreatedResponseSchema` **o** `EntityResourceSchema` | Si devuelves 201 + recurso completo, usa `EntityResourceSchema`. |
| PUT        | `/entities/:id`     | Reemplazar recurso (idempotente)                 | `UpdateEntityCommandSchema` + `UpdateEntityByIdParamsSchema` | `EntityResourceSchema`          | También válido con PATCH para cambios parciales. |
| PATCH      | `/entities/:id`     | Actualizar parcialmente                           | `PatchEntityCommandSchema` + `UpdateEntityByIdParamsSchema`  | `EntityResourceSchema`          | Usa un comando separado si el payload difiere del PUT. |
| DELETE     | `/entities/:id`     | Eliminar por ID                                  | `DeleteEntityByIdParamsSchema`             | — (204 No Content) **o** `EntityDeletedResponseSchema` | 204 recomendado. Si devuelves body, usa `EntityDeletedResponseSchema`. |

---

## Esquemas reutilizables (Responses)

- **Item para listados:**  
  `EntitySummarySchema`

- **Recurso completo:**  
  `EntityResourceSchema`

- **Respuestas compuestas:**
  - `EntityListResponseSchema` → `data: EntitySummarySchema[]` + paginación/meta
  - `EntityDetailResponseSchema` → típicamente `EntityResourceSchema`
  - `EntityCreatedResponseSchema` → `{ id, createdAt, ... }` si no devuelves el recurso completo
  - `EntityDeletedResponseSchema` → `{ id, deleted: true }` si no usas 204

---

## Convenciones de sufijos

### Requests
- `...CommandSchema` → **body** (mutaciones)
- `...ParamsSchema` → **route params** (`/:id`)
- `...QuerySchema` → **query string** (`?page=...`)
- `...CriteriaSchema` → para queries normalizadas con patrón Criteria

### Responses
- `...ListResponseSchema` → listado paginado
- `...SummarySchema` → item de listado
- `...DetailResponseSchema` → detalle de recurso
- `...ResourceSchema` → representación completa del recurso
- `...CreatedResponseSchema` → recurso recién creado
- `...DeletedResponseSchema` → confirmación de borrado (si no usas 204)

# Ejemplos de nombres de Schemas por entidad

## 1. Customers

### Requests
- `CreateCustomerCommandSchema`
- `UpdateCustomerCommandSchema`
- `PatchCustomerCommandSchema`
- `DeleteCustomerByIdParamsSchema`
- `GetCustomerByIdParamsSchema`
- `CustomerListCriteriaSchema`  
- `SearchCustomerQuerySchema`

### Responses
- `CustomerSummarySchema`
- `CustomerResourceSchema`
- `CustomerListResponseSchema`
- `CustomerDetailResponseSchema`
- `CustomerCreatedResponseSchema`
- `CustomerDeletedResponseSchema`

---

## 2. Products

### Requests
- `CreateProductCommandSchema`
- `UpdateProductCommandSchema`
- `PatchProductCommandSchema`
- `DeleteProductByIdParamsSchema`
- `GetProductByIdParamsSchema`
- `ProductListCriteriaSchema`  
- `SearchProductQuerySchema`

### Responses
- `ProductSummarySchema`
- `ProductResourceSchema`
- `ProductListResponseSchema`
- `ProductDetailResponseSchema`
- `ProductCreatedResponseSchema`
- `ProductDeletedResponseSchema`

---

## Notas
- Reutilizar esquemas básicos (`EntitySummarySchema`, `EntityResourceSchema`) en respuestas compuestas para cumplir el principio **DRY**.
- **Sufijos**: mantener siempre los sufijos `CommandSchema`, `ParamsSchema`, `QuerySchema`, `CriteriaSchema`, `ListResponseSchema`, `SummarySchema`, `DetailResponseSchema`, `ResourceSchema`, `CreatedResponseSchema`, `DeletedResponseSchema`.
- **Pluralización**: usar singular para el nombre de la entidad en los Schemas (ej. `Customer`, `Product`), incluso si la ruta es plural (`/customers`, `/products`).
- **Carpetas sugeridas**:
    modules/
    <entity>/
        application/
        dto/
            requests/
            responses/
        domain/
        infrastructure/
        api/