feat(loans): overdue recalls (solleciti) and email loan receipt (#360)

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 Full version-by-version history for Pinakes. The README shows only the latest release; everything older lives here.
 
+## [Unreleased]
+
+## [0.7.62-rc.1] - 2026-08-19
+
+Overdue-loan recalls (solleciti) and emailing the loan receipt (#360).
+
+### Features
+
+- **Loan recalls (solleciti)**: overdue loans can now be chased beyond the
+  single overdue notification. Automatic recalls repeat at a configurable
+  interval up to a configurable cap (Settings → Loans → "Solleciti automatici",
+  off by default; sent by the notifications cron or on admin login). Staff can
+  also send a manual recall for one loan from the loan detail page, or for many
+  at once from the loans list via the bulk action bar — manual recalls ignore
+  the automatic schedule but share the same per-loan counter
+  (`prestiti.recall_count` / `last_recall_at`, added by
+  `migrate_0.7.62-rc.1.sql` and self-healed at runtime). New editable email
+  template `loan_recall_notification` in all five locales.
+- **Email the loan receipt PDF**: next to "Scarica Ricevuta PDF", the loan
+  detail page now has "Invia Ricevuta via Email", which sends the same PDF as
+  an attachment to the loan's user (new editable template
+  `loan_receipt_email`; the mailer gained in-memory attachment support).
+- **Emails in the recipient's language**: user-facing notification emails
+  (loan warnings/overdue/recalls, receipt, approvals, pickups, returns,
+  reservations, wishlist, registration and account emails — and per-admin for
+  admin alerts) now render in the recipient's preferred language
+  (`utenti.locale`, the same value that drives their UI language), including
+  date formats and translated labels, falling back to the installation locale
+  when the user has none. Password-reset mail already followed the
+  requester's session language.
+- **Language choice at registration**: on multi-language installs the
+  registration form now offers a "Lingua preferita" select (defaulting to the
+  language the visitor is browsing in), validated server-side against the
+  shipped locales. The profile page and the admin user forms already offered
+  the same choice; together they cover registration, self-service and admin.
+
 ## [0.7.61]
 
 Physical-copy management from the book summary, with the whole holding and

app/Controllers/PrestitiController.php

@@ -1025,12 +1025,24 @@ public function update(Request $request, Response $response, mysqli $db, int $id
                     "UPDATE prestiti
                         SET stato = CASE WHEN data_scadenza < ? THEN 'in_ritardo' ELSE 'in_corso' END,
                             warning_sent = CASE WHEN data_scadenza < ? THEN warning_sent ELSE 0 END,
-                            overdue_notification_sent = CASE WHEN data_scadenza < ? THEN overdue_notification_sent ELSE 0 END
+                            overdue_notification_sent = CASE WHEN data_scadenza < ? THEN overdue_notification_sent ELSE 0 END,
+                            recall_count = 0,
+                            last_recall_at = NULL
                       WHERE id = ? AND attivo = 1 AND stato IN ('in_corso', 'in_ritardo')"
                 );
                 $recalcStato->bind_param('sssi', $today, $today, $today, $id);
                 $recalcStato->execute();
                 $recalcStato->close();
+            } elseif ($newUserId !== (int) $locked['utente_id']) {
+                // A recall belongs to the recipient who received it. Reassigning
+                // the loan must not carry that recipient's count/cooldown over to
+                // the new user, even when the due date itself is unchanged.
+                $resetRecall = $db->prepare(
+                    'UPDATE prestiti SET recall_count = 0, last_recall_at = NULL WHERE id = ?'
+                );
+                $resetRecall->bind_param('i', $id);
+                $resetRecall->execute();
+                $resetRecall->close();
             }
 
             // Ricalcola la disponibilità (M6c): spostare le date di un 'prenotato'
@@ -1622,7 +1634,9 @@ public function bulkExtend(Request $request, Response $response, mysqli $db): Re
                     SET data_scadenza = ?,
                         stato = CASE WHEN ? < ? THEN 'in_ritardo' ELSE 'in_corso' END,
                         warning_sent = CASE WHEN ? < ? THEN warning_sent ELSE 0 END,
