Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions characterization/contract/test_shipment_exceptions_api_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -355,6 +355,47 @@ 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["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[with_carrier]
assert carrier_row["carrierName"] == person["name"], (
f"expected carrierName {person['name']!r}, got {carrier_row['carrierName']!r}"
)
no_carrier_row = rows[without_carrier]
assert no_carrier_row["carrierName"] is None, (
f"expected null carrierName, got {no_carrier_row['carrierName']!r}"
)
Comment on lines +379 to +393

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: New criterion-31 test can be flaky when more than 500 overdue rows exist

The test reads a single page with max=500 and then looks up its two freshly created shipments in that page (rows[with_carrier], rows[without_carrier]). On a database with more than 500 qualifying overdue inbound shipments, or if the default daysLate desc ordering pushes the 4-day-late fixtures past the page boundary, the lookups raise KeyError rather than a meaningful assertion failure. Filtering with minDaysLate/origin/destination or paging through the result set would make the assertion deterministic.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Real limitation, left as-is for now: narrowing with minDaysLate/origin would change the test whose RED output is quoted in the description, and the demo dataset has far fewer than 500 overdue inbound rows. Worth tightening (filter by minDaysLate=4 plus the seeded origin) in a follow-up if this suite ever runs against a production-sized database.

finally:
_delete_shipment(client, with_carrier)
_delete_shipment(client, without_carrier)

Comment on lines +367 to +397

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: New test is inserted between criteria 28 and 29, breaking file ordering

test_criterion_31_... is placed before test_criterion_29_session_is_required/test_criterion_30_warehouse_is_required, while the acceptance-criteria doc places the Carrier section between sorting and Auth. Purely cosmetic, but it makes the file order (28, 31, 29, 30) inconsistent with the numbering and with the rest of the suite.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intentional. The new criterion is numbered 31 rather than inserted at 29 so the existing criteria numbers and the test names derived from them stay stable; the test was appended to match. The acceptance-criteria doc notes the same reasoning.


def test_criterion_29_session_is_required():
"""Criterion 29: an unauthenticated session returns 401."""
from obx import BASE_URL
Expand Down
1 change: 1 addition & 0 deletions grails-app/i18n/messages.properties
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Only the English message bundle gains the new Carrier label

react.stockMovement.column.carrier.label is added only to grails-app/i18n/messages.properties. This matches how the adjacent react.stockMovement.column.daysLate.label was introduced (also English-only, translations flow through Crowdin), so non-English locales will fall back to the JSX defaultMessage="Carrier" until translations land.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intentional — matches how the adjacent react.stockMovement.column.daysLate.label was added; translations come through Crowdin and the JSX defaultMessage="Carrier" covers the gap meanwhile.

react.stockMovement.overdue.label=Overdue
react.stockMovement.outbound.filters.requisitionStatus.label=Requisition Status
react.stockMovement.outbound.filters.requestType.label=Request type
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ class ShipmentExceptionService {
destination : locationReference(shipment.destination),
expectedShippingDate : shipment.expectedShippingDate,
expectedDeliveryDate : shipment.expectedDeliveryDate,
carrierName : shipment.carrier?.name,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Carrier resolution adds one lazy association load per overdue row

shipment.carrier?.name dereferences a lazy Person association for each row, so the exception list issues an extra select per shipment that has a carrier (classic N+1 on top of the already per-row dateDelivered()/getMostRecentEvent() calls). Acceptable for a paginated exception report, but note that the criteria query is unpaginated at the DB level (all matching shipments are loaded and filtered in memory in grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy:32-72), so the carrier loads scale with the total overdue set rather than page size.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accurate, and accepted: carrier is an existing lazy association and the criteria query already materializes the full overdue set and filters in memory, so this adds one select per row that has a carrier. No change here — batching/join-fetching the whole query is a separate performance change, not part of this spec beat.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 Lazy carrier association is accessed the same way as the endpoint the author reports 500s

shipment.carrier?.name reads a lazily-loaded Person proxy (the criteria query at grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy:32-42 does not eager-fetch carrier). The PR description reports that ShipmentApiController.getWizardDetails (grails-app/controllers/org/pih/warehouse/api/ShipmentApiController.groovy:1632) throws IllegalArgumentException: object is not an instance of declaring class on the analogous shipment.carrier.name/.email access once a carrier is set. Person uses tablePerHierarchy false with subclasses (e.g. User), and getName() is a transient getter that reads firstName/lastName directly, which is exactly the pattern that breaks on a base-class Hibernate proxy whose real row is a subclass. The new contract test picks the first row from /api/persons (sorted lastName desc), so it may only ever exercise a plain Person. Worth verifying the overdue endpoint with a carrier that is a User subclass instance; if it throws, the whole exception page returns 500 rather than just omitting the carrier name.

Open in Devin Review (Staging)

Was this helpful? React with 👍 or 👎 to provide feedback.

Debug

Playground

daysLate : daysLate,
status : shipment.status?.code?.name(),
shipmentItemCount : shipment.shipmentItemCount ?: shipment.shipmentItems?.size() ?: 0,
Expand Down
22 changes: 22 additions & 0 deletions openapi/specs/shipment-exceptions-acceptance-criteria.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
25 changes: 23 additions & 2 deletions openapi/specs/shipment-exceptions-api.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -201,6 +212,7 @@ components:
- expectedDeliveryDate
- daysLate
- status
- carrierName
properties:
id:
$ref: '../components/common.yaml#/components/schemas/Id'
Expand Down Expand Up @@ -248,6 +260,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.
Comment on lines +263 to +271

@devin-ai-integration devin-ai-integration Bot Aug 20, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: carrierName documented as always present but not in the schema's required list

The endpoint description and acceptance criterion 31 both state that every row carries carrierName (the contract test asserts the key exists on all rows), yet carrierName is added only to properties and not to the required list of OverdueInboundShipment. Spec-based validation (check(...) in the contract test harness) therefore would not catch a regression that drops the key entirely; only the hand-written assertion in characterization/contract/test_shipment_exceptions_api_contract.py:380-385 would. If "always present, possibly null" is the intended contract, adding it to required (it is already nullable: true) would make the spec self-enforcing.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed that required would make "always present, possibly null" self-enforcing. Not changing it here because the existing OverdueInboundShipment schema lists no required properties at all, so adding only carrierName would be inconsistent; making the whole row schema required is a separate spec decision. Flagged to the author.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correction to my previous reply — I was wrong that the schema has no required list; it lists id, shipmentNumber, origin, destination, expectedDeliveryDate, daysLate, status. Fixed in ddd2bd6: carrierName is now required (and stays nullable: true), so the spec-based validation in the contract harness enforces criterion 31's "every row has the key". Redocly lint clean, suite still 31 passed.

shipmentItemCount:
type: integer
description: Number of shipment items, for context on the exception list.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,12 @@ const StockMovementInboundTable = ({
accessor: 'daysLate',
width: 100,
Cell: (row) => (<TableCell {...row} />),
}, {
Header: <Translate id="react.stockMovement.column.carrier.label" defaultMessage="Carrier" />,
accessor: 'carrierName',
sortable: false,
minWidth: 180,
Cell: (row) => (<TableCell {...row} tooltip defaultValue="None" />),
}] : []),
], [overdue, shipmentStatuses, translate]);

Expand Down
Loading