feat(android): Phase 2 people — browse, rename, confirm suggestions #1123

Merged
chris merged 2 commits from ux-android-people into main 2026-10-11 20:36:59 +02:00
Owner

What

Phase 2 people surface for the Android app (spec 055 T008) — the "family heart" screen. A browse grid of recognised faces, one person's wall with inline rename, and the confirmation strip that turns a tentative face into a named person.

Browse (Routes.PEOPLE)

  • Person cards: rounded face medallion, name or a quiet "not named yet" state, photo count.
  • Ordering follows spec 001 S3.3 scenario 22 — named people first, alphabetical and case-insensitive, then unnamed by face count desc, media count desc, then record id as a stable tiebreaker so the grid never reorders between refreshes. Computed client-side because the contract puts no order guarantee on GET /people.
  • Every cursor page is walked first (bounded, see risks) so ordering sees the whole family at once.
  • Pull-to-refresh, friendly loading/empty states.

Person detail (Routes.PERSON_DETAIL)

  • Header with face medallion + name + count, inline rename dialog, media wall straight from the embedded PersonDetailView.media (one request), tap opens the viewer.
  • PersonDetailViewModel is activity-scoped the same way SearchViewModel is, so the wall survives the trip into the viewer and back.

Suggestions

  • "Vorschläge" entry with a count badge (>0), horizontal cards reading "Ist das {Name}?" with face crop and explicit Ja/Nein buttons — no swipe gestures. One decision at a time; the next card appears only once the first lands.
  • A card with no personAssignmentId renders undecidable and says so rather than sending a decision the server cannot file (ISSUE-129). Each answer tells the grid to re-read, so a confirmation shows up below without a manual refresh.

Face crop

Client-side crop from the API's normalised {x,y,width,height} bounding box via a Coil 3.6.3 Transformation, decoding at 512px so a ~10% face region keeps real resolution after the crop. A missing or unreadable box degrades to the full thumbnail rather than a wrong region. The request must stay aspect-preserving (Scale.Fit) or the fractions land in the wrong place.

API layer

Five person-assignments calls appended as one clearly-separated additive tail block in MemoriesApi/HttpMemoriesApi, the idiom the timeline and search lanes already use:

Method Endpoint
personCards(cursor, limit) GET /api/person-assignments/people
personDetail(id) GET /api/person-assignments/people/{id}
renamePerson(id, name) POST /api/person-assignments/people/{id}/rename
tentativeAssignments() GET /api/person-assignments/tentative
decidePersonAssignments(ids, decision) POST /api/person-assignments/confirm

personCards is a wider projection than the search lane's existing people(limit) filter picker (representative face crop, face and media counts, seen-at stamps), so no search file was touched.

Payload fields found

Contract is specs/001-v1-baseline/contracts/core-api.openapi.yaml (core-api is not in this repo).

  • PeoplePage{people: PersonRecordView[], nextCursor?} — cursor is a zero-based offset string, absent on page one; limit capped at 200 server-side.
  • PersonRecordView{personRecordId, displayName, assignmentState, faceCount, mediaCount, representativeMediaItemId?, representativePreviewUrl?, representativeBoundingBox?, firstSeenAt?, lastSeenAt?}. displayName is required-but-may-be-empty; blank ⇒ unnamed.
  • PersonDetailView = PersonRecordView + {media: PersonMediaItemView[]} — media is required. The contract answers PersonDetailView | MergePeopleResponse, and the second shape (no media) therefore fails to decode into the error state rather than rendering a silently empty wall (ISSUE-127).
  • PersonMediaItemView{id, mediaType, captureTimestamp?, previewUrl?, previewStatus?} — no thumbnailUrl, no dimensions (ISSUE-126), so the wall uses the preview rendition.
  • FaceAssignmentView{faceAnnotationId, mediaItemId, boundingBox, faceState, personAssignmentId?, personRecordId?, personDisplayName?, assignmentState?, ...}
  • DecidePersonAssignmentsRequest{assignmentIds, decision: confirm|reject} — assignmentIds are personAssignmentId values.
  • RenamePersonRequest{displayName} — body carries nothing but the name.
  • boundingBox is an untyped object {x, y, width, height} normalised 0..1, decoded via a tolerant reader that answers null for any box it cannot fully read.

Testing

