Data Model Reference

This page documents all JPA entities in the svc-envio-encomienda microservice. The data model represents the core business objects: clients, shipments, packages, and branches.

Entity Overview

The system consists of four main entities:

Cliente - Customer/sender information
Envio - Shipment tracking and logistics
Encomienda - Physical package details
Sucursal - Branch office locations

Cliente Entity

Table: clientes
Source: org.jchilon3mas.springcloud.svc.envio.encomienda.entidades.Cliente
Location: svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/entidades/Cliente.java:13 Represents a customer who sends packages through the system.

Fields

id - Long

Type: Long
Annotations: @Id, @GeneratedValue(strategy = GenerationType.IDENTITY)
Description: Primary key, auto-generated.

dni - String

Type: String
Annotations: @Column(unique = true, nullable = false, length = 8)
Description: National identity document number. Must be unique, exactly 8 characters.

The DNI serves as a natural unique identifier for customers in Peru.

nombreCompleto - String

Type: String
Annotations: @Column(nullable = false)
Description: Full name of the customer. Required field.

correo - String

Type: String
Annotations: @Column(unique = true)
Description: Email address. Must be unique across all customers.

telefono - String

Type: String
Annotations: @Column(length = 9)
Description: Phone number, typically 9 digits for mobile phones.

Annotations

@Entity - Marks this as a JPA entity
@Data - Lombok annotation generating getters, setters, toString, equals, and hashCode
@NoArgsConstructor - Generates no-argument constructor
@AllArgsConstructor - Generates constructor with all fields
@Table(name = "clientes") - Maps to the clientes table

Envio Entity

Table: envios
Source: org.jchilon3mas.springcloud.svc.envio.encomienda.entidades.Envio
Location: svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/entidades/Envio.java:17 Core entity representing a shipment from origin to destination branch.

Fields

id - Long

Type: Long
Annotations: @Id, @GeneratedValue(strategy = GenerationType.IDENTITY)
Description: Primary key, auto-generated.

codigoSeguimiento - String

Type: String
Annotations: @Column(unique = true, nullable = false, updatable = false)
Description: Unique tracking code for the shipment. Format: ENV-{timestamp}. Auto-generated by @PrePersist method.

This field cannot be updated after creation (updatable = false).

remitente - Cliente

Type: Cliente
Annotations: @ManyToOne, @JoinColumn(name = "remitente_id", nullable = false)
Description: The customer sending the package. Many shipments can belong to one customer.

encomienda - Encomienda

Type: Encomienda
Annotations: @OneToOne(cascade = CascadeType.ALL), @JoinColumn(name = "encomienda_id", referencedColumnName = "id", unique = true, nullable = false)
Description: The physical package being shipped. One-to-one relationship with cascade operations.

Deleting an Envio will cascade delete its associated Encomienda.

sucursalOrigen - Sucursal

Type: Sucursal
Annotations: @ManyToOne, @JoinColumn(name = "sucursal_origen_id", nullable = false)
Description: Branch where the package originates.

sucursalDestino - Sucursal

Type: Sucursal
Annotations: @ManyToOne, @JoinColumn(name = "sucursal_destino_id", nullable = false)
Description: Destination branch where package will arrive.

nombreDestinatario - String

Type: String
Annotations: @Column(nullable = false)
Description: Full name of the recipient.

dniDestinatario - String

Type: String
Annotations: @Column(nullable = false, length = 20)
Description: Recipient’s identity document number.

placa - String

Type: String
Annotations: @Column(length = 7)
Description: Vehicle license plate for transportation. Optional field.

fechaEnvio - LocalDateTime

Type: LocalDateTime
Annotations: @Column(nullable = false)
Description: Timestamp when shipment was registered.

fechaEntrega - LocalDateTime

Type: LocalDateTime
Annotations: @Column(name = "fecha_entrega")
Description: Timestamp when package was delivered. Null until delivery.

contrasenaEntrega - String

Type: String
Annotations: @Column(nullable = false, length = 4)
Description: 4-digit delivery password for pickup verification.

This is a security mechanism. Ensure proper handling and storage.

precio - double

Type: double
Annotations: @Column(nullable = false)
Description: Total shipping cost in local currency.

estado - EstadoEnvio

Type: EstadoEnvio (enum)
Annotations: @Enumerated(EnumType.STRING), @Column(nullable = false)
Default: EstadoEnvio.PENDIENTE
Description: Current shipment status.Possible values:

PENDIENTE - Registered, awaiting dispatch
EN_TRANSITO - In transit to destination
DISPONIBLE - Available for pickup at destination
ENTREGADO - Successfully delivered
CANCELADO - Shipment cancelled

Stored as STRING in database for readability and forward compatibility.

Lifecycle Methods

@PrePersist - generarCodigoSeguimiento()

