All updates
QAFrontend

QA Promotion: Single-Document Download Alignment and Clearer Archived-Mail Folder Errors

PR #1021pixbox-supportMay 21, 2026 · 14:26 UTC
QAMay 21, 2026

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=true API 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): Removed useBulkDownloadDocumentsMutation; single-row handleDownload now calls a new handleRowDownload that invokes useBulkZipDocumentsMutation in explicit mode for the one document id, passing existing export filters/search/grid status, then routes the result through handleDownloadResponse.
  • #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 the replace_existing=true flag; both map to friendly failure text and a recovery hint.
  • Types (websocket.types.ts): Added optional error_code and error_codes fields to BackgroundJobFailedDetail so 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.