Fuchs_Intranet/Fuchs/Docs/Decisions/0023-user-action-failures-persisted-to-db-log.md

status, date, applyTo, supersededBy

status	date	applyTo	supersededBy
Accepted	2026-09-16	Fuchs/Controllers/** Fuchs/code/FuchsIntranet.cs Fuchs/js/intranet/**

0023 — Failures of user actions are persisted to fds__admin_logdebug, with the SQL and a readable description

Context

Support diagnoses production problems from a query over the fds__admin_logdebug table (EXECUTE [dbo].[fds__admin_logdebug] via Fuchs_intranet.debug_log) — not from the web server's logs/ErrorLog.txt (0003), which is rarely reachable. Reviewing the 2026-09-16 production extract of that table showed three gaps:

• Every "SQL Error in getSQLDataSet" row (twelve execution timeouts in one morning) had Data = NULL. FIS_SQLOptions.OnError logged its constructor context (the fn/id/code, usually null) instead of the data OCORE hands over (new { sql = … }), so nobody could tell which statement timed out.
• Unhandled exceptions from IntranetController.Do went to ILogger only. A customer's failing "PDF-Vorschau" left no trace in the table at all.
• The browser's generic failure alert reads its description from the x-ocms-desc response header, which the backend never set — so users always saw an empty "Der Server hat einen Fehler gemeldet:".

Decision

• The DB log row must carry what is needed to attribute the failure. FIS_SQLOptions merges the OCORE payload (the SQL statement) with the caller context into the Data column ({ sql, context }). New OnError hooks must never drop the statement.
• Every failure that interrupts a user action is written to fds__admin_logdebug too, in addition to ILogger and the notification required by 0003: the Do catch-all writes Unhandled exception in Do {fn}/{id} with route, user and the form field names (never values — they can carry tokens/PII); the PDF-preview endpoints go through a shared guard (IntranetController.PdfPreviewAsync) that logs PDF preview failed (endpoint) with ref/user/duration, counts fuchs.pdf.previews{outcome} and toasts the user.
• A 500 carries its message in the x-ocms-desc header (ServerError(msg) → EncodeResponseDescription: percent-encoded ASCII, spaces as %20 because the client maps + to space before decodeURIComponent). Handlers that return a 500 should pass a user-readable German message; the frontend shows it verbatim.
• Preview calls in the frontend never fail silently. They use a 120 s timeout ($inv.pdfPreviewTimeout), one shared error handler ($inv.pdfPreviewFailed) and a complete handler that unfreezes the editor and reports a timeout — postXT returns early on a timeout without calling error, so complete is the only place it is observable.

Consequences

• Support can attribute a SQL timeout to its statement straight from the table; a failing preview is visible as one row with endpoint, reference id, user and duration.
• debug_log is a synchronous DB round-trip and is only used on error paths; it must not be added to hot/success paths (see 0003 on the cost of DB logging).
• x-ocms-desc is user-facing: messages must be German, short, and free of secrets. The innermost exception text is acceptable for an internal intranet audience.

Alternatives considered

• Enable FuchsLoggerProvider.DatabaseLoggingEnabled so every ILogger error lands in the DB. Rejected: it would write every LogError (including expected/handled ones and background-service noise) with a DB round-trip each, and the provider has no access to the request context (user, route) that makes a row actionable.
• Return the message only in the JSON body. The generic client failure path never parses the body of a non-2xx response; the header is the existing contract in oci_basic.js.