Flujo de Trabajo Central y Ejemplo

// packages/core/types/entities/User.ts
// Define la entidad User
export interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

// packages/core/types/machines/user/UserCreationMachineTypes.ts
import { User } from '../../entities/User';
import { CreateUserInput } from '../../../validation/userSchema'; // Tipo de entrada desde la capa de validación
import { UserService } from '../../../services/user/domain/UserService'; // Interfaz del Servicio

// Contexto de la Máquina: Almacena entrada validada, resultado final (User), error e instancia del servicio.
export interface UserCreationMachineContext {
  validatedInput?: CreateUserInput; // Contiene datos *después* de la validación Yup
  user?: User; // Contiene la entidad User final *después* de la llamada exitosa al servicio y procesamiento
  error?: string;
  userService?: UserService; // La instancia del servicio resuelta
}

// Eventos de la Máquina
export type UserCreationMachineEvent =
  | { type: 'CREATE'; input: CreateUserInput } // El evento lleva la entrada validada
  | { type: 'RETRY' };

// packages/core/validation/userSchema.ts
import * as yup from 'yup';

export const userSchema = yup.object({
  name: yup.string().required("Name is required"), // El nombre es requerido
  email: yup.string().email("Invalid email format").required("Email is required"), // Formato de email inválido, El email es requerido
});

// Tipo derivado del esquema de validación
export type CreateUserInput = yup.InferType<typeof userSchema>;

// packages/core/services/user/domain/UserTypes.ts
import { User } from '../../../types/entities/User';

// --- DTOs de Métodos de Servicio ---
// Define las formas de datos específicas para los métodos de UserService

// DTO de entrada para el método createUser
export interface CreateUserMethodInput {
  name: string;
  email: string;
}

// DTO de salida para el método createUser
// Caso simple: devuelve la entidad User creada.
export interface CreateUserMethodOutput {
  user: User;
}

// packages/core/services/user/domain/UserService.ts
// --- Interfaz del Servicio (Contrato) ---
// Define *qué* operaciones proporciona el servicio, usando los DTOs para las formas de datos.

import { CreateUserMethodInput, CreateUserMethodOutput } from './UserTypes';

export interface UserService {
  createUser(data: CreateUserMethodInput): Promise<CreateUserMethodOutput>;
  // Define otros métodos de servicio aquí usando sus respectivos DTOs desde UserTypes.ts
}

// packages/core/services/user/implementations/DefaultUserService.ts
import { UserService } from '../domain/UserService';
// *** Importa los DTOs de Método específicos definidos por el contrato del servicio ***
import { CreateUserMethodInput, CreateUserMethodOutput } from '../domain/UserTypes';
import { User } from '../../../types/entities/User'; // Necesario para construir la entidad interna/salida

// Implementación Concreta de la Strategy usando el contrato DTO definido
export class DefaultUserService implements UserService {
  // *** La firma del método usa los DTOs del servicio ***
  async createUser(data: CreateUserMethodInput): Promise<CreateUserMethodOutput> {
    console.log('DefaultUserService: Received service input DTO:', data); // DTO de entrada del servicio recibido

    // Simula interacción con BD o lógica de negocio usando datos del DTO de entrada
    const newUserEntity: User = { // Construye la entidad interna
      id: crypto.randomUUID(),
      name: data.name, // Usa datos del DTO de entrada
      email: data.email, // Usa datos del DTO de entrada
      createdAt: new Date(),
    };

    // await db.users.insert(newUserEntity); // Llamada real a la base de datos

    console.log('DefaultUserService: User entity created:', newUserEntity); // Entidad User creada

    // *** Devuelve el DTO de Salida del Servicio definido ***
    // (Coincidiendo con la estructura en UserTypes.ts)
    return { user: newUserEntity };
  }
}

// packages/core/services/user/serviceMap.ts
import { UserService } from './domain/UserService';
import { DefaultUserService } from './implementations/DefaultUserService';

const serviceImplementations: Record<string, UserService> = {
  default: new DefaultUserService(),
};

// Función Factory para obtener la implementación de servicio apropiada
export function getUserService(type: string = 'default'): UserService {
  const serviceInstance = serviceImplementations[type.toLowerCase()];
  if (!serviceInstance) {
      console.warn(`UserService strategy type "${type}" not found, falling back to default.`); // Tipo de estrategia no encontrado, volviendo al default.
      return serviceImplementations['default']; // Asegura que el default exista
  }
  return serviceInstance;
}

// packages/core/services/user/index.ts
// Archivo Barrel exportando la función factory
export { getUserService } from './serviceMap';

// packages/core/machines/userCreationMachine.ts
import { createMachine, assign } from 'xstate';
import {
    UserCreationMachineContext,
    UserCreationMachineEvent
} from '../types/machines/user/UserCreationMachineTypes';
// *** Importa los DTOs de Servicio necesarios para la invocación y procesamiento del resultado ***
import { CreateUserMethodInput, CreateUserMethodOutput } from '../services/user/domain/UserTypes';
import { UserService } from '../services/user/domain/UserService'; // Para tipar el contexto

