feat(api): decision endpoint honors selectedOccurrenceRefs subset #1007

Merged
chris merged 1 commit from feat/decision-subset-refs into main 2026-10-03 19:16:00 +02:00
Owner

Zusammenfassung

POST /api/discovery/class-instance-candidates/{id}/decision akzeptiert optional selectedOccurrenceRefs (List<String> | null), damit der Suggestion-Carousel-Merge-Dialog nur eine von der Card ausgewählte Teilmenge der Bilder auf eine Zielperson anwendet.

  • null/abwesend = exaktes Legacy-Verhalten (alle Refs, alle bestehenden Aufrufe unverändert)
  • Nicht-leeres Array = nur diese Refs werden geschrieben; nur bei decision:"accepted" mit existingInstanceId und createNewInstance (Feld anwesend; Legacy-Signal details.createdAsNew wird ebenfalls akzeptiert)
  • Leeres Array, leere Refs, Refs die nicht in occurrence_refs der Candidate stehen, Subset ohne Ziel/Flag, oder Subset bei jedem nicht-accepted-Entscheid (inkl. Stash) → 400
  • Strenges Subset: ausgewählte Refs bekommen Occurrence-Writes (allowMove=true unverändert), die Candidate bleibt pending mit geschrumpften occurrence_refs (Rest-Card erscheint erneut), Response outcome:"subset_applied"
  • Vollständige Auswahl (alle Refs) → degeneriert auf exakten Legacy-Accept (state:"accepted", outcome:"applied")

