FactuGES_ERP/docs/CONVENCION NOMBRADO DE ESQUEMAS DTO.md

# Convención de Nombres de Schemas DTO

Guía específica de naming para schemas DTO. Complementa, pero no sustituye, a [DTOS - GUÍA DE DISEÑO.md](./DTOS - GUÍA DE DISEÑO.md), que sigue siendo la referencia principal de diseño.

## Alcance

Usa este documento cuando la duda sea cómo nombrar un schema. Si la duda es de semántica, tipado, opcionalidad o modelado del contrato, usa antes la guía general de DTOs.

## Reglas base

1. Usar singular para el nombre base de la entidad: `Customer`, `Product`, `Proforma`.
2. En operaciones sobre recurso único, el verbo va primero.
3. En listados, el sustantivo principal va primero: `CustomerList`, nunca `ListCustomer`.
4. Mantener sufijos estables según el rol del schema.
5. No mezclar convenciones distintas para la misma familia de endpoints.

## Patrones recomendados

### Recurso único

```text
<Verb><Entity><Condition><SchemaRole>
```

Ejemplos:

- `GetCustomerByIdParamsSchema`
- `DeleteCustomerByIdParamsSchema`
- `UpdateIssuedInvoiceByIdCommandSchema`

### Colecciones

```text
<Entity>List<CriteriaOrFilter><SchemaRole>
```

Ejemplos:

- `CustomerListCriteriaSchema`
- `ProformaListResponseSchema`
- `IssuedInvoiceListQuerySchema`

## Sufijos estables

### Request

- `CommandSchema`: body de create, update o patch
- `ParamsSchema`: route params
- `QuerySchema`: query string raw
- `CriteriaSchema`: query normalizada con patrón Criteria

### Response

- `SummarySchema`: item de listado
- `ResourceSchema`: representación completa del recurso
- `DetailResponseSchema`: response de detalle
- `ListResponseSchema`: response de listado
- `CreatedResponseSchema`: confirmación o payload de creación
- `DeletedResponseSchema`: confirmación explícita de borrado cuando no se usa `204`

## Ejemplos

### Customers

- `CreateCustomerCommandSchema`
- `GetCustomerByIdParamsSchema`
- `CustomerListCriteriaSchema`
- `CustomerSummarySchema`
- `CustomerResourceSchema`
- `CustomerListResponseSchema`

### Proformas

- `CreateProformaCommandSchema`
- `UpdateProformaByIdParamsSchema`
- `ProformaListCriteriaSchema`
- `ProformaSummarySchema`
- `ProformaDetailResponseSchema`

## Errores a evitar

- `ListCustomerCriteriaSchema`
- `CustomersListResponseSchema`
- `UpdateCustomerCommandByIdSchema`
- `ProductGetByIdParamsSchema`

## Relación con la guía general

La guía de DTOs define:

- organización por carpetas
- tipado semántico
- manejo de `null`, `optional()` y colecciones
- diseño de `create`, `update`, `list` y `detail`

Este documento solo fija el naming.