feat(documents): allow deletion when acq order lines are terminal

* Closes rero#3225.
* Add module-level constant `ACQ_ORDER_LINE_BLOCKING_STATUSES`
  (APPROVED, ORDERED, PARTIALLY_RECEIVED) in `documents/api.py` to
  avoid reallocating the list on every call to `get_links_to_me()`.
* Filter the `acq_order_lines` link count by these blocking statuses so
  that order lines in a terminal state (RECEIVED, CANCELLED) no longer
  prevent document deletion.
* Guard the receipt-line ES dumper against a missing document: when the
  document has already been deleted, fall back to the pid extracted from
  the `$ref` instead of raising an error.
* Guard the order-line ES dumper the same way, for consistency.
* Override `replace_refs()` in `AcqOrderLine` to resolve the document
  reference manually before delegating to the parent: if the document
  has been deleted the lazy `JsonRef` proxy would raise a
  `JsonRefError` during `deepcopy` inside the base dumper, making any
  edit to a receipt-line (or other resource triggering order-line
  re-indexation) fail. Follows the same pattern already used in
  `Template.replace_refs()`.
* Extend the reception-workflow test with `get_links_to_me()` assertions
  at each stage of the workflow, and verify that once all order lines are
  terminal the document reports no blocking links and no reasons not to
  delete.

Co-Authored-by: Peter Weber <peter.weber@rero.ch>
Co-Authored-by: Pascal Repond <pascal.repond@rero.ch>

Author: rerowep

rero_ils/modules/acquisition/acq_order_lines/api.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # RERO ILS
-# Copyright (C) 2019-2022 RERO
+# Copyright (C) 2019-2026 RERO
 # Copyright (C) 2019-2022 UCLouvain
 #
 # This program is free software: you can redistribute it and/or modify
@@ -82,11 +82,19 @@ def extended_validation(self, **kwargs):
 
         :return: False if
             - notes array has multiple notes with same type
