Arquitectura Hexagonal (Ports & Adapters) y Clean Architecture

package com.acme.taskflow.tareas.dominio;

// Sin imports de Spring, JPA ni Jackson
public final class Tarea {
    private final TareaId id;
    private final ProyectoId proyecto;
    private String titulo;
    private EstadoTarea estado;
    private Responsable responsable;

    public static Tarea nueva(TareaId id, ProyectoId proyecto, String titulo) {
        return new Tarea(id, proyecto, titulo, EstadoTarea.PENDIENTE, null);
    }

    public void asignarA(Responsable nuevo) {
        if (estado == EstadoTarea.COMPLETADA) {
            throw new TareaCerradaException(id);
        }
        this.responsable = Objects.requireNonNull(nuevo);
    }

    public void completar() {
        if (responsable == null) throw new TareaSinResponsableException(id);
        this.estado = EstadoTarea.COMPLETADA;
    }

    // constructor completo, getters de solo lectura...
}

public record TareaId(UUID valor) {
    public static TareaId nuevo() { return new TareaId(UUID.randomUUID()); }
}

package com.acme.taskflow.tareas.aplicacion.puertos.entrada;

public interface AsignarTareaUseCase {
    void asignar(AsignarTareaCommand comando);

    record AsignarTareaCommand(TareaId tareaId, String emailResponsable) {
        public AsignarTareaCommand {
            Objects.requireNonNull(tareaId);
            if (emailResponsable == null || !emailResponsable.contains("@")) {
                throw new IllegalArgumentException("Email no válido");
            }
        }
    }
}

package com.acme.taskflow.tareas.aplicacion;

public class AsignarTareaService implements AsignarTareaUseCase {
    private final CargarTareaPort cargar;
    private final GuardarTareaPort guardar;
    private final BuscarMiembroPort miembros;

    public AsignarTareaService(CargarTareaPort cargar, GuardarTareaPort guardar, BuscarMiembroPort miembros) {
        this.cargar = cargar;
        this.guardar = guardar;
        this.miembros = miembros;
    }

    @Override
    public void asignar(AsignarTareaCommand cmd) {
        Tarea tarea = cargar.cargar(cmd.tareaId())
            .orElseThrow(() -> new TareaNoEncontradaException(cmd.tareaId()));
        Responsable r = miembros.porEmail(cmd.emailResponsable())
            .orElseThrow(() -> new MiembroNoEncontradoException(cmd.emailResponsable()));
        tarea.asignarA(r);                     // la regla está en el dominio
        guardar.guardar(tarea);
    }
}

package com.acme.taskflow.tareas.aplicacion.puertos.salida;

public interface CargarTareaPort {
    Optional<Tarea> cargar(TareaId id);
}

public interface GuardarTareaPort {
    void guardar(Tarea tarea);
}

public interface BuscarMiembroPort {
    Optional<Responsable> porEmail(String email);
}

public interface NotificarAsignacionPort {
    void tareaAsignada(Tarea tarea, Responsable responsable);
}

// En los tests de aplicación: dobles de una línea
class TareasEnMemoria implements CargarTareaPort, GuardarTareaPort {
    final Map<TareaId, Tarea> datos = new HashMap<>();
    public Optional<Tarea> cargar(TareaId id) { return Optional.ofNullable(datos.get(id)); }
    public void guardar(Tarea t) { datos.put(t.id(), t); }
}

// Adaptador primario: HTTP -> comando -> caso de uso
@RestController
@RequestMapping("/api/tareas")
class TareaWebAdapter {
    private final AsignarTareaUseCase asignar;
    TareaWebAdapter(AsignarTareaUseCase asignar) { this.asignar = asignar; }

    @PutMapping("/{id}/responsable")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    void asignar(@PathVariable UUID id, @RequestBody @Valid AsignarRequest body) {
        asignar.asignar(new AsignarTareaCommand(new TareaId(id), body.email()));
    }
}

// Adaptador secundario: puerto de salida -> JPA
@Component
class TareaPersistenciaAdapter implements CargarTareaPort, GuardarTareaPort {
    private final TareaJpaRepository jpa;
    TareaPersistenciaAdapter(TareaJpaRepository jpa) { this.jpa = jpa; }

    @Override
    public Optional<Tarea> cargar(TareaId id) {
        return jpa.findById(id.valor()).map(TareaJpaMapper::aDominio);
    }

    @Override
    public void guardar(Tarea tarea) {
        jpa.save(TareaJpaMapper.aEntidad(tarea));    // TareaJpaEntity: @Entity, solo aquí
    }
}

/*
com.acme.taskflow
└── tareas
    ├── dominio                     Tarea, TareaId, Responsable, excepciones
    ├── aplicacion
    │   ├── puertos
    │   │   ├── entrada             AsignarTareaUseCase, CompletarTareaUseCase
    │   │   └── salida              CargarTareaPort, GuardarTareaPort, NotificarAsignacionPort
    │   └── AsignarTareaService     (sin anotaciones de Spring)
    └── adaptadores
        ├── entrada
        │   ├── web                 TareaWebAdapter, DTOs de la API
        │   └── mensajeria          TareaEventosListener
        ├── salida
        │   ├── persistencia        TareaPersistenciaAdapter, TareaJpaEntity, TareaJpaRepository
        │   └── notificaciones      NotificadorEmailAdapter
        └── config                  TareasConfig (cableado)
*/

@Configuration
class TareasConfig {
    @Bean
    AsignarTareaUseCase asignarTarea(CargarTareaPort cargar, GuardarTareaPort guardar,
                                     BuscarMiembroPort miembros) {
        return new AsignarTareaService(cargar, guardar, miembros);   // el núcleo no conoce Spring
    }
}