refactor(common): subscription↔authorization N:1, authorization as aggregate root (#122 PR B1)

[dfcoffin]

PR B1 — subscription↔authorization N:1 rework (Authorization as aggregate root)

First half of the #122 "PR B" split (B1 = schema + entity rework; B2 = the subscription-create back-channel endpoint that consumes this). Pure refactor — no new endpoint, no behavior change to request handling.

Why

The ESPI grant model produces two subscriptions per authorization: an Energy subscription (keyed to authorizations.resource_uri) and, when the grant includes Customer/PII scope, a Customer subscription (keyed to authorizations.customer_resource_uri). The old @OneToOne could not represent that. The authorization is the aggregate root; a subscription has no independent lifecycle — it is created and removed only through its authorization.

Relationship

• SubscriptionEntity.authorization: @OneToOne → @ManyToOne, NOT NULL, cascade DETACH (owning side; FK subscriptions.authorization_id).
• AuthorizationEntity: @OneToOne subscription → @OneToMany subscriptions (mappedBy, cascade=ALL, orphanRemoval=true).

This enforces the agreed lifecycle invariants:

1. Removed authorization ⇒ its subscriptions removed — JPA cascade=ALL + orphanRemoval and DB ON DELETE CASCADE.
2. A subscription is never added/removed independently — only through the authorization aggregate.
3. Revoking Customer/PII access removes only the customerResourceURI subscription — drop that child from the collection; orphanRemoval deletes it; the energy subscription stays. (customer_resource_uri stays nullable: an authorization has 1 or 2 subscriptions.)

Migration (edit-in-place, vendor-neutral db/migration)

• Dropped authorizations.subscription_id + FK fk_authorization_subscription (the back-reference that blocked N:1).
• subscriptions.authorization_id → NOT NULL + FK → authorizations.id ON DELETE CASCADE (was index-only).
• The 3-DB TestContainers integration run (MySQL/PostgreSQL/H2) is the safety net for vendor divergence.

Consequent code

• findByAuthorization_Id / findByAuthorizationId: Optional → List.
• NotificationServiceImpl iterates each authorization's subscriptions.
• AuthorizationServiceImpl.createAuthorizationEntity sets the owning side and maintains both directions.
• AuthorizationMapper ignores the subscriptions collection (aggregate children).
• ResourceValidationFilter matches the requested {subscriptionId} against the authorization's subscription collection (removed a dead local var).

Tests

• New N:1 test: two subscriptions (energy + customer/PII) backed by one authorization, both found via findByAuthorization_Id.
• createValidSubscription() now attaches a required authorization; fixed three tests that assumed a nullable authorization (one repurposed to the bare-entity isActive() null branch).
• Full openespi-common suite green (SubscriptionRepositoryTest 24/24; zero failures/errors across all module reports).

Known follow-up (not this PR)

Customer/PII access has no independent revocation trigger yet — the consent-withdrawal-vs-token-revocation lifecycle gap. B1 makes the mechanism correct (CASCADE/orphanRemoval); the policy/trigger is deferred. I can file a tracking issue.

Refs #122. Depends on nothing; PR B2 (subscription-create endpoint) builds on this.

🤖 Generated with Claude Code