feat(android): Phase 4 upload activity + manual photo picker upload #1127

Merged
chris merged 5 commits from ux-android-upload into main 2026-10-12 00:17:28 +02:00
Owner

What

Phase 4 upload work for the Android app (spec 049), in two parts:

A. Cross-device upload-activity surface — a new "Upload-Aktivität" card in the MEHR hub opens a screen that lists upload sessions across the family (any device), polling GET /api/upload-activity every 5s while visible. It shows active/interrupted work in plain German, per-session progress ("34 von 120 Fotos", current file name), state labels ("Wird geprüft…", "Wird verarbeitet…", "Fertig", "Fehler" with count), per-session cancel behind a confirmation dialog, an empty state ("Gerade läuft kein Upload."), pull-to-refresh, and a refresh on open.

B. Manual photo upload from this device — a "Fotos hochladen" button on that same screen drives the system photo picker (PickMultipleVisualMedia, ~20/invocation, "Mehr auswählen" repeats) and feeds the existing UploadSessionClient machinery (create → files with fingerprint headers → commit with Idempotency-Key). Picked content:// URIs are read via ContentResolver. The manual session is a regular upload session, so it appears in surface A with live counts.

Payload findings (important)

The activity feed does not carry clientType. I verified this against the server source (UploadActivitySession, UploadActivityController) and the web client (uploadActivity.ts): clientType (browser/api/cli) is a session-creation field only and is never echoed back in GET /api/upload-activity.

The wire shape is a bare JSON array of UploadActivitySessionDto:

sessionId, derivedStatus, createdAt/updatedAt (ISO|null),
plannedCount (Int|null), totalCount, receivedCount, committedCount,
processingCount, failedCount, skippedCount, receivingFileNames[] (max 20)

Consequence: per-device labels ("Desktop" / "Browser" / "Telefon") are not possible from the feed. Rather than invent a label, the screen labels only sessions this device can prove it started — its own manual uploads plus the backup engine's open batch — as "Dieses Gerät", and leaves every other row unattributed. Tracked as [ISSUE-131].

POST /api/upload-activity/{sessionId}/cancel: any 2xx is success and the body is never parsed (the server may answer 200 with a full UploadSession or empty); 404 = not-found/foreign, 409 = already terminal.