export const userCreationMachine = createMachine({
  id: 'userCreation',
  types: {} as { context: UserCreationMachineContext, events: UserCreationMachineEvent },
  initial: 'idle',
  // El Context contiene la entrada validada, resultado potencial (user), error y servicio
  context: {
    validatedInput: undefined,
    user: undefined,
    error: undefined,
    userService: undefined,
  },
  states: {
    idle: {
      on: {
        CREATE: {
          target: 'creating',
          // Guard asegura que la instancia del servicio esté disponible en el contexto
          guard: ({ context }) => !!context.userService,
          // Action asigna la entrada validada del evento al contexto
          actions: assign({
            validatedInput: ({ event }) => event.input,
            error: undefined, // Limpia errores previos
          }),
        },
      },
    },
    creating: {
      // Invoca la llamada al servicio
      invoke: {
        id: 'invokeCreateUserService',
        // La función src prepara el DTO y llama al método del servicio
        src: async ({ context }) => {
          // Type guards por seguridad
          if (!context.userService) throw new Error('UserService missing in context'); // Falta UserService en el contexto
          if (!context.validatedInput) throw new Error('Validated input missing in context'); // Falta entrada validada en el contexto

          // *** Prepara el DTO CreateUserMethodInput para la llamada al servicio ***
          // Mapea datos desde context.validatedInput de la máquina a la forma del DTO de servicio.
          const serviceInput: CreateUserMethodInput = {
            name: context.validatedInput.name,
            email: context.validatedInput.email,
          };
          console.log('Machine: Calling createUser service with DTO:', serviceInput); // Máquina: Llamando al servicio createUser con DTO:

          // *** La Máquina invoca el método del servicio usando el DTO preparado ***
          return await context.userService.createUser(serviceInput);
        },
        // onDone maneja el resultado exitoso (DTO de Salida) del servicio
        onDone: {
          target: 'success',
          actions: assign({
             // *** Procesa el DTO CreateUserMethodOutput ***
             // Extrae los datos relevantes (la entidad User) del DTO de salida del servicio
             // y asígnalos al campo context.user de la máquina.
            user: ({ event }) => {
                const serviceOutput = event.output as CreateUserMethodOutput;
                console.log('Machine: Received service output DTO:', serviceOutput); // Máquina: DTO de salida del servicio recibido:
                return serviceOutput.user; // Extrae la propiedad user basada en la estructura del DTO
            },
          }),
        },
        // onError maneja fallos durante la invocación del servicio
        onError: {
          target: 'failure',
          actions: assign({
            error: ({ event }) => (event.error as Error)?.message ?? 'User creation failed in service', // La creación de usuario falló en el servicio
          }),
        },
      },
    },
    success: {
      // Estado final de éxito
      type: 'final',
    },
    failure: {
      // Estado final de fallo (podría permitir reintentos)
      on: { RETRY: 'creating' }
    },
  },
});

// packages/core/actions/userActions.ts
'use server';
import { userSchema, CreateUserInput } from '../validation/userSchema';
import { userCreationMachine } from '../machines/userCreationMachine';
import { getUserService } from '../services/user'; // Importa factory
import { User } from '../types/entities/User'; // Importa entidad para el tipo de resultado final
import { interpret } from 'xstate';
import * as yup from 'yup';

// Estructura de Resultado de Acción Estandarizada para el cliente
export interface ActionResult<T = any> {
  success: boolean;
  data?: T; // Contiene los datos finales relevantes (ej., el User creado)
  error?: string;
  validationErrors?: { path: string; message: string }[];
}

// La Server Action orquesta validación, resolución de servicio y ejecución de máquina
export async function createUserAction(
  input: CreateUserInput // Action recibe entrada cruda (pero con suerte con la forma correcta) del cliente
): Promise<ActionResult<User>> { // Promete la entidad User final en caso de éxito
  try {
    // 1. Validar Entrada usando esquema Yup
    await userSchema.validate(input, { abortEarly: false });
    const validatedInput = input; // Usa la entrada post-validación
    console.log('Action: Input validation successful'); // Validación de entrada exitosa

    // 2. Resolver la Instancia de Servicio requerida usando la factory
    const userService = getUserService(); // Obtener la implementación por defecto
    console.log('Action: Resolved UserService instance'); // Instancia UserService resuelta

    // 3. Interpretar y ejecutar la máquina XState
    console.log('Action: Interpreting userCreationMachine'); // Interpretando userCreationMachine
    // Usa una Promise para esperar a que la máquina alcance un estado final
    return new Promise((resolve) => {
      const machineActor = interpret(
        // Proporciona contexto inicial a la máquina:
        userCreationMachine.withContext({
            userService: userService, // Inyecta el servicio resuelto
            validatedInput: undefined, // La máquina empieza limpia, obtendrá entrada vía evento
            user: undefined,
            error: undefined,
        })
      ).onTransition((state) => {
          // 4. Resolver la Promise cuando la máquina alcanza un estado final
          if (state.matches('success')) {
            console.log('Action: Machine finished successfully. Final context:', state.context); // Máquina finalizada con éxito. Contexto final:
            // Extrae los datos finales del User del contexto de la máquina
            resolve({ success: true, data: state.context.user });
            machineActor.stop(); // Detiene el intérprete
          }
          if (state.matches('failure')) {
            console.error('Action: Machine finished with failure:', state.context.error); // Máquina finalizada con fallo:
            resolve({ success: false, error: state.context.error });
            machineActor.stop(); // Detiene el intérprete
          }
        })
        .start(); // Inicia el intérprete de la máquina

      // 5. Envía el evento inicial con la entrada validada para iniciar el proceso
      console.log('Action: Sending CREATE event to machine with validated input:', validatedInput); // Enviando evento CREATE a la máquina con entrada validada:
      machineActor.send({ type: 'CREATE', input: validatedInput });
    });

  } catch (error) {
    // Manejar Errores de Validación específicamente
    if (error instanceof yup.ValidationError) {
      console.error('Action: Validation failed:', error.inner); // Validación fallida:
      return {
        success: false,
        validationErrors: error.inner.map((err) => ({
          path: err.path ?? 'unknown',
          message: err.message,
        })),
      };
    }
    // Manejar Otros Errores Inesperados (ej., fallo en resolución de servicio, problemas de configuración de máquina)
    console.error('Action: Unexpected error during setup:', error); // Error inesperado durante la configuración:
    return {
      success: false,
      error: error instanceof Error ? error.message : 'An unexpected server setup error occurred.', // Ocurrió un error inesperado de configuración del servidor.
    };
  }
}