-                        overdue_notification_sent = CASE WHEN ? < ? THEN overdue_notification_sent ELSE 0 END
+                        overdue_notification_sent = CASE WHEN ? < ? THEN overdue_notification_sent ELSE 0 END,
+                        recall_count = 0,
+                        last_recall_at = NULL
                   WHERE id = ? AND attivo = 1 AND stato IN ('in_corso', 'in_ritardo')"
             );
 
@@ -1941,7 +1955,8 @@ public function renew(Request $request, Response $response, mysqli $db, int $id)
             $updateStmt = $db->prepare("
                 UPDATE prestiti
                 SET data_scadenza = ?, renewals = ?, pickup_deadline = NULL,
-                    warning_sent = 0, overdue_notification_sent = 0
+                    warning_sent = 0, overdue_notification_sent = 0,
+                    recall_count = 0, last_recall_at = NULL
                 WHERE id = ?
             ");
             $updateStmt->bind_param("sii", $newDueDate, $newRenewalCount, $id);
@@ -2159,6 +2174,121 @@ public function exportCsv(Request $request, Response $response, mysqli $db): Res
             ->withHeader('Pragma', 'no-cache');
     }
 
+    /**
+     * #360: manual recall (sollecito) for a single overdue loan — JSON endpoint
+     * behind the "Invia Sollecito" button on the loan detail page.
+     */
+    public function sendRecall(Request $request, Response $response, mysqli $db, int $id): Response
+    {
+        if ($guard = $this->guardStaffAccess($response)) {
+            return $guard;
+        }
+        if ($blocked = $this->catalogueModeJsonGuard($response)) {
+            return $blocked;
+        }
+        // CSRF validated by CsrfMiddleware.
+
+        $result = (new NotificationService($db))->sendManualRecall($id);
+
+        $response->getBody()->write((string) json_encode([
+            'success' => (bool) $result['success'],
+            'message' => (string) $result['message'],
+        ]));
+        return $response->withHeader('Content-Type', 'application/json');
+    }
+
+    /**
+     * #360: bulk recall — sends the sollecito email to every selected loan that
+     * is genuinely overdue. Mirrors bulkExtend()'s form-POST + redirect-flash
+     * shape; per-loan claims live in NotificationService::sendManualRecall(),
+     * so a loan that isn't overdue, has no email, or fails to send is skipped
+     * (counted) without aborting the batch.
+     */
+    /**
+     * Upper bound on one synchronous bulk-recall batch. Each loan is a real
+     * SMTP send inside this HTTP request, so the cap must stay small enough
+     * not to trip max_execution_time (same rationale as the 20-item cap on
+     * /admin/books/bulk-enrich/start). Larger overdue backlogs are what the
+     * automatic recall scheduler is for.
+     */
+    private const BULK_RECALL_MAX_LOANS = 50;
+
+    /**
+     * A bulk action is synchronous, but it must not monopolize the PHP worker.
+     * One SMTP attempt is still bounded separately by EmailService's timeout.
+     */
+    private const BULK_RECALL_TIME_BUDGET_SECONDS = 15.0;
+
+    public function bulkRecall(Request $request, Response $response, mysqli $db): Response
+    {
+        if ($guard = $this->guardStaffAccess($response)) {
+            return $guard;
+        }
+        $data = (array) $request->getParsedBody();
+        // CSRF validated by CsrfMiddleware.
+
+        $ids = array_values(array_unique(array_filter(
+            array_map('intval', (array) ($data['ids'] ?? [])),
+            static fn (int $i): bool => $i > 0
+        )));
+
+        $backUrl = url('/admin/loans');
+        if ($ids === [] || count($ids) > self::BULK_RECALL_MAX_LOANS) {
+            return $response->withHeader('Location', $backUrl . '?error=bulk_recall_invalid')->withStatus(302);
+        }
+
+        $service = new NotificationService($db);
+        $sent = 0;
+        $skipped = 0;
+        $startedAt = hrtime(true);
+        $total = count($ids);
+        foreach ($ids as $index => $loanId) {
+            $elapsedSeconds = (hrtime(true) - $startedAt) / 1_000_000_000;
+            if ($elapsedSeconds >= self::BULK_RECALL_TIME_BUDGET_SECONDS) {
+                $skipped += $total - $index;
+                break;
+            }
+
+            // The interactive single-loan endpoint keeps its retry policy. In a
+            // bulk HTTP request use one bounded attempt per recipient: repeating
+            // the same SMTP failure up to 50 times would exceed the request SLA.
+            $result = $service->sendManualRecall($loanId, 1, 0);
+            if ($result['success']) {
+                $sent++;
+            } else {
+                $skipped++;
+            }
+        }
+
+        return $response
+            ->withHeader('Location', $backUrl . '?bulk_recalled=' . $sent . '&bulk_recall_skipped=' . $skipped)
+            ->withStatus(302);
+    }
+
+    /**
+     * #360: email the loan receipt PDF to the loan's user — JSON endpoint
+     * behind the "Invia Ricevuta via Email" button on the loan detail page.
+     * The attached document is the same one downloadPdf() serves.
+     */
+    public function emailPdf(Request $request, Response $response, mysqli $db, int $id): Response
+    {
+        if ($guard = $this->guardStaffAccess($response)) {
+            return $guard;
+        }
+        if ($blocked = $this->catalogueModeJsonGuard($response)) {
+            return $blocked;
+        }
+        // CSRF validated by CsrfMiddleware.
+
+        $result = (new NotificationService($db))->sendLoanReceiptEmail($id);
+
+        $response->getBody()->write((string) json_encode([
+            'success' => (bool) $result['success'],
+            'message' => (string) $result['message'],
+        ]));
+        return $response->withHeader('Content-Type', 'application/json');
+    }
+
     private function guardStaffAccess(Response $response): ?Response
     {
         $role = $_SESSION['user']['tipo_utente'] ?? '';
@@ -2167,4 +2297,23 @@ private function guardStaffAccess(Response $response): ?Response
         }
         return null;
     }
