Skip to content

feature: carrierName on overdue inbound shipments (spec → red test → implementation) - #4

Open
matthewguerra-cog wants to merge 5 commits into
spec-demo-basefrom
devin/1787199000-carrier-name-spec
Open

matthewguerra-cog wants to merge 5 commits into
spec-demo-basefrom
devin/1787199000-carrier-name-spec

Conversation

@matthewguerra-cog

@matthewguerra-cog matthewguerra-cog commented Aug 20, 2026 •

Copy link
Copy Markdown
Collaborator

✨ Description of Change

Link to GitHub issue or Jira ticket: n/a (Act 4 of the spec-driven-development rehearsal)

Description:

carrierName was added to the overdue-inbound contract first, then proven RED by a contract test, then implemented. The commit history is the story:

commit beat
656be62 spec + acceptance criterion (no code)
96f8dbb contract test for criterion 31 (RED)
a68e999 test fixup: match rows by shipment id (see caveats)
3bbfe0c implementation: service serialization + Carrier column
ddd2bd6 review follow-up: carrierName added to the schema's required list

1. Spec diff summary

openapi/specs/shipment-exceptions-api.yaml (version 0.1.0 → 0.2.0)

  • info.description now records the domain fact behind the field: Shipment.carrier is a nullable core.Person ("the person or organization that actually carries the goods from A to B") whose display name is Person.getName(), already serialized as carrier: {id, name, email} by ShipmentApiController.
  • The endpoint description states that every row carries carrierName, null when no carrier is recorded.
  • OverdueInboundShipment gains:
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 ... Not sortable or filterable
    in this version.
  • carrierName is also listed in required (while staying nullable: true), so the spec-based validation in the contract harness enforces criterion 31's "every row has the key" (added in ddd2bd6 after review).

openapi/specs/shipment-exceptions-acceptance-criteria.md

  • New criterion 31 — carrier set ⇒ carrierName == that person's display name; otherwise-identical shipment with no carrier ⇒ carrierName == null; every row in data has the key. (Numbered 31 so the existing criteria/test names stay stable.)
  • New decision 6 — the carrier is Shipment.carrier; shipmentMethod.shipper (a Shipper used for tracking links) and the free-text driverName are deliberately not used; no new column and no migration; carrierName is not sortable/filterable.

Redocly lint: clean across all specs (Woohoo! Your API descriptions are valid. 🎉).

2. RED contract-test output

Run against the app built from the pre-change implementation (image openboxes/openboxes:java21-prechange, i.e. spec-demo-base code) with the new test present:

test_shipment_exceptions_api_contract.py::test_criterion_31_carrier_name_reports_the_shipment_carrier FAILED [ 93%]

=================================== FAILURES ===================================
_________ test_criterion_31_carrier_name_reports_the_shipment_carrier __________
            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}"
E           AssertionError: rows without a carrierName key: ['198RHP', '198VJV', '259HKA', '382KPM', '452JNV', '501YJR', '550QUZ', '561DBS', '581VXK', '707EMG', '737XUP', '878KKV', '893NHQ', '898XHV', '926SXC', '959KRT', '991YHA']
E           assert not ['198RHP', '198VJV', '259HKA', '382KPM', '452JNV', '501YJR', ...]

test_shipment_exceptions_api_contract.py:385: AssertionError
=========================== short test summary info ============================
FAILED test_shipment_exceptions_api_contract.py::test_criterion_31_carrier_name_reports_the_shipment_carrier
========================= 1 failed, 30 passed in 6.51s =========================

The test seeds two overdue inbound shipments via the API (one gets a carrier via POST /api/shipments/{id}/tracking), reads GET /api/shipments/exceptions/overdue, and cleans up after itself.

3. Implementation summary

  • ShipmentExceptionService.getOverdueInboundShipments — each row map gains carrierName: shipment.carrier?.name. No query, domain, or schema change: carrier is an existing nullable association.
  • StockMovementInboundTable.jsx — the overdue column set gains a non-sortable Carrier column on carrierName, rendered with TableCell ... defaultValue="None" so an absent carrier reads as None.
  • messages.properties — react.stockMovement.column.carrier.label=Carrier.
  • docs/api-guide/ — no change: the overdue endpoint is not documented there (the spec is its documentation).

4. GREEN output