Location: svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/entidades/Envio.java:67Automatically generates tracking code before entity persistence:

@PrePersist
public void generarCodigoSeguimiento() {
    if (this.codigoSeguimiento == null) {
        this.codigoSeguimiento = "ENV-" + System.currentTimeMillis();
    }
}

Only generates if codigoSeguimiento is null, allowing manual override if needed.

Encomienda Entity

Table: encomiendas
Source: org.jchilon3mas.springcloud.svc.envio.encomienda.entidades.Encomienda
Location: svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/entidades/Encomienda.java:13 Represents the physical package or parcel being shipped.

Fields

id - Long

Type: Long
Annotations: @Id, @GeneratedValue(strategy = GenerationType.IDENTITY)
Description: Primary key, auto-generated.

peso - double

Type: double
Annotations: @Column(nullable = false)
Description: Package weight in kilograms. Required field.

Weight is used for pricing calculation and vehicle assignment.

dimensiones - String

Type: String
Annotations: @Column(nullable = false)
Description: Package dimensions, typically in format “LxWxH” (e.g., “10x20x30” cm).

descripcion - String

Type: String
Annotations: @Column(nullable = false, length = 500)
Description: Description of package contents. Maximum 500 characters.

Ensure accurate descriptions for customs and handling purposes.

envio - Envio

Type: Envio
Annotations: @OneToOne(mappedBy = "encomienda")
Description: Back-reference to the parent shipment. Bidirectional relationship.

Sucursal Entity

Table: sucursales
Source: org.jchilon3mas.springcloud.svc.envio.encomienda.entidades.Sucursal
Location: svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/entidades/Sucursal.java:13 Represents a physical branch office location.

Fields

id - Long

Type: Long
Annotations: @Id, @GeneratedValue(strategy = GenerationType.IDENTITY)
Description: Primary key, auto-generated.

codigoSucursal - String

Type: String
Annotations: @Column(nullable = false)
Description: Branch code identifier (e.g., “LIM-01”, “ARE-02”).

nombreSucursal - String

Type: String
Annotations: @Column(nullable = false)
Description: Branch name or location identifier.

direccion - String

Type: String
Annotations: @Column(nullable = false)
Description: Physical street address of the branch.

ciudad - String

Type: String
Annotations: @Column(nullable = false)
Description: City where the branch is located.

Relationships Summary

Cliente (1) ----< (N) Envio
Envio (1) ----< (1) Encomienda
Sucursal (1) ----< (N) Envio [as origen]
Sucursal (1) ----< (N) Envio [as destino]

Key Relationship Rules

Cliente → Envio: One customer can have many shipments (ManyToOne)
Envio → Encomienda: Each shipment has exactly one package (OneToOne with cascade)
Envio → Sucursal: Each shipment has origin and destination branches (ManyToOne)

The cascade setting on Envio → Encomienda means deleting a shipment will automatically delete its package.

Database Schema Notes

Naming Conventions

Table names are plural: clientes, envios, encomiendas, sucursales
Foreign key columns use _id suffix: remitente_id, encomienda_id
Enum values stored as strings for clarity

Indexes

Consider adding indexes on frequently queried fields:

Cliente.dni (already unique)
Cliente.correo (already unique)
Envio.codigoSeguimiento (already unique)
Envio.estado (for filtering by status)
Sucursal.codigoSucursal (for lookups)

Data Validation

All entities use Lombok’s @Data annotation which generates:

toString() - for logging
equals() and hashCode() - for collections
Getters and setters - for property access

Consider adding @EqualsAndHashCode(onlyExplicitlyIncluded = true) with @EqualsAndHashCode.Include on id fields to avoid issues with lazy-loaded relationships.

Additional Resources

Data Model Reference

Data Model Reference

Entity Overview

Cliente Entity

Fields

Annotations

Envio Entity

Fields

Lifecycle Methods

Encomienda Entity

Fields

Sucursal Entity

Fields

Relationships Summary

Key Relationship Rules

Database Schema Notes

Naming Conventions

Indexes

Data Validation

Build docs developers (and LLMs) love

Additional Resources

​Data Model Reference

​Entity Overview

​Cliente Entity

​Fields

​Annotations

​Envio Entity

​Fields

​Lifecycle Methods

​Encomienda Entity

​Fields

​Sucursal Entity

​Fields

​Relationships Summary

​Key Relationship Rules

​Database Schema Notes

​Naming Conventions

​Indexes

​Data Validation

Build docs developers (and LLMs) love

Data Model Reference

Entity Overview

Cliente Entity

Fields

Annotations

Envio Entity

Fields

Lifecycle Methods

Encomienda Entity

Fields

Sucursal Entity

Fields

Relationships Summary

Key Relationship Rules

Database Schema Notes

Naming Conventions

Indexes

Data Validation