Skip to content

feat: ESPI 4.0 Schema Compliance - Phase 24: CustomerAgreement Complete Implementation #92

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
dfcoffin merged 1 commit into from
Jan 27, 2026
Merged

feat: ESPI 4.0 Schema Compliance - Phase 24: CustomerAgreement Complete Implementation #92

dfcoffin merged 1 commit into from
Jan 27, 2026
+3,250 −162

Conversation

@dfcoffin
Copy link
Contributor

@dfcoffin dfcoffin commented Jan 27, 2026

Summary

Complete implementation of CustomerAgreement entity, DTO, repository, service, and mapper layers to achieve full ESPI 4.0 customer.xsd schema compliance (lines 159-209, 622-642, 819-872).

Key Achievements:

  • Full CustomerAgreement CRUD operations with repository and service layers
  • Complete Document inheritance chain (19 fields total)
  • ElectronicAddress 8-field compliance across 8 entities
  • Status 4-field compliance with unique XML type names
  • DateTimeInterval namespace-agnostic solution for cross-domain usage
  • Comprehensive test coverage (25 tests: 4 DTO + 21 repository)

XSD Compliance:

  • CustomerAgreement (customer.xsd:159-209): loadMgmt, isPrePay, shutOffDatetime
  • Agreement (customer.xsd:622-642): signDate, validityInterval, agreementStatus
  • Document (customer.xsd:819-872): createdDateTime, lastModifiedDateTime, revisionNumber, subject, title, docStatus, status, comment, type, electronicAddress

Files Changed: 41 (+3324, -236)

New Files

  • CustomerAgreementRepository.java - JPA repository with UUID-based queries
  • CustomerAgreementService.java - Service interface
  • CustomerAgreementServiceImpl.java - Service implementation with full CRUD
  • CustomerAgreementDtoTest.java - JAXB XML marshalling tests (4 tests)
  • CustomerAgreementRepositoryTest.java - JPA persistence tests (21 tests)

Modified Files

Entity Layer

  • CustomerAgreementEntity.java - Added 13 Document fields, 3 Agreement fields, @AttributeOverride annotations
  • CustomerAccountEntity.java - Added @AttributeOverride for docStatus (Status 4-field compliance)
  • ServiceSupplierEntity.java - Added @AttributeOverride for electronicAddress (8-field compliance)

DTO Layer

  • CustomerAgreementDto.java - Complete XSD-compliant structure with unique StatusDto type name "AgreementStatus"
  • CustomerAccountDto.java - Added remark field to StatusDto propOrder, type name "DocStatus"
  • CustomerDto.java - ElectronicAddressDto 8-field structure
  • Moved DateTimeIntervalDto.java from dto/usage to dto/common for namespace-agnostic support

Mapper Layer

  • CustomerAgreementMapper.java - Bidirectional mappings for all 19 fields
  • CustomerMapper.java - Updated ElectronicAddress mappings to 8-field structure
  • DateTimeIntervalMapper.java - Package update

Database

  • V3__Create_additiional_Base_Tables.sql - Added 4 missing ElectronicAddress columns to service_suppliers table (lan, mac, userID, password)

Import Updates (13 files)

Updated imports after DateTimeIntervalDto package move:

  • 7 main files: CustomerAgreementDto, CustomerAgreementDtoTest, ElectricPowerQualitySummaryDto, DateTimeIntervalMapper, UsageExportService, DtoExportServiceImpl, UsageXmlDebugTest
  • 6 usage DTOs: IntervalBlockDto, IntervalReadingDto, AuthorizationDto, UsageSummaryDto, LineItemDto, UsageAtomEntryDto

Critical Fixes

1. ElectronicAddress 8-Field Compliance

Issue: customer.xsd lines 886-936 define 8 fields (lan, mac, email1, email2, web, radio, userID, password) but entities only had 4 fields.

Resolution:

  • Updated 8 entities with complete @AttributeOverride annotations
  • Updated all DTOs and mappers to use 8-field structure
  • Added missing columns to migration script

Affected Entities: CustomerEntity, CustomerAccountEntity, CustomerAgreementEntity, ServiceSupplierEntity, MeterEntity, ServiceLocationEntity, EndDeviceEntity, StatementEntity

2. Status 4-Field Compliance

Issue: customer.xsd lines 1254-1284 define 4 fields (value, dateTime, remark, reason) but remark was missing.

Resolution:

  • Added remark to Status entity @embeddable
  • Updated all StatusDto classes with remark in propOrder
  • Added @AttributeOverride for remark in all entities using Status

3. JAXB XML Type Name Collisions

Issue: Multiple StatusDto classes using same XML type name "Status" caused IllegalAnnotationsException.

Resolution:

  • CustomerDto.StatusDto → name="PersonStatus"
  • CustomerAccountDto.StatusDto → name="DocStatus"
  • CustomerAgreementDto.StatusDto → name="AgreementStatus"

4. Namespace Contamination

Issue: DateTimeIntervalDto in dto/usage package had hardcoded espi namespace, contaminating customer domain when used by CustomerAgreementDto.

Resolution:

  • Moved DateTimeIntervalDto from dto/usage to dto/common
  • Removed all namespace declarations from @XmlRootElement and @XmlType
  • Now inherits namespace from usage context (espi or cust)
  • Updated 13 import statements across codebase

Test Results

Phase 24 CustomerAgreement Tests: 25/25 PASSED ✓

  • DTO Tests (4): Full data marshalling, field order, namespace compliance, ElectronicAddress fields
  • Repository Tests (21): CRUD operations, Document fields, Agreement fields, CustomerAgreement fields, base class functionality

