docs(admin): processing issues page — per-library scan-failure ledger
Third admin page. Documents the severity stat cards (errors/warnings/ info, cards only appear when non-zero), the per-issue card fields, and the three actions with their real semantics: Retry (per-item scanner re-run — success closes the issue, failure surfaces the real error), Retry all (sequential queue with done/total progress, deliberately not a library-wide scan), Dismiss (warnings/info only, confirm-guarded; errors cannot be dismissed). Links to scanning.md for the retry-vs- library-scan distinction. Glossary gains Retry, Retry all, Dismiss.
This commit is contained in:
1 parent
b3a8cbd582
commit
88e3de606c
2 files changed
+73
No files matched your search
@@ -0,0 +1,61 @@
|
||||
<!-- Ground truth: templates/admin_processing_issues.templ (stats cards,
|
||||
Retry all queue, per-issue Retry/Dismiss, severity badges),
|
||||
internal/handlers/processing_issues.go (RetryProcessingIssue — success
|
||||
closes the issue, failure returns the real error; resolve path),
|
||||
internal/router/library.go (issue routes), the deliberately-not-a-
|
||||
library-rescan design comment in the template. Re-verify against these
|
||||
when the page changes. -->
|
||||
|
||||
# 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.
|
||||
Reference in new issue
Block a user