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..995cac38ce0 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -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 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 +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). daysLate is the calendar-day difference in the server time zone: @@ -196,21 +196,27 @@ components: required: - id - shipmentNumber + - name - origin - destination + - expectedShippingDate - expectedDeliveryDate - daysLate - status + - shipmentItemCount 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 @@ -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