feat: ESPI 4.0 Schema Compliance - Phase 16b: UsagePoint Add Enum Fields & Reorder

This PR implements Phase 16b of the UsagePoint schema compliance work, adding 3
missing enum fields and reordering all entity fields to match exact ESPI 4.0 XSD
sequence. Builds on Phase 16a (PR #83) which added Boolean/String fields.

## Changes in Phase 16b

### New Enum Classes (domain/common)
- `AmiBillingReadyKind` - AMI billing readiness lifecycle states (7 values)
- `UsagePointConnectedKind` - Network connection states (3 values)
- `PhaseCodeKind` - Phase identifiers for electrical systems (27 values)

### Entity Updates (UsagePointEntity)
- Added 3 enum fields in correct XSD positions:
  - `amiBillingReady` (XSD position 5)
  - `connectionState` (XSD position 7)
  - `phaseCode` (XSD position 15)
- **Reordered ALL fields to match exact ESPI 4.0 XSD element sequence**
- Added XSD position comments for each field (positions 1-21)
- Added section headers for clarity (XSD fields, legacy fields, relationships)
- Documented legacy fields (`uri`, `kind`) as NOT in XSD for Phase 16c review

### Database Migrations
Updated all three vendor-specific V2 migrations:
- **H2**: Added 3 enum columns (VARCHAR 32) in XSD sequence
- **MySQL**: Added 3 enum columns (VARCHAR 32) in XSD sequence
- **PostgreSQL**: Added 3 enum columns (VARCHAR 32) in XSD sequence

### Testing
- Added comprehensive repository test: `shouldPersistAndRetrievePhase16bEnumFields()`
- Verifies all 3 enum fields persist and retrieve correctly
- All 584 tests passing (was 583, added 1 new test)

## XSD Compliance Achieved

Fields now match exact ESPI 4.0 XSD sequence (espi.xsd:486-613):
1. roleFlags
2. ServiceCategory
3. status
4. serviceDeliveryPoint (relationship)
5. **amiBillingReady** ✅ NEW (Phase 16b)
6. checkBilling (Phase 16a)
7. **connectionState** ✅ NEW (Phase 16b)
8. estimatedLoad
9. grounded (Phase 16a)
10. isSdp (Phase 16a)
11. isVirtual (Phase 16a)
12. minimalUsageExpected (Phase 16a)
13. nominalServiceVoltage
14. outageRegion (Phase 16a)
15. **phaseCode** ✅ NEW (Phase 16b)
16. ratedCurrent
17. ratedPower
18. readCycle (Phase 16a)
19. readRoute (Phase 16a)
20. serviceDeliveryRemark (Phase 16a)
21. servicePriority (Phase 16a)
22-23. pnodeRefs, aggregateNodeRefs (relationships)

## Technical Details

### Enum Design
- All enums follow existing ServiceCategory pattern
- String-based values for AmiBillingReadyKind, UsagePointConnectedKind
- Integer-based values for PhaseCodeKind (per XSD UInt16)
- Each enum has `fromValue()` method for deserialization
- Stored as VARCHAR(32) in database using `@Enumerated(EnumType.STRING)`

### Field Ordering
- Entity fields now match exact XSD element sequence
- Improves maintainability and XSD compliance verification
- Inline comments mark XSD positions for each field
- Legacy fields clearly separated with TODO for Phase 16c

### Additive-Only Changes
This PR is **100% additive** with zero breaking changes:
- All new fields are nullable/optional
- No field deletions or renames
- No changes to existing relationships
- Backward compatible database migrations

## Test Results
```
Tests run: 584, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS
```

## Related
- Issue #28 - Phase 16: UsagePoint
- PR #83 - Phase 16a: Add Missing Boolean/String Fields
- Part 2 of 5 sub-phases for complete UsagePoint compliance

## Next Steps (Phase 16c)
- Repository cleanup (remove non-indexed queries)
- Review legacy fields (`kind`, `uri`)
- Convert @query to Spring Data JPA derived queries

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: dfcoffin

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

@@ -0,0 +1,94 @@
+/*
+ *
+ *        Copyright (c) 2025 Green Button Alliance, Inc.
+ *
+ *
+ *     Licensed under the Apache License, Version 2.0 (the "License");
+ *     you may not use this file except in compliance with the License.
+ *     You may obtain a copy of the License at
+ *
+ *          http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *     Unless required by applicable law or agreed to in writing, software
+ *     distributed under the License is distributed on an "AS IS" BASIS,
+ *     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *     See the License for the specific language governing permissions and
+ *     limitations under the License.
+ *
+ */
+
+package org.greenbuttonalliance.espi.common.domain.common;
+
+/**
+ * Lifecycle states of the metering installation at a usage point with respect to
+ * readiness for billing via advanced metering infrastructure reads.
+ * Per ESPI 4.0 XSD: AmiBillingReadyKind enumeration.
+ */
+public enum AmiBillingReadyKind {
+	/**
+	 * Usage point is equipped with an AMI capable meter that is not yet currently
+	 * equipped with a communications module.
+	 */
+	AMI_CAPABLE("amiCapable"),
+
+	/**
+	 * Usage point is equipped with an AMI capable meter; however, the AMI functionality
+	 * has been disabled or is not being used.
+	 */
+	AMI_DISABLED("amiDisabled"),
+
+	/**
+	 * Usage point is equipped with an operating AMI capable meter and accuracy has been
+	 * certified for billing purposes.
+	 */
+	BILLING_APPROVED("billingApproved"),
+
+	/**
+	 * Usage point is equipped with an AMI capable meter having communications capability.
+	 */
+	ENABLED("enabled"),
+
+	/**
+	 * Usage point is equipped with a non AMI capable meter.
+	 */
+	NON_AMI("nonAmi"),
+
+	/**
+	 * Usage point is not currently equipped with a meter.
+	 */
+	NON_METERED("nonMetered"),
+
+	/**
+	 * Usage point is equipped with an AMI capable meter that is functioning and
+	 * communicating with the AMI network.
+	 */
+	OPERABLE("operable");
+
+	private final String value;
+
+	AmiBillingReadyKind(String value) {
+		this.value = value;
+	}
+
+	public String getValue() {
+		return value;
+	}
+
+	/**
+	 * Converts a string value to the corresponding AmiBillingReadyKind enum constant.
+	 *
+	 * @param value the string value from XML/XSD
+	 * @return the matching enum constant, or null if not found
+	 */
+	public static AmiBillingReadyKind fromValue(String value) {
+		if (value == null) {
+			return null;
+		}
+		for (AmiBillingReadyKind kind : AmiBillingReadyKind.values()) {
+			if (kind.value.equals(value)) {
+				return kind;
+			}
+		}
+		return null;
+	}
+}

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

@@ -0,0 +1,191 @@
+/*
+ *
+ *        Copyright (c) 2025 Green Button Alliance, Inc.
+ *
+ *
+ *     Licensed under the Apache License, Version 2.0 (the "License");
+ *     you may not use this file except in compliance with the License.
+ *     You may obtain a copy of the License at
+ *
+ *          http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *     Unless required by applicable law or agreed to in writing, software
+ *     distributed under the License is distributed on an "AS IS" BASIS,
+ *     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *     See the License for the specific language governing permissions and
+ *     limitations under the License.
+ *
+ */
+
+package org.greenbuttonalliance.espi.common.domain.common;
+
+/**
+ * Enumeration of phase identifiers. Allows designation of phases for both transmission
+ * and distribution equipment, circuits and loads. Residential and small commercial loads
+ * are often served from single-phase, or split-phase, secondary circuits. Phases 1 and 2
+ * refer to hot wires that are 180 degrees out of phase, while N refers to the neutral wire.
+ * Through single-phase transformer connections, these secondary circuits may be served from
+ * one or two of the primary phases A, B, and C. For three-phase loads, use the A, B, C
+ * phase codes instead of s12N.
+ * <p>
+ * Per ESPI 4.0 XSD: PhaseCodeKind enumeration (UInt16 values).
+ */
+public enum PhaseCodeKind {
+	/**
+	 * ABC to Neutral (three-phase, four-wire).
+	 */
+	ABCN(225),
+
+	/**
+	 * Involving all phases (three-phase).
+	 */
+	ABC(224),
+
+	/**
+	 * AB to Neutral.
+	 */
+	ABN(193),
+
+	/**
+	 * Phases A, C and neutral.
+	 */
+	ACN(41),
+
+	/**
+	 * BC to neutral.
+	 */
+	BCN(97),
+
+	/**
+	 * Phases A to B.
+	 */
+	AB(132),
+
+	/**
+	 * Phases A and C.
+	 */
+	AC(96),
+
+	/**
+	 * Phases B to C.
+	 */
+	BC(66),
+
+	/**
+	 * Phases A to neutral.
+	 */
+	AN(129),
+
+	/**
+	 * Phases B to neutral.
+	 */
+	BN(65),
+
+	/**
+	 * Phases C to neutral.
+	 */
+	CN(33),
+
+	/**
+	 * Phase A.
+	 */
+	A(128),
+
+	/**
+	 * Phase B.
+	 */
+	B(64),
+
+	/**
+	 * Phase C.
+	 */
+	C(32),
+
+	/**
+	 * Neutral.
+	 */
+	N(16),
+
+	/**
+	 * Phase S2 to neutral.
+	 */
+	S2N(272),
+
+	/**
+	 * Phase S1, S2 to neutral (split-phase secondary).
+	 */
+	S12N(784),
+
+	/**
+	 * Phase S1 to Neutral.
+	 */
+	S1N(528),
+
+	/**
+	 * Phase S2.
+	 */
+	S2(256),
+
+	/**
+	 * Phase S1 to S2.
+	 */
+	S12(768),
+
+	/**
+	 * Phase S1.
+	 */
+	S1(512),
+
+	/**
+	 * Not applicable to any phase.
+	 */
+	NONE(0),
+
+	/**
+	 * Phase A current relative to Phase A voltage.
+	 */
+	A_TO_AV(136),
+
+	/**
+	 * Phase B current or voltage relative to Phase A voltage.
+	 */
+	B_AV(72),
+
+	/**
+	 * Phase C current or voltage relative to Phase A voltage.
+	 */
+	C_AV(40),
+
+	/**
+	 * Neutral to ground.
+	 */
+	NG(17);
+
+	private final Integer value;
+
+	PhaseCodeKind(Integer value) {
+		this.value = value;
+	}
+
+	public Integer getValue() {
+		return value;
+	}
+
+	/**
+	 * Converts an integer value to the corresponding PhaseCodeKind enum constant.
+	 *
+	 * @param value the integer value from XML/XSD
+	 * @return the matching enum constant, or null if not found
+	 */
+	public static PhaseCodeKind fromValue(Integer value) {
+		if (value == null) {
+			return null;
+		}
+		for (PhaseCodeKind kind : PhaseCodeKind.values()) {
+			if (kind.value.equals(value)) {
+				return kind;
+			}
+		}
+		return null;
+	}
+}

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

@@ -0,0 +1,75 @@
+/*
+ *
+ *        Copyright (c) 2025 Green Button Alliance, Inc.
+ *
+ *
+ *     Licensed under the Apache License, Version 2.0 (the "License");
+ *     you may not use this file except in compliance with the License.
+ *     You may obtain a copy of the License at
+ *
+ *          http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *     Unless required by applicable law or agreed to in writing, software
+ *     distributed under the License is distributed on an "AS IS" BASIS,
+ *     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *     See the License for the specific language governing permissions and
+ *     limitations under the License.
+ *
+ */
+
+package org.greenbuttonalliance.espi.common.domain.common;
+
+/**
+ * State of the usage point with respect to connection to the network.
+ * Per ESPI 4.0 XSD: UsagePointConnectedKind enumeration.
+ */
+public enum UsagePointConnectedKind {
+	/**
+	 * The usage point is connected to the network and able to receive or send
+	 * the applicable commodity (electricity, gas, water, etc.).
+	 */
+	CONNECTED("connected"),
+
+	/**
+	 * The usage point has been disconnected through operation of a disconnect function
+	 * within the meter present at the usage point. The usage point is unable to receive
+	 * or send the applicable commodity (electricity, gas, water, etc.). A logical
+	 * disconnect can often be achieved without utilising a field crew.
+	 */
+	LOGICALLY_DISCONNECTED("logicallyDisconnected"),
+
+	/**
+	 * The usage point has been disconnected from the network at a point upstream of the meter.
+	 * The usage point is unable to receive or send the applicable commodity (electricity,
+	 * gas, water, etc.). A physical disconnect is often achieved by utilising a field crew.
+	 */
+	PHYSICALLY_DISCONNECTED("physicallyDisconnected");
+
+	private final String value;
+
+	UsagePointConnectedKind(String value) {
+		this.value = value;
+	}
+
+	public String getValue() {
+		return value;
+	}
+
+	/**
+	 * Converts a string value to the corresponding UsagePointConnectedKind enum constant.
+	 *
+	 * @param value the string value from XML/XSD
+	 * @return the matching enum constant, or null if not found
+	 */
+	public static UsagePointConnectedKind fromValue(String value) {
+		if (value == null) {
+			return null;
+		}
+		for (UsagePointConnectedKind kind : UsagePointConnectedKind.values()) {
+			if (kind.value.equals(value)) {
+				return kind;
+			}
+		}
+		return null;
+	}
+}