QA Promotion: Single-Document Download Alignment and Clearer Archived-Mail Folder Errors
Executive summary
Promotes two frontend fixes from development into the QA environment. Single-document downloads from the document grid now use the same reliable server-side flow as bulk downloads, and failure messages for archived mails that cannot be moved to a new folder are now shown in plain, user-friendly language instead of raw backend codes.
Why this was needed
Two distinct issues were addressed:
- #1019: A standalone "Download" action on a single document row used a separate, older download path than bulk downloads, leading to inconsistent behavior.
- #1020: When a bulk folder assignment failed because a mail was archived, the failure panel surfaced internal backend wording (e.g. the
replace_existing=trueAPI flag), which is confusing and unprofessional for end users.
Client / user impact
- Downloading a single document now behaves identically to bulk download, going through the established server-side ZIP flow for consistent, predictable results.
- Users who hit an archived-mail folder-assignment failure see a clear message — "This mail is currently archived and cannot be assigned to another folder" — plus an actionable recovery hint to restore the mail or enable "Replace existing folders" and retry.
- No change to underlying permissions, data, or available actions; this is behavior alignment and messaging clarity only.
Technical scope
Batch promotion of dev into qa (4 commits, 3 files, +94/-9):
- #1019 — Standalone document row download (
DocumentGrid.tsx): RemoveduseBulkDownloadDocumentsMutation; single-rowhandleDownloadnow calls a newhandleRowDownloadthat invokesuseBulkZipDocumentsMutationinexplicitmode for the one document id, passing existing export filters/search/grid status, then routes the result throughhandleDownloadResponse. - #1020 — Archived-mail failure copy (
BulkOperationProgressFailureDetails.tsx): Added detection of the archived add-only guard via a stable error code (MAIL_ARCHIVED_REQUIRES_REPLACE_EXISTING) plus a legacy-message fallback that matches old free-text mentioning archived mail and thereplace_existing=trueflag; both map to friendly failure text and a recovery hint. - Types (
websocket.types.ts): Added optionalerror_codeanderror_codesfields toBackgroundJobFailedDetailso the UI can key off machine-readable codes.
Risk & mitigation
Low. Scope is limited to two UI components and one optional type addition. The download change reuses an already-proven bulk ZIP path. The failure-message change preserves a legacy text-matching fallback, so older backend responses lacking the new error code still render the friendly message. Main regression surface is single-document download behavior and the rendering of failure reasons/recovery hints in the bulk progress panel.
QA validation focus
- Trigger a single-document "Download" from the document grid and confirm the file downloads correctly via the server-side ZIP flow (same outcome as bulk download); verify error toast still appears on failure.
- Confirm filters, search term, and grid status are respected for the single-row download.
- Run a bulk "Move to folder" that includes an archived mail and verify the failure panel shows the friendly archived-mail message and the recovery hint, with no raw backend terms (e.g.
replace_existing=true) visible. - Verify non-archived failure reasons (e.g. permission errors) are unaffected and still display their own hints.