Fuchs_Intranet/Fuchs/Docs/Decisions/0025-invoice-document-regenerate-on-miss.md

status, date, applyTo, supersededBy

status	date	applyTo	supersededBy
Accepted	2026-09-16	Fuchs/Controllers/IntranetController.Invoices*.cs Fuchs/Controllers/IntranetController.Requests.cs Fuchs/Services/InvoiceService.cs Fuchs_Database/dbo/Stored Procedures/fds__getReportDocument.sql Fuchs_Database/dbo/Stored Procedures/fds__setInvoiceFile.sql

0025 — Invoice document endpoints regenerate a missing final PDF on read

Context

A finalised invoice's PDF is rendered exactly once, at finalisation (req/sconf → StoreInvoiceDocumentFileAsync → fds__setInvoiceFile), and stored in fds__invoices.[file] (primary) plus blob storage (archive). If that single write fails — observed on 2026-09-16 for W7VAL/R2026-0258, where the fds__setInvoiceFile call timed out under DB load — the invoice is left finalised with [file] = NULL and nothing ever retries.

The read endpoints then disagreed: req/idoc regenerated a missing file (a fallback carried over from the legacy VB fuchs_ocms_intranet_requests.vb "idoc" case), while inv/rdoc — the endpoint the invoice list's preview icon actually calls — read fds__getReportDocument and returned a permanent 404.

Decision

Both invoice document read endpoints (req/idoc, inv/rdoc) regenerate and persist the PDF via StoreInvoiceDocumentFileAsync when no stored bytes exist, only when the invoice is

• finalised (IsFinal, i.e. !FdsInvoiceData.IsDraft), and
• not external (IsExternal false — an MFR-sourced document has no template to regenerate from; a missing MFR file stays a 404).

A read is therefore allowed to write [file], upload the blob and emit InvoiceFileCreated — the same side effects finalisation would have had.

Every failure inside StoreInvoiceDocumentFileAsync/StoreReminderDocumentFileAsync (render threw, render produced no bytes, DB write threw, DB write matched 0 rows) is logged at Error level individually, because the method signals all four to callers with the same empty array. The 0-rows case needed switching from setSQLValue_async (reports success once ExecuteNonQueryAsync completes without throwing, regardless of rows affected) to setSQLValue_async_result, whose AffectedRows makes a no-op UPDATE ... WHERE [file] IS NULL distinguishable from an actual write — this is what made the original incident's failure invisible to every log.

Consequences

• Drafts are never persisted by a read. fds__setInvoiceFile writes WHERE [file] IS NULL and fds__setInvoiceFinal never clears [file]; a draft render stored early would make the later final write a no-op and the invoice would carry the watermarked draft PDF forever. The !IsDraft gate is load-bearing — do not relax it.
• The regenerated PDF is rendered from the invoice's current data. That is acceptable because a finalised invoice is immutable in the editor; it is not acceptable for anything mutable.
• A read on a cold miss now costs a render plus a DB write, so it is exposed to the same fds__setInvoiceFile timeout that caused the miss. The client preview timeout ($inv.pdfPreviewTimeout) must stay generous (120 s).
• inv/rdoc still serves external (MFR) documents purely from fds__getReportDocument; regeneration never applies to them.

Alternatives considered

• Retry at finalisation instead of on read. Would cover the store failure but not an already-damaged row; regeneration on read heals both and matches the behaviour req/idoc already had.
• Regenerate drafts too, to mirror req/idoc's render path. req/idoc renders a draft on the fly without storing it; persisting a draft through fds__setInvoiceFile is what causes the permanent-draft defect above.
• Return 404 and rely on the _BackupAndClearInvoiceFile recovery links. That proc is a manual-only maintenance tool, and the inv/rdoc?create=1 link it prints was never implemented on that endpoint.