From 656be62c61bf54c7165e53ff9acad5614c91de51 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:32:25 +0000 Subject: [PATCH 1/5] feature: add carrierName to the overdue inbound shipments contract (spec only) Co-Authored-By: Matthew Guerra --- ...shipment-exceptions-acceptance-criteria.md | 22 +++++++++++++++++ openapi/specs/shipment-exceptions-api.yaml | 24 +++++++++++++++++-- 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/openapi/specs/shipment-exceptions-acceptance-criteria.md b/openapi/specs/shipment-exceptions-acceptance-criteria.md index 3672385db4e..eb7aa768e3a 100644 --- a/openapi/specs/shipment-exceptions-acceptance-criteria.md +++ b/openapi/specs/shipment-exceptions-acceptance-criteria.md @@ -108,6 +108,19 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`. 28. **Unsupported sort values are rejected.** `sort=carrier` responds `400` (the parameter is a closed enum in the contract). +## Carrier + +(Numbered after the auth criteria so the existing criterion numbers, and the +contract tests named after them, stay stable.) + +31. **carrierName reports the shipment carrier and is null when unset.** For a + qualifying overdue shipment whose `carrier` is set to a person, the row + carries `carrierName` equal to that person's display name + (`Person.getName()`, i.e. "firstName lastName"); for an otherwise + identical shipment with no carrier, the row carries `carrierName` = null. + Every row in `data` has the `carrierName` key. (`Shipment.carrier` is a + nullable `Person` association — see decision 6.) + ## Auth 29. **A session is required.** Called without the `JSESSIONID` cookie, the @@ -131,3 +144,12 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`. midnight. There is no client-supplied `asOfDate`. 5. **Overdue vs. never shipped — decided.** Shipments in derived status `PENDING` that are past due are included. +6. **Carrier identity — decided.** The carrier is `Shipment.carrier`, the + nullable `Person` association documented in the domain as "the person or + organization that actually carries the goods from A to B", and already + serialized as `carrier: {id, name, email}` by `ShipmentApiController`. The + exception rows expose only its display name as `carrierName`; the + `shipmentMethod.shipper` (a `Shipper` reference used for tracking links) + and the free-text `driverName` are deliberately not used, and no new column + or migration is introduced. `carrierName` is not sortable or filterable in + this version. diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml index c999ff23124..201e400db7a 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -37,8 +37,13 @@ info: PARTIALLY_RECEIVED, RECEIVED). Row status is derived from getStatus(), which can return PENDING, SHIPPED, PARTIALLY_RECEIVED or RECEIVED; CREATED is unreachable via getStatus(). There is no CANCELLED shipment status; a - cancellation is recorded as a shipment event with EventCode.CANCELLED. - version: 0.1.0 + cancellation is recorded as a shipment event with EventCode.CANCELLED. The + party responsible for carrying the goods is Shipment.carrier, a nullable + association to core.Person ("the person or organization that actually + carries the goods from A to B"), whose display name is Person.getName() + ("firstName lastName"); ShipmentApiController already serializes it as + carrier: {id, name, email}. + version: 0.2.0 servers: - url: http://localhost:8080/openboxes description: Local Docker baseline (docs/migration/RUNNING_LOCALLY.md) @@ -69,6 +74,12 @@ paths: Rows with daysLate below minDaysLate are excluded. + Each row also carries carrierName, the display name of the party + responsible for carrying the shipment (Shipment.carrier, a nullable + Person association), so a manager can chase the right carrier straight + from the exception list. It is null when no carrier is recorded. + + The result set is paginated with the standard max/offset params and sorted by daysLate descending (most overdue first) by default. max defaults to 50 when omitted; values above 500 are rejected with 400. @@ -248,6 +259,15 @@ components: received or delivered shipments are excluded; a PARTIALLY_RECEIVED shipment is reported only when it has neither a RECEIVED nor a DELIVERED event. + carrierName: + type: string + nullable: true + description: > + Display name of the carrier responsible for the shipment, from + Shipment.carrier.name (Person.getName(), i.e. "firstName + lastName"). Null when the shipment has no carrier: the carrier + association is nullable in the domain and is not required to send + a shipment. Not sortable or filterable in this version. shipmentItemCount: type: integer description: Number of shipment items, for context on the exception list. From 96f8dbbfccfd9923bc17e224ee0b206f1fbd5e52 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:33:45 +0000 Subject: [PATCH 2/5] feature: contract test for carrierName on overdue inbound shipments (red) Co-Authored-By: Matthew Guerra --- .../test_shipment_exceptions_api_contract.py | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/characterization/contract/test_shipment_exceptions_api_contract.py b/characterization/contract/test_shipment_exceptions_api_contract.py index e5ae2530398..0799772edc9 100644 --- a/characterization/contract/test_shipment_exceptions_api_contract.py +++ b/characterization/contract/test_shipment_exceptions_api_contract.py @@ -355,6 +355,43 @@ def test_criterion_28_unsupported_sort_is_rejected(client): assert response.json()["errorCode"] == 400 +def _set_carrier(client, shipment_id, person_id): + response = client.request( + "POST", f"/api/shipments/{shipment_id}/tracking", + json={"carrierId": person_id}, + ) + assert response.status_code == 200 + return response + + +def test_criterion_31_carrier_name_reports_the_shipment_carrier(client): + """Criterion 31: carrierName is the carrier display name, null when unset.""" + person = client.get_json("/api/persons", params={"max": 1})["data"][0] + expected_delivery = (date.today() - timedelta(days=4)).isoformat() + with_carrier = _create_shipment( + client, f"{TEST_PREFIX} carrier", expected_delivery=expected_delivery, + ) + without_carrier = _create_shipment( + client, f"{TEST_PREFIX} no carrier", expected_delivery=expected_delivery, + ) + try: + _set_carrier(client, with_carrier, person["id"]) + rows = {row["shipmentNumber"]: row for row in _rows(client, max=500)["data"]} + missing = sorted(number for number, row in rows.items() if "carrierName" not in row) + assert not missing, f"rows without a carrierName key: {missing}" + carrier_row = rows[_shipment_number(client, with_carrier)] + assert carrier_row["carrierName"] == person["name"], ( + f"expected carrierName {person['name']!r}, got {carrier_row['carrierName']!r}" + ) + no_carrier_row = rows[_shipment_number(client, without_carrier)] + assert no_carrier_row["carrierName"] is None, ( + f"expected null carrierName, got {no_carrier_row['carrierName']!r}" + ) + finally: + _delete_shipment(client, with_carrier) + _delete_shipment(client, without_carrier) + + def test_criterion_29_session_is_required(): """Criterion 29: an unauthenticated session returns 401.""" from obx import BASE_URL From a68e99960223b153232f69697face8e95154fd17 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:42:57 +0000 Subject: [PATCH 3/5] feature: match overdue rows by shipment id in the carrierName contract test Avoids GET /api/shipments/{id}, which returns 500 on this branch once a carrier is set, and keeps the assertion focused on the overdue payload. Co-Authored-By: Matthew Guerra --- .../test_shipment_exceptions_api_contract.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/characterization/contract/test_shipment_exceptions_api_contract.py b/characterization/contract/test_shipment_exceptions_api_contract.py index 0799772edc9..46595d43438 100644 --- a/characterization/contract/test_shipment_exceptions_api_contract.py +++ b/characterization/contract/test_shipment_exceptions_api_contract.py @@ -376,14 +376,18 @@ def test_criterion_31_carrier_name_reports_the_shipment_carrier(client): ) try: _set_carrier(client, with_carrier, person["id"]) - rows = {row["shipmentNumber"]: row for row in _rows(client, max=500)["data"]} - missing = sorted(number for number, row in rows.items() if "carrierName" not in row) + rows = {row["id"]: row for row in _rows(client, max=500)["data"]} + missing = sorted( + rows[shipment_id]["shipmentNumber"] + for shipment_id in rows + if "carrierName" not in rows[shipment_id] + ) assert not missing, f"rows without a carrierName key: {missing}" - carrier_row = rows[_shipment_number(client, with_carrier)] + carrier_row = rows[with_carrier] assert carrier_row["carrierName"] == person["name"], ( f"expected carrierName {person['name']!r}, got {carrier_row['carrierName']!r}" ) - no_carrier_row = rows[_shipment_number(client, without_carrier)] + no_carrier_row = rows[without_carrier] assert no_carrier_row["carrierName"] is None, ( f"expected null carrierName, got {no_carrier_row['carrierName']!r}" ) From 3bbfe0cb85608e03b307c08a104c1f375f1b9f34 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:42:57 +0000 Subject: [PATCH 4/5] feature: serialize carrierName and show a Carrier column on the overdue inbound list Co-Authored-By: Matthew Guerra --- grails-app/i18n/messages.properties | 1 + .../pih/warehouse/shipping/ShipmentExceptionService.groovy | 1 + .../stock-movement/inbound/StockMovementInboundTable.jsx | 6 ++++++ 3 files changed, 8 insertions(+) diff --git a/grails-app/i18n/messages.properties b/grails-app/i18n/messages.properties index eccb253c8c1..53bb6a4a784 100644 --- a/grails-app/i18n/messages.properties +++ b/grails-app/i18n/messages.properties @@ -4305,6 +4305,7 @@ react.stockMovement.column.name.label=Name react.stockMovement.column.dateCreated.label=Date Created react.stockMovement.column.expectedReceiptDate=Expected Receipt Date react.stockMovement.column.daysLate.label=Days Late +react.stockMovement.column.carrier.label=Carrier react.stockMovement.overdue.label=Overdue react.stockMovement.outbound.filters.requisitionStatus.label=Requisition Status react.stockMovement.outbound.filters.requestType.label=Request type diff --git a/grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy b/grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy index a35a0cd18ba..1b8270dd060 100644 --- a/grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy +++ b/grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy @@ -65,6 +65,7 @@ class ShipmentExceptionService { destination : locationReference(shipment.destination), expectedShippingDate : shipment.expectedShippingDate, expectedDeliveryDate : shipment.expectedDeliveryDate, + carrierName : shipment.carrier?.name, daysLate : daysLate, status : shipment.status?.code?.name(), shipmentItemCount : shipment.shipmentItemCount ?: shipment.shipmentItems?.size() ?: 0, diff --git a/src/js/components/stock-movement/inbound/StockMovementInboundTable.jsx b/src/js/components/stock-movement/inbound/StockMovementInboundTable.jsx index 63b3a1ae052..26075b37342 100644 --- a/src/js/components/stock-movement/inbound/StockMovementInboundTable.jsx +++ b/src/js/components/stock-movement/inbound/StockMovementInboundTable.jsx @@ -255,6 +255,12 @@ const StockMovementInboundTable = ({ accessor: 'daysLate', width: 100, Cell: (row) => (), + }, { + Header: , + accessor: 'carrierName', + sortable: false, + minWidth: 180, + Cell: (row) => (), }] : []), ], [overdue, shipmentStatuses, translate]); From ddd2bd655f407fbb18ed1d60c75fc39cbf7a2863 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:50:28 +0000 Subject: [PATCH 5/5] feature: require carrierName on overdue inbound rows so the spec enforces criterion 31 Co-Authored-By: Matthew Guerra --- openapi/specs/shipment-exceptions-api.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml index 201e400db7a..9361e00a6c8 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -212,6 +212,7 @@ components: - expectedDeliveryDate - daysLate - status + - carrierName properties: id: $ref: '../components/common.yaml#/components/schemas/Id'