feat(api): self person claim + profile photo endpoints (spec 057 backend) #1158

Merged
chris merged 4 commits from feat/057-self-person-backend into main 2026-10-12 20:18:02 +02:00
Owner

Spec 057 backend lane (S057T001-T003).

What

  • V159__self_persons.sql: self_persons table — PK user_account_id ON DELETE CASCADE, UNIQUE class_instance_id ON DELETE CASCADE, profile_media_item_id FK SET NULL, crop columns DOUBLE PRECISION with 0..1 CHECK, created/updated_at.
  • SelfPersonService (JdbcClient, session auth): view / claim / unlink / setProfilePhoto / profilePhotoFile / claimsFor. Claim upsert is deliberately non-transactional so 409 conflict diagnostics (claimedByDisplayName) can run after a constraint failure.
  • SelfPersonController: GET/PUT/DELETE /api/profile/self-person, PUT/GET /api/profile/self-person/photo — 404 invisible instance, 409 CONFLICT with claimedByDisplayName, 422 media not in person occurrences, 400 invalid crop (0..1, x+size<=1, y+size<=1), size clamp {256,512}; photo serve reads derived_assets (derived_type=profile_photo, variant=size) as image/jpeg with ETag + 365d immutable cache + Vary: Cookie.
  • ApiExceptionHandler: SelfPersonClaimedException -> 409 ProblemDetail, SelfPersonPhotoMediaException -> 422; existing 404/400 handlers cover NoSuchElement/IllegalArgument.
  • selfPersonClaim {state: none|self|other, claimedByDisplayName?} attached on the people class-instances read path via batch claimsFor lookup (null = not computed -> client treats as none).
  • Pinned worker contract: job type profile_photo_crop, payload keys exactly mediaItemId, cropX, cropY, cropSize, generationVersion; enqueue + result ingestion with current-generation gating (stale results dropped) and multi-variant completion.

Verification

  • rtk ./gradlew :apps:api:test full suite: BUILD SUCCESSFUL, tests=1909 failures=0 errors=0 skipped=9.
  • Post-rebase targeted rerun of the 5 new test classes: 41 tests, 0 failures, 0 errors (Migration 3, Service/Postgres 14, Controller 13, Discovery claim 4, Result acceptance 7).

Notes

  • No live single-person GET endpoint exists, so S057T003 is attached to the people class-instance list read path rather than a detail endpoint.
  • Out of scope: web getPersonDetail -> GET /api/discovery/domains/people/class-instances/{id} has no api mapping (web TODO in DiscoveryInstanceDetail.svelte).
Spec 057 backend lane (S057T001-T003). ## What - **V159__self_persons.sql**: self_persons table — PK user_account_id ON DELETE CASCADE, UNIQUE class_instance_id ON DELETE CASCADE, profile_media_item_id FK SET NULL, crop columns DOUBLE PRECISION with 0..1 CHECK, created/updated_at. - **SelfPersonService** (JdbcClient, session auth): view / claim / unlink / setProfilePhoto / profilePhotoFile / claimsFor. Claim upsert is deliberately non-transactional so 409 conflict diagnostics (claimedByDisplayName) can run after a constraint failure. - **SelfPersonController**: GET/PUT/DELETE `/api/profile/self-person`, PUT/GET `/api/profile/self-person/photo` — 404 invisible instance, 409 CONFLICT with claimedByDisplayName, 422 media not in person occurrences, 400 invalid crop (0..1, x+size<=1, y+size<=1), size clamp {256,512}; photo serve reads derived_assets (derived_type=profile_photo, variant=size) as image/jpeg with ETag + 365d immutable cache + Vary: Cookie. - **ApiExceptionHandler**: SelfPersonClaimedException -> 409 ProblemDetail, SelfPersonPhotoMediaException -> 422; existing 404/400 handlers cover NoSuchElement/IllegalArgument. - **selfPersonClaim** `{state: none|self|other, claimedByDisplayName?}` attached on the people class-instances read path via batch claimsFor lookup (null = not computed -> client treats as none). - **Pinned worker contract**: job type `profile_photo_crop`, payload keys exactly `mediaItemId, cropX, cropY, cropSize, generationVersion`; enqueue + result ingestion with current-generation gating (stale results dropped) and multi-variant completion. ## Verification - `rtk ./gradlew :apps:api:test` full suite: **BUILD SUCCESSFUL, tests=1909 failures=0 errors=0 skipped=9**. - Post-rebase targeted rerun of the 5 new test classes: **41 tests, 0 failures, 0 errors** (Migration 3, Service/Postgres 14, Controller 13, Discovery claim 4, Result acceptance 7). ## Notes - No live single-person GET endpoint exists, so S057T003 is attached to the people class-instance list read path rather than a detail endpoint. - Out of scope: web `getPersonDetail` -> `GET /api/discovery/domains/people/class-instances/{id}` has no api mapping (web TODO in DiscoveryInstanceDetail.svelte).
feat(api): self person claim and profile photo endpoints (spec 057 backend)
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 3s
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 1m54s
e5c80e112d
- V159__self_persons.sql: self_persons table (PK user_account_id CASCADE,
  UNIQUE class_instance_id, profile_media_item_id SET NULL, crop 0..1 CHECK)
