docs: Add multi-phase ESPI schema compliance plan and reference diagrams

[dfcoffin]

Summary

Adds a comprehensive 26-phase plan to address Issue #28 by reviewing and updating all Usage and Customer domain entities to ensure compliance with NAESB ESPI 4.0 schema (espi.xsd and customer.xsd) element sequences.

Closes

Addresses #28

Files Added

• MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md: Detailed 26-phase implementation plan with complete tasks for entities, DTOs, mappers, repositories, services, Flyway migrations, and tests
• ESPI Usage.pdf: Atom link relationship diagram for espi.xsd main resources
• ESPI Usage Summary Classes.pdf: Atom link relationship diagram for summary classes
• Retail Customer Resource Atom Link Usage.pdf: Atom link relationships for customer.xsd resources

Plan Structure

The plan processes entities in dependency order (parents before children):

Usage Domain (Phases 1-16)

• Phase 1-16: Process espi.xsd entities including TimeConfiguration, ReadingType, IntervalReading, ReadingQuality, IntervalBlock, MeterReading, ServiceDeliveryPoint, PnodeRef, AggregatedNodeRef, LineItem, UsageSummary, ElectricPowerQualitySummary, RetailCustomer, Subscription, BatchList, and UsagePoint

Customer Domain (Phases 17-26)

• Phase 17-26: Process customer.xsd entities including ProgramDateIdMappings, CustomerAccount, Statement, Customer, ServiceSupplier, Asset, ServiceLocation, CustomerAgreement, EndDevice, and Meter

Each Phase Includes

1. Entity field order verification against XSD schema
2. DTO updates with JAXB annotations
3. Bidirectional MapStruct mapper updates (Entity-to-DTO and DTO-to-Entity)
4. Repository query optimization (keep only index field queries)
5. Service method schema compliance review
6. Flyway migration script updates (update original scripts)
7. Comprehensive testing with XML marshalling/unmarshalling and XSD validation
8. Git workflow (branch, commit, push, PR)

Key Corrections Applied

• MeterReading: Documented that it has NO child elements, only Atom links to IntervalBlock and ReadingType
• Cross-stream reference: ServiceLocation (customer.xsd PII stream) references UsagePoint (espi.xsd non-PII stream) via href URL string, NOT Atom link
• Bidirectional Atom links: All bidirectional relationships properly documented
• Customer domain relationships: Corrected per schema diagrams including Statement ↔ Customer/CustomerAccount, CustomerAgreement ↔ ServiceSupplier/ServiceLocation/ProgramDateIdMappings, EndDevice ↔ ServiceLocation

Branch Strategy

Each phase will use a separate feature branch:

• Naming: feature/schema-compliance-phase-{number}-{entity-name}
• One entity per phase with all associated files
• Commit, push, and PR merge before starting next phase

Test Requirements

• Unit tests for entity, service, repository
• Integration tests using TestContainers (MySQL, PostgreSQL, H2)
• XML marshalling/unmarshalling tests for ALL phases
• XSD schema validation (espi.xsd for usage domain, customer.xsd for customer domain)

Next Steps

After this PR is merged:

1. Begin Phase 1: TimeConfiguration (LocalTimeParameters)
2. Create branch: feature/schema-compliance-phase-1-time-configuration
3. Execute all 8 task categories for Phase 1
4. Continue through all 26 phases in order