73 lines
3.9 KiB
Markdown
73 lines
3.9 KiB
Markdown
---
|
|
status: Accepted
|
|
date: 2026-07-08
|
|
applyTo:
|
|
- "Fuchs/Controllers/**"
|
|
- "Fuchs/Services/**"
|
|
- "Fuchs/Notifications/**"
|
|
supersededBy: ""
|
|
---
|
|
|
|
# 0003 — Any exception that interrupts a user action notifies the user (not just the log)
|
|
|
|
## Context
|
|
[0001](0001-domain-events-and-notification-triggers.md) requires the *modeled*
|
|
failure paths (invoice/reminder/banking create, send, import) to publish a
|
|
`*IssueAsync`/`*Failed` event. But an action can also fail through an
|
|
**unexpected/unmodeled** exception — a bug, a transient dependency error, an
|
|
edge case nobody wrote a specific failure event for. Those were only landing in
|
|
the log (`_logger.LogError` + an HTTP 500), so the user saw the action stop with
|
|
no explanation and no notification. The user asked that *whenever* an exception
|
|
interrupts a process they initiated, they be told via the notification system.
|
|
|
|
## Decision
|
|
Every exception that **interrupts a user-initiated action** must surface to the
|
|
user through `IEventService`, in addition to being logged. Concretely:
|
|
|
|
- **Catch-all safety net at the dispatcher.** `IntranetController.Do`'s
|
|
top-level `catch` publishes a generic `UserIssueAsync("Aktion fehlgeschlagen",
|
|
…)` for any `Do_Process_*` action that throws without having already published
|
|
its own (more specific) issue event. It is guarded by
|
|
`UserIdent.IsAuthenticated` — pre-auth flows (login/logout, anonymous GETs)
|
|
have no session to notify and the HTTP status already conveys the failure.
|
|
- **Handlers with their own `catch` must notify locally.** A handler that
|
|
swallows its exception (returns a 500/error result instead of rethrowing)
|
|
never reaches the `Do` net, so it must call the matching issue event itself —
|
|
e.g. `HandleInvoiceGet` calls `InvoiceIssueAsync` before returning 500. Prefer
|
|
the domain-specific method (`InvoiceIssueAsync`/`ReminderIssueAsync`/
|
|
`BankingImportIssueAsync`); fall back to `UserIssueAsync` when none fits.
|
|
- **Message stays user-readable and broadcast-safe.** Per
|
|
[0002](0002-gui-notification-delivery-signalr.md) notifications are broadcast
|
|
to every logged-in session, so the German `Message`/`Context` must never carry
|
|
the raw exception text or anything sensitive — diagnostics go to the log; the
|
|
user gets a plain "could not be completed" message.
|
|
|
|
This deliberately **excludes** operations that do not interrupt a discrete user
|
|
action: background/best-effort work (blob archiving, startup self-tests,
|
|
per-entry parse skips) stays log-only, and auto-refreshing read views (dashboard
|
|
widgets, report reloads) return their error status without a toast, because
|
|
notifying on every poll cycle would spam the user rather than inform them.
|
|
|
|
## Consequences
|
|
- New `catch` blocks on a request-handling path must be classified: does the
|
|
exception interrupt a user action? If yes → publish an issue event (specific
|
|
if one exists, else `UserIssueAsync`). If it is background/best-effort or an
|
|
auto-poll read → log only, and say so in a comment.
|
|
- The `Do` net is a backstop, not a replacement for specific events: modeled
|
|
failures should still publish their contextful `*IssueAsync` at the point of
|
|
failure so the message names the invoice/reminder/file involved.
|
|
- Because the net only fires on *unhandled* exceptions (handled flows return
|
|
rather than rethrow), it does not double-notify the flows that already report
|
|
their own failures.
|
|
|
|
## Alternatives considered
|
|
- **Rely solely on 0001's per-flow issue events**: rejected — it leaves every
|
|
unmodeled/unexpected exception silent, which is exactly the gap the user
|
|
reported.
|
|
- **Notify on every failing read/poll too (widgets, reports)**: rejected —
|
|
auto-refresh would turn a transient backend hiccup into a stream of toasts;
|
|
those paths surface failure via HTTP status instead.
|
|
- **Surface the raw exception message to the GUI**: rejected for the same
|
|
reason as 0001 — not user-understandable, leaks internals, and (per 0002) is
|
|
visible to every logged-in session.
|