feat: ESPI 4.0 Schema Compliance - Phase 21: ServiceSupplier Complete Implementation (#96)

This phase implements full ESPI 4.0 compliance for ServiceSupplier and refactors
all Organisation phone number handling from PhoneNumberEntity table to embedded
TelephoneNumber fields.

Key Changes:
- Created ServiceSupplierDto, OrganisationDto, TelephoneNumberDto with JAXB annotations
- Implemented ServiceSupplierMapper, OrganisationMapper, TelephoneNumberMapper
- Fixed SupplierKind enum to match XSD (6 values: UTILITY, RETAILER, OTHER, LSE, MDMA, MSP)
- Refactored Organisation to use embedded phone1/phone2 (TelephoneNumber)
- Deleted PhoneNumberEntity, OrganisationRole, PhoneNumberService (no longer needed)
- Updated ServiceSupplierEntity and CustomerEntity with phone @AttributeOverride
- Optimized TelephoneNumber column sizes to prevent MySQL row size limit
- Updated V3 Flyway migration with embedded phone columns
- Resolved Spring bean conflicts (removed BaseMapperUtils inheritance)
- Removed legacy usagePointId field from ElectricPowerQualitySummaryDto
- Added 24 new DTO tests (ServiceSupplierDtoTest, OrganisationDtoTest, TelephoneNumberDtoTest)

Test Results:
- Total: 760 tests (all passing)
- Integration: PostgreSQL (2/2), H2 (3/3), MySQL (2/2)

Related Issue: #28 (Phase 21)

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: dfcoffin

openespi-common/PHASE_21_SERVICE_SUPPLIER_IMPLEMENTATION_PLAN.md

@@ -47,28 +47,28 @@
 @AllArgsConstructor
 public class TelephoneNumber implements Serializable {
 
-    @Column(name = "country_code", length = 256)
+    @Column(name = "country_code", length = 10)
     private String countryCode;
 
-    @Column(name = "area_code", length = 256)
+    @Column(name = "area_code", length = 10)
     private String areaCode;
 
-    @Column(name = "city_code", length = 256)
+    @Column(name = "city_code", length = 10)
     private String cityCode;
 
-    @Column(name = "local_number", length = 256)
+    @Column(name = "local_number", length = 30)
     private String localNumber;
 
-    @Column(name = "ext", length = 256)
+    @Column(name = "ext", length = 20)
     private String ext;
 
-    @Column(name = "dial_out", length = 256)
+    @Column(name = "dial_out", length = 10)
     private String dialOut;
 
-    @Column(name = "international_prefix", length = 256)
+    @Column(name = "international_prefix", length = 10)
     private String internationalPrefix;
 
-    @Column(name = "itu_phone", length = 256)
+    @Column(name = "itu_phone", length = 50)
     private String ituPhone;
 
     @Override

openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/customer/common/TelephoneNumber.java

@@ -168,6 +168,22 @@ public class CustomerAccountEntity extends IdentifiedObject {
     @AttributeOverride(name = "postalAddress.stateOrProvince", column = @Column(name = "postal_state_or_province"))
     @AttributeOverride(name = "postalAddress.postalCode", column = @Column(name = "postal_postal_code"))
     @AttributeOverride(name = "postalAddress.country", column = @Column(name = "postal_country"))
+    @AttributeOverride(name = "phone1.countryCode", column = @Column(name = "contact_phone1_country_code"))
+    @AttributeOverride(name = "phone1.areaCode", column = @Column(name = "contact_phone1_area_code"))
+    @AttributeOverride(name = "phone1.cityCode", column = @Column(name = "contact_phone1_city_code"))
+    @AttributeOverride(name = "phone1.localNumber", column = @Column(name = "contact_phone1_local_number"))
+    @AttributeOverride(name = "phone1.ext", column = @Column(name = "contact_phone1_ext"))
+    @AttributeOverride(name = "phone1.dialOut", column = @Column(name = "contact_phone1_dial_out"))
+    @AttributeOverride(name = "phone1.internationalPrefix", column = @Column(name = "contact_phone1_international_prefix"))
+    @AttributeOverride(name = "phone1.ituPhone", column = @Column(name = "contact_phone1_itu_phone"))
+    @AttributeOverride(name = "phone2.countryCode", column = @Column(name = "contact_phone2_country_code"))
+    @AttributeOverride(name = "phone2.areaCode", column = @Column(name = "contact_phone2_area_code"))
+    @AttributeOverride(name = "phone2.cityCode", column = @Column(name = "contact_phone2_city_code"))
+    @AttributeOverride(name = "phone2.localNumber", column = @Column(name = "contact_phone2_local_number"))
+    @AttributeOverride(name = "phone2.ext", column = @Column(name = "contact_phone2_ext"))
+    @AttributeOverride(name = "phone2.dialOut", column = @Column(name = "contact_phone2_dial_out"))
+    @AttributeOverride(name = "phone2.internationalPrefix", column = @Column(name = "contact_phone2_international_prefix"))
+    @AttributeOverride(name = "phone2.ituPhone", column = @Column(name = "contact_phone2_itu_phone"))
     @AttributeOverride(name = "electronicAddress.lan", column = @Column(name = "contact_lan"))
     @AttributeOverride(name = "electronicAddress.mac", column = @Column(name = "contact_mac"))
     @AttributeOverride(name = "electronicAddress.email1", column = @Column(name = "contact_email1"))

openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/customer/entity/CustomerAccountEntity.java

@@ -27,7 +27,6 @@
 import org.greenbuttonalliance.espi.common.domain.common.IdentifiedObject;
 import org.greenbuttonalliance.espi.common.domain.customer.enums.CustomerKind;
 import org.greenbuttonalliance.espi.common.domain.usage.TimeConfigurationEntity;
-import org.hibernate.annotations.SQLRestriction;
 import org.hibernate.proxy.HibernateProxy;
 
 import java.time.OffsetDateTime;
@@ -69,6 +68,22 @@ public class CustomerEntity extends IdentifiedObject {
     @AttributeOverride(name = "postalAddress.stateOrProvince", column = @Column(name = "customer_postal_state_or_province"))
     @AttributeOverride(name = "postalAddress.postalCode", column = @Column(name = "customer_postal_postal_code"))
     @AttributeOverride(name = "postalAddress.country", column = @Column(name = "customer_postal_country"))
+    @AttributeOverride(name = "phone1.countryCode", column = @Column(name = "customer_phone1_country_code"))
+    @AttributeOverride(name = "phone1.areaCode", column = @Column(name = "customer_phone1_area_code"))
+    @AttributeOverride(name = "phone1.cityCode", column = @Column(name = "customer_phone1_city_code"))
+    @AttributeOverride(name = "phone1.localNumber", column = @Column(name = "customer_phone1_local_number"))
+    @AttributeOverride(name = "phone1.ext", column = @Column(name = "customer_phone1_ext"))
+    @AttributeOverride(name = "phone1.dialOut", column = @Column(name = "customer_phone1_dial_out"))
+    @AttributeOverride(name = "phone1.internationalPrefix", column = @Column(name = "customer_phone1_international_prefix"))
+    @AttributeOverride(name = "phone1.ituPhone", column = @Column(name = "customer_phone1_itu_phone"))
+    @AttributeOverride(name = "phone2.countryCode", column = @Column(name = "customer_phone2_country_code"))
+    @AttributeOverride(name = "phone2.areaCode", column = @Column(name = "customer_phone2_area_code"))
+    @AttributeOverride(name = "phone2.cityCode", column = @Column(name = "customer_phone2_city_code"))
+    @AttributeOverride(name = "phone2.localNumber", column = @Column(name = "customer_phone2_local_number"))
+    @AttributeOverride(name = "phone2.ext", column = @Column(name = "customer_phone2_ext"))
+    @AttributeOverride(name = "phone2.dialOut", column = @Column(name = "customer_phone2_dial_out"))
+    @AttributeOverride(name = "phone2.internationalPrefix", column = @Column(name = "customer_phone2_international_prefix"))
+    @AttributeOverride(name = "phone2.ituPhone", column = @Column(name = "customer_phone2_itu_phone"))
     @AttributeOverride(name = "electronicAddress.lan", column = @Column(name = "customer_lan"))
     @AttributeOverride(name = "electronicAddress.mac", column = @Column(name = "customer_mac"))
     @AttributeOverride(name = "electronicAddress.email1", column = @Column(name = "customer_email1"))
@@ -158,16 +173,6 @@ public class CustomerEntity extends IdentifiedObject {
     @OneToMany(mappedBy = "customer", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
     private List<StatementEntity> statements = new ArrayList<>();
 
-    /**
-     * Phone numbers for this customer's organisation.
-     * Managed via separate PhoneNumberEntity to avoid column conflicts.
-     * Initialized to empty ArrayList to avoid null pointer exceptions.
-     */
-    @OneToMany(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
-    @JoinColumn(name = "parent_entity_uuid", referencedColumnName = "id")
-    @SQLRestriction("parent_entity_type = 'CustomerEntity'")
-    private List<PhoneNumberEntity> phoneNumbers = new ArrayList<>();
-
     /**
      * Embeddable class for Status
      */

openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/customer/entity/CustomerEntity.java

@@ -25,6 +25,7 @@
 import lombok.*;
 import org.greenbuttonalliance.espi.common.domain.customer.common.ElectronicAddress;
 import org.greenbuttonalliance.espi.common.domain.customer.common.StreetAddress;
+import org.greenbuttonalliance.espi.common.domain.customer.common.TelephoneNumber;
 
 import java.io.Serializable;
 
@@ -59,8 +60,17 @@ public class Organisation implements Serializable {
     @Embedded
     private StreetAddress postalAddress;
 
-    // PhoneNumber fields removed - phone numbers are managed separately via PhoneNumberEntity
-    // to avoid JPA column mapping conflicts in embedded contexts
+    /**
+     * Primary phone number for this organisation.
+     */
+    @Embedded
+    private TelephoneNumber phone1;
+
+    /**
+     * Secondary phone number for this organisation.
+     */
+    @Embedded
+    private TelephoneNumber phone2;
 
     /**
      * Electronic address for this organisation.