[BW-DL-01] Audit actionable download and offline recovery UX #15
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
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?
Classification
Active planning/audit item. No download behavior change in this issue.
Problem / opportunity
BookWave already has substantial download/offline architecture, but the user experience around failure, pause, storage exhaustion/removal, network constraints, stale manifests, and repair/retry paths has accumulated incrementally. Before adding a download/status widget or more automation, we need to identify which states are genuinely actionable for a listener and whether the current UI gives the right explanation and recovery action.
User value
Make offline listening more trustworthy: when a download is not usable, BookWave should say what happened, what still exists locally, and the safest next action instead of reducing every problem to a generic failure/retry state.
Scope
Audit current download architecture, UI, state model, risks, device-test evidence, PRODUCT_SPEC/ADRs, and reference-client research. Produce a concrete recovery UX plan covering at least:
.partdata and resumability;For each state, record:
End with small independent implementation slices rather than one broad 'downloads redesign' PR.
Explicitly out of scope
Dependencies
None for the audit. Any later implementation slices may depend on current download architecture or documentation decisions discovered here.
Architecture seams affected
Planning must inspect and preserve the distinction between:
Server / API assumptions
Audiobookshelf remains the source for authorization/library identity and download media URLs. The audit must not assume the server can repair missing local files or expose state it does not actually provide. Authentication expiry and server-unreachable states should reuse existing application error semantics where possible.
Storage / migration implications
Audit only. Any proposed future state additions must say whether they require manifest/schema migration and how existing partial/completed downloads are interpreted safely. Existing files must never be deleted merely because a newer UI cannot classify them.
Privacy / security
Do not expose book titles/server information in diagnostics or system surfaces beyond existing privacy policy. Recovery actions must respect active-profile authorization; a physical file existing on disk does not by itself grant another profile access.
Automated-test level
The audit should map every recommended implementation slice to its appropriate level: pure state-machine/domain tests, manifest/storage tests, WorkManager tests, repository tests, and UI/Robolectric tests. Destructive or filesystem repair behavior requires explicit regression coverage.
Device / platform acceptance
Plan device tests for removable storage loss/return where possible, airplane/offline mode, Wi-Fi/cellular policy, process death during transfer, low-storage behavior, and playback of a completed download after server loss. Do not label emulator/JVM evidence as equivalent to actual removable-storage behavior.
Estimated effort
Audit/planning: Medium. Follow-up implementation cost to be estimated per slice.
Implementation risk
Audit: Low. Future recovery work: Medium/high because incorrect repair/deletion semantics can destroy useful partial data or make valid offline media unavailable.
Recommended sequence
Start now in parallel with BW-DOC-01. Finish the audit before deciding whether a download/status widget deserves roadmap priority.
Acceptance criteria
main, not inferred from old plans.Superseded by the full BW-DL-01 audit summary in #104. The audit remains issue-based; implementation is split into #107–#112. GitHub PR #106 is planning-only material and is being closed without merge.
BW-DL-01 audit result
This issue is the planning/audit owner. It does not represent an implementation PR.
Current-state findings from
mainDownloadedBookEntity.failureSummaryis populated byDefaultDownloadRepository.markFailed(...), butDownloadMappers.toDomain(...)does not carry it intoOfflineBook. The Downloads UI therefore knows that a row failed but cannot explain the safe failure reason already persisted.Failedrow can therefore callPauseDownloadUseCase, becomePaused, and clear the failure reason instead of offering Retry.FailedbeforeBookDownloadWorkerreturnsResult.retry(). During WorkManager retry/backoff, the screen can say Failed even though BookWave will continue automatically. Network constraints can similarly leave work waiting while the manifest only says incomplete/queued.file://path is temporarily unavailable. Reinserting the card does not automatically restore the manifest to Complete. The selected missing volume also falls back to internal storage for new downloads without making that fallback especially clear to the listener..partdata; Retry/Resume can reuse it.OfflineFiles.discardPartials(...)already exists and is a good candidate for an explicit secondary destructive recovery action rather than automatic cleanup.Implementation slices created
failureSummaryalready exists.Discard partial downloadas a secondary action. Depends on #108.Recommended implementation order
#107 -> #108 -> #109, then#110;#112may proceed after #108 independently. #111 waits for the owner decision and should not block the non-destructive recovery work.Widget conclusion
Do not prioritize a generic download-count widget. Once #107–#110 exist, reconsider a download/status widget only if it can surface persistent actionable states such as
Waiting for Wi-Fi,Retry needed, orStorage unavailable. A raw count is not worth Home-screen space.Audit status
The planning work of BW-DL-01 is complete enough to hand off its child issues. Application behavior remains unchanged by this issue.