Saltar al contenido principal
El directorio packages/core alberga la lógica de negocio central, desacoplada de cualquier implementación de UI específica.
CarpetaResponsabilidadTecnologías / Patrones Clave
actions/Funciones del lado del servidor invocables desde el cliente. Valida la entrada, instancia e inicia la máquina XState apropiada, espera su resultado final.Next.js Server Actions
machines/Define y gestiona flujos de trabajo complejos con estado (Patrón State). Orquesta el flujo de la lógica de negocio, preparando DTOs, invocando métodos en implementaciones de Servicio resueltas y procesando DTOs de salida.XState
services/Encapsula operaciones de dominio discretas mediante una Capa de Servicios estructurada (Patrón Strategy). Implementa tareas específicas (interacción con BD, llamadas API) invocadas por las máquinas, usando el contrato definido por su interfaz y DTOs de método.TypeScript Interfaces/Classes. Interfaz y DTOs de Método definidos en services/[domain]/domain/. Implementaciones en services/[domain]/implementations/.
types/Define estructuras de datos base compartidas (Entities), tipos de utilidad comunes y tipos para máquinas XState, organizados en subdirectorios (common/, entities/, machines/). Excluye DTOs de métodos de servicio.TypeScript
validation/Define esquemas de validación de datos, usados principalmente por actions/ antes de iniciar una máquina.Yup (InferType)
Para el flujo estándar que conecta estas capas, consulta la Guía del Flujo de Trabajo Principal.

​
Estructura de la Capa de Servicios (packages/core/services/[domain]/)

Los servicios proporcionan implementaciones concretas de operaciones de negocio específicas, invocadas por las máquinas de estado. La estructura dentro de cada directorio de dominio de servicio (ej., packages/core/services/user/) sigue un patrón claro que promueve la separación de la abstracción de la implementación:
  1. domain/: Este directorio define la Capa de Abstracción para el servicio. Contiene solamente:
    • [Domain]Service.ts: La interface TypeScript que define el contrato del servicio (ej., UserService). Especifica qué operaciones proporciona el servicio.
    • [Domain]Types.ts: Define los Data Transfer Objects (DTOs) – los tipos/interfaces TypeScript específicos para los parámetros de entrada (input) y valores de retorno (output) de cada método declarado en la interfaz [Domain]Service.ts (ej., CreateUserMethodInput, CreateUserMethodOutput). Especifica la forma de los datos con los que trabaja el servicio en su límite.
    • Fundamentalmente, esta carpeta no contiene ninguna lógica de implementación ni hace referencia directa a tipos de otras capas como validation.
  2. implementations/: Contiene las clases concretas Strategy que implementan la interfaz [Domain]Service.ts. Cada archivo típicamente representa una estrategia o versión diferente de la lógica del servicio (ej., DefaultUserService.ts, AdminUserService.ts). Esto es cómo se realizan las operaciones del servicio, mapeando potencialmente los DTOs de entrada a tipos internos si es necesario.
  3. serviceMap.ts: Implementa un patrón Factory Method o Service Locator. Típicamente exporta una función (ej., getUserService) que toma criterios (como un ID de cliente, rol de usuario, feature flag) y devuelve la instancia de servicio concreta apropiada del directorio implementations/. Este mapa o su función getter debe ser accesible para la máquina XState (ej., pasado a través del context o importado directamente si es apropiado).
  4. index.ts: Un simple archivo barrel file que exporta la API pública del módulo de servicio, principalmente la función factory/locator de serviceMap.ts (ej., export { getUserService } from './serviceMap';).

​
Tipos Centrales (packages/core/types/)

El directorio types/ es crucial para mantener la consistencia y habilitar el análisis estático en toda la lógica central.
Estructura de packages/core/types/
types/
├── common/         # Tipos verdaderamente genéricos (ej. PaginationResult)
├── entities/       # Modelos de datos/entidades centrales (ej. User, Document)
│   ├── User.ts
│   └── Document.ts
│   └── ...
├── machines/       # Tipos de máquinas XState (Context, Events), organizados por máquina/dominio
│   ├── user/       # ej. tipos para máquinas de usuario
│   │   └── UserCreationMachineTypes.ts
│   ├── radicacion/ # ej. tipos para máquinas de radicación
│   │   └── DocumentIntakeMachineTypes.ts
│   └── ...
└── index.ts        # Opcional: Re-exportar tipos clave
  • Entities: Representan las estructuras de datos centrales de la aplicación (ej., un objeto User que coincide con el esquema de la base de datos).
  • Machine Types: Definen la forma del Context y los posibles Events para cada máquina XState, asegurando la seguridad de tipos durante las transiciones de estado y la ejecución lógica. Se mantienen separados de los Service DTOs.
  • Common Types: Tipos de utilidad usados en diferentes dominios (ej., envoltorios de respuesta API estandarizados, estructuras de paginación).

​
Validación (packages/core/validation/)

Toda entrada proveniente del cliente hacia una Server Action debe ser validada antes de ser procesada.
  • Usa Yup para la definición y validación de esquemas.
  • Los esquemas se definen en packages/core/validation/, típicamente organizados por dominio (ej., userSchema.ts).
  • Las Server Actions importan y usan estos esquemas para validar la entrada.
  • Usa yup.InferType<typeof yourSchema> para derivar tipos TypeScript directamente de los esquemas para usar en Actions y potencialmente como el tipo de entrada inicial para Machines (validatedInput).
  • Los errores de validación deben resultar en un retorno temprano desde la Action con una respuesta de error estructurada (ver ActionResult en la Guía del Flujo de Trabajo Principal).