feat: ESPI 4.0 Schema Compliance - Phase 11: UsageSummary

[dfcoffin]

Summary

Complete rebuild of UsageSummary entity, DTOs, and mappers to achieve full ESPI 4.0 XSD compliance (espi.xsd:806-939). This phase adds all missing fields, reorders existing fields to match XSD sequence, and implements proper collection management for tariff rider references.

Entity Changes

• ✅ Added 5 missing fields to UsageSummaryEntity:
  • commodity (Integer) - CommodityKind enumeration
  • tariffProfile (String 256) - Tariff schedule structure
  • readCycle (String 256) - Meter read cycle day
  • tariffRiderRefs (List) - Rate options collection
  • billingChargeSource (BillingChargeSource) - Billing source information
• ✅ Reordered all 25 entity fields to match XSD sequence exactly (espi.xsd:816-935)
• ✅ Added helper methods: addTariffRiderRef(), removeTariffRiderRef()
• ✅ Updated merge(), unlink(), and toString() methods

New Domain Objects

• ✅ TariffRiderRefEntity - Object-based entity (Long ID with auto-increment)
  • Fields: riderType, enrollmentStatus, effectiveDate
  • Per ESPI 4.0 XSD (espi.xsd:1602-1627)
  • Belongs to TariffRiderRefs collection in UsageSummary
• ✅ BillingChargeSource - Embeddable value object
  • Field: agencyName (String 256)
  • Per ESPI 4.0 XSD (espi.xsd:1628-1643)

DTO Changes

• ✅ Completely rebuilt UsageSummaryDto with all 32 fields in XSD order
• ✅ Added all 10 SummaryMeasurement DTO fields:
  • overallConsumptionLastPeriod
  • currentBillingPeriodOverAllConsumption
  • currentDayLastYearNetConsumption
  • currentDayNetConsumption
  • currentDayOverallConsumption
  • peakDemand
  • previousDayLastYearOverallConsumption
  • previousDayNetConsumption
  • previousDayOverallConsumption
  • ratchetDemand
• ✅ Added ratchetDemandPeriod (DateTimeIntervalDto)
• ✅ Added costAdditionalDetailLastPeriod collection (List)
• ✅ Fixed statusTimeStamp type: OffsetDateTime → Long (TimeType, epoch seconds)
• ✅ Created BillingChargeSourceDto for XML marshalling

Mapper Changes

• ✅ Created TariffRiderRefMapper with bidirectional entity/DTO conversion
• ✅ Added collection conversion methods with @nAmed qualifiers:
  • tariffRiderRefsDtoToEntityList - Unwraps TariffRiderRefsDto to List
  • entityListToTariffRiderRefsDto - Wraps List in TariffRiderRefsDto
• ✅ Updated UsageSummaryMapper with all new field mappings
• ✅ Added SummaryMeasurementMapper, LineItemMapper, TariffRiderRefMapper dependencies

Database Migrations

• ✅ Added tariff_rider_refs table to V2 migrations (MySQL, PostgreSQL, H2):
  • Primary key: BIGSERIAL/AUTO_INCREMENT (Long ID)
  • Fields: rider_type, enrollment_status, effective_date
  • Foreign key to usage_summaries with CASCADE delete
  • Indexes on usage_summary_id, rider_type, enrollment_status
• ✅ Added 4 new columns to usage_summaries table:
  • commodity (INTEGER)
  • tariff_profile (VARCHAR 256)
  • read_cycle (VARCHAR 256)
  • billing_charge_source_agency_name (VARCHAR 256)
• ✅ Added indexes for new columns

Test Updates

• ✅ Updated TestApplication @EntityScan to include domain.common package
• ✅ All 533 tests passing (0 failures, 0 errors, 0 skipped)
• ✅ Flyway migrations apply cleanly to H2, MySQL, and PostgreSQL

Test Plan

• All entity fields match XSD sequence (espi.xsd:816-935)
• TariffRiderRefEntity properly maps to tariff_rider_refs table
• BillingChargeSource embedded correctly in usage_summaries table
• UsageSummaryDto includes all 25 XSD fields
• MapStruct mappers handle all field conversions
• Flyway migrations apply successfully
• All repository tests pass
• Entity persistence and retrieval work correctly
• Collection management (tariffRiderRefs) works properly

Migration Notes

Important: This PR modifies existing V2 Flyway migrations. In development environments, clear Flyway's schema history before applying:

-- For H2 test databases (automatic with clean-on-validation-error: true)
-- For MySQL/PostgreSQL development:
DELETE FROM flyway_schema_history WHERE version = '2';

Related Issues

Closes #28

---

🤖 Generated with Claude Code