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
14 changes: 9 additions & 5 deletions openapi/specs/shipment-exceptions-acceptance-criteria.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`.
1. **Overdue, unreceived, inbound shipment is included.** A shipment with
`destination` = the session warehouse or one of its child locations,
`expectedDeliveryDate` 3 days in the past and derived status `SHIPPED`
appears in `data`, keyed by its `shipmentNumber`.
appears in `data`, identified by matching `shipmentNumber`.
2. **Future expected delivery date is excluded.** A shipment with
`expectedDeliveryDate` 3 days in the future does not appear in `data` for
any page of the result set.
Expand All @@ -29,8 +29,10 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`.
appear, and no row in `data` has `status` = `RECEIVED`.
5. **Received-or-delivered shipments are excluded.** A shipment with a past
`expectedDeliveryDate` that has either a `RECEIVED` or `DELIVERED` shipment
event (`dateDelivered()` non-null) does not appear, even when its derived
status is `PARTIALLY_RECEIVED`.
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`.
Comment on lines +32 to +35

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

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.

Confirmed, thanks — that matches the line references this change is built on, no action needed.

6. **Null expected delivery date is excluded.** A shipment with
`expectedDeliveryDate` null and an `expectedShippingDate` well in the past
does not appear, and every row in `data` has a non-null
Expand All @@ -51,8 +53,10 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`.
10. **Partially received shipments are included.** A shipment with a past
`expectedDeliveryDate`, derived status `PARTIALLY_RECEIVED`, and neither a
`RECEIVED` nor a `DELIVERED` event appears, because part of the goods is
still outstanding. The received/delivered exclusion takes precedence when
either event exists (see decision 2).
still outstanding (the `actualDeliveryDate` fallback is transient and
derives from `RECEIVED`, so `RECEIVED`/`DELIVERED` events are the only
signals). The received/delivered exclusion takes precedence when either
event exists (see decision 2).

## daysLate

Expand Down
35 changes: 22 additions & 13 deletions openapi/specs/shipment-exceptions-api.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,15 @@ info:

NOTE ON INTENT: every other spec under openapi/specs/ is descriptive - it
pins the CURRENT behavior of an existing *ApiController (see
openapi/README.md). This one is different: it is a contract-first spec for
a NEW endpoint that does not exist yet, agreed before any implementation.
The controller (org.pih.warehouse.api.ShipmentExceptionApiController) and
its URL mapping are proposed, not present in
grails-app/controllers/org/pih/warehouse/UrlMappings.groovy.
openapi/README.md). This one was authored contract-first, and the endpoint
has since been implemented at org.pih.warehouse.api.ShipmentExceptionApiController
with a UrlMappings.groovy entry for "/api/shipments/exceptions/overdue".


PATH CHOICE: the path deliberately has three segments after /api so it
cannot be swallowed by the existing generic mappings, which are declared
ahead of any new mapping would matter: "/api/${resource}s/$id" and the
PATH CHOICE: the path deliberately has three segments after /api.
Declaration order in UrlMappings.groovy could matter for a two-segment
path because existing generic mappings might swallow it, but it does not
matter for this three-segment path: "/api/${resource}s/$id" and the
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
catch-all "/api/$action/$id?" (ApiController) both match at most two
segments after /api, while "/api/${resource}s/$id/status" has three
segments but requires the literal third segment "status". The
Expand Down Expand Up @@ -58,7 +57,8 @@ paths:
locations. Received/delivered exclusion is based on dateDelivered(),
which resolves a RECEIVED event and falls back to a DELIVERED event, so
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).
Comment on lines 59 to +61

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

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.

Matches my own cross-check — nothing to change here.



daysLate is the calendar-day difference in the server time zone:
Expand Down Expand Up @@ -196,21 +196,27 @@ components:
required:
- id
- shipmentNumber
- name
- origin
- destination
- expectedShippingDate
Comment thread
staging-devin-ai-integration[bot] marked this conversation as resolved.
Resolved
Comment on lines +199 to +202

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

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.

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.

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

Comment on lines +199 to +202

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

🔍 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).

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.

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.

- expectedDeliveryDate
- daysLate
- status
- shipmentItemCount

@staging-devin-ai-integration staging-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.

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

Open in Devin Review (Staging)

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

Debug

Playground

properties:
id:
$ref: '../components/common.yaml#/components/schemas/Id'
shipmentNumber:
type: string
description: Human-readable shipment number shown on the shipment screens.
description: >
Human-readable shipment number shown on the shipment screens. The
underlying domain column is nullable, but ShipmentService.saveShipment
generates one via shipmentIdentifierService.generate for every
created shipment, so this field is required here.
name:
type: string
nullable: true
description: Shipment name (nullable in the domain).
description: Required shipment name.
shipmentType:
type: string
nullable: true
Expand Down Expand Up @@ -250,7 +256,10 @@ components:
RECEIVED nor a DELIVERED event.
shipmentItemCount:
type: integer
description: Number of shipment items, for context on the exception list.
description: >-
Formula-derived item count for the exception list. The endpoint
always populates it, falling back to the item collection size and
then 0, so it is always present.

LocationRef:
type: object
Expand Down
Loading