Modelos de dominio de MULTAGAL

0Mapa de la actividad

Sigue este orden: cada paso usa tipos del anterior, así nunca escribes una referencia a algo que aún no existe.

1. Entiende el dominioGlosario, entidades, relaciones y estados del expediente (sección 1). Sin esto no sabrás qué campos poner.
2. EnumeradosNo dependen de nada: son lo primero que compila.
3. Objetos valorCoordenadas, DireccionPostal, Matricula: piezas pequeñas que usarán las entidades.
4. Las doce entidadesEn tres bloques: catálogo → personas y vehículos → procedimiento.
5. ComprobacionesNulos, imports prohibidos y compilación.
6. ADRdocs/adr/0001-modelado-del-dominio.md con las cinco decisiones, sus alternativas descartadas y el porqué.

1Entiende el dominio antes de teclear

MULTAGAL es el subsistema de tramitación de expedientes sancionadores de una administración de tráfico. Cubre el ciclo de vida completo de una denuncia: captación, tramitación, notificación, alegaciones, resolución, pago y, en su caso, detracción de puntos.

Glosario mínimo

Las doce entidades y sus datos

La columna «Datos» es tu lista de campos. Léela como un enunciado: cada coma es, casi siempre, un atributo.

Relaciones

Del diagrama entidad-relación de la fuente. Te dice qué tipo apunta a qué otro (qué campo de tipo entidad lleva cada record/clase).

El expediente es una máquina de estados

Casi todas las reglas de negocio son restricciones sobre las transiciones válidas. De aquí salen los valores de EstadoExpediente.

Estados finales: PAGADO, PAGADO_BONIFICADO, SOBRESEIDO, PRESCRITO.

Reglas de negocio que afectan al modelo

No las implementas ahora (eso llega desde la A0.4), pero tu modelo tiene que poder expresarlas. Si una regla necesita un dato, ese dato tiene que existir como campo.

2Prepara los ficheros

Paquete obligatorio del proyecto: es.edu.multagal.domain.model (arquitectura en capas, apartado f). Diecinueve ficheros como mínimo.

src/main/java/es/edu/multagal/domain/model/
├── Gravedad.java               ← enumerados (4)
├── EstadoExpediente.java
├── EstadoPermiso.java
├── ResultadoNotificacion.java
├── Coordenadas.java            ← objetos valor (3)
├── DireccionPostal.java
├── Matricula.java
├── Infraccion.java             ← entidades (12)
├── Radar.java
├── Conductor.java
├── PermisoConduccion.java
├── Vehiculo.java
├── Titularidad.java
├── Denuncia.java
├── Expediente.java
├── Notificacion.java
├── Alegacion.java
├── Resolucion.java
└── Pago.java

• Crear el paquete domain/model (si no lo tienes de la A0.2) y localizar dónde irán los 19 tipos

3Enumerados: adiós a los String mágicos

Criterio 3: los enumerados sustituyen a los String mágicos. Si un campo sólo admite un conjunto cerrado de valores, es un enum.

Gravedad — viene dada en la fuente, cópiala tal cual:

package es.edu.multagal.domain.model;

public enum Gravedad { LEVE, GRAVE, MUY_GRAVE }

EstadoExpediente — sale directamente de la máquina de estados de la sección 1. Escríbelo tú: son nueve valores.

package es.edu.multagal.domain.model;

public enum EstadoExpediente {
    INICIADO,
    NOTIFICADO,
    ALEGADO,
    RESUELTO,
    FIRME,
    SOBRESEIDO,
    PAGADO,
    PAGADO_BONIFICADO,
    PRESCRITO
}

EstadoPermiso y ResultadoNotificacion — aquí la fuente no enumera los valores: los decides tú. Pistas de la fuente:

• R3 habla de un permiso suspendido y de un conductor a 0 puntos con «el permiso activo».
• La notificación «puede requerir varios intentos», cada uno «con acuse y resultado»: el resultado tiene que distinguir un intento que llega de uno que no.

// EstadoPermiso.java — ACTIVO y SUSPENDIDO salen de R3; añade otros si los justificas
public enum EstadoPermiso { ACTIVO, SUSPENDIDO }

// ResultadoNotificacion.java — propuesta: la fuente sólo dice «con acuse y resultado»
public enum ResultadoNotificacion { ENTREGADA, RECHAZADA, AUSENTE, DESCONOCIDO }

public enum Gravedad {
    LEVE(3), GRAVE(6), MUY_GRAVE(6);

