Repository navigation
Correct domain-fact errors in the overdue inbound shipments contract - #2
matthewguerra-cog wants to merge 4 commits into
Conversation
🤖 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:
|
Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
7c39723 to
185d970
Compare
| - name | ||
| - origin | ||
| - destination | ||
| - expectedShippingDate |
There was a problem hiding this comment.
📝 Info: shipmentNumber requiredness is an endpoint guarantee that legacy rows can break
The new note explains required for shipmentNumber from ShipmentService.saveShipment generating one. The service simply passes through shipment.shipmentNumber (grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy:62) and the domain column is nullable: true (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:167), so any shipment created through another path (imports, data migration, direct SQL) would yield a null value for a field the contract declares required. Same class of risk applies to status, which is emitted as shipment.status?.code?.name() and declared required with a closed enum.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Good catch on the constraint — shipmentNumber(nullable: true, ...) (Shipment.groovy:171) is indeed looser than the contract.
Keeping it required and non-nullable, because for this endpoint the response value is always populated: ShipmentService.saveShipment assigns shipment.shipmentNumber = shipmentIdentifierService.generate(shipment) (:508) on every shipment created through the service, and the merged ShipmentExceptionService passes it straight through. The domain column is nullable only to accommodate direct saves that bypass that path, which is not a shape a warehouse manager's overdue list should be written against.
I am adding a one-line note to the field description recording that the column is nullable but populated by shipmentIdentifierService, so nobody later reads required as a domain-level guarantee. Flagging for @matthewguerra-cog: if you'd rather the contract mirror the raw domain constraint here, say so and I'll loosen it.
There was a problem hiding this comment.
Agreed on the mechanism — that's exactly why the note calls it an endpoint guarantee rather than a domain one, and I'm leaving shipmentNumber required: a null shipment number on an overdue-shipment row is unactionable for the warehouse manager (there is nothing to chase the carrier with), so a legacy row like that is a data problem to surface, not a response shape to bless. @matthewguerra-cog can overrule me if he'd rather the contract mirror the raw column.
On status: that one isn't the same risk. Shipment.getStatus() has no null path — every branch returns a ShipmentStatus with a non-null code, with PENDING as the unconditional else — so no creation path can produce a null status. Detail in the other thread.
| event (`dateDelivered()` non-null; its `actualDeliveryDate` fallback is | ||
| transient and derives from the `RECEIVED` event, so `RECEIVED`/`DELIVERED` | ||
| events are the only signals) does not appear, even when its derived status | ||
| is `PARTIALLY_RECEIVED`. |
There was a problem hiding this comment.
📝 Info: dateDelivered()/actualDeliveryDate claim verified against the domain
Checked the corrected claim: dateDelivered() resolves the RECEIVED event, falls back to DELIVERED, then to actualDeliveryDate (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:677-683), and actualDeliveryDate is a transient (:108) whose getter returns the RECEIVED event date (:400-403). So the new wording — RECEIVED/DELIVERED events being the only exclusion signals, with no standalone column to seed — matches the domain, and the fallback is indeed redundant.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Confirmed, thanks — that matches the line references this change is built on, no action needed.
Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
| - name | ||
| - origin | ||
| - destination | ||
| - expectedShippingDate |
There was a problem hiding this comment.
🔍 status is required and enum-constrained but derived from a nullable getter
Unchanged by this PR, but relevant to its stated goal of aligning required/nullable claims with the implementation: the service emits status: shipment.status?.code?.name(), which can be null if getStatus() returns null, yet status remains in required with a closed enum. Since this PR audited the other required fields, this one may deserve the same treatment (either document the guarantee or make the field nullable).
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Checked this one and it doesn't hold: Shipment.getStatus() cannot return null. Every branch returns a freshly constructed ShipmentStatus with a non-null code — RECEIVED / PARTIALLY_RECEIVED / SHIPPED, and PENDING as the unconditional else. So shipment.status?.code?.name() always yields one of the enum names, and status stays required with the closed enum.
The enum in the contract deliberately omits CREATED for the same reason: the derived status never produces it.
Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
| - expectedDeliveryDate | ||
| - daysLate | ||
| - status | ||
| - shipmentItemCount |
There was a problem hiding this comment.
🔍 status is in required but the implementation can emit null
The status property stays in the required list with a closed enum, yet the implementation emits shipment.status?.code?.name() (grails-app/services/org/pih/warehouse/shipping/ShipmentExceptionService.groovy:69), which is null-safe navigated. Shipment.getStatus() (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:437) is generally expected to return a non-null status, but since this PR audits required/nullable claims against the implementation, it may be worth confirming that no reachable code path yields a null status for a shipment that passes the overdue/unreceived filters — otherwise the contract would declare a required, non-nullable enum for a value that can serialize as null.
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
| either event excludes a shipment even when its derived status is | ||
| PARTIALLY_RECEIVED. | ||
| PARTIALLY_RECEIVED (actualDeliveryDate is transient and derives from | ||
| the RECEIVED event, so RECEIVED/DELIVERED events are the only signals). |
There was a problem hiding this comment.
📝 Info: Claims about the merged implementation cross-check out
Verified the accuracy corrections against the merged code: the endpoint and mapping do exist (grails-app/controllers/org/pih/warehouse/UrlMappings.groovy:1262, ShipmentExceptionApiController), dateDelivered()'s ?: actualDeliveryDate tail resolves the transient getter that reads the RECEIVED event (Shipment.groovy:400-403, :677-683), so RECEIVED/DELIVERED events really are the only exclusion signals; name(nullable: false) and expectedShippingDate(nullable: false) match the new required entries; and shipmentItemCount is always populated via the ?: size() ?: 0 fallback in the service. The status enum excluding RECEIVED also holds, since getStatus() only returns RECEIVED when a RECEIVED event exists, which already forces exclusion.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Matches my own cross-check — nothing to change here.
✨ Description of Change
Link to GitHub issue or Jira ticket: follow-up to #1 (spec-driven development rehearsal, Act 1)
Description:
Accuracy-only follow-up to the contract merged in #1, now rebased on top of the merged Act 2 work (#3). No agreed behavior changes — calendar-day
daysLate, inbound-includes-child-locations, the derivedstatusenum, defaultmax50 and the no-warehouse 400 all stay exactly as approved. What changes is where the contract misstated the domain model.namewas declarednullable: truewith the comment "(nullable in the domain)". It isn't:Shipment.groovy:169declaresname(nullable: false, blank: false, maxSize: 255). Now non-nullable and inrequired.expectedShippingDatewas documented as "required in the domain, so always present" but was missing fromrequiredwhileexpectedDeliveryDatewas in it. Added, so the two agree.shipmentItemCountstays a plain non-nullable integer, now with a description that explains why: it is a Hibernate formula field constrainednullable: true(Shipment.groovy:160,206), but the mergedShipmentExceptionServiceemitsshipment.shipmentItemCount ?: shipment.shipmentItems?.size() ?: 0, so the response value is always present. (An earlier revision of this PR marked itnullable: trueoff the domain constraint alone; that would have documented a response shape the implementation never produces.)shipmentItemCountis also added torequired, so the schema matches that always-present prose.shipmentNumberkeepsrequired/non-nullable, with a note that the domain column isnullable: truebutShipmentService.saveShipmentpopulates it viashipmentIdentifierService.generate(ShipmentService.groovy:508) — sorequiredhere is an endpoint guarantee, not a domain-level one.data, keyed by itsshipmentNumber" —datais an array, so it now says "identified by matchingshipmentNumber".PATH CHOICEparagraph had a garbled clause ("declared ahead of any new mapping would matter"); rewritten. The mapping analysis itself is unchanged and still holds.?: actualDeliveryDatetail ofdateDelivered()resolves a transient whose getter derives from the RECEIVED event (static transients,Shipment.groovy:108;getActualDeliveryDate(),:400-403) — so RECEIVED/DELIVERED events are the only exclusion signals and nobody seeds a fixture against a non-existent column. This corrects a review comment that claimed a standaloneactualDeliveryDatecolumn could exclude a shipment.NOTE ON INTENTblock still said the endpoint "does not exist yet" and that the controller and URL mapping were "proposed, not present". Both landed with Overdue inbound shipments: endpoint, contract tests, and inbound list Overdue view (spec-driven Act 2) #3 (ShipmentExceptionApiController.groovy,UrlMappings.groovy:1262), so it now says the spec was authored contract-first and has since been implemented there.This PR's diff touches only
openapi/specs/shipment-exceptions-api.yamlandopenapi/specs/shipment-exceptions-acceptance-criteria.md— no controller, URL mapping, React or contract-test changes here (the implementation itself already merged in #3).Consistency with the merged implementation
Rebasing onto the merged Act 2 work also resolved a conflict in the criteria doc, where Act 2 converted the "Open questions" section into "Decisions": this PR keeps that Decisions wording and only updates the stale cross-reference in criterion 10. Every required/nullable claim in the spec was cross-checked against
ShipmentExceptionService.getOverdueInboundShipments,ShipmentExceptionApiControllerandcharacterization/contract/test_shipment_exceptions_api_contract.py; no further mismatch remains.Verification
npx @redocly/cli@1.34.2 lint --config openapi/redocly.yaml 'openapi/specs/*.yaml' openapi/components/common.yaml— 0 errors, 0 warnings (the exact command theopenapi-lintCI job runs).Open items
The naming/layout suggestions from review on #1 — renaming to
shipment-exception-api.yamland moving prescriptive specs to e.g.openapi/proposals/— are deliberately not done here; the paths were specified as-is and are yours to decide.Devin-Org: engineering
Link to Devin session: https://app.devin.ai/sessions/fac0eacd88a44c08b704f4eca4926851
Requested by: @matthewguerra-cog
Devin Review
6a76d42