feat(copies): manage physical copies (add + set status) from the book summary

app/Controllers/PrestitiController.php

@@ -1317,7 +1317,9 @@ public function processReturn(Request $request, Response $response, mysqli $db,
             // delle prenotazioni: solo così copie_disponibili e libri.stato riflettono lo
             // stato finale e un libro restituito torna correttamente prestabile (TXN-002,
             // TXN-005, A2). insideTransaction:true mantiene l'atomicità della transazione.
-            $integrity->recalculateBookAvailability($libro_id, insideTransaction: true);
+            if (!$integrity->recalculateBookAvailability($libro_id, insideTransaction: true)) {
+                throw new \RuntimeException('Failed to recalculate availability after loan return.');
+            }
 
             $db->commit();
 

app/Controllers/ReservationManager.php

@@ -189,11 +189,26 @@ public function processBookAvailability($bookId)
                 FROM prenotazioni r
                 JOIN utenti u ON r.utente_id = u.id
                 WHERE r.libro_id = ? AND r.stato = 'attiva'
-                AND r.data_inizio_richiesta <= ?
+                AND (
+                    -- Real requested start that has arrived. '1000-01-01' is
+                    -- MySQL's minimum valid DATE: the floor rejects 0000-00-00
+                    -- dump rows (which would otherwise be promoted back-dated)
+                    -- without embedding the literal '0000-00-00', which a
+                    -- NO_ZERO_DATE server refuses even at prepare time.
+                    (r.data_inizio_richiesta >= '1000-01-01' AND r.data_inizio_richiesta <= ?)
+                    -- Legacy row with no requested start: promote only while the
+                    -- reservation deadline is still valid (today or future). An
+                    -- already-expired deadline must be left for the expiry /
+                    -- cancellation path, never converted into a loan back-dated
+                    -- to the past.
+                    OR (r.data_inizio_richiesta IS NULL
+                        AND r.data_scadenza_prenotazione IS NOT NULL
+                        AND DATE(r.data_scadenza_prenotazione) >= ?)
+                )
                 ORDER BY r.queue_position ASC
                 LIMIT 1
             ");
-            $stmt->bind_param('is', $bookId, $today);
+            $stmt->bind_param('iss', $bookId, $today, $today);
             $stmt->execute();
             $result = $stmt->get_result();
             $nextReservation = $result->fetch_assoc();
@@ -204,13 +219,19 @@ public function processBookAvailability($bookId)
                 // R_END once: a legacy prenotazione may have data_fine_richiesta NULL but
                 // data_scadenza_prenotazione set — passing the raw NULL would make
                 // isDateRangeAvailable() return false and the row would never promote.
-                $startDate = $nextReservation['data_inizio_richiesta'];
+                $startDate = $nextReservation['data_inizio_richiesta']
+                    ?: (!empty($nextReservation['data_scadenza_prenotazione'])
+                        ? substr((string) $nextReservation['data_scadenza_prenotazione'], 0, 10)
+                        : null);
                 $endDate = $nextReservation['data_fine_richiesta']
                     ?: (!empty($nextReservation['data_scadenza_prenotazione'])
                         ? substr((string) $nextReservation['data_scadenza_prenotazione'], 0, 10)
                         : $startDate);
-                // Feed the resolved end to createLoanFromReservation() too (it reads
-                // $reservation['data_fine_richiesta'] for the loan period).
+                // Feed both resolved bounds to createLoanFromReservation() too.
+                // Legacy rows can have a NULL requested start but a valid legacy
+                // deadline; selecting them without normalising the start would
+                // still make isDateRangeAvailable() reject them forever.
+                $nextReservation['data_inizio_richiesta'] = $startDate;
                 $nextReservation['data_fine_richiesta'] = $endDate;
 
                 // #157: pass the promoted reservation's queue_position so the
@@ -246,7 +267,9 @@ public function processBookAvailability($bookId)
                     // counted. Recalc again now that the reservation is 'completata', so the
                     // commitment is counted exactly once.
                     $integrity = new \App\Support\DataIntegrity($this->db);
-                    $integrity->recalculateBookAvailability($bookId, true);
+                    if (!$integrity->recalculateBookAvailability($bookId, true)) {
+                        throw new \RuntimeException('Failed to recalculate availability after reservation promotion.');
+                    }
 
                     // Update queue positions for remaining reservations.
                     // Pass the completed reservation's position: the converted
@@ -359,8 +382,10 @@ private function createLoanFromReservation($reservation)
         $ownTransaction = $this->beginTransactionIfNeeded();
 
         try {
-            // Find an available copy for this date range (no overlapping loans)
-            // Consider 'disponibile' and 'prenotato' copies (exclude perso/danneggiato/manutenzione)
+            // Find an available copy for this date range (no overlapping loans).
+            // Promotion happens only when the requested start has arrived, so a
+            // physically-out ('prestato') copy is intentionally excluded here;
+            // it becomes eligible through the return/reassignment path.
             // The NOT EXISTS clause ensures no overlapping loans for the requested dates
             // Note: 'da_ritirare' copies are still 'disponibile' but have a loan reservation
             $copyStmt = $this->db->prepare("
@@ -452,7 +477,9 @@ private function createLoanFromReservation($reservation)
 
             // Update book availability (inside transaction)
             $integrity = new \App\Support\DataIntegrity($this->db);
-            $integrity->recalculateBookAvailability($bookId, true);
+            if (!$integrity->recalculateBookAvailability($bookId, true)) {
+                throw new \RuntimeException('Failed to recalculate availability for the promoted reservation.');
+            }
 
             $this->commitIfOwned($ownTransaction);
             return $loanId;
@@ -883,7 +910,9 @@ public function cancelExpiredReservations(): int
             $integrity = new \App\Support\DataIntegrity($this->db);
             foreach ($affectedBooks as $bookId) {
                 $this->reorderQueuePositions($bookId);
-                $integrity->recalculateBookAvailability($bookId, true);
+                if (!$integrity->recalculateBookAvailability($bookId, true)) {
+                    throw new \RuntimeException('Failed to recalculate availability after reservation expiry.');
+                }
             }
 
             $this->commitIfOwned($ownTransaction);

app/Controllers/ReservationsAdminController.php

@@ -280,7 +280,9 @@ public function update(Request $request, Response $response, mysqli $db, int $id
             }
 
             $integrity = new \App\Support\DataIntegrity($db);
-            $integrity->recalculateBookAvailability($libroId, insideTransaction: true);
+            if (!$integrity->recalculateBookAvailability($libroId, insideTransaction: true)) {
+                throw new \RuntimeException('Failed to recalculate availability after reservation update.');
+            }
 
             // Cancelling/completing an active reservation frees a slot: promote the next
             // queued reservation(s) right away, exactly like every other release path
@@ -535,7 +537,9 @@ public function store(Request $request, Response $response, mysqli $db): Respons
             $stmt->close();
 
             $integrity = new \App\Support\DataIntegrity($db);
-            $integrity->recalculateBookAvailability($libroId, insideTransaction: true);
+            if (!$integrity->recalculateBookAvailability($libroId, insideTransaction: true)) {
+                throw new \RuntimeException('Failed to recalculate availability after reservation creation.');
+            }
 
             $db->commit();
             return $response->withHeader('Location', url('/admin/reservations') . '?created=1')->withStatus(302);

app/Controllers/ReservationsController.php

@@ -434,17 +434,27 @@ public function createReservation($request, $response, $args)
             }
             $dupReservationStmt->close();
 
+            // The pre-transaction eligibility check is only a fast fail. Lock
+            // and re-check the patron before creating the durable request so a
+            // concurrent suspension/card expiry cannot slip through the gap.
+            $userLockStmt = $this->db->prepare("SELECT id FROM utenti WHERE id = ? FOR UPDATE");
+            $userLockStmt->bind_param('i', $userId);
+            $userLockStmt->execute();
+            $userLockStmt->get_result();
+            $userLockStmt->close();
+            $eligibilityError = \App\Support\LoanEligibility::checkUser($this->db, $userId);
+            if ($eligibilityError !== null) {
+                $this->db->rollback();
+                $response->getBody()->write(json_encode([
+                    'success' => false,
+                    'message' => \App\Support\LoanEligibility::errorMessage($eligibilityError),
+                ]));
+                return $response->withHeader('Content-Type', 'application/json')->withStatus(403);
+            }
+
             // Enforce max active loans per user (admin setting; 0 = no limit)
             $maxLoans = (int) ((new \App\Models\SettingsRepository($this->db))->get('loans', 'max_active_loans_per_user', '0') ?? 0);
             if ($maxLoans > 0) {
-                // Serialize concurrent same-user requests on different books: the
-                // per-book libri lock taken earlier does not mutually-exclude them,
-                // so without this both could pass the limit check and both commit.
-                $userLockStmt = $this->db->prepare("SELECT id FROM utenti WHERE id = ? FOR UPDATE");
-                $userLockStmt->bind_param('i', $userId);
-                $userLockStmt->execute();
-                $userLockStmt->close();
-
                 $cntStmt = $this->db->prepare("SELECT COUNT(*) FROM prestiti WHERE utente_id = ? AND attivo = 1 AND stato IN ('prenotato','da_ritirare','in_corso','in_ritardo')");
                 $cntStmt->bind_param('i', $userId);
                 $cntStmt->execute();

app/Controllers/UserActionsController.php

@@ -232,7 +232,9 @@ public function cancelLoan(Request $request, Response $response, mysqli $db): Re
             // siamo dentro la transazione aperta in questo metodo, evita il
             // commit implicito di una begin_transaction() annidata)
             $integrity = new \App\Support\DataIntegrity($db);
-            $integrity->recalculateBookAvailability((int) $loan['libro_id'], insideTransaction: true);
+            if (!$integrity->recalculateBookAvailability((int) $loan['libro_id'], insideTransaction: true)) {
+                throw new \RuntimeException('Failed to recalculate availability after loan cancellation.');
+            }
 
             $db->commit();
 
@@ -347,12 +349,28 @@ public function cancelReservation(Request $request, Response $response, mysqli $
             $updatePos->close();
             $reorderStmt->close();
 
-            // Recalculate book availability
+            // Cancelling a queue reservation frees a promised capacity unit.
+            // Promote every now-eligible row in the same transaction, matching
+            // the admin cancellation and physical-copy release paths.
+            $reservationManager = new \App\Controllers\ReservationManager($db);
+            $reservationManager->setExternalTransaction(true);
+            for ($promoGuard = 0; $promoGuard < 1000 && $reservationManager->processBookAvailability($libroId); $promoGuard++) {
+                // promote until the newly-freed capacity is exhausted
+            }
+
             $integrity = new \App\Support\DataIntegrity($db);
-            $integrity->recalculateBookAvailability($libroId, insideTransaction: true);
+            if (!$integrity->recalculateBookAvailability($libroId, insideTransaction: true)) {
+                throw new \RuntimeException('Failed to recalculate availability after reservation cancellation.');
+            }
 
             $db->commit();
 
+            try {
+                $reservationManager->flushDeferredNotifications();
+            } catch (\Throwable $e) {
+                SecureLogger::warning('Failed to flush reservation notifications after user cancellation', ['error' => $e->getMessage()]);
+            }
+
             return $response->withHeader('Location', RouteTranslator::route('reservations') . '?canceled=1')->withStatus(302);
 
         } catch (\Throwable $e) {
@@ -452,7 +470,9 @@ public function changeReservationDate(Request $request, Response $response, mysq
 
             // Recalculate book availability
             $integrity = new \App\Support\DataIntegrity($db);
-            $integrity->recalculateBookAvailability($libroId, insideTransaction: true);
+            if (!$integrity->recalculateBookAvailability($libroId, insideTransaction: true)) {
+                throw new \RuntimeException('Failed to recalculate availability after reservation date change.');
+            }
 
             $db->commit();
 
@@ -568,19 +588,22 @@ public function loan(Request $request, Response $response, mysqli $db): Response
             }
             $dupReservationStmt->close();
 
+            // Revalidate eligibility while holding the user row. The fast check
+            // before the transaction improves feedback, but an administrator can
+            // suspend the patron between that check and this INSERT.
+            $userLockStmt = $db->prepare("SELECT id FROM utenti WHERE id = ? FOR UPDATE");
+            $userLockStmt->bind_param('i', $utenteId);
+            $userLockStmt->execute();
+            $userLockStmt->get_result();
+            $userLockStmt->close();
+            if (\App\Support\LoanEligibility::checkUser($db, $utenteId) !== null) {
+                $db->rollback();
+                return $this->back($response, ['loan_error' => 'not_eligible']);
+            }
+
             // Enforce max active loans per user (admin setting; 0 = no limit)
             $maxLoans = (int) ((new \App\Models\SettingsRepository($db))->get('loans', 'max_active_loans_per_user', '0') ?? 0);
             if ($maxLoans > 0) {
-                // Serialize concurrent loan requests by the SAME user: the per-book
-                // libri lock taken earlier does not mutually exclude two requests
-                // for *different* books, so without this both could read the same
-                // activeCount below the limit and both insert, exceeding it.
-                // Locking the user row forces them to run one at a time.
-                $userLockStmt = $db->prepare("SELECT id FROM utenti WHERE id = ? FOR UPDATE");
-                $userLockStmt->bind_param('i', $utenteId);
-                $userLockStmt->execute();
-                $userLockStmt->close();
-
                 $cntStmt = $db->prepare("SELECT COUNT(*) FROM prestiti WHERE utente_id = ? AND attivo = 1 AND stato IN ('prenotato','da_ritirare','in_corso','in_ritardo')");
                 $cntStmt->bind_param('i', $utenteId);
                 $cntStmt->execute();
@@ -729,6 +752,18 @@ public function reserve(Request $request, Response $response, mysqli $db): Respo
             }
             $dupLoanStmt->close();
 
+            // Revalidate under the user lock so a concurrent suspension/card
+            // expiry cannot race the pre-transaction eligibility check.
+            $userLockStmt = $db->prepare("SELECT id FROM utenti WHERE id = ? FOR UPDATE");
+            $userLockStmt->bind_param('i', $utenteId);
+            $userLockStmt->execute();
+            $userLockStmt->get_result();
+            $userLockStmt->close();
+            if (\App\Support\LoanEligibility::checkUser($db, $utenteId) !== null) {
+                $db->rollback();
+                return $this->back($response, ['reserve_error' => 'not_eligible']);
+            }
+
             // Canonical peak-capacity decision (same service as admin create,
             // approval, renew and audit), excluding this user defensively.
             $capacity = new \App\Services\CapacityService($db);
@@ -759,7 +794,9 @@ public function reserve(Request $request, Response $response, mysqli $db): Respo
 
                 // Recalculate book availability after reservation
                 $integrity = new \App\Support\DataIntegrity($db);
-                $integrity->recalculateBookAvailability($libroId, insideTransaction: true);
+                if (!$integrity->recalculateBookAvailability($libroId, insideTransaction: true)) {
+                    throw new \RuntimeException('Failed to recalculate availability after reservation creation.');
+                }
 
                 $db->commit();
                 $params = ['reserve_success' => 1];