- SelfPersonService: view/claim/unlink/setProfilePhoto/profilePhotoFile/claimsFor
- SelfPersonController: GET/PUT/DELETE /api/profile/self-person,
  PUT/GET /api/profile/self-person/photo (derived_assets profile_photo serve,
  size clamp 256/512, ETag + immutable cache)
- ApiExceptionHandler: 409 SelfPersonClaimedException (claimedByDisplayName),
  422 SelfPersonPhotoMediaException
- selfPersonClaim {state, claimedByDisplayName?} attached on the people
  class-instance read path via batch claimsFor lookup
- profile_photo_crop job enqueue + worker result ingestion (pinned contract:
  payload keys mediaItemId/cropX/cropY/cropSize/generationVersion), current
  generation gating, stale results dropped
- tests: migration, service (Postgres), controller, claim attachment,
  result acceptance
fix(api): align self person photo ingestion with worker protocol (spec 057 follow-ups)
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 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build postgres image (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 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 1m56s
73b9e0c263
Follow-up alignment with the worker lane (PR #1149) and cross-lane review:

- WorkerResultService: honor the payload 'complete' flag (absent=true) for
  derived_asset results so the 512 variant is not rejected after the 256
  result completed the job; route derived_asset results with
  derivedType=profile_photo through the profile-photo promoter so the
  current-generation gate applies to the real worker protocol (the
  profile_photo_crop/profile_photo result-type alias stays accepted).
- V160__profile_photo_crop_ml_worker_capability.sql: grant profile_photo_crop
  to the ML/media worker credential via array_cat (V084/V095 precedent) so
  existing installs and restores can lease the job; WorkerCredentialBootstrap
  ML_JOB_TYPES already lists the type.
- Crop validation is width-anchored (x=left/W, y=top/H, size=side/W):
  x+size<=1 always (dimension-free), y+size*W/H<=1 when the media dimensions
  are known. The old y+size<=1 check 400'd valid portrait crops (e.g.
  y=0.25,size=1.0 on 3000x4000) and accepted overflowing landscape crops
  (y=0.3,size=0.7 on 4000x3000). Unknown dimensions skip the
  aspect-dependent bound; the worker clamps the window into the raster.
- GET photo already selects the current generation_version and superseded
  generation rows stay in derived_assets (supersede, old rows kept — now
  asserted in tests).

Tests: width-anchored fit (portrait accept, landscape reject, unknown-dims
fallback), derived_asset complete-flag protocol, generation gating via the
derived_asset route, generic derived_asset routing unchanged, V160 content.
fix(deploy): advertise profile_photo_crop on the media worker capabilities
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 5s
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 6m57s
d4bfe8c164
The compose MEMORIES_WORKER_CAPABILITIES for memories-worker-media overrides
the worker-media application.yml default, so the deployed worker never
advertised profile_photo_crop — the job type added by V160/ML_JOB_TYPES and
PR #1149 could never be leased. Insert it before video_preview to match the
application.yml default and WorkerProperties ordering.
chris merged commit 8a47c8bb95 into main 2026-10-12 20:18:02 +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!1158
No description provided.