    private final int mesesPrescripcion;

    Gravedad(int mesesPrescripcion) { this.mesesPrescripcion = mesesPrescripcion; }

    public int mesesPrescripcion() { return mesesPrescripcion; }
}

• Crear Gravedad (LEVE, GRAVE, MUY_GRAVE)
• Crear EstadoExpediente con los nueve estados de la máquina de estados
• Crear EstadoPermiso y ResultadoNotificacion, y apuntar para el ADR por qué elegiste esos valores

4Objetos valor

Un objeto valor no tiene identidad propia: dos Coordenadas con la misma latitud y longitud son la misma. Por eso encajan de forma natural con record (inmutable, con equals/hashCode por valor).

Coordenadas — dada en la fuente:

public record Coordenadas(double latitud, double longitud) { }

Matricula — la fuente te pregunta: ¿debe ser un tipo propio o basta con un String? Piensa qué gana un tipo propio: no puedes pasar un NIF donde se espera una matrícula, y el lugar natural para validar/normalizar el formato es su constructor. Esa es la decisión 4 del ADR.

// Matricula.java — el formato exacto no lo fija la fuente; aquí sólo se normaliza
public record Matricula(String valor) {
    public Matricula {                       // constructor compacto
        if (valor == null || valor.isBlank()) {
            throw new IllegalArgumentException("La matrícula no puede estar vacía");
        }
        valor = valor.replace(" ", "").replace("-", "").toUpperCase();
    }
}

// DireccionPostal.java — campos propuestos (la fuente sólo dice «domicilio»)
public record DireccionPostal(
        String via,
        String numero,
        String codigoPostal,
        String municipio,
        String provincia) { }

• Crear Coordenadas y DireccionPostal como objetos valor
• Crear Matricula como tipo propio (o decidir que no y justificarlo en el ADR)

5Las doce entidades, en tres bloques

Para cada campo aplica siempre las mismas tres preguntas: ¿qué tipo Java? · ¿puede ser null? · ¿cambiará con el tiempo?

Bloque A · Catálogo: Infraccion y Radar

No dependen de ninguna otra entidad. Infraccion viene dada en la fuente:

public record Infraccion(
        String codigo,
        String articulo,
        String descripcion,
        BigDecimal importeBase,
        int puntos,
        Gravedad gravedad) { }

Ahora Radar: identificador, ubicación, tipo, límite de velocidad controlado. Pista: la ubicación ya tiene tipo (Coordenadas).

public record Radar(
        String identificador,
        Coordenadas ubicacion,
        String tipo,              // la fuente no enumera los tipos: si los cierras, pásalo a enum
        int limiteVelocidad) { }  // km/h

• Crear Infraccion y Radar

Bloque B · Personas y vehículos

public record Conductor(
        String nif,                     // NIF/NIE — en pruebas, siempre datos sintéticos
        String nombre,
        DireccionPostal domicilio,
        LocalDate fechaExpedicion,
        int saldoPuntos) { }

public record PermisoConduccion(
        Conductor conductor,
        Set<String> clases,             // "A", "B", "C"…
        LocalDate validoDesde,
        LocalDate validoHasta,
        EstadoPermiso estado) { }

public record Vehiculo(
        Matricula matricula,
        String marca,
        String modelo,
        String tipo,
        LocalDate fechaMatriculacion,
        LocalDate caducidadItv) { }      // una forma de expresar el «estado de ITV»

public record Titularidad(
        Conductor conductor,
        Vehiculo vehiculo,
        LocalDate fechaAlta,
        LocalDate fechaBaja) { }         // null = titularidad vigente

• Crear Conductor, PermisoConduccion, Vehiculo y Titularidad

Bloque C · El procedimiento

public record Denuncia(
        LocalDateTime fechaHora,        // el hecho ocurre a una hora concreta
        Coordenadas lugar,
        String agente,                  // null si la capta un radar
        Radar radar,                    // null si la formula un agente
        Infraccion infraccion,
        Vehiculo vehiculo,
        Conductor conductor) { }        // null cuando la capta un radar

public record Expediente(
        String numero,
        EstadoExpediente estado,
        BigDecimal importe,
        LocalDate fechaNotificacion,    // null mientras no se haya notificado
        Denuncia denuncia) { }

public record Notificacion(
        Expediente expediente,
        int intento,                    // 1, 2, 3… «puede requerir varios intentos»
        LocalDateTime fechaIntento,
        LocalDate fechaAcuse,           // null si no hubo acuse
        ResultadoNotificacion resultado) { }