Same test, same suite, against the app rebuilt with the implementation (./gradlew prepareDocker -Dgrails.env=prod, image openboxes/openboxes:java21-local):

test_shipment_exceptions_api_contract.py::test_criterion_31_carrier_name_reports_the_shipment_carrier PASSED [ 93%]

============================== 31 passed in 2.31s ==============================

Redocly lint after implementation: clean (~9s). ESLint on the touched JSX: 0 errors, 12 warnings, all pre-existing react/jsx-props-no-spreading in that file.


📷 Screenshots & Recordings

Overdue view on the Inbound Movement List, scrolled to the new column. Demo overdue with carrier shows Ms Superuser; the carrier-less rows show None.

Overdue view with Carrier column


Not verified, and why

  • Jest suite — cannot run in this environment: all 41 suites fail to transform with [BABEL] Requires Babel "^7.22.0 || >8.0.0-alpha <8.0.0-beta", but was loaded with "7.21.8". This is a pre-existing dependency-resolution problem in the installed node_modules (it fails identically for files this PR does not touch), not a regression from this change. ESLint was run instead.
  • Test fixup commit a68e999 — the RED test originally resolved shipment numbers via GET /api/shipments/{id}, which returns 500 on this branch as soon as a carrier is set: IllegalArgumentException: object is not an instance of declaring class at ShipmentApiController.getWizardDetails (the carrier: [... email: shipment.carrier.email] line). That is a pre-existing bug in an endpoint this PR does not touch and is left alone; the test now matches rows by shipment id instead. The RED output quoted above was re-captured against the pre-change image using this final version of the test, so RED and GREEN differ only by the implementation commit.
  • Carrier column sorting/filtering — deliberately out of scope per decision 6, so not exercised.

Devin-Org: engineering

Link to Devin session: https://app.devin.ai/sessions/dc4ff02face84bcdb122707383aa7e6a
Requested by: @matthewguerra-cog


Devin Review

Status Commit
🟢 Reviewed ddd2bd6
Open in Devin Review (Staging)

devin-ai-integration Bot and others added 4 commits August 20, 2026 01:32
…pec only)

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
…red)

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
…t 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 <matthew.guerra@cognition.ai>
…ue inbound list

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
@matthewguerra-cog matthewguerra-cog self-assigned this Aug 20, 2026
@devin-ai-integration

Copy link
Copy Markdown

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment, CI, and merge conflict monitoring

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Devin Review found 5 potential issues.

Open in Devin Review

Comment on lines +262 to +270
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.

@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.

Comment on lines +379 to +393
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}"
)

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.

Comment on lines +367 to +397
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}"
)
finally:
_delete_shipment(client, with_carrier)
_delete_shipment(client, without_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: 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.

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.

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.

@staging-devin-ai-integration staging-devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Devin Review found 1 potential issue.

Open in Devin Review (Staging)
Debug

Playground

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.

🔍 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

…rces criterion 31

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
@devin-ai-integration

Copy link
Copy Markdown

CI note: run-backend-tests (mysql:8.0.36) failed with 12 integrationTest failures, all in LocationGroupApiSpec / RecordStockApiSpec / CategoryApiCRUDSpec / ProductApiCRUDSpec / ProductClassificationApiCRUDSpec. Every one fails in the shared ApiSpec.createMainProduct setup, where POST /api/products returns 500 from a fixture race:

SQLIntegrityConstraintViolationException occurred when processing request: [POST] /openboxes/api/products
Cannot add or update a child row: a foreign key constraint fails
  (`test`.`product`, CONSTRAINT `FKED8DCCEFEF4C770D` FOREIGN KEY (`category_id`) REFERENCES `category` (`id`) ...)

Not caused by this PR: the diff touches only the shipment-exceptions spec/criteria, ShipmentExceptionService, the inbound React table, one message key, and a Python contract test — none of which are exercised by those specs. The same job passed on the previous head 3bbfe0c of this branch, and the same fixture failure appeared on the unrelated branch devin/1787182177-shipment-exceptions-spec-fixups (4aa477c, LocalizationApiSpec + LocationGroupApiSpec), so it is an intermittent shared-fixture failure. I do not have permission to re-run the failed job via the API; a maintainer re-run should clear it. All characterization, openapi-lint, api-snapshot, and frontend jobs pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant