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
@@ -143,6 +143,29 @@ 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:
+            document = extracted_data_from_ref(doc_ref, data="record")
+            if document:
+                data["document"] = dict(document)
+            else:
+                doc_pid = extracted_data_from_ref(doc_ref)
+                data["document"] = {"pid": doc_pid}
+        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,16 @@ 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"] = {
+                "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": 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
@@ -64,6 +64,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 +287,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 +366,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 +616,11 @@ 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() == {}
+
     # TEST 8: DELETE RECEIPTS
     #   * Delete the second receipt. This will also delete the related receipt
     #     lines. The order status must remain to PARTIALLY_RECEIVED.