diff --git a/docs/admin/library-processing-issues.md b/docs/admin/library-processing-issues.md new file mode 100644 index 00000000..e1e0a5ad --- /dev/null +++ b/docs/admin/library-processing-issues.md @@ -0,0 +1,61 @@ + + +# Processing Issues + +Processing Issues is each library's ledger of items the scanner could not +fully process — a corrupt file, an unsupported format, metadata that +wouldn't parse. It is per-library: you reach it from that library's panel +on the Libraries page (the link only appears when the library has issues). + +## What's on the page + +Three count cards — **Errors**, **Warnings**, **Info** — show how many +open issues sit at each severity (a card only appears when that severity +has issues). Below them, one card per issue showing: + +- the item's **title** and a plain-language **description** of what went + wrong +- **Type**, **Format**, **File** (full path), and **Library** type +- a severity badge: red for errors, amber for warnings, neutral for info + +## Fixing an issue + +### Retry + +Runs that one item back through the scanner. This is a per-item scan — +the item's file is re-read and re-extracted exactly like a book-page +[Rescan](scanning.md), not a pass over the library. If it succeeds, the +issue closes itself; if it fails again, the page shows the *real* error, +so you know why it still fails instead of staring at a stale complaint. + +### Retry all + +Queues every issue currently on the page and works through them **one at +a time** — the button shows progress as "done / total" while the queue +drains. This is deliberately not a whole-library scan: fixing a handful of +bad files never re-reads the good ones. Per-issue **Retry** buttons are +disabled while the queue is running. + +When the queue finishes, the page refreshes itself from the server — +closed issues disappear, still-failing ones stay with fresh error text. + +### Dismiss + +Closes an issue without re-processing — for warnings and info items you've +looked at and judged fine (a confirm dialog guards the click). **Errors +cannot be dismissed**: they must be fixed and successfully retried. The +Dismiss button simply doesn't exist on an error card. + +## How issues get here and leave + +The scanner creates an issue whenever it fails to process an item during a +scan. Issues leave the page three ways: a successful **Retry** (or any +later scan that processes the item cleanly), a **Dismiss** you chose for a +warning or info item, or the file's problem being fixed on disk and the +next scan handling the item cleanly. diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md index a5415f75..29922f10 100644 --- a/docs/developer/ui-controls.md +++ b/docs/developer/ui-controls.md @@ -228,6 +228,18 @@ label: Scan this folder where: Admin → Libraries → a library's panel → a folder row does: Shallow-scans only that folder's subtree — unchanged files are skipped, and items in the library's other folders are never marked missing by a partial scan. +label: Retry +where: Admin → Libraries → a library's Processing Issues page → an issue card +does: Re-runs that one item through the scanner (a per-item scan, not a library pass). Success closes the issue; failure shows the real error. + +label: Retry all +where: Admin → Libraries → a library's Processing Issues page → beside the severity cards +does: Queues every issue on the page and re-runs them one at a time, showing done/total progress. Deliberately not a whole-library scan. + +label: Dismiss +where: Admin → Libraries → Processing Issues → warning and info cards only +does: Closes the issue without re-processing, after a confirm. Error-severity issues cannot be dismissed. + label: Resume rewind where: audio player → player settings; profile settings does: Rewinds playback a configured few seconds when you resume.