Gate: Store and Use Golden Record UpdatedAt Timestamps

[nicoprow]

Required Changes

Gate Output API (bpdm-gate-api)

The nested output representation DTOs need new nullable fields to expose the golden record timestamps to API consumers:

• LegalEntityRepresentationOutputDto — add updatedAt: Instant?
• SiteRepresentationOutputDto — add updatedAt: Instant?
• AddressComponentOutputDto — add updatedAt: Instant?

These fields are distinct from the top-level updatedAt on BusinessPartnerOutputDto, which reflects when the Gate record itself was last written.

Entity (BusinessPartnerDb)

Add three nullable columns to BusinessPartnerDb to persist the golden record timestamps received from the Orchestrator:

• legalEntityUpdatedAt: Instant?
• siteUpdatedAt: Instant?
• addressUpdatedAt: Instant?

Flyway Migration

Add a new migration script (next version after V7_4_0_4) that adds the three nullable timestamp columns to the business_partners table. No backfill is required; existing rows default to null.

Mappings

Three mapping steps need to be updated to carry the timestamps through the full pipeline:

• OrchestratorMappings — read updatedAt from the Orchestrator task result's LegalEntity, Site, and PostalAddress components into OutputUpsertData
• OutputUpsertMappings — write those fields from OutputUpsertData onto the BusinessPartnerDb entity columns
• BusinessPartnerMappings — read the entity columns back into the nested representation DTOs of BusinessPartnerOutputDto

Service: Conditional Write Logic (TaskResolutionChunkService)

Before persisting an output record, compare the incoming golden record timestamps (from OutputUpsertData) against the timestamps already stored on the existing BusinessPartnerDb output record:

• If all incoming timestamps are null, always proceed with the write (backwards compatibility when the Pool does not yet populate timestamps).
• If the stored timestamps are null (first write), always proceed.
• If every non-null incoming timestamp is equal to or earlier than the corresponding stored timestamp, skip the upsert for that business partner. No new changelog entry should be created.
• If any incoming timestamp is strictly newer than the stored one, proceed with the write as normal.

---

Testing

1. Exactly One Changelog Entry Created per Sharing Cycle

New output (first-time share): Share a business partner input that has no prior output record. After the sharing cycle completes successfully, query the output changelog for that externalId. Verify that exactly one CREATED entry exists and no duplicates are present.

Existing output (re-share): Share a business partner whose output already exists. After the cycle completes, query the output changelog. Verify that exactly one new UPDATED entry was added since the previous cycle, with no duplicate UPDATED entries for the same externalId.

2. Golden Record Timestamps Surfaced in Gate Output

After a business partner input has been shared and reaches Success status:

1. Query the Gate V7 output endpoint for the business partner.
2. Verify that legalEntity.updatedAt, site.updatedAt, and address.updatedAt in the response are non-null.
3. Query the Pool for the corresponding golden record BPNs (BPNL, BPNS, BPNA).
4. Confirm that each updatedAt value in the Gate output matches the updatedAt of the corresponding Pool record exactly.