feat(documents)!: unify offers and issued orders end to end

One coherent pass over the two sibling document models, driven by a 3-lens
1:1 scan (~60 divergences inventoried) + user decisions. Migration adds
issued_orders.locked_by/locked_at and the issued_order_sections table
(mirror of scope_sections; applied to dev + test DBs).

Issued orders gained (offers as reference implementation):
- rich-text SECTIONS with CZ/EN titles, rendered on their own PDF page in
  the PO template's red style (shared DocumentSectionSchema, one-transaction
  create/update incl. items - fixes a torn-write bug)
- edit LOCKING (lock/heartbeat/unlock routes, 423 + holder name, 30s TTL =
  3 missed 10s heartbeats; locked_by enrichment on detail)
- archived-PDF serving: GET /:id/file reads the NAS copy (new
  readIssuedByNumber sweep) with live-render fallback + re-archive; offers'
  /file got the same fallback (kills the 'ulozte nabidku' dead end)
- NAS cleanup on delete, in-tx po_number uniqueness (409), collision-advancing
  number previews (also invoice previews), PUT returns assigned po_number

Offers hardened (issued as reference):
- VALID_TRANSITIONS enforced (no more numberless 'ordered' offers; invalidate
  follows the table; order creation only from active offers) +
  valid_transitions on detail
- explicit 400 instead of silent edits outside draft/active (mirrored on
  issued: explicit 400 replaced silent drops)
- customer existence check + Number(null)->0 clear bug fixed; delete of a
  linked offer -> 409 instead of P2003 500; error-token convention; Zod caps
  DB-aligned (desc 500/unit 20/number 50/project_code 100, isoDateString
  dates, ints for positions); audit old/new values + koncept fallbacks;
  list id tiebreaks; stats include trimmed; NAS delete dedupe

Frontend unification (6 new shared modules):
- components/document/{DocumentItemsEditor,SectionsEditor,LockBanner}
- hooks/{useDocumentLock,useUnsavedChangesGuard,useDocumentPdf(+list variant)}
- OfferDetail 1940->1100 lines, IssuedOrderDetail 1400->980: headline-only
  document number (form field removed), one form layout/readonly convention,
  view-permission opens read-only everywhere (issued's editable-for-viewers
  hole closed), server-driven transition buttons, dirty guard + Enter submit
  on both, useApiMutation everywhere (new opt-in envelope mode), fixed
  infinite spinner on failed detail fetch, draft PDFs hidden (no number yet)
- lists: supplier filter + count line on issued, Mena column dropped + mono
  numbers on offers, shared hardened per-row PDF flow (spinner, double-click
  guard, 401 close, blob cleanup), proper Czech quotes, real CTA empty
  states, query-lib cleanups (["offers","customers"] key, typed list rows,
  shared CurrencyAmount, retry:false on details)
- pdf-shared.ts: one escapeHtml/cleanQuillHtml(strict)/formatNum(NBSP)/
  formatCurrency/formatDate for all four PDF routes; offer PDF keeps its
  monochrome look (fractional qty fix: 1.5 no longer prints as 2); issued
  PDF language now comes from the document column

+49 tests (suite 364 -> 413). Each stage passed an independent review; final
cross-stage integration review verified the FE<->BE contracts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/routes/admin/offers-pdf.ts

@@ -1,102 +1,24 @@
 import { FastifyInstance } from "fastify";
+import type { Prisma, company_settings } from "@prisma/client";
 import prisma from "../../config/database";
 import { requirePermission } from "../../middleware/auth";
-import { localDateCzStr } from "../../utils/date";
 import { nasOffersManager } from "../../services/nas-offers-manager";
 import { htmlToPdf } from "../../utils/html-to-pdf";
 import { parseId, success } from "../../utils/response";
+import {
+  formatDate,
+  formatNum,
+  formatCurrency,
+  escapeHtml,
+  cleanQuillHtml,
+  buildQuillIndentCss,
+} from "../../utils/pdf-shared";
 import createDOMPurify from "dompurify";
 import { JSDOM } from "jsdom";
 
 const window = new JSDOM("").window;
 const DOMPurify = createDOMPurify(window);
 
