Repository navigation
feature: carrierName on overdue inbound shipments (spec → red test → implementation) - #4
matthewguerra-cog wants to merge 5 commits into
Conversation
…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>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
| 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. |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| 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}" | ||
| ) |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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) | ||
|
|
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| destination : locationReference(shipment.destination), | ||
| expectedShippingDate : shipment.expectedShippingDate, | ||
| expectedDeliveryDate : shipment.expectedDeliveryDate, | ||
| carrierName : shipment.carrier?.name, |
There was a problem hiding this comment.
🔍 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
…rces criterion 31 Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
|
CI note: Not caused by this PR: the diff touches only the shipment-exceptions spec/criteria, |
✨ Description of Change
Link to GitHub issue or Jira ticket: n/a (Act 4 of the spec-driven-development rehearsal)
Description:
carrierNamewas added to the overdue-inbound contract first, then proven RED by a contract test, then implemented. The commit history is the story:656be6296f8dbba68e9993bbfe0cddd2bd6carrierNameadded to the schema'srequiredlist1. Spec diff summary
openapi/specs/shipment-exceptions-api.yaml(version0.1.0→0.2.0)info.descriptionnow records the domain fact behind the field:Shipment.carrieris a nullablecore.Person("the person or organization that actually carries the goods from A to B") whose display name isPerson.getName(), already serialized ascarrier: {id, name, email}byShipmentApiController.carrierName, null when no carrier is recorded.OverdueInboundShipmentgains:carrierNameis also listed inrequired(while stayingnullable: true), so the spec-based validation in the contract harness enforces criterion 31's "every row has the key" (added inddd2bd6after review).openapi/specs/shipment-exceptions-acceptance-criteria.mdcarrierName== that person's display name; otherwise-identical shipment with no carrier ⇒carrierName== null; every row indatahas the key. (Numbered 31 so the existing criteria/test names stay stable.)Shipment.carrier;shipmentMethod.shipper(aShipperused for tracking links) and the free-textdriverNameare deliberately not used; no new column and no migration;carrierNameis 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-basecode) with the new test present:The test seeds two overdue inbound shipments via the API (one gets a carrier via
POST /api/shipments/{id}/tracking), readsGET /api/shipments/exceptions/overdue, and cleans up after itself.3. Implementation summary
ShipmentExceptionService.getOverdueInboundShipments— each row map gainscarrierName: shipment.carrier?.name. No query, domain, or schema change:carrieris an existing nullable association.StockMovementInboundTable.jsx— theoverduecolumn set gains a non-sortableCarriercolumn oncarrierName, rendered withTableCell ... defaultValue="None"so an absent carrier reads asNone.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, imageopenboxes/openboxes:java21-local):Redocly lint after implementation: clean (~9s). ESLint on the touched JSX: 0 errors, 12 warnings, all pre-existing
react/jsx-props-no-spreadingin that file.📷 Screenshots & Recordings
Overdue view on the Inbound Movement List, scrolled to the new column.
Demo overdue with carriershowsMs Superuser; the carrier-less rows showNone.Not verified, and why
[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 installednode_modules(it fails identically for files this PR does not touch), not a regression from this change. ESLint was run instead.a68e999— the RED test originally resolved shipment numbers viaGET /api/shipments/{id}, which returns 500 on this branch as soon as a carrier is set:IllegalArgumentException: object is not an instance of declaring classatShipmentApiController.getWizardDetails(thecarrier: [... 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.Devin-Org: engineering
Link to Devin session: https://app.devin.ai/sessions/dc4ff02face84bcdb122707383aa7e6a
Requested by: @matthewguerra-cog
Devin Review
ddd2bd6