Semantik-Begründung

  • Parity-Variante A: snapshot/lockedSnapshot bleiben vollständig — der 409-Fix-Vergleich (PR #1005) liest weiterhin die kompletten Ref-Setze; gefiltert werden nur die Writes. Ein veraltetes Subset, das nicht mehr in die gelockte Zeile passt, schlägt wie ein Parity-Miss fehl (keine Writes → 409-Pfad), nie ein Ref das die Candidate nicht trägt.
  • Stash-Pfad: Subset-Feld wird dort nicht gesendet; es wird kontrakt-konform mit 400 abgelehnt (stillschweigend anwenden oder ignorieren wäre beides falsch).
  • afterAcceptance: erhält für Subset-Erwartungen eine lokal eingeschränkte Snapshot-Kopie, damit nur die angewendeten Refs in discovery_results.state='accepted' landen (Rest-Refes bleiben owner_tentative).
  • Overlap-Cleanup wird für Subset übersprungen (Kompetitoren beziehen sich auf die volle Card; die Rest-Card bleibt handlungsfähig); Review-Decision-Details tragen partialSubset/selectedOccurrences/remainingOccurrences (Owner-Audit bleibt wahrheitsgemäß).
  • DisplayName-Guard entschärft nur wenn existingInstanceId gesetzt ist: dort gewinnt das explizite Ziel über die Neuperson-Erzeugung (Merge-Semantik) — sonst würde der vertraglich geforderte Triple accepted + existingInstanceId + createNewInstance ohne Namen mit 400 scheitern.
  • Ref-Matching (lässig): akzeptierte Formen: type:id (kanonisch), bare kanonische id, rohe faceAnnotationId/occurrenceId/occurrenceKey; mediaItemId bewusst nicht (mehrere Refs pro Bild).
  • Nebenfix: Der Accept-Unit-Copy der Candidate-Zeile hinkte ein LinkedHashMap-Copy auf H2 (Großbuchstaben-Spaltenlabels) — candidate_id+Provenance wurden NULL geschrieben. Jetzt LinkedCaseInsensitiveMap (PG-Verhalten unverändert, H2-Latentfehler behoben u. a. auch für filterAssignedRefs-Pfade).

Tests

  • Neu in ClassInstanceDiscoveryServiceTest (4 Fälle):
    • subsetAcceptWritesOnlySelectedRefsAndKeepsCandidatePendingWithRemainder (inkl. Rest-Card-Entscheid im Legacy-Nachlauf)
    • subsetAcceptWithAllRefsOrWithoutFieldKeepsLegacyBehavior (explizit vollständige Liste + abwesendes Feld)
    • subsetValidationRejectsEmptyUnknownAndUnsupportedRequests (leer/unbekannt/blank/Stash/ohne Ziel/ohne Flag → 400, keine Writes)
    • subsetAcceptWithCreateNewInstanceStillMergesIntoExplicitTarget (Ziel gewinnt, keine neue Person, type:id-Form)
  • rtk ./gradlew :apps:api:test grün: 139 Testklassen, 1503 Tests, 0 Failures/Errors
  • OpenAPI-Contract (specs/001-v1-baseline/contracts/core-api.openapi.yaml) um selectedOccurrenceRefs, existingInstanceId, createNewInstance (Request) und outcome (Result) ergänzt; specs/037/047 dokumentieren dieses Request/Response-Verhalten nicht (unverändert)

Abweichungen / Hinweise

  • Response-Kontrakt: Teilmenge → state:"accepted" + outcome:"subset_applied" (applied/all_faces_already_assigned unverändert). Frontend liest die Decision-Response nicht aus (geprüft) — geringes Risiko.
  • createNewInstance wird als Anwesenheit (non-null) gelesen, nicht als Wahrheitswert — false ist zulässig und entspricht dem Merge-Flow.
## Zusammenfassung `POST /api/discovery/class-instance-candidates/{id}/decision` akzeptiert optional `selectedOccurrenceRefs` (`List<String>` | null), damit der Suggestion-Carousel-Merge-Dialog nur eine von der Card ausgewählte Teilmenge der Bilder auf eine Zielperson anwendet. - `null`/abwesend = exaktes Legacy-Verhalten (alle Refs, alle bestehenden Aufrufe unverändert) - Nicht-leeres Array = nur diese Refs werden geschrieben; **nur** bei `decision:"accepted"` mit `existingInstanceId` **und** `createNewInstance` (Feld anwesend; Legacy-Signal `details.createdAsNew` wird ebenfalls akzeptiert) - Leeres Array, leere Refs, Refs die nicht in `occurrence_refs` der Candidate stehen, Subset ohne Ziel/Flag, oder Subset bei jedem nicht-`accepted`-Entscheid (inkl. Stash) → **400** - Strenges Subset: ausgewählte Refs bekommen Occurrence-Writes (`allowMove=true` unverändert), die Candidate bleibt `pending` mit geschrumpften `occurrence_refs` (Rest-Card erscheint erneut), Response `outcome:"subset_applied"` - Vollständige Auswahl (alle Refs) → degeneriert auf exakten Legacy-Accept (`state:"accepted"`, `outcome:"applied"`) ### Semantik-Begründung - **Parity-Variante A:** `snapshot`/`lockedSnapshot` bleiben vollständig — der 409-Fix-Vergleich (PR #1005) liest weiterhin die kompletten Ref-Setze; gefiltert werden **nur die Writes**. Ein veraltetes Subset, das nicht mehr in die gelockte Zeile passt, schlägt wie ein Parity-Miss fehl (keine Writes → 409-Pfad), nie ein Ref das die Candidate nicht trägt. - **Stash-Pfad:** Subset-Feld wird dort nicht gesendet; es wird kontrakt-konform mit 400 abgelehnt (stillschweigend anwenden *oder* ignorieren wäre beides falsch). - **`afterAcceptance`:** erhält für Subset-Erwartungen eine lokal eingeschränkte Snapshot-Kopie, damit nur die angewendeten Refs in `discovery_results.state='accepted'` landen (Rest-Refes bleiben `owner_tentative`). - **Overlap-Cleanup** wird für Subset übersprungen (Kompetitoren beziehen sich auf die volle Card; die Rest-Card bleibt handlungsfähig); Review-Decision-Details tragen `partialSubset`/`selectedOccurrences`/`remainingOccurrences` (Owner-Audit bleibt wahrheitsgemäß). - **DisplayName-Guard entschärft** nur wenn `existingInstanceId` gesetzt ist: dort gewinnt das explizite Ziel über die Neuperson-Erzeugung (Merge-Semantik) — sonst würde der vertraglich geforderte Triple `accepted + existingInstanceId + createNewInstance` ohne Namen mit 400 scheitern. - **Ref-Matching (lässig):** akzeptierte Formen: `type:id` (kanonisch), bare kanonische id, rohe `faceAnnotationId`/`occurrenceId`/`occurrenceKey`; `mediaItemId` bewusst **nicht** (mehrere Refs pro Bild). - **Nebenfix:** Der Accept-Unit-Copy der Candidate-Zeile hinkte ein `LinkedHashMap`-Copy auf H2 (Großbuchstaben-Spaltenlabels) — `candidate_id`+Provenance wurden NULL geschrieben. Jetzt `LinkedCaseInsensitiveMap` (PG-Verhalten unverändert, H2-Latentfehler behoben u. a. auch für `filterAssignedRefs`-Pfade). ## Tests - Neu in `ClassInstanceDiscoveryServiceTest` (4 Fälle): - `subsetAcceptWritesOnlySelectedRefsAndKeepsCandidatePendingWithRemainder` (inkl. Rest-Card-Entscheid im Legacy-Nachlauf) - `subsetAcceptWithAllRefsOrWithoutFieldKeepsLegacyBehavior` (explizit vollständige Liste + abwesendes Feld) - `subsetValidationRejectsEmptyUnknownAndUnsupportedRequests` (leer/unbekannt/blank/Stash/ohne Ziel/ohne Flag → 400, keine Writes) - `subsetAcceptWithCreateNewInstanceStillMergesIntoExplicitTarget` (Ziel gewinnt, keine neue Person, `type:id`-Form) - `rtk ./gradlew :apps:api:test` **grün**: 139 Testklassen, 1503 Tests, 0 Failures/Errors - OpenAPI-Contract (`specs/001-v1-baseline/contracts/core-api.openapi.yaml`) um `selectedOccurrenceRefs`, `existingInstanceId`, `createNewInstance` (Request) und `outcome` (Result) ergänzt; `specs/037/047` dokumentieren dieses Request/Response-Verhalten nicht (unverändert) ## Abweichungen / Hinweise - Response-Kontrakt: Teilmenge → `state:"accepted"` + `outcome:"subset_applied"` (`applied`/`all_faces_already_assigned` unverändert). Frontend liest die Decision-Response nicht aus (geprüft) — geringes Risiko. - `createNewInstance` wird als *Anwesenheit* (non-null) gelesen, nicht als Wahrheitswert — `false` ist zulässig und entspricht dem Merge-Flow.
feat(api): decision endpoint honors selectedOccurrenceRefs subset
All checks were successful
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 4s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 6m59s
843dddbb26
POST /api/discovery/class-instance-candidates/{id}/decision accepts an
optional selectedOccurrenceRefs list so the Suggestion-Carousel Merge
dialog can apply only a chosen subset of a candidate's images to a
target person.

Contract:
- absent/null -> exact legacy all-refs behavior (all existing callers)
- non-empty subset only for decision=accepted with existingInstanceId
  AND createNewInstance present; empty array, blank refs, refs not
  belonging to the candidate, or any non-accepted decision -> 400
- strict subset: selected refs get occurrence writes, candidate stays
  pending with the remainder (state=pending, occurrence_refs shrunk),
  response outcome=subset_applied
- full selection -> degrades to legacy accept (state=accepted)

Parity/locking (PR #1005) unchanged: snapshot/lockedSnapshot stay
complete, only the applied writes are filtered; a stale override fails
like a parity miss (no writes, 409 path).

Also fixes candidate_id/provenance written NULL when the accept unit
copies the candidate row on H2 (plain LinkedHashMap copy drops
Spring's case-insensitive row keys).
chris merged commit feb3a4f21c into main 2026-10-03 19:16:00 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1007
No description provided.