Uecko_ERP/docs/CONVENCION NOMBRADO DE ESQUEMAS DTO.md

📝 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
<Condición>

• 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
List<Criterio/Filtro>

• 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/ / application/ dto/ requests/ responses/ domain/ infrastructure/ api/