David
dac22372b9
- Archived historical documents for DTO design and naming conventions. - Added normative documentation for HTTP request flow and module boundaries. - Introduced testing guidelines for backend layers. - Updated onboarding module documentation and clarified onboarding requirements. - Deprecated backend prompt base and prompt auth documents. - Adjusted paths in testing documentation for consistency.
2.6 KiB
DTOs y schemas HTTP
Estado: NORMATIVO. Esta guía es la SSOT de contratos HTTP, schemas y naming de DTOs.
Ubicación y compartición
Los Request DTO se ubican normalmente en:
modules/<module>/src/common/dto/request
Los DTOs de response y subcontratos compartidos siguen la estructura common/dto/response y common/dto/shared cuando corresponda. common es deliberadamente importable tanto por backend como por web: el cliente puede usar el RequestDTO para tipar el payload que envía.
Un RequestDTO no pertenece a Infrastructure.
Zod es la SSOT
Cada contrato nace de un schema Zod y el tipo se infiere de él:
export const CreateXRequestSchema = z.object({ /* contrato HTTP */ });
export type CreateXRequestDTO = z.infer<typeof CreateXRequestSchema>;
No crear interfaces manuales paralelas. Cada endpoint define sus request y response DTOs, salvo subcontratos que sean realmente idénticos y estables.
Naming
Para body HTTP, usar <Action><Resource>RequestSchema y <Action><Resource>RequestDTO:
CreateCustomerRequestSchema
CreateProformaRequestSchema
CompleteInitialOnboardingRequestSchema
Para params y query se mantiene el rol explícito, por ejemplo GetCustomerByIdParamsRequestSchema o CustomerListQueryRequestSchema, según la convención local ya establecida. CommandSchema no es el nombre general de un body HTTP: un Command es una representación de Application cuando realmente exista.
En output usar nombres que expresen el contrato: SummarySchema, ResourceSchema, DetailResponseSchema, ListResponseSchema, CreatedResponseSchema o DeletedResponseSchema.
Semántica del contrato
undefined, null, "" y [] tienen significados diferentes y el schema debe expresarlos. Evitar .default() y .transform() en DTOs de negocio salvo necesidad justificada; la normalización y la decisión de Maybe pertenecen a Application.
Usar schemas semánticos para UUID, fechas, timestamps, porcentajes, importes y cantidades. Los decimales exactos no viajan como number; Money, Amount, Percentage y Quantity mantienen el contrato de precisión existente.
Responses y snapshots
El schema Zod es también la SSOT del contrato de salida. Los snapshot builders se tipan contra el DTO inferido, son deterministas, no implementan lógica de negocio ni acceden a Infrastructure. Pueden convertir Value Objects a primitivas, enums internos a valores de contrato y Maybe a null.
La ejecución de validateRequest y la transición hacia InputMapper se documentan en Flujo HTTP y entrada a Application.