+
+    /**
+     * #360: refuse the loan email/recall JSON endpoints in catalogue mode, the
+     * same intent bulkRecall's route enforces with a redirect. Loans are
+     * disabled in catalogue mode, so a lingering row must not still trigger a
+     * patron email through the single-item AJAX endpoints. Returns a JSON body
+     * (these are fetch() endpoints) instead of a redirect.
+     */
+    private function catalogueModeJsonGuard(Response $response): ?Response
+    {
+        if (!\App\Support\ConfigStore::isCatalogueMode()) {
+            return null;
+        }
+        $response->getBody()->write((string) json_encode([
+            'success' => false,
+            'message' => __('Funzione non disponibile in modalità catalogo.'),
+        ]));
+        return $response->withHeader('Content-Type', 'application/json')->withStatus(403);
+    }
 }

app/Controllers/RegistrationController.php

@@ -146,12 +146,21 @@ public function register(Request $request, Response $response, mysqli $db): Resp
         // Default stato: sospeso (richiede approvazione admin). Email da verificare
         $stato = 'sospeso';
         $ruolo = 'standard';
-        // The application language is selected for the whole installation.
-        // Persist it explicitly instead of relying on the historical it_IT
-        // schema default, which is wrong on installations using another locale.
-        $locale = \App\Support\I18n::normalizeLocaleCode(
-            \App\Support\I18n::getInstallationLocale()
-        );
+        // #360: the registrant picks their language on the form (the select is
+        // rendered only on multi-language installs). Validate against the
+        // locales this installation actually ships; anything missing or
+        // invalid falls back to the installation locale — the historical
+        // behaviour. The stored value drives the user's UI language and the
+        // language of every email the app sends them.
+        $locale = '';
+        if (isset($data['locale']) && is_scalar($data['locale'])) {
+            $locale = \App\Support\I18n::normalizeLocaleCode(trim((string) $data['locale']));
+        }
+        if ($locale === '' || !isset(\App\Support\I18n::getAvailableLocales()[$locale])) {
+            $locale = \App\Support\I18n::normalizeLocaleCode(
+                \App\Support\I18n::getInstallationLocale()
+            );
+        }
         if (!\App\Support\I18n::isValidLocaleCode($locale)) {
             $locale = 'it_IT';
         }