From 185d9701753c899c262deb7170dc18297d7b5366 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 19 Aug 2026 23:29:59 +0000 Subject: [PATCH 1/4] feature: correct shipment exception schema facts Co-Authored-By: Matthew Guerra --- ...shipment-exceptions-acceptance-criteria.md | 14 ++++++++----- openapi/specs/shipment-exceptions-api.yaml | 20 ++++++++++++------- 2 files changed, 22 insertions(+), 12 deletions(-) diff --git a/openapi/specs/shipment-exceptions-acceptance-criteria.md b/openapi/specs/shipment-exceptions-acceptance-criteria.md index 3672385db4e..7dac0376016 100644 --- a/openapi/specs/shipment-exceptions-acceptance-criteria.md +++ b/openapi/specs/shipment-exceptions-acceptance-criteria.md @@ -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. @@ -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`. 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 @@ -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 diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml index c999ff23124..35be9f7b077 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -16,9 +16,10 @@ info: grails-app/controllers/org/pih/warehouse/UrlMappings.groovy. - 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 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 @@ -58,7 +59,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). daysLate is the calendar-day difference in the server time zone: @@ -196,8 +198,10 @@ components: required: - id - shipmentNumber + - name - origin - destination + - expectedShippingDate - expectedDeliveryDate - daysLate - status @@ -209,8 +213,7 @@ components: description: Human-readable shipment number shown on the shipment screens. name: type: string - nullable: true - description: Shipment name (nullable in the domain). + description: Required shipment name. shipmentType: type: string nullable: true @@ -250,7 +253,10 @@ components: RECEIVED nor a DELIVERED event. shipmentItemCount: type: integer - description: Number of shipment items, for context on the exception list. + description: >- + Number of shipment items, for context on the exception list. + Derived from the denormalized count, falling back to the item + collection size, so it is always present. LocationRef: type: object From c05d0675d7bfece518c4e183e9d0f333a65ddaf2 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:25:29 +0000 Subject: [PATCH 2/4] feature: refine shipment exception field wording Co-Authored-By: Matthew Guerra --- openapi/specs/shipment-exceptions-api.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml index 35be9f7b077..3c0d1f50b6f 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -210,7 +210,11 @@ components: $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 description: Required shipment name. @@ -254,9 +258,9 @@ components: shipmentItemCount: type: integer description: >- - Number of shipment items, for context on the exception list. - Derived from the denormalized count, falling back to the item - collection size, so it is always present. + 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 From 4aa477cf985d8fc459f213a02e01d5ad1f257942 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:28:43 +0000 Subject: [PATCH 3/4] feature: align shipment item count schema requiredness Co-Authored-By: Matthew Guerra --- openapi/specs/shipment-exceptions-api.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml index 3c0d1f50b6f..494e6a429bc 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -205,6 +205,7 @@ components: - expectedDeliveryDate - daysLate - status + - shipmentItemCount properties: id: $ref: '../components/common.yaml#/components/schemas/Id' From 6a76d4253f3f98fd109ae328878822c0a5241fa3 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 01:32:21 +0000 Subject: [PATCH 4/4] feature: update shipment exception controller wording Co-Authored-By: Matthew Guerra --- openapi/specs/shipment-exceptions-api.yaml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml index 494e6a429bc..995cac38ce0 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -9,11 +9,9 @@ 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.