feat(api): manual face bbox create + scope update endpoints #1161

Merged
chris merged 1 commit from feature/manual-face-bbox-backend into main 2026-10-12 21:24:26 +02:00
Owner

Backend half of the manual face bbox feature. Spec: `docs/superpowers/specs/2026-10-12-manual-face-bbox-design.md` (Backend + Decisions sections).

Endpoints (contract pinned with the frontend lane)

  1. POST `/api/media/{mediaItemId}/discovery/faces` — body `{"scope": {"x","y","width","height"}}` (normalized 0..1). Creates a manual face via the revived `ClassInstanceService.createFaceAnnotation` (now the real create path, deprecation dropped): `domain_key='people'`, `input_version='manual'`, `confidence NULL`, `worker_job_id NULL`, fresh-UUID idempotency key (`"manual-"+id`, no cross-request collision). Returns 200 with the `OccurrenceAssignmentView` shape incl. `"manual": true` (unassigned: LEFT JOIN occurrences → null assignment fields).
  2. PATCH `/api/discovery/faces/{faceAnnotationId}/scope` — body same shape. Updates `discovery_results.scope` only when `input_version='manual'`. 200 updated `OccurrenceAssignmentView`; 409 `IllegalStateException` when the face is auto-detected or terminally gone (rejected/superseded — the stale-face-list case from the spec's error handling); 404 `NoSuchElementException` for unknown ids; 403 for foreign faces (existing face-endpoint pattern via `requireOwner`).
  3. Validation (create + PATCH, at controller request boundary and as the canonical service-level guard): finite numbers only, `x,y >= 0`, `width,height in [0.05, 1]`, `x+width <= 1`, `y+height <= 1` → else `IllegalArgumentException` → 400 ProblemDetail via `ApiExceptionHandler` (project's usual error shape).
  4. `manual: boolean` added (last component) to `OccurrenceAssignmentView`, derived from `input_version = 'manual'`; `dr.input_version` selected in both queries feeding the row mapper (`facesForMedia`, `faceAssignment`).

Design choices

  • `state='accepted'` for fresh manual faces, NOT `owner_tentative`: `owner_tentative` drives the recognition scheduler / face-crop backfill pipeline (`PeopleDiscoveryRecognitionScheduler`, `FaceCropBackfillScheduler`), which is exactly the worker/embedding interaction the spec puts out of scope. `accepted` unassigned faces list in `facesForMedia` and stay assignable through the unchanged assign flow.
  • No face-recognition dirty mark on create or scope update: scope-only edits never change embeddings, and a manual face carries no embedding, so a dirty mark would at best be a no-op re-match trigger. `markDirty` stays where it belongs — in the assign/name/unassign flows (unchanged).
  • Dedup interplay (`deduplicateOverlappingFaces`, IoU ≥ 0.90): a manual face overlapping a detection is deduplicated on read exactly like worker overlaps; the create response uses `faceAssignment` (single-face query) so it is never swallowed.

Tests

`ClassInstanceServiceTest` (H2-backed, real SQL):

  • `facesForMediaExposesManualFlagForManualAndWorkerRows` — manual=true for `input_version='manual'`, false for worker rows (new fixture overload with configurable `input_version`)
  • `createManualFacePersistsUnassignedManualRowAndReturnsView` — view shape + DB row (manual pattern, confidence/worker_job_id NULL) + listing visibility + no dirty mark
  • `createManualFaceRejectsInvalidScope` — full validation matrix incl. inclusive boundary acceptance
  • `updateManualFaceScopeMovesManualBox` — persists + reflects in listing, no dirty mark
  • `updateManualFaceScopeRejectsWorkerFacesAndInvalidScopes` — 409 + untouched scope
  • `updateManualFaceScopeUnknownOrTerminallyGoneFacesAreConflictsOrNotFound` — 404 / 409 / 403

`DiscoveryControllerTest` (Mockito, existing pattern): create delegation + manual=true passthrough; PATCH delegation; 409/404 propagation; invalid scope rejected at the controller before delegation (real validation code, service never touched). The 3 pre-existing `OccurrenceAssignmentView` constructions updated for the new `manual` component.

Verification

```
rtk ./gradlew :apps:api:test --tests 'DiscoveryControllerTest' --tests 'ClassInstanceServiceTest' → BUILD SUCCESSFUL (13 new tests, all green)
rtk ./gradlew :apps:api:test → BUILD SUCCESSFUL (1928 tests, 0 failures/errors)
```

Backend half of the manual face bbox feature. Spec: \`docs/superpowers/specs/2026-10-12-manual-face-bbox-design.md\` (Backend + Decisions sections). ## Endpoints (contract pinned with the frontend lane) 1. **POST \`/api/media/{mediaItemId}/discovery/faces\`** — body \`{"scope": {"x","y","width","height"}}\` (normalized 0..1). Creates a manual face via the revived \`ClassInstanceService.createFaceAnnotation\` (now the real create path, deprecation dropped): \`domain_key='people'\`, \`input_version='manual'\`, \`confidence NULL\`, \`worker_job_id NULL\`, fresh-UUID idempotency key (\`"manual-"+id\`, no cross-request collision). Returns **200** with the \`OccurrenceAssignmentView\` shape incl. \`"manual": true\` (unassigned: LEFT JOIN occurrences → null assignment fields). 2. **PATCH \`/api/discovery/faces/{faceAnnotationId}/scope\`** — body same shape. Updates \`discovery_results.scope\` only when \`input_version='manual'\`. **200** updated \`OccurrenceAssignmentView\`; **409** \`IllegalStateException\` when the face is auto-detected or terminally gone (rejected/superseded — the stale-face-list case from the spec's error handling); **404** \`NoSuchElementException\` for unknown ids; **403** for foreign faces (existing face-endpoint pattern via \`requireOwner\`). 3. **Validation** (create + PATCH, at controller request boundary and as the canonical service-level guard): finite numbers only, \`x,y >= 0\`, \`width,height in [0.05, 1]\`, \`x+width <= 1\`, \`y+height <= 1\` → else \`IllegalArgumentException\` → 400 ProblemDetail via \`ApiExceptionHandler\` (project's usual error shape). 4. **\`manual: boolean\`** added (last component) to \`OccurrenceAssignmentView\`, derived from \`input_version = 'manual'\`; \`dr.input_version\` selected in both queries feeding the row mapper (\`facesForMedia\`, \`faceAssignment\`). ## Design choices - **\`state='accepted'\` for fresh manual faces**, NOT \`owner_tentative\`: \`owner_tentative\` drives the recognition scheduler / face-crop backfill pipeline (\`PeopleDiscoveryRecognitionScheduler\`, \`FaceCropBackfillScheduler\`), which is exactly the worker/embedding interaction the spec puts out of scope. \`accepted\` unassigned faces list in \`facesForMedia\` and stay assignable through the unchanged assign flow. - **No face-recognition dirty mark** on create or scope update: scope-only edits never change embeddings, and a manual face carries no embedding, so a dirty mark would at best be a no-op re-match trigger. \`markDirty\` stays where it belongs — in the assign/name/unassign flows (unchanged). - Dedup interplay (\`deduplicateOverlappingFaces\`, IoU ≥ 0.90): a manual face overlapping a detection is deduplicated on read exactly like worker overlaps; the create response uses \`faceAssignment\` (single-face query) so it is never swallowed. ## Tests \`ClassInstanceServiceTest\` (H2-backed, real SQL): - \`facesForMediaExposesManualFlagForManualAndWorkerRows\` — manual=true for \`input_version='manual'\`, false for worker rows (new fixture overload with configurable \`input_version\`) - \`createManualFacePersistsUnassignedManualRowAndReturnsView\` — view shape + DB row (manual pattern, confidence/worker_job_id NULL) + listing visibility + no dirty mark - \`createManualFaceRejectsInvalidScope\` — full validation matrix incl. inclusive boundary acceptance - \`updateManualFaceScopeMovesManualBox\` — persists + reflects in listing, no dirty mark - \`updateManualFaceScopeRejectsWorkerFacesAndInvalidScopes\` — 409 + untouched scope - \`updateManualFaceScopeUnknownOrTerminallyGoneFacesAreConflictsOrNotFound\` — 404 / 409 / 403 \`DiscoveryControllerTest\` (Mockito, existing pattern): create delegation + manual=true passthrough; PATCH delegation; 409/404 propagation; invalid scope rejected at the controller before delegation (real validation code, service never touched). The 3 pre-existing \`OccurrenceAssignmentView\` constructions updated for the new \`manual\` component. ## Verification \`\`\` rtk ./gradlew :apps:api:test --tests '*DiscoveryControllerTest*' --tests '*ClassInstanceServiceTest*' → BUILD SUCCESSFUL (13 new tests, all green) rtk ./gradlew :apps:api:test → BUILD SUCCESSFUL (1928 tests, 0 failures/errors) \`\`\`
feat(api): manual face bbox create + scope update endpoints
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
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 / 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
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 7m4s
c076fd68cc
- POST /api/media/{mediaItemId}/discovery/faces — creates a manual face
  (input_version='manual', confidence/worker_job_id NULL, state='accepted'),
  returns OccurrenceAssignmentView with manual=true
- PATCH /api/discovery/faces/{faceAnnotationId}/scope — updates scope of
  manual faces only; 404 unknown, 409 non-manual/terminally-gone, 403 foreign
- validateManualFaceScope: finite numbers, x,y >= 0, width,height in [0.05,1],
  x+width <= 1, y+height <= 1 (IllegalArgumentException -> 400 ProblemDetail)
- OccurrenceAssignmentView gains manual flag derived from input_version
- Revives ClassInstanceService.createFaceAnnotation as the real create path

Spec: docs/superpowers/specs/2026-10-12-manual-face-bbox-design.md
chris merged commit 4f71a4f49d into main 2026-10-12 21:24:26 +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!1161
No description provided.