// apps/radicacion/app/crear-usuario/page.tsx (Ejemplo - UI Simplificada)
'use client';
import React, { useState, useTransition, FormEvent } from 'react';
import { createUserAction, ActionResult } from '@core/actions/userActions';
import { CreateUserInput } from '@core/validation/userSchema'; // La página usa el tipo de validación para el formulario
import { User } from '@core/types/entities/User'; // La página espera la entidad User final en el resultado
// --- Importa componentes reales del Design System ---
import { Button } from 'mappnext/ds-tw/atoms/Button'; // Reemplaza con tu ruta real
import { InputField } from 'mappnext/ds-tw/molecules/InputField'; // Reemplaza con tu ruta real
// --- ---

export default function CreateUserPage() {
  // El estado del formulario coincide con la forma CreateUserInput (de la validación)
  const [formData, setFormData] = useState<CreateUserInput>({ name: '', email: '' });
  const [isPending, startTransition] = useTransition();
  // El estado del resultado espera el ActionResult que contiene el User final o errores
  const [result, setResult] = useState<ActionResult<User> | null>(null);

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const { name, value } = e.target;
    setFormData((prev) => ({ ...prev, [name]: value }));
    if (result) setResult(null); // Limpia resultado al cambiar el formulario
  };

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    setResult(null); // Limpia resultado previo
    startTransition(async () => {
      // Llama a la server action con los datos del formulario
      const actionResult = await createUserAction(formData);
      setResult(actionResult); // Actualiza el estado con el resultado de la action
      if (actionResult.success) {
         setFormData({ name: '', email: '' }); // Resetea el formulario en caso de éxito
         console.log("UI: User created!", actionResult.data); // ¡Usuario creado!
         // Opcionalmente mostrar toast de éxito, redirigir, etc.
      } else {
         console.error("UI: Creation failed:", actionResult.error || actionResult.validationErrors); // Creación fallida:
         // Errores de validación/servidor se muestran vía el estado result abajo
      }
    });
  };

  // Ayudante para obtener error de validación para una ruta de campo específica
  const getValidationError = (path: string): string | undefined => {
    return result?.validationErrors?.find(err => err.path === path)?.message;
  };

  return (
    <div className="p-4 max-w-md mx-auto">
      <h1 className="text-2xl font-bold mb-4">Crear Usuario (Ejemplo Simple)</h1>
      <form onSubmit={handleSubmit} className="space-y-4">
        {/* Campos de entrada vinculados al estado formData */}
        <InputField
          name="name"
          label="Nombre" // Cambiado a Español
          value={formData.name}
          onChange={handleChange}
          error={getValidationError('name')} // Muestra error de validación si existe
          disabled={isPending}
          required
        />
        <InputField
          name="email"
          label="Email" // Se mantiene
          type="email"
          value={formData.email}
          onChange={handleChange}
          error={getValidationError('email')} // Muestra error de validación si existe
          disabled={isPending}
          required
        />

        {/* Muestra error general del servidor (de fallo de máquina/servicio) */}
        {result && !result.success && result.error && (
           <p className="text-sm text-red-600 mt-2">Error: {result.error}</p>
        )}

        {/* Muestra mensaje de éxito */}
        {result?.success && result.data && (
           <p className="text-sm text-green-600 mt-2">¡Usuario "{result.data.name}" creado exitosamente!</p>
        )}

        {/* Botón de envío muestra estado pendiente */}
        <Button type="submit" disabled={isPending} className="w-full mt-4">
          {isPending ? 'Creando...' : 'Crear Usuario'}
        </Button>
      </form>
    </div>
  );
}