feat(android): Phase 2 people — browse, rename, confirm suggestions #1123
Loading…
Reference in a new issue
No description provided.
Delete branch "ux-android-people"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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)GET /people.Person detail (
Routes.PERSON_DETAIL)PersonDetailView.media(one request), tap opens the viewer.PersonDetailViewModelis activity-scoped the same waySearchViewModelis, so the wall survives the trip into the viewer and back.Suggestions
personAssignmentIdrenders 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.3Transformation, 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-assignmentscalls appended as one clearly-separated additive tail block inMemoriesApi/HttpMemoriesApi, the idiom the timeline and search lanes already use:personCards(cursor, limit)GET /api/person-assignments/peoplepersonDetail(id)GET /api/person-assignments/people/{id}renamePerson(id, name)POST /api/person-assignments/people/{id}/renametentativeAssignments()GET /api/person-assignments/tentativedecidePersonAssignments(ids, decision)POST /api/person-assignments/confirmpersonCardsis a wider projection than the search lane's existingpeople(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?}—cursoris a zero-based offset string, absent on page one;limitcapped at 200 server-side.PersonRecordView{personRecordId, displayName, assignmentState, faceCount, mediaCount, representativeMediaItemId?, representativePreviewUrl?, representativeBoundingBox?, firstSeenAt?, lastSeenAt?}.displayNameis required-but-may-be-empty; blank ⇒ unnamed.PersonDetailView = PersonRecordView + {media: PersonMediaItemView[]}—mediais required. The contract answersPersonDetailView | 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?}— nothumbnailUrl, nodimensions(ISSUE-126), so the wall uses the preview rendition.FaceAssignmentView{faceAnnotationId, mediaItemId, boundingBox, faceState, personAssignmentId?, personRecordId?, personDisplayName?, assignmentState?, ...}DecidePersonAssignmentsRequest{assignmentIds, decision: confirm|reject}—assignmentIdsarepersonAssignmentIdvalues.RenamePersonRequest{displayName}— body carries nothing but the name.boundingBoxis an untyped object{x, y, width, height}normalised 0..1, decoded via a tolerant reader that answersnullfor 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 onlydisplayName, confirm body is ids + decision, and aMergePeopleResponsedecodes as an error not an empty wall.PeopleViewModelTest— ordering, empty/loading/error, unauthorized (viaUnauthorizedApiException, which is a separate class fromApiHttpException(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:
isNullOrBlank(), so a server answering"0" → "0"walked all 5 pages and showed duplicates. Now tracks seen cursors and breaks on repetition.displayNameis a legitimately unnamed person (FR-021h) and belongs in the unnamed list, and the "no invented name" invariant isnone { isNamed && name.isBlank() }— unnamed cards do have a blank name by design.Risks / known issues
Four entries appended to
KNOWN_ISSUES.md:low) — the media wall decodes the preview rendition per tile, becausePersonMediaItemViewadvertises nothumbnailUrland nodimensions. Network/memory cost only; fix upstream.med) — a person opened mid-merge answersMergePeopleResponse(nomedia), so the detail screen shows its generic error until the merge settles. Merge UI is out of Phase 2 scope.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.low) — a tentative row with nopersonAssignmentIdrenders as an undecidable card;POST /confirmis keyed on assignment ids and there is no id to send.Other risks worth a reviewer's eye:
assignmentIds=personAssignmentIdhas no in-repo client precedent; it is read offFaceAssignmentView. Worth confirming against a live server before this ships to family devices.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.