-function formatDate(date: Date | string | null | undefined): string {
-  if (!date) return "";
-  const d = new Date(date);
-  if (isNaN(d.getTime())) return String(date);
-  return localDateCzStr(d);
-}
-
-/** Format number with comma decimal separator and non-breaking space thousands separator */
-function formatNum(n: number, decimals: number): string {
-  const abs = Math.abs(n);
-  const fixed = abs.toFixed(decimals);
-  const [intPart, decPart] = fixed.split(".");
-  const withSep = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, "\u00A0");
-  const result = decPart ? `${withSep},${decPart}` : withSep;
-  return n < 0 ? `-${result}` : result;
-}
-
-function formatCurrency(amount: number, currency: string): string {
-  const n = Number(amount) || 0;
-  switch (currency) {
-    case "EUR":
-      return `${formatNum(n, 2)} \u20AC`;
-    case "USD":
-      return `$${Math.abs(n)
-        .toFixed(2)
-        .replace(/\B(?=(\d{3})+(?!\d))/g, ",")}`;
-    case "CZK":
-      return `${formatNum(n, 2)} K\u010D`;
-    case "GBP":
-      return `\u00A3${Math.abs(n)
-        .toFixed(2)
-        .replace(/\B(?=(\d{3})+(?!\d))/g, ",")}`;
-    default:
-      return `${formatNum(n, 2)} ${currency}`;
-  }
-}
-
-function escapeHtml(str: string | null | undefined): string {
-  if (!str) return "";
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-/** Sanitize Quill HTML: keep safe tags, remove event handlers, merge adjacent spans */
-function cleanQuillHtml(html: string | null | undefined): string {
-  if (!html) return "";
-  const allowedTags =
-    "<p><br><strong><em><u><s><ul><ol><li><span><sub><sup><a><h1><h2><h3><h4><blockquote><pre>";
-  let s = html;
-  // Remove dangerous tags with content
-  s = s.replace(
-    /<(script|iframe|object|embed|style|link|meta|base|form|input|textarea|button|select|svg|math)[^>]*>[\s\S]*?<\/\1>/gi,
-    "",
-  );
-  s = s.replace(
-    /<(script|iframe|object|embed|style|link|meta|base|form|input|textarea|button|select|svg|math)[^>]*\/?>/gi,
-    "",
-  );
-  // Strip event handlers
-  s = s.replace(/\s+on\w+\s*=\s*("[^"]*"|'[^']*'|[^\s>]*)/gi, "");
-  s = s.replace(/\s+on\w+\s*=\s*[^\s>]*/gi, "");
-  // Strip javascript:/data:/vbscript: in href and src (defense-in-depth,
-  // matching the invoices/orders copies — DOMPurify runs first).
-  s = s.replace(
-    /href\s*=\s*["']?\s*(javascript|data|vbscript)\s*:[^"'>\s]*/gi,
-    'href="#"',
-  );
-  s = s.replace(
-    /src\s*=\s*["']?\s*(javascript|data|vbscript)\s*:[^"'>\s]*/gi,
-    'src=""',
-  );
-  // Replace &nbsp; with regular space (outside of tags)
-  s = s.replace(/(&nbsp;)/g, " ");
-  s = s.replace(/\s+style\s*=\s*("[^"]*"|'[^']*'|[^\s>]*)/gi, "");
-  // Merge adjacent spans with same attributes
-  let prev = "";
-  while (prev !== s) {
-    prev = s;
-    s = s.replace(/<span([^>]*)>(.*?)<\/span>\s*<span\1>/gs, "<span$1>$2");
-  }
-  return s;
-}
-
 interface AddressResult {
   name: string;
   lines: string[];
@@ -210,120 +132,117 @@ const TRANSLATIONS: Record<string, Record<string, string>> = {
   of: { EN: "of", CZ: "z" },
 };
 
-export default async function offersPdfRoutes(
-  fastify: FastifyInstance,
-): Promise<void> {
-  fastify.get<{ Params: { id: string } }>(
-    "/:id",
-    { preHandler: requirePermission("offers.view") },
-    async (request, reply) => {
-      const id = parseId(request.params.id, reply);
-      if (id === null) return;
-      const query = request.query as Record<string, string>;
+/** Quotation row with the relations the PDF template renders. */
+export type OfferForPdf = Prisma.quotationsGetPayload<{
+  include: {
+    customers: true;
+    quotation_items: true;
+    scope_sections: true;
+  };
+}>;
 
-      try {
-        const quotation = await prisma.quotations.findUnique({
-          where: { id },
-          include: {
-            customers: true,
-            quotation_items: { orderBy: { position: "asc" } },
-            scope_sections: { orderBy: { position: "asc" } },
-          },
-        });
+/**
+ * Build the full offer PDF/preview HTML. Extracted from the route handler so
+ * the offers /:id/file live-render fallback (quotations.ts) can reuse the
+ * exact same template without going through HTTP.
+ */
+export function renderOfferHtml(
+  quotation: OfferForPdf,
+  settings: company_settings | null,
+): string {
+  const isCzech = (quotation.language ?? "EN") !== "EN";
+  const langKey = isCzech ? "CZ" : "EN";
+  const currency = quotation.currency || "EUR";
+  const t = (key: string): string => TRANSLATIONS[key]?.[langKey] || key;
 
-        if (!quotation) {
-          return reply
-            .status(404)
-            .type("text/html")
-            .send("<html><body><h1>Nab\u00EDdka nenalezena</h1></body></html>");
-        }
+  let logoImg = "";
+  if (settings?.logo_data) {
+    const buf = Buffer.from(settings.logo_data);
+    let mime = "image/png";
+    if (buf[0] === 0xff && buf[1] === 0xd8) mime = "image/jpeg";
+    else if (buf[0] === 0x47 && buf[1] === 0x49) mime = "image/gif";
+    else if (buf[0] === 0x52 && buf[1] === 0x49) mime = "image/webp";
+    logoImg = `<img src="data:${escapeHtml(mime)};base64,${buf.toString("base64")}" class="logo" />`;
+  }
 
-        const settings = await prisma.company_settings.findFirst();
-        const isCzech = (quotation.language ?? "EN") !== "EN";
-        const langKey = isCzech ? "CZ" : "EN";
-        const currency = quotation.currency || "EUR";
-        const t = (key: string): string => TRANSLATIONS[key]?.[langKey] || key;
+  // Offers are NOT tax documents — the total is NET only (no VAT math).
+  const items = quotation.quotation_items;
+  let total = 0;
+  for (const item of items) {
+    if (item.is_included_in_total !== false) {
+      total += (Number(item.quantity) || 0) * (Number(item.unit_price) || 0);
+    }
+  }
+  // Visibility uses the SAME per-language title rule as the render loop plus
+  // a tag-stripped content check (an empty-Quill "<p><br></p>" doesn't count)
+  // — otherwise a section with only the other language's title would count as
+  // content and produce a scope page holding nothing but the header. Mirrors
+  // issued-orders-pdf.
+  const stripSectionTags = (html: string | null | undefined): string =>
+    (html || "")
+      .replace(/<[^>]*>/g, "")
+      .replace(/&nbsp;/g, " ")
+      .trim();
+  const resolveSectionTitle = (s: {
+    title: string | null;
+    title_cz: string | null;
+  }): string =>
+    isCzech && (s.title_cz || "").trim() ? s.title_cz || "" : s.title || "";
+  const visibleSections = quotation.scope_sections.filter(
+    (s) => resolveSectionTitle(s).trim() || stripSectionTags(s.content),
+  );
+  const hasScopeContent = visibleSections.length > 0;
 
-        let logoImg = "";
-        if (settings?.logo_data) {
-          const buf = Buffer.from(settings.logo_data);
-          let mime = "image/png";
-          if (buf[0] === 0xff && buf[1] === 0xd8) mime = "image/jpeg";
-          else if (buf[0] === 0x47 && buf[1] === 0x49) mime = "image/gif";
-          else if (buf[0] === 0x52 && buf[1] === 0x49) mime = "image/webp";
-          logoImg = `<img src="data:${escapeHtml(mime)};base64,${buf.toString("base64")}" class="logo" />`;
-        }
+  const cust = buildAddressLines(
+    quotation.customers as unknown as Record<string, unknown>,
+    false,
+    t,
+  );
+  const supp = buildAddressLines(
+    settings as unknown as Record<string, unknown>,
+    true,
+    t,
+  );
 
-        // Offers are NOT tax documents — the total is NET only (no VAT math).
-        const items = quotation.quotation_items;
-        let total = 0;
-        for (const item of items) {
-          if (item.is_included_in_total !== false) {
-            total +=
-              (Number(item.quantity) || 0) * (Number(item.unit_price) || 0);
-          }
-        }
-        let hasScopeContent = false;
-        for (const s of quotation.scope_sections) {
-          if ((s.content || "").trim() || (s.title || "").trim()) {
-            hasScopeContent = true;
-            break;
-          }
-        }
+  const custLinesHtml = cust.lines
+    .map((l) => `<div class="address-line">${escapeHtml(l)}</div>`)
+    .join("");
+  const suppLinesHtml = supp.lines
+    .map((l) => `<div class="address-line">${escapeHtml(l)}</div>`)
+    .join("");
 
-        const cust = buildAddressLines(
-          quotation.customers as unknown as Record<string, unknown>,
-          false,
-          t,
-        );
-        const supp = buildAddressLines(
-          settings as unknown as Record<string, unknown>,
-          true,
-          t,
-        );
+  // Indentation CSS for Quill
+  const indentCSS = buildQuillIndentCss();
 
-        const custLinesHtml = cust.lines
-          .map((l) => `<div class="address-line">${escapeHtml(l)}</div>`)
-          .join("");
-        const suppLinesHtml = supp.lines
-          .map((l) => `<div class="address-line">${escapeHtml(l)}</div>`)
-          .join("");
-
-        // Indentation CSS for Quill
-        let indentCSS = "";
-        for (let n = 1; n <= 9; n++) {
-          const pad = n * 3;
-          const liPad = n * 3 + 1.5;
-          indentCSS += `  .ql-indent-${n} { padding-left: ${pad}em; }\n`;
-          indentCSS += `  li.ql-indent-${n} { padding-left: ${liPad}em; }\n`;
-        }
-
-        let itemsHtml = "";
-        items.forEach((item, i) => {
-          const lineTotal =
-            (Number(item.quantity) || 0) * (Number(item.unit_price) || 0);
-          const subDesc = item.item_description || "";
-          const evenClass = i % 2 === 1 ? ' class="even"' : "";
-          itemsHtml += `<tr${evenClass}>
+  let itemsHtml = "";
+  items.forEach((item, i) => {
+    const qty = Number(item.quantity) || 0;
+    const lineTotal = qty * (Number(item.unit_price) || 0);
+    // Integers render without decimals; fractional quantities keep 2 decimals
+    // (the old toFixed(0) ROUNDED 1.5 → 2 on the printed document).
+    const qtyDecimals = Math.floor(qty) === qty ? 0 : 2;
+    const subDesc = item.item_description || "";
+    const evenClass = i % 2 === 1 ? ' class="even"' : "";
+    itemsHtml += `<tr${evenClass}>
             <td class="row-num">${i + 1}</td>
             <td class="desc">${escapeHtml(item.description)}${subDesc ? `<div class="item-subdesc">${escapeHtml(subDesc)}</div>` : ""}</td>
-            <td class="center">${formatNum(Number(item.quantity) || 1, 0)}${(item.unit || "").trim() ? ` / ${escapeHtml((item.unit || "").trim())}` : ""}</td>
+            <td class="center">${formatNum(qty, qtyDecimals)}${(item.unit || "").trim() ? ` / ${escapeHtml((item.unit || "").trim())}` : ""}</td>
             <td class="right">${formatCurrency(Number(item.unit_price) || 0, currency)}</td>
             <td class="right total-cell">${formatCurrency(lineTotal, currency)}</td>
           </tr>`;
-        });
+  });
 
-        // No Mezisoučet/VAT rows — they would only duplicate the net total.
-        const totalsHtml = `<div class="grand">
+  // No Mezisoučet/VAT rows — they would only duplicate the net total.
+  const totalsHtml = `<div class="grand">
       <span class="label">${escapeHtml(t("total_no_vat"))}</span>
       <span class="value">${formatCurrency(total, currency)}</span>
     </div>`;
-        const quotationNumber = escapeHtml(quotation.quotation_number);
+  const quotationNumber = escapeHtml(quotation.quotation_number);
 
-        let scopeHtml = "";
-        if (hasScopeContent) {
-          scopeHtml += '<div class="scope-page">';
-          scopeHtml += `<div class="page-header">
+  let scopeHtml = "";
+  if (hasScopeContent) {
+    scopeHtml += '<div class="scope-page">';
+    scopeHtml += `<div class="page-header">
           <div class="left">
             <div class="page-title">${escapeHtml(t("title"))}</div>
             <div class="quotation-number">${quotationNumber}</div>
@@ -334,27 +253,23 @@ export default async function offersPdfRoutes(
         </div>
         <hr class="separator" />`;
 
-          for (const section of quotation.scope_sections) {
-            const title =
-              isCzech && (section.title_cz || "").trim()
-                ? section.title_cz
-                : section.title || "";
-            const content = (section.content || "").trim();
-            if (!title && !content) continue;
-            scopeHtml += '<div class="scope-section">';
-            if (title)
-              scopeHtml += `<div class="scope-section-title">${escapeHtml(title)}</div>`;
-            if (content)
-              scopeHtml += `<div class="section-content">${cleanQuillHtml(DOMPurify.sanitize(content))}</div>`;
-            scopeHtml += "</div>";
-          }
-          scopeHtml += "</div>";
-        }
+    for (const section of visibleSections) {
+      const title = resolveSectionTitle(section);
+      const content = (section.content || "").trim();
+      scopeHtml += '<div class="scope-section">';
+      if (title.trim())
+        scopeHtml += `<div class="scope-section-title">${escapeHtml(title)}</div>`;
+      if (content)
+        scopeHtml += `<div class="section-content">${cleanQuillHtml(DOMPurify.sanitize(content))}</div>`;
+      scopeHtml += "</div>";
+    }
+    scopeHtml += "</div>";
+  }
 
-        const pageLabel = escapeHtml(t("page"));
-        const ofLabel = escapeHtml(t("of"));
+  const pageLabel = escapeHtml(t("page"));
+  const ofLabel = escapeHtml(t("of"));
 
-        const html = `<!DOCTYPE html>
+  const html = `<!DOCTYPE html>
 <html lang="${isCzech ? "cs" : "en"}">
 <head>
 <meta charset="utf-8" />
@@ -732,6 +647,40 @@ ${indentCSS}
 </body>
 </html>`;
 
+  return html;
+}
+
+export default async function offersPdfRoutes(
+  fastify: FastifyInstance,
+): Promise<void> {
+  fastify.get<{ Params: { id: string } }>(
+    "/:id",
+    { preHandler: requirePermission("offers.view") },
+    async (request, reply) => {
+      const id = parseId(request.params.id, reply);
+      if (id === null) return;
+      const query = request.query as Record<string, string>;
+
+      try {
+        const quotation = await prisma.quotations.findUnique({
+          where: { id },
+          include: {
+            customers: true,
+            quotation_items: { orderBy: { position: "asc" } },
+            scope_sections: { orderBy: [{ position: "asc" }, { id: "asc" }] },
+          },
+        });
+
+        if (!quotation) {
+          return reply
+            .status(404)
+            .type("text/html")
+            .send("<html><body><h1>Nabídka nenalezena</h1></body></html>");
+        }
+
+        const settings = await prisma.company_settings.findFirst();
+        const html = renderOfferHtml(quotation, settings);
+
         const saveMode = query.save === "1";
 
         // Save PDF to NAS