+            - an update would leave the line non-cancelled while its document
+              has been deleted
         """
         # NOTES fields testing
         note_types = [note.get("type") for note in self.get("notes", [])]
         if len(note_types) != len(set(note_types)):
             return _("Cannot have multiple notes of the same type.")
+        # Deleted-document guard: a document may be deleted once all its order
+        # lines reach a terminal status (RECEIVED or CANCELLED). Prevent any
+        # subsequent update that would re-activate the line (remove or unset
+        # `is_cancelled`) while the document no longer exists.
+        if self.updated and not self.get("is_cancelled") and not self.document:
+            return _("Cannot save an active order line for a deleted document.")
         from rero_ils.modules.acquisition.acq_orders.api import AcqOrder
         from rero_ils.modules.acquisition.acq_orders.models import AcqOrderStatus
 
@@ -143,6 +151,26 @@ def _build_total_amount(cls, data):
         """Build total amount for order line."""
         data["total_amount"] = data["amount"] * data["quantity"]
 
+    def replace_refs(self):
+        """Replace $ref with real data, handling deleted documents gracefully.
+
+        The document linked to an order line may have been deleted (allowed
+        when all order lines reach a terminal status). To avoid a
+        ``JsonRefError`` during indexing, we resolve the document ref manually
+        before delegating to the parent, then restore the original ref.
+        """
+        doc_ref = self.pop("document", None)
+        try:
+            data = super().replace_refs()
+        finally:
+            if doc_ref:
+                self["document"] = doc_ref
+        if doc_ref:
+            doc_pid = extracted_data_from_ref(doc_ref)
+            # Mimic what the standard jsonresolver returns: {pid, type}.
+            data["document"] = {"pid": doc_pid, "type": "doc"}
+        return data
+
     # GETTER & SETTER =========================================================
     #   * Define some properties as shortcut to quickly access object attrs.
     #   * Defines some getter methods to access specific object values.

rero_ils/modules/acquisition/acq_order_lines/dumpers.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # RERO ILS
-# Copyright (C) 2019-2022 RERO
+# Copyright (C) 2019-2026 RERO
 # Copyright (C) 2019-2022 UCLouvain
 #
 # This program is free software: you can redistribute it and/or modify
@@ -59,15 +59,18 @@ def dump(self, record, data):
         # Add document information's: pid, formatted title and ISBN
         # identifiers (remove None values from document metadata)
         document = record.document
-        identifiers = document.get_identifiers(filters=[IdentifierType.ISBN], with_alternatives=True)
-        identifiers = [identifier.normalize() for identifier in identifiers]
-
-        data["document"] = {
-            "pid": document.pid,
-            "title": TitleExtension.format_text(document.get("title", [])),
-            "identifiers": identifiers,
-        }
-        data["document"] = {k: v for k, v in data["document"].items() if v}
+        if document:
+            identifiers = document.get_identifiers(filters=[IdentifierType.ISBN], with_alternatives=True)
+            identifiers = [identifier.normalize() for identifier in identifiers]
+            data["document"] = {
+                "pid": document.pid,
+                "title": TitleExtension.format_text(document.get("title", [])),
+                "identifiers": identifiers,
+            }
+            data["document"] = {k: v for k, v in data["document"].items() if v}
+        else:
+            # Document has been deleted; keep only the pid extracted from the $ref
+            data["document"] = {"pid": record.document_pid}
         return data
 
 

rero_ils/modules/acquisition/acq_receipt_lines/dumpers.py

@@ -50,12 +50,19 @@ def dump(self, record, data):
         # Add document information's: pid, formatted title and ISBN identifiers
         # (remove None values from document metadata)
         document = order_line.document
-        identifiers = document.get_identifiers(filters=[IdentifierType.ISBN], with_alternatives=True)
-        identifiers = [identifier.normalize() for identifier in identifiers]
-        data["document"] = {
-            "pid": document.pid,
-            "title": TitleExtension.format_text(document.get("title", [])),
-            "identifiers": identifiers,
-        }
-        data["document"] = {k: v for k, v in data["document"].items() if v}
+        if document:
+            identifiers = document.get_identifiers(filters=[IdentifierType.ISBN], with_alternatives=True)
+            identifiers = [identifier.normalize() for identifier in identifiers]
+            data["document"] = {
+                k: v
+                for k, v in {
+                    "pid": document.pid,
+                    "title": TitleExtension.format_text(document.get("title", [])),
+                    "identifiers": identifiers,
+                }.items()
+                if v
+            }
+        else:
+            # Document has been deleted; keep only the pid extracted from the $ref
+            data["document"] = {"pid": order_line.document_pid}
         return data

rero_ils/modules/documents/api.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # RERO ILS
-# Copyright (C) 2019-2023 RERO
+# Copyright (C) 2019-2026 RERO
 # Copyright (C) 2019-2023 UCLouvain
 #
 # This program is free software: you can redistribute it and/or modify
@@ -29,6 +29,7 @@
 from jsonschema.exceptions import ValidationError
 
 from rero_ils.modules.acquisition.acq_order_lines.api import AcqOrderLinesSearch
+from rero_ils.modules.acquisition.acq_order_lines.models import AcqOrderLineStatus
 from rero_ils.modules.api import IlsRecord, IlsRecordsIndexer, IlsRecordsSearch
 from rero_ils.modules.commons.identifiers import IdentifierFactory, IdentifierType
 from rero_ils.modules.documents.tasks import reindex_document_items
@@ -57,6 +58,12 @@
 # fetcher
 document_id_fetcher = partial(id_fetcher, provider=DocumentProvider)
 
+ACQ_ORDER_LINE_BLOCKING_STATUSES = [
+    AcqOrderLineStatus.APPROVED,
+    AcqOrderLineStatus.ORDERED,
+    AcqOrderLineStatus.PARTIALLY_RECEIVED,
+]
+
 
 class DocumentsSearch(IlsRecordsSearch):
     """DocumentsSearch."""
@@ -313,8 +320,14 @@ def get_links_to_me(self, get_pids=False):
             exclude_states=[LoanState.CANCELLED, LoanState.ITEM_RETURNED],
         )
         file_query = self.get_records_files_query().source()
-        acq_order_lines_query = AcqOrderLinesSearch().filter("term", document__pid=self.pid)
+
+        acq_order_lines_query = (
+            AcqOrderLinesSearch()
+            .filter("term", document__pid=self.pid)
+            .filter("terms", status=ACQ_ORDER_LINE_BLOCKING_STATUSES)
+        )
         local_fields_query = LocalFieldsSearch().get_local_fields(self.provider.pid_type, self.pid)
+
         relation_types = {
             "partOf": "partOf.document.pid",
             "supplement": "supplement.pid",

tests/api/acquisition/test_acquisition_reception_workflow.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # RERO ILS
-# Copyright (C) 2021 RERO
+# Copyright (C) 2021-2026 RERO
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License as published by
@@ -19,14 +19,18 @@
 
 from unittest import mock
 
+import pytest
 from flask import url_for
 from invenio_accounts.testutils import login_user_via_session
+from jsonschema.exceptions import ValidationError
 
 from rero_ils.modules.acquisition.acq_order_lines.api import AcqOrderLine
+from rero_ils.modules.acquisition.acq_order_lines.dumpers import AcqOrderLineESDumper
 from rero_ils.modules.acquisition.acq_order_lines.models import AcqOrderLineStatus
 from rero_ils.modules.acquisition.acq_orders.api import AcqOrder
 from rero_ils.modules.acquisition.acq_orders.models import AcqOrderStatus
 from rero_ils.modules.acquisition.acq_receipt_lines.api import AcqReceiptLinesSearch
+from rero_ils.modules.acquisition.acq_receipt_lines.dumpers import AcqReceiptLineESDumper
 from rero_ils.modules.acquisition.acq_receipts.api import (
     AcqReceipt,
     AcqReceiptLine,
@@ -35,6 +39,7 @@
 from rero_ils.modules.acquisition.acq_receipts.models import (
     AcqReceiptLineCreationStatus,
 )
+from rero_ils.modules.documents.api import Document
 from rero_ils.modules.notifications.api import Notification
 from rero_ils.modules.notifications.models import (
     NotificationChannel,
@@ -64,6 +69,7 @@ def test_acquisition_reception_workflow(
     document,
 ):
     """Test complete acquisition workflow."""
+    assert "acq_order_lines" not in document.get_links_to_me()
 
     def assert_account_data(accounts):
         """Assert account informations."""
@@ -286,6 +292,8 @@ def assert_account_data(accounts):
     }
     assert_account_data(manual_controls)
 
+    assert document.get_links_to_me() == {"acq_order_lines": 6}
+
     # STEP 3 :: UPDATE ORDER LINES
     #   * Cancel some order lines and change some quantities --> make sure
     #     calculations still good
@@ -363,6 +371,8 @@ def assert_account_data(accounts):
     assert order_line_1.unreceived_quantity == 5
     assert order_line_1.status == AcqOrderLineStatus.APPROVED
 
+    assert document.get_links_to_me() == {"acq_order_lines": 4}
+
     # STEP 4 :: SEND THE ORDER
     #    * Test send order and make sure statuses are up to date.
     #      - check order lines (status, order-date)
@@ -611,6 +621,48 @@ def assert_account_data(accounts):
     }
     assert_account_data(manual_controls)
 
+    # All order lines are now RECEIVED or CANCELLED (no blocking statuses remain),
+    # so the document should have no links preventing deletion.
+    assert "acq_order_lines" not in document.get_links_to_me()
+    assert document.reasons_not_to_delete() == {}
+
+    # STEP 7.5: DOCUMENT DELETION + RE-INDEXATION WITH DELETED DOCUMENT
+    #   * Delete the document to validate the deletion path and
+    #     exercise the guards:
+    #       - AcqOrderLine.replace_refs(): must not raise JsonRefError when
+    #         the order line is re-indexed after document deletion.
+    #       - AcqOrderLineESDumper: must fall back to {"pid": ...} only.
+    #       - AcqReceiptLineESDumper: same fallback for receipt-line ES dumps.
+    doc_pid = document.pid
+    url = url_for("invenio_records_rest.doc_item", pid_value=doc_pid)
+    res = client.delete(url)
+    assert res.status_code == 204
+    assert Document.get_record_by_pid(doc_pid) is None
+
+    # replace_refs() must return the document stub without raising JsonRefError.
+    terminal_line = AcqOrderLine.get_record_by_pid(order_line_5.pid)
+    replaced = terminal_line.replace_refs()
+    assert replaced["document"] == {"pid": doc_pid, "type": "doc"}
+
+    # AcqOrderLineESDumper must fall back to pid-only when document is absent.
+    dumped_ol = terminal_line.dumps(dumper=AcqOrderLineESDumper())
+    assert dumped_ol["document"] == {"pid": doc_pid}
+
+    # AcqReceiptLineESDumper must also fall back to pid-only.
+    receipt_line = next(receipt_2.get_receipt_lines())
+    dumped_rl = receipt_line.dumps(dumper=AcqReceiptLineESDumper())
+    assert dumped_rl["document"] == {"pid": doc_pid}
+
+    # Full re-indexation (the _prepare_record / replace_refs path) must not raise.
+    terminal_line.reindex()
+
+    # extended_validation must reject any attempt to un-cancel a CANCELLED
+    # order line whose document is gone (deleted-document guard).
+    cancelled_line = AcqOrderLine.get_record_by_pid(order_line_3.pid)
+    assert cancelled_line.get("is_cancelled")  # sanity: must be CANCELLED
+    with pytest.raises(ValidationError, match="deleted document"):
+        cancelled_line.update({"is_cancelled": False})
+
     # TEST 8: DELETE RECEIPTS
     #   * Delete the second receipt. This will also delete the related receipt
     #     lines. The order status must remain to PARTIALLY_RECEIVED.