Full Test Suite: 634/634 PASSED ✓

  • openespi-common complete test suite
  • MySQL TestContainers integration tests (2/2)
  • Migration verification tests (11/11)
  • BUILD SUCCESS ✓

Test Plan

  • DTO XML marshalling produces valid customer.xsd-compliant output
  • Repository CRUD operations persist all 19 fields correctly
  • ElectronicAddress 8-field structure works across all entities
  • Status 4-field structure with unique XML type names
  • DateTimeInterval supports both espi and cust namespaces
  • No namespace contamination in customer domain
  • All integration tests pass
  • MySQL TestContainers tests pass
  • No regressions in existing functionality

Related Issues

Closes #28 - ESPI 4.0 Schema Compliance - Phase 24: CustomerAgreement

Migration Impact

  • Database migration V3 updated with 4 new columns (backwards compatible)
  • No breaking changes to existing APIs
  • DateTimeIntervalDto moved to common package (import updates required if external consumers exist)

🤖 Generated with Claude Code

@dfcoffin @claude
feat: ESPI 4.0 Schema Compliance - Phase 24: CustomerAgreement Comple…
567af9b 
…te Implementation (#28)

Implements comprehensive CustomerAgreement support following ESPI 4.0 customer.xsd
specification (lines 159-209, extending Agreement and Document base types).

## Repository & Service Layer
- Add CustomerAgreementRepository with JPA persistence operations
- Add CustomerAgreementService interface and CustomerAgreementServiceImpl
- Implement CRUD operations with full relationship management

## Entity Updates
- Complete CustomerAgreementEntity with all Document, Agreement, and CustomerAgreement fields
- Add Document fields: type, authorName, createdDateTime, lastModifiedDateTime,
  revisionNumber, electronicAddress (8 fields), subject, title, docStatus (4 fields),
  status (4 fields), comment
- Add Agreement fields: signDate, validityInterval (DateTimeInterval)
- Add CustomerAgreement fields: loadMgmt, isPrePay, shutOffDateTime, currency, agreementId
- Fix futureStatus type from Status to List<Status> per XSD
- Add @AttributeOverride annotations for all embedded types (docStatus, status)

## ElectronicAddress 8-Field Compliance
Updated 8 entities to support all ElectronicAddress fields per customer.xsd lines 886-936:
- Added lan, mac, userID, password fields to:
  * CustomerEntity (customer_lan, customer_mac, customer_user_id, customer_password)
  * CustomerAccountEntity (doc_lan, doc_mac, doc_user_id, doc_password)
  * CustomerAgreementEntity (doc_lan, doc_mac, doc_user_id, doc_password)
  * EndDeviceEntity (device_lan, device_mac, device_user_id, device_password)
  * Location (location_lan, location_mac, location_user_id, location_password)
  * Organisation (lan, mac, user_id, password)
  * ServiceLocationEntity (location_lan, location_mac, location_user_id, location_password)
  * ServiceSupplierEntity (supplier_lan, supplier_mac, supplier_user_id, supplier_password)
- Added @AttributeOverride annotations for all embedded ElectronicAddress fields

## Status 4-Field Compliance
Updated Status embedded type to match customer.xsd lines 1254-1284:
- Added remark field between dateTime and reason
- Updated all DTOs (CustomerAccountDto, CustomerAgreementDto) with remark
- Added @AttributeOverride annotations for embedded Status objects

## DTO & Marshalling
- Create CustomerAgreementDto matching XSD field order exactly
- Add nested StatusDto with unique XML type name "AgreementStatus"
- Update CustomerAccountDto.StatusDto to use "DocStatus" XML type name
- Update CustomerDto.StatusDto propOrder to include remark
- Remove Atom wrapper fields from all customer DTOs
- Implement comprehensive JAXB annotations with customer namespace

## Mapper Updates
- Update CustomerAgreementMapper with all Document, Agreement, and CustomerAgreement field mappings
- Update CustomerMapper for 8-field ElectronicAddress
- Update TariffRiderRefMapper imports

## DateTimeInterval Namespace Fix
- Move DateTimeIntervalDto from dto/usage to dto/common package
- Remove hardcoded espi namespace declarations to support both usage and customer contexts
- Update all imports across usage DTOs, mappers, and export services
- Fixes Customer domain XML from incorrectly declaring espi namespace

## Database Migration
- Update V3__Create_additiional_Base_Tables.sql with:
  * All missing Document fields in customer_agreements table
  * 4 missing ElectronicAddress fields in service_suppliers table
  * 4 remark fields for Status objects in multiple tables
  * Proper column ordering and constraints

## Tests
- Add CustomerAgreementDtoTest with 4 XML marshalling tests
- Add CustomerAgreementRepositoryTest with 21 JPA persistence tests
  * Nested test structure: CRUD, Document fields, Agreement fields, CustomerAgreement fields, Base class
  * Full coverage of all entity fields and relationships
- All Phase 24 tests pass (25/25)
- All integration tests pass (634/634)

## Issue Resolution
Resolves #28 - Phase 24 CustomerAgreement Implementation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@dfcoffin dfcoffin mentioned this pull request Jan 27, 2026
Open
@dfcoffin dfcoffin merged commit c1fa7bd into main Jan 27, 2026
5 checks passed
@dfcoffin dfcoffin deleted the feature/schema-compliance-phase-24-customer-agreement branch January 27, 2026 05:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Review Current Usage and Customer Entity Classes to ensure they match their ESPI Schema XSD files

2 participants

@dfcoffin