./gradlew :app:testDebugUnitTest — 291 tests, 0 failures (was 287 before; 4 new suites/expanders).

  • PeopleJsonTest — payload parsing incl. the tolerant face-box reader.
  • HttpPeopleApiTest — wire contract: exact paths, cursor absent on page one + limit=200, bearer header, rename body is only displayName, confirm body is ids + decision, and a MergePeopleResponse decodes as an error not an empty wall.
  • PeopleViewModelTest — ordering, empty/loading/error, unauthorized (via UnauthorizedApiException, which is a separate class from ApiHttpException(401)), and the full cursor walk.
  • PersonDetailViewModelTest — load/retry/rename flow, blank-name refusal, failed rename keeps old name.
  • SuggestionsViewModelTest — confirm/reject, one-at-a-time guard, next-card progression, undecidable card, failed answer keeps the card.

Two bugs found and fixed during verification:

  1. Cursor loop could repeat a page. The guard only checked isNullOrBlank(), so a server answering "0" → "0" walked all 5 pages and showed duplicates. Now tracks seen cursors and breaks on repetition.
  2. Two test assertions were wrong, not the code: a blank displayName is a legitimately unnamed person (FR-021h) and belongs in the unnamed list, and the "no invented name" invariant is none { isNamed && name.isBlank() } — unnamed cards do have a blank name by design.

Risks / known issues

Four entries appended to KNOWN_ISSUES.md:

  • ISSUE-126 (low) — the media wall decodes the preview rendition per tile, because PersonMediaItemView advertises no thumbnailUrl and no dimensions. Network/memory cost only; fix upstream.
  • ISSUE-127 (med) — a person opened mid-merge answers MergePeopleResponse (no media), so the detail screen shows its generic error until the merge settles. Merge UI is out of Phase 2 scope.
  • ISSUE-128 (low) — browse walks at most 5 pages of 200 (1000 people) per load so ordering can see everyone at once; a larger archive shows the first 1000 with no "more" affordance.
  • ISSUE-129 (low) — a tentative row with no personAssignmentId renders as an undecidable card; POST /confirm is keyed on assignment ids and there is no id to send.

Other risks worth a reviewer's eye:

  • assignmentIds = personAssignmentId has no in-repo client precedent; it is read off FaceAssignmentView. Worth confirming against a live server before this ships to family devices.
  • Version bump to 0.1.9 / versionCode 10 follows the per-lane convention (timeline 7/0.1.6 → search 8/0.1.7 → albums 9/0.1.8).
  • No compose-ui-test dependency exists in this project, so navigation-level behaviour (the three new routes) is not covered by the JVM suite — same limitation the search lane documented.

Scope deliberately left out

Merge suggestions UI, stash/disband, embedding map, split/move, assignment history, face markers on photos, and collaborative/shared persons. Each is a separate slice and none is needed for the family-confirmation loop.