public record Alegacion(
        Expediente expediente,
        LocalDate fechaPresentacion,
        String texto,
        List<String> documentos,        // nombres de los adjuntos (los binarios llegan en la UD5)
        boolean contestada) { }         // R5

public record Resolucion(
        Expediente expediente,
        LocalDate fecha,
        String fundamento,
        boolean firme) { }              // R2

public record Pago(
        Expediente expediente,
        LocalDate fecha,
        BigDecimal importe,
        boolean bonificado) { }         // R1

• Crear Denuncia y Expediente
• Crear Notificacion, Alegacion, Resolucion y Pago

6Comprueba antes de escribir el ADR

Tres comprobaciones rápidas. Hazlas ahora: si algo falla, cambia el código antes de documentarlo.

a) Los nulos, uno a uno

Recorre cada tipo y pregúntate qué campos pueden ser null legítimamente (porque el dominio lo permite, no por pereza). Apunta la lista para el ADR. Ejemplo de la fuente: Denuncia.conductor es null cuando la capta un radar.

b) Ningún import de fuera en domain

Es la regla de dependencia del apartado f: domain no depende de nada — ni de Spring, ni de JPA, ni de Jackson. Si tu Expediente importa org.springframework.*, el dominio ha dejado de ser el núcleo estable. Compruébalo mirando los import:

grep -rnE "import (org\.springframework|jakarta\.persistence|com\.fasterxml)" src/main/java/es/edu/multagal/domain

Get-ChildItem -Recurse src/main/java/es/edu/multagal/domain -Filter *.java |
  Select-String -Pattern 'import (org\.springframework|jakarta\.persistence|com\.fasterxml)'

Resultado correcto: ninguna línea. Sólo deberías ver imports de java.* (java.math.BigDecimal, java.time.*, java.util.*).

c) Compila

./mvnw clean package

• Hacer la lista de campos que pueden ser legítimamente null (y por qué)
• Ejecutar la búsqueda de imports y obtener cero resultados en domain
• Comprobar que ./mvnw clean package termina sin errores

7Las cinco decisiones del ADR

Criterio 5: el ADR justifica las decisiones, no sólo las describe. Para cada una: qué decidiste, qué alternativa descartaste y por qué.

System.out.println(0.1 + 0.2);                          // 0.30000000000000004
System.out.println(new BigDecimal("0.1")
        .add(new BigDecimal("0.2")));                   // 0.3

Plantilla del ADR

Mismo formato simplificado que el ADR 0000 de la A0.2 (decisión, alternativas descartadas, consecuencias), con una entrada por decisión:

# ADR-0001 — Modelado del dominio
**Fecha:** AAAA-MM-DD
**Estado:** aceptada

## Contexto
Primer modelo Java del dominio MULTAGAL, sin persistencia (UD0).
En la UD4 se mapeará con JPA.

## Decisión 1 — record o clase
**Decisión:** ...
**Alternativa descartada:** ...
**Por qué:** ...

## Decisión 2 — Tipo de los importes
**Decisión:** BigDecimal
**Alternativa descartada:** double
**Por qué:** ...

## Decisión 3 — Tipo de las fechas
**Decisión:** ... para la fecha de comisión; ... para el plazo de pronto pago
**Alternativa descartada:** ...
**Por qué:** ...

## Decisión 4 — Matricula: tipo propio o String
**Decisión:** ...
**Alternativa descartada:** ...
**Por qué:** ...

## Decisión 5 — Campos que admiten null
| Campo | ¿Por qué puede ser null? |
|-------|--------------------------|
| Denuncia.conductor | La capta un radar: capta una matrícula, no una persona |
| ...   | ... |

## Consecuencias
Qué implica todo lo anterior para la UD3 (JDBC) y la UD4 (JPA).

• Redactar docs/adr/0001-modelado-del-dominio.md con las cinco decisiones, sus alternativas descartadas y el porqué

✓Criterios de aceptación

Así se corrige. Repásalos uno a uno antes de dar la actividad por cerrada.

• Repasar los cinco criterios de aceptación y confirmar que se cumplen todos

?Para la defensa oral

Preguntas de la autoevaluación de la UD0 relacionadas con esta actividad. Respóndelas sin mirar.

• ¿Por qué el paquete domain no debe importar nada de Spring?
• ¿Por qué los importes van en BigDecimal y no en double?
• Enumera las reglas de dependencia entre las capas del proyecto. ¿Puede controller llamar a repository?