Design decisions

  • Visibility rule (pure, tested): always show created, receiving, commit_requested, committing, processing, stale (interrupted = the prime cancel target per spec 049's unfinished-work focus), failed; show completed/completed_with_issues only within a ~15-min grace of updatedAt (mirrors the server's staleness window); hide cancelled/expired. Cancellable = created, receiving, commit_requested, committing, stale (the rest return 409).
  • Denominator = plannedCount ?: totalCount (the web client's plannedTotal); current file = receivingFileNames.firstOrNull().
  • Polling, not SSE: the web client uses SSE upload_activity_changed with a 60s polling fallback. Android v1 polls every 5s while the screen is visible — simpler and just as resilient. SSE is out of scope here.
  • plannedFileCount added to CreateUploadSessionBody/createSession (additive, default null) so manual sessions get a constant X/Y denominator. BackupEngine is unaffected.
  • Manual pipeline lives in :core as ManualUploadCoordinator (pure JVM, MockWebServer-testable): hashes via ContentHasher, reuses UploadSessionClient, per-file 4xx → failed-and-continue (mirrors BackupEngine), transport/auth errors propagate. clientFileKey = "picker:{uri}", sourceLabel = device label, clientType left at the default "api" (honest).
  • VM stays resource-free (status→German mapping is in the screen, matching the ViewerMessageKind precedent). New DTOs live in a separate net/UploadActivityDtos.kt to keep the MemoriesApi/HttpMemoriesApi conflict surface to one additive tail block.

Scope / known limitations (v1)

  • SSE not used — polling as above.
  • Manual upload is tied to the screen staying open — the ViewModel is destination-scoped, so navigating away stops the poll loop and lets an in-flight manual upload finish in the background. A WorkManager-backed background path is out of scope for v1; an interrupted run leaves a stale session, which is cancellable from this same screen.
  • No arbitrary files/folders or share-sheet upload — photo picker only (image/* + video/*).

Testing

  • UploadActivityJsonTest — wire shapes (full row, older payload without plannedCount, unknown-field tolerance, empty feed).
  • HttpUploadActivityApiTest — exact paths, bearer header, "any 2xx, body ignored" cancel rule, 404/409 surfacing.
  • UploadActivityViewModelTest — visibility grace window, cancellability, planned/numerator mapping, local-vs-stranger labelling, 404/protocol degradation to empty, unauthorized logout, cancel confirm/fail/dismiss.
  • ManualUploadCoordinatorTest (:core, MockWebServer) — one session with planned count, fingerprint headers (filename, client-file-key, client-content-hash, client-relative-path), single commit Idempotency-Key, per-file 4xx isolation, skipped counts, progress sequence, transport-failure abort.

:app:testDebugUnitTest + :app:assembleDebug + :core:test pass; :app:lintDebug adds no new errors over the 18 pre-existing baseline.

Refs: spec:049

## What Phase 4 upload work for the Android app (spec 049), in two parts: **A. Cross-device upload-activity surface** — a new "Upload-Aktivität" card in the MEHR hub opens a screen that lists upload sessions across the family (any device), polling `GET /api/upload-activity` every 5s while visible. It shows active/interrupted work in plain German, per-session progress ("34 von 120 Fotos", current file name), state labels ("Wird geprüft…", "Wird verarbeitet…", "Fertig", "Fehler" with count), per-session cancel behind a confirmation dialog, an empty state ("Gerade läuft kein Upload."), pull-to-refresh, and a refresh on open. **B. Manual photo upload from this device** — a "Fotos hochladen" button on that same screen drives the system photo picker (`PickMultipleVisualMedia`, ~20/invocation, "Mehr auswählen" repeats) and feeds the existing `UploadSessionClient` machinery (create → files with fingerprint headers → commit with `Idempotency-Key`). Picked `content://` URIs are read via `ContentResolver`. The manual session is a regular upload session, so it appears in surface A with live counts. ## Payload findings (important) The activity feed **does not carry `clientType`**. I verified this against the server source (`UploadActivitySession`, `UploadActivityController`) and the web client (`uploadActivity.ts`): `clientType` (`browser`/`api`/`cli`) is a **session-creation** field only and is never echoed back in `GET /api/upload-activity`. The wire shape is a bare JSON array of `UploadActivitySessionDto`: ``` sessionId, derivedStatus, createdAt/updatedAt (ISO|null), plannedCount (Int|null), totalCount, receivedCount, committedCount, processingCount, failedCount, skippedCount, receivingFileNames[] (max 20) ``` Consequence: per-device labels ("Desktop" / "Browser" / "Telefon") are **not possible** from the feed. Rather than invent a label, the screen labels only sessions this device can prove it started — its own manual uploads plus the backup engine's open batch — as "Dieses Gerät", and leaves every other row unattributed. Tracked as [ISSUE-131]. `POST /api/upload-activity/{sessionId}/cancel`: any 2xx is success and the body is **never parsed** (the server may answer 200 with a full `UploadSession` or empty); 404 = not-found/foreign, 409 = already terminal. ## Design decisions - **Visibility rule** (pure, tested): always show `created`, `receiving`, `commit_requested`, `committing`, `processing`, `stale` (interrupted = the prime cancel target per spec 049's unfinished-work focus), `failed`; show `completed`/`completed_with_issues` only within a ~15-min grace of `updatedAt` (mirrors the server's staleness window); hide `cancelled`/`expired`. Cancellable = `created`, `receiving`, `commit_requested`, `committing`, `stale` (the rest return 409). - **Denominator** = `plannedCount ?: totalCount` (the web client's `plannedTotal`); current file = `receivingFileNames.firstOrNull()`. - **Polling, not SSE**: the web client uses SSE `upload_activity_changed` with a 60s polling fallback. Android v1 polls every 5s while the screen is visible — simpler and just as resilient. SSE is out of scope here. - **`plannedFileCount`** added to `CreateUploadSessionBody`/`createSession` (additive, default `null`) so manual sessions get a constant X/Y denominator. `BackupEngine` is unaffected. - **Manual pipeline** lives in `:core` as `ManualUploadCoordinator` (pure JVM, MockWebServer-testable): hashes via `ContentHasher`, reuses `UploadSessionClient`, per-file 4xx → failed-and-continue (mirrors `BackupEngine`), transport/auth errors propagate. `clientFileKey = "picker:{uri}"`, `sourceLabel` = device label, `clientType` left at the default `"api"` (honest). - VM stays resource-free (status→German mapping is in the screen, matching the `ViewerMessageKind` precedent). New DTOs live in a separate `net/UploadActivityDtos.kt` to keep the `MemoriesApi`/`HttpMemoriesApi` conflict surface to one additive tail block. ## Scope / known limitations (v1) - **SSE not used** — polling as above. - **Manual upload is tied to the screen staying open** — the ViewModel is destination-scoped, so navigating away stops the poll loop and lets an in-flight manual upload finish in the background. A WorkManager-backed background path is out of scope for v1; an interrupted run leaves a `stale` session, which is cancellable from this same screen. - **No arbitrary files/folders or share-sheet upload** — photo picker only (`image/*` + `video/*`). ## Testing - `UploadActivityJsonTest` — wire shapes (full row, older payload without `plannedCount`, unknown-field tolerance, empty feed). - `HttpUploadActivityApiTest` — exact paths, bearer header, "any 2xx, body ignored" cancel rule, 404/409 surfacing. - `UploadActivityViewModelTest` — visibility grace window, cancellability, planned/numerator mapping, local-vs-stranger labelling, 404/protocol degradation to empty, unauthorized logout, cancel confirm/fail/dismiss. - `ManualUploadCoordinatorTest` (`:core`, MockWebServer) — one session with planned count, fingerprint headers (`filename`, `client-file-key`, `client-content-hash`, `client-relative-path`), single commit `Idempotency-Key`, per-file 4xx isolation, skipped counts, progress sequence, transport-failure abort. `:app:testDebugUnitTest` + `:app:assembleDebug` + `:core:test` pass; `:app:lintDebug` adds no new errors over the 18 pre-existing baseline. Refs: spec:049
Drive the pick -> upload -> commit pipeline against the existing
UploadSessionClient machinery, without the backup engine's MediaStore
scan or Room bookkeeping.

- ManualUploadItem carries a re-openable stream factory (Android side
  hands ContentResolver.openInputStream) and a stable clientFileKey
  ("picker:{uri}") because a content:// uri has no MediaStore id.
- Per-file 4xx rejections are isolated and counted, exactly like
  BackupEngine; transport/auth/session-gone errors abort the run.
- Add an optional plannedFileCount to CreateUploadSessionBody/createSession
  so a manual session gets a constant X/Y denominator in the activity
  feed. BackupEngine is unaffected (defaults to null).

Covers the pipeline with MockWebServer: fingerprint headers, commit
Idempotency-Key, 4xx isolation, skipped counts, progress sequence.
Expose GET /api/upload-activity and POST /api/upload-activity/{id}/cancel
(spec 049). The endpoint is not in the OpenAPI contract yet, so the web
client (uploadActivity.ts) is the source of truth for the shapes.

- UploadActivitySessionDto is lenient (nullable/defaults) like the web
  client's normalizeSession, and lives in its own file so the
  MemoriesApi/HttpMemoriesApi conflict surface stays one additive tail
  block. Rows are a bare JSON array.
- The feed carries NO clientType (it is a session-creation field only,
  never echoed back), so per-device labelling is impossible from the
  payload; documented on the DTO and guarded by a regression test.
- Cancel treats any 2xx as success and never parses the body (the
  server may answer with a full session or empty); 404/409 surface as
  ApiHttpException.

Covers DTO parsing and the exact paths/bearer header/cancel rule.
Surface A: a screen (opened from a MEHR hub card) listing cross-device
upload sessions, polling every 5s while visible. Shows unfinished work
in plain German (active + interrupted always, finished within a ~15-min
grace), per-session progress ("34 von 120 Fotos", current file), state
labels, per-session cancel behind a confirmation dialog, an empty state,
pull-to-refresh, and a refresh on open.

Surface B: a "Fotos hochladen" button drives PickMultipleVisualMedia
(~20/invocation, "Mehr auswählen" repeats) through the core
ManualUploadCoordinator, so a picked batch is a regular upload session
that appears in the same list with live counts.

- VM keeps pure, testable policy (visibility grace, cancellability,
  planned/numerator mapping) and labels only sessions it can prove this
  device started (own manual uploads + the backup engine's open batch)
  as "Dieses Gerät"; the feed has no clientType, so strangers are left
  unattributed rather than guessed.
- Status -> German mapping lives in the screen (VM stays resource-free,
  matching ViewerMessageKind).
- AppViewModelFactory builds the VM with an UploadSessionClient for the
  current session and the device sourceLabel.
- New plurals define both one and other in every locale, so no new
  MissingQuantity lint errors.

Refs spec:049. SSE is out of scope for v1 (polling); manual upload is
tied to the screen staying open.
One whole-card entry (same pattern as search/people/albums) so a family
member spots the upload-activity screen without hunting through a menu.

Bump the app to 0.3.0 (versionCode 12) for the Phase 4 upload work.

Record ISSUE-131: the activity feed does not expose clientType, so
sessions cannot be labelled per-device; only sessions this device can
prove it started are marked "Dieses Gerät".
feat(android): wire the upload-activity destination into app nav
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 4s
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 8s
Build and Deploy / Android unit tests and debug APK (push) Successful in 16m6s
46b606a9ec
Isolated final commit for the conflict-prone nav file. Adds the
UPLOAD_ACTIVITY route, the MEHR-hub onUploadActivity callback, and the
destination composable (destination-scoped ViewModel so the 5s poll and
any in-flight manual upload live exactly as long as the screen is
reachable). No bottom-bar changes.
chris force-pushed ux-android-upload from 46b606a9ec
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 4s
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 8s
Build and Deploy / Android unit tests and debug APK (push) Successful in 16m6s
to 9611bdd387
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 / 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 5m7s
2026-10-11 23:55:49 +02:00
Compare
chris force-pushed ux-android-upload from 9611bdd387
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 / 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 5m7s
to d984e13b91
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 7s
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 12s
Build and Deploy / Android unit tests and debug APK (push) Successful in 5m32s
2026-10-12 00:06:18 +02:00
Compare
chris merged commit 5dd93bfc1f into main 2026-10-12 00:17:28 +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!1127
No description provided.