## What Phase 2 people surface for the Android app (spec 055 T008) — the "family heart" screen. A browse grid of recognised faces, one person's wall with inline rename, and the confirmation strip that turns a tentative face into a named person. ### Browse (`Routes.PEOPLE`) - Person cards: rounded face medallion, name or a quiet "not named yet" state, photo count. - Ordering follows spec 001 S3.3 scenario 22 — named people first, alphabetical and case-insensitive, then unnamed by face count desc, media count desc, then record id as a stable tiebreaker so the grid never reorders between refreshes. Computed client-side because the contract puts no order guarantee on `GET /people`. - Every cursor page is walked first (bounded, see risks) so ordering sees the whole family at once. - Pull-to-refresh, friendly loading/empty states. ### Person detail (`Routes.PERSON_DETAIL`) - Header with face medallion + name + count, inline rename dialog, media wall straight from the embedded `PersonDetailView.media` (one request), tap opens the viewer. - `PersonDetailViewModel` is activity-scoped the same way `SearchViewModel` is, so the wall survives the trip into the viewer and back. ### Suggestions - "Vorschläge" entry with a count badge (>0), horizontal cards reading "Ist das {Name}?" with face crop and **explicit Ja/Nein buttons — no swipe gestures**. One decision at a time; the next card appears only once the first lands. - A card with no `personAssignmentId` renders undecidable and says so rather than sending a decision the server cannot file (ISSUE-129). Each answer tells the grid to re-read, so a confirmation shows up below without a manual refresh. ### Face crop Client-side crop from the API's normalised `{x,y,width,height}` bounding box via a Coil 3.6.3 `Transformation`, decoding at 512px so a ~10% face region keeps real resolution after the crop. A missing or unreadable box degrades to the full thumbnail rather than a wrong region. The request must stay aspect-preserving (`Scale.Fit`) or the fractions land in the wrong place. ### API layer Five `person-assignments` calls appended as one clearly-separated additive tail block in `MemoriesApi`/`HttpMemoriesApi`, the idiom the timeline and search lanes already use: | Method | Endpoint | | --- | --- | | `personCards(cursor, limit)` | `GET /api/person-assignments/people` | | `personDetail(id)` | `GET /api/person-assignments/people/{id}` | | `renamePerson(id, name)` | `POST /api/person-assignments/people/{id}/rename` | | `tentativeAssignments()` | `GET /api/person-assignments/tentative` | | `decidePersonAssignments(ids, decision)` | `POST /api/person-assignments/confirm` | `personCards` is a wider projection than the search lane's existing `people(limit)` filter picker (representative face crop, face and media counts, seen-at stamps), so **no search file was touched**. ## Payload fields found Contract is `specs/001-v1-baseline/contracts/core-api.openapi.yaml` (core-api is not in this repo). - `PeoplePage{people: PersonRecordView[], nextCursor?}` — `cursor` is a zero-based offset **string**, absent on page one; `limit` capped at 200 server-side. - `PersonRecordView{personRecordId, displayName, assignmentState, faceCount, mediaCount, representativeMediaItemId?, representativePreviewUrl?, representativeBoundingBox?, firstSeenAt?, lastSeenAt?}`. `displayName` is required-but-may-be-empty; blank ⇒ unnamed. - `PersonDetailView = PersonRecordView + {media: PersonMediaItemView[]}` — **`media` is required**. The contract answers `PersonDetailView | MergePeopleResponse`, and the second shape (no media) therefore fails to decode into the error state rather than rendering a silently empty wall (ISSUE-127). - `PersonMediaItemView{id, mediaType, captureTimestamp?, previewUrl?, previewStatus?}` — **no `thumbnailUrl`, no `dimensions`** (ISSUE-126), so the wall uses the preview rendition. - `FaceAssignmentView{faceAnnotationId, mediaItemId, boundingBox, faceState, personAssignmentId?, personRecordId?, personDisplayName?, assignmentState?, ...}` - `DecidePersonAssignmentsRequest{assignmentIds, decision: confirm|reject}` — `assignmentIds` are `personAssignmentId` values. - `RenamePersonRequest{displayName}` — body carries nothing but the name. - `boundingBox` is an untyped object `{x, y, width, height}` normalised 0..1, decoded via a tolerant reader that answers `null` for any box it cannot fully read. ## Testing `./gradlew :app:testDebugUnitTest` — **291 tests, 0 failures** (was 287 before; 4 new suites/expanders). - `PeopleJsonTest` — payload parsing incl. the tolerant face-box reader. - `HttpPeopleApiTest` — wire contract: exact paths, cursor absent on page one + `limit=200`, bearer header, rename body is only `displayName`, confirm body is ids + decision, and a `MergePeopleResponse` decodes as an error not an empty wall. - `PeopleViewModelTest` — ordering, empty/loading/error, unauthorized (via `UnauthorizedApiException`, which is a **separate class** from `ApiHttpException(401)`), and the full cursor walk. - `PersonDetailViewModelTest` — load/retry/rename flow, blank-name refusal, failed rename keeps old name. - `SuggestionsViewModelTest` — confirm/reject, one-at-a-time guard, next-card progression, undecidable card, failed answer keeps the card. Two bugs found and fixed during verification: 1. **Cursor loop could repeat a page.** The guard only checked `isNullOrBlank()`, so a server answering `"0" → "0"` walked all 5 pages and showed duplicates. Now tracks seen cursors and breaks on repetition. 2. **Two test assertions were wrong**, not the code: a blank `displayName` is a legitimately unnamed person (FR-021h) and belongs in the unnamed list, and the "no invented name" invariant is `none { isNamed && name.isBlank() }` — unnamed cards *do* have a blank name by design. ## Risks / known issues Four entries appended to `KNOWN_ISSUES.md`: - **ISSUE-126** (`low`) — the media wall decodes the **preview** rendition per tile, because `PersonMediaItemView` advertises no `thumbnailUrl` and no `dimensions`. Network/memory cost only; fix upstream. - **ISSUE-127** (`med`) — a person opened **mid-merge** answers `MergePeopleResponse` (no `media`), so the detail screen shows its generic error until the merge settles. Merge UI is out of Phase 2 scope. - **ISSUE-128** (`low`) — browse walks at most 5 pages of 200 (**1000 people**) per load so ordering can see everyone at once; a larger archive shows the first 1000 with no "more" affordance. - **ISSUE-129** (`low`) — a tentative row with no `personAssignmentId` renders as an undecidable card; `POST /confirm` is keyed on assignment ids and there is no id to send. Other risks worth a reviewer's eye: - **`assignmentIds` = `personAssignmentId`** has no in-repo client precedent; it is read off `FaceAssignmentView`. Worth confirming against a live server before this ships to family devices. - Version bump to **0.1.9 / versionCode 10** follows the per-lane convention (timeline 7/0.1.6 → search 8/0.1.7 → albums 9/0.1.8). - No compose-ui-test dependency exists in this project, so navigation-level behaviour (the three new routes) is not covered by the JVM suite — same limitation the search lane documented. ## Scope deliberately left out Merge suggestions UI, stash/disband, embedding map, split/move, assignment history, face markers on photos, and collaborative/shared persons. Each is a separate slice and none is needed for the family-confirmation loop.
The family's faces surface (spec 055 T008): a browse grid, one person's
wall, and the confirmation strip that turns a tentative face into a named
person.

API layer
Five person-assignments calls in the additive tail-block idiom the timeline
and search lanes already use, so a concurrent lane merges cleanly:

- personCards(cursor, limit) pages GET /people with a wider projection than
  the search lane's people(limit) filter picker (representative face crop,
  face and media counts, seen-at stamps) so no search file is touched
- personDetail / renamePerson read and write GET|POST /people/{id}[/rename]
- tentativeAssignments + decidePersonAssignments drive /tentative and /confirm

PersonDetailDto keeps media required: the contract answers PersonDetailView |
MergePeopleResponse, and the second shape (no media) then fails to decode
into the error state rather than rendering a silently empty wall.

FaceBox carries the normalised {x,y,width,height} the API reports, with a
tolerant reader that answers null for any box it cannot fully read, so the
UI falls back to an uncropped thumbnail instead of inventing a region.

Browse
Orders the way spec 001 S3.3 scenario 22 describes — named people first and
alphabetically, then unnamed by face count — computed client-side because
the contract puts no order guarantee on GET /people and a half-sorted grid
would make "where is Oma?" a hunt. Every page is walked first (bounded, see
KNOWN_ISSUES) so that ordering sees the whole family at once.

Unnamed people get no invented name anywhere (spec 001 FR-021h):
displayName blank reads as "not named yet" and the card shows a quiet state
label instead, so nobody appears to have been called something they were
not.

Suggestions
Buttons, never a swipe deck: one decision at a time, the next card waits its
turn, a stray flick cannot decide a person for a grandparent. A card with no
personAssignmentId cannot be answered and says so rather than sending a
decision the server cannot file (KNOWN_ISSUES ISSUE-129). Each answer tells
the grid to re-read, so a confirmation shows up below without a manual
refresh.

Faces
Cropped client-side from the API's normalised bounding box via a Coil
transformation, requesting a 512px decode so a ~10% face region keeps real
resolution after the crop; a missing or unreadable box degrades to the full
thumbnail rather than a wrong region.

Detail
The wall comes straight from PersonDetailView, so opening a person is one
request. PersonDetailViewModel is activity-scoped (the same way
SearchViewModel is) so the wall survives the trip into the viewer and back.

Wiring
SettingsScreen's search card becomes a shared HubCard so the new Personen
entry follows the identical pattern instead of duplicating it. Version bump
to 0.1.9 / versionCode 10, matching the per-lane convention.
test(android): people — ordering, rename, decision flow, payload and wire contracts
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 / 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 4s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m40s
c1619ac16c
Covers the four promises the people surface makes, each at the layer that can
break it.

Ordering is tested directly against orderPeople (named first, alphabetical and
case-insensitive, then unnamed by face count with the record id as a stable
tiebreaker) and again through the ViewModel, including the cursor walk that
lets ordering see every page — and the repeated-cursor case that must stop
rather than spin.

Rename asserts the server's answer is adopted wholesale, that a blank name is
refused instead of quietly un-naming someone, and that a failed rename leaves
the old name and the dialog intact.

The decision flow asserts one answer at a time: a second confirm while the
first is out is ignored rather than queued, the next card appears only once the
first lands, a card with no assignment id sends nothing and stays put
(ISSUE-129), and a failed answer keeps the card for a retry.

The 401 cases use UnauthorizedApiException rather than ApiHttpException(401) —
the two are separate classes and only the first reaches the unauthorized branch.

The wire test pins the exact paths and bodies (cursor absent on page one, limit
200, rename carries only displayName, confirm carries the assignment ids plus
the decision), and checks that a MergePeopleResponse decodes as an error
instead of an empty wall.

KNOWN_ISSUES gains ISSUE-126 through ISSUE-129: the media wall decodes the
preview rendition because PersonMediaItemView advertises no thumbnailUrl, a
person opened mid-merge answers MergePeopleResponse and shows the generic
error until the merge settles, the grid walks at most 5 pages of 200, and a
tentative row with no personAssignmentId renders as an undecidable card.
chris merged commit 2c1c42be54 into main 2026-10-11 20:36:59 +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!1123
No description provided.