From 54ac49f2e56a87dca6b7ca8b4c99c3560619f04d 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:15:17 +0000 Subject: [PATCH 1/2] feature: contract for overdue inbound shipments API (spec only) Co-Authored-By: Matthew Guerra --- ...shipment-exceptions-acceptance-criteria.md | 121 +++++++++ openapi/specs/shipment-exceptions-api.yaml | 243 ++++++++++++++++++ 2 files changed, 364 insertions(+) create mode 100644 openapi/specs/shipment-exceptions-acceptance-criteria.md create mode 100644 openapi/specs/shipment-exceptions-api.yaml diff --git a/openapi/specs/shipment-exceptions-acceptance-criteria.md b/openapi/specs/shipment-exceptions-acceptance-criteria.md new file mode 100644 index 00000000000..d8583f5d141 --- /dev/null +++ b/openapi/specs/shipment-exceptions-acceptance-criteria.md @@ -0,0 +1,121 @@ +# Acceptance criteria — overdue inbound shipments + +Contract under review: `openapi/specs/shipment-exceptions-api.yaml`, +`GET /api/shipments/exceptions/overdue`. + +Business intent: a warehouse manager wants the list of inbound shipments whose +expected delivery date has passed and that have not been received yet, with how +many days late each one is, so carriers can be chased before a stockout. + +Each statement below is written so a single API contract test can prove it +(seed or pick the described shipment, call the endpoint, assert on the +response). "The endpoint" always means the operation above, called with a +session bound to a warehouse via `POST /api/chooseLocation/{locationId}`. + +## Inclusion / exclusion + +1. **Overdue, unreceived, inbound shipment is included.** A shipment with + `destination` = the session warehouse, `expectedDeliveryDate` 3 days in the + past and status `SHIPPED` appears in `data`, keyed by its `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. +3. **Expected delivery date of today is excluded.** A shipment whose + `expectedDeliveryDate` is today does not appear, because its floored + `daysLate` is 0, which is below the default threshold of 1. +4. **Received shipments are excluded.** A shipment with + `expectedDeliveryDate` in the past and status `RECEIVED` does not appear, + and no row in `data` has `status` = `RECEIVED`. +5. **Delivered-but-not-received shipments are excluded.** A shipment with a + past `expectedDeliveryDate` that has an actual delivery recorded + (`actualDeliveryDate` / `dateDelivered()` non-null) does not appear, even + when its status is still `SHIPPED`. +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 + `expectedDeliveryDate`. +7. **Cancelled shipments are excluded.** A shipment with a past + `expectedDeliveryDate` that carries a shipment event with + `EventCode.CANCELLED` does not appear. (There is no `CANCELLED` + `ShipmentStatusCode`; cancellation is event-based — see open question 1.) +8. **Only inbound shipments are included.** A shipment whose `origin` is the + session warehouse and whose `destination` is another location does not + appear; every row in `data` has `destination.id` equal to the session + warehouse id (or one of its child locations). +9. **Inbound is relative to the session warehouse.** The same overdue shipment + appears when the session is bound to its destination warehouse and does not + appear when the session is bound to a different warehouse. +10. **Partially received shipments are included.** A shipment with a past + `expectedDeliveryDate` and status `PARTIALLY_RECEIVED` appears, because + part of the goods is still outstanding (see open question 2). + +## daysLate + +11. **daysLate is whole days, floored.** For a shipment whose + `expectedDeliveryDate` is 2 days and 18 hours in the past, `daysLate` is + exactly 2. +12. **daysLate is never below the threshold.** Every row in `data` has + `daysLate` >= the effective `minDaysLate` (1 when the parameter is + omitted). +13. **daysLate is an integer >= 1 on every row.** No row carries a null, + fractional, zero or negative `daysLate`. + +## Filtering + +14. **Default threshold is 1 day.** Called without `minDaysLate`, the response + includes a shipment 1 day late and excludes a shipment 0 days late (due + today). +15. **minDaysLate filters.** With `minDaysLate=5`, a shipment 3 days late is + absent and a shipment 7 days late is present; every returned row has + `daysLate >= 5`. +16. **minDaysLate below 1 is rejected.** `minDaysLate=0` responds `400` with + the shared validation error body (`errorCode` 400). +17. **origin filters.** With `origin=`, every row has + `origin.id` = A, and an otherwise-qualifying shipment from a different + origin is absent. +18. **destination filters.** With `destination=`, the + qualifying shipment is present; with the id of an unrelated location, the + response is an empty `data` array with `totalCount` 0 (no error). +19. **Unknown filter ids are not errors.** With `origin=`, the + response is `200` with `data` empty and `totalCount` 0. + +## Pagination and sorting + +20. **Response envelope.** The body always carries `data`, `count`, `max`, + `offset` and `totalCount`; `count` equals `data.length`. +21. **totalCount ignores pagination.** With at least 3 qualifying shipments, + `max=1` returns `count` 1 while `totalCount` stays equal to the number of + qualifying shipments. +22. **offset pages.** With `max=1`, the row at `offset=1` differs from the row + at `offset=0`, and `offset` is echoed back unchanged. +23. **Default sort is daysLate descending.** Called without `sort`/`order`, + `daysLate` values across `data` are in non-increasing order (most overdue + first). +24. **sort is honoured.** With `sort=expectedDeliveryDate&order=asc`, the + `expectedDeliveryDate` values across `data` are in non-decreasing order. +25. **Unsupported sort values are rejected.** `sort=carrier` responds `400` + (the parameter is a closed enum in the contract). + +## Auth + +26. **A session is required.** Called without the `JSESSIONID` cookie, the + endpoint responds `401` with the shared error body. + +## Open questions for the human + +1. **Cancellation semantics.** `ShipmentStatusCode` has no `CANCELLED` value; + the only cancellation signal is a shipment event with + `EventCode.CANCELLED`. Criterion 7 assumes "cancelled" means "has a + CANCELLED event, and that event is the latest one". Confirm, or name the + signal you actually want. +2. **Partially received shipments.** Criterion 10 reports them as still + overdue. Confirm — the alternative is to exclude anything with any receipt. +3. **Inbound definition.** The contract defines inbound as + `destination` = session warehouse (or a child location of it). Confirm that + is the right notion of "relative to the requesting location", rather than, + say, any location the user has access to. +4. **Time zone / clock.** `daysLate` is floored using the server time zone. + Confirm that is acceptable, or specify a client-supplied `asOfDate`. +5. **Overdue vs. never shipped.** A shipment still in status `CREATED` or + `PENDING` past its expected delivery date is reported (it is late). Confirm + you want those, or restrict to shipments that have actually shipped. diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml new file mode 100644 index 00000000000..b6c68f9b5d7 --- /dev/null +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -0,0 +1,243 @@ +openapi: 3.0.3 +info: + title: OpenBoxes - ShipmentExceptionApiController + description: > + Read-only shipment exception reporting for warehouse managers: inbound + shipments whose expected delivery date has passed and that have not been + received yet, with how many days late each one is. + + + 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. + + + 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 + catch-all "/api/$action/$id?" (ApiController) both match at most two + segments after /api, and "/api/shipments/$id" would otherwise capture a + two-segment path such as /api/shipments/overdue with id="overdue". No + existing mapping matches /api/shipments/exceptions/overdue (all declared + "/api/shipments/$id/" mappings require a different literal third + segment), so the new mapping is unambiguous wherever it is declared. + + + Shipment data model facts this contract relies on + (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy): + expectedShippingDate is required, expectedDeliveryDate is nullable, + receipt/delivery is derived (actualDeliveryDate / dateDelivered()), and + currentStatus is a ShipmentStatusCode (CREATED, PENDING, SHIPPED, + PARTIALLY_RECEIVED, RECEIVED). There is no CANCELLED shipment status; a + cancellation is recorded as a shipment event with EventCode.CANCELLED. + version: 0.1.0 +servers: + - url: http://localhost:8080/openboxes + description: Local Docker baseline (docs/migration/RUNNING_LOCALLY.md) +security: + - cookieAuth: [] +paths: + /api/shipments/exceptions/overdue: + get: + operationId: getOverdueInboundShipments + summary: Inbound shipments that are late and not yet received + description: > + Returns one row per inbound shipment that is overdue relative to the + warehouse selected on the session (POST /api/chooseLocation/{id}): + expectedDeliveryDate is set, is in the past, the shipment has not been + received or delivered, and it has not been cancelled. Inbound means + the shipment's destination is the session warehouse. + + + daysLate is whole days only (floor of the elapsed time between + expectedDeliveryDate and "now" in the server time zone), so a shipment + due yesterday reports daysLate = 1. Rows with daysLate below + minDaysLate (default 1) are excluded, which means a shipment that is + due today is never reported. + + + The result set is paginated with the standard max/offset params and + sorted by daysLate descending (most overdue first) by default. + parameters: + - $ref: '#/components/parameters/origin' + - $ref: '#/components/parameters/destination' + - $ref: '#/components/parameters/minDaysLate' + - $ref: '#/components/parameters/sort' + - $ref: '#/components/parameters/order' + - $ref: '../components/common.yaml#/components/parameters/max' + - $ref: '../components/common.yaml#/components/parameters/offset' + responses: + '200': + $ref: '#/components/responses/OverdueInboundShipmentsOk' + '400': + $ref: '../components/common.yaml#/components/responses/ValidationError' + '401': + $ref: '../components/common.yaml#/components/responses/Unauthorized' + '500': + $ref: '../components/common.yaml#/components/responses/ServerError' + +components: + securitySchemes: + cookieAuth: + $ref: '../components/common.yaml#/components/securitySchemes/cookieAuth' + + parameters: + origin: + name: origin + in: query + required: false + description: > + Restrict to shipments sent from this origin location id. Unknown ids + yield an empty page, not an error. + schema: + $ref: '../components/common.yaml#/components/schemas/Id' + destination: + name: destination + in: query + required: false + description: > + Restrict to shipments arriving at this destination location id. Must + be the session warehouse or one of its child locations; any other + value yields an empty page. + schema: + $ref: '../components/common.yaml#/components/schemas/Id' + minDaysLate: + name: minDaysLate + in: query + required: false + description: > + Minimum whole days late a shipment must be to appear. Defaults to 1. + Values below 1 are rejected with 400. + schema: + type: integer + minimum: 1 + default: 1 + sort: + name: sort + in: query + required: false + description: Row property to sort by. Defaults to daysLate. + schema: + type: string + default: daysLate + enum: + - daysLate + - expectedDeliveryDate + - shipmentNumber + - origin + - destination + order: + name: order + in: query + required: false + description: > + Sort direction. Defaults to desc, so the most overdue shipments come + first. + schema: + type: string + default: desc + enum: [asc, desc] + + responses: + OverdueInboundShipmentsOk: + description: > + A page of overdue inbound shipments. totalCount reflects the full + filtered result set, count the number of rows in this page. + content: + application/json: + schema: + type: object + required: [data, count, max, offset, totalCount] + properties: + data: + type: array + items: + $ref: '#/components/schemas/OverdueInboundShipment' + count: + type: integer + description: Number of rows in this page. + max: + type: integer + description: Page size applied (the requested max, or the default). + offset: + type: integer + description: Zero-based index of the first row in this page. + totalCount: + type: integer + description: Total number of matching shipments, ignoring pagination. + + schemas: + OverdueInboundShipment: + type: object + description: One overdue inbound shipment. + required: + - id + - shipmentNumber + - origin + - destination + - expectedDeliveryDate + - daysLate + - status + properties: + id: + $ref: '../components/common.yaml#/components/schemas/Id' + shipmentNumber: + type: string + description: Human-readable shipment number shown on the shipment screens. + name: + type: string + nullable: true + description: Shipment name (nullable in the domain). + shipmentType: + type: string + nullable: true + description: ShipmentType name (e.g. Air, Sea, Land, Suitcase). + origin: + $ref: '#/components/schemas/LocationRef' + destination: + $ref: '#/components/schemas/LocationRef' + expectedShippingDate: + type: string + format: date-time + description: > + Date the origin expected to ship the goods (required in the + domain, so always present). + expectedDeliveryDate: + type: string + format: date-time + description: > + Date the shipment was expected to arrive. Always present on these + rows: shipments with a null expectedDeliveryDate cannot be + overdue and are excluded. + daysLate: + type: integer + minimum: 1 + description: > + Whole days between expectedDeliveryDate and now, floored. Never + below the effective minDaysLate. + status: + type: string + enum: [CREATED, PENDING, SHIPPED, PARTIALLY_RECEIVED] + description: > + Current ShipmentStatusCode. RECEIVED never appears; a + PARTIALLY_RECEIVED shipment is still outstanding and is reported. + shipmentItemCount: + type: integer + description: Number of shipment items, for context on the exception list. + + LocationRef: + type: object + description: Minimal location reference (id + display name). + required: [id, name] + properties: + id: + $ref: '../components/common.yaml#/components/schemas/Id' + name: + type: string + locationNumber: + type: string + nullable: true From cbcc8c1288ed54ce24e8c736e0f711709455e621 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:23:52 +0000 Subject: [PATCH 2/2] feature: clarify shipment exception contract rules Co-Authored-By: Matthew Guerra --- ...shipment-exceptions-acceptance-criteria.md | 74 ++++++++++++------- openapi/specs/shipment-exceptions-api.yaml | 61 ++++++++++----- 2 files changed, 88 insertions(+), 47 deletions(-) diff --git a/openapi/specs/shipment-exceptions-acceptance-criteria.md b/openapi/specs/shipment-exceptions-acceptance-criteria.md index d8583f5d141..dccb6e974bb 100644 --- a/openapi/specs/shipment-exceptions-acceptance-criteria.md +++ b/openapi/specs/shipment-exceptions-acceptance-criteria.md @@ -15,21 +15,22 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`. ## Inclusion / exclusion 1. **Overdue, unreceived, inbound shipment is included.** A shipment with - `destination` = the session warehouse, `expectedDeliveryDate` 3 days in the - past and status `SHIPPED` appears in `data`, keyed by its `shipmentNumber`. + `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`. 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. 3. **Expected delivery date of today is excluded.** A shipment whose - `expectedDeliveryDate` is today does not appear, because its floored + `expectedDeliveryDate` is today does not appear, because its calendar-day `daysLate` is 0, which is below the default threshold of 1. 4. **Received shipments are excluded.** A shipment with - `expectedDeliveryDate` in the past and status `RECEIVED` does not appear, - and no row in `data` has `status` = `RECEIVED`. -5. **Delivered-but-not-received shipments are excluded.** A shipment with a - past `expectedDeliveryDate` that has an actual delivery recorded - (`actualDeliveryDate` / `dateDelivered()` non-null) does not appear, even - when its status is still `SHIPPED`. + `expectedDeliveryDate` in the past and derived status `RECEIVED` does not + 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`. 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 @@ -43,17 +44,20 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`. appear; every row in `data` has `destination.id` equal to the session warehouse id (or one of its child locations). 9. **Inbound is relative to the session warehouse.** The same overdue shipment - appears when the session is bound to its destination warehouse and does not - appear when the session is bound to a different warehouse. + appears when the session is bound to its destination warehouse or its parent + warehouse when the destination is a child location, and does not appear + when the session is bound to a different warehouse. 10. **Partially received shipments are included.** A shipment with a past - `expectedDeliveryDate` and status `PARTIALLY_RECEIVED` appears, because - part of the goods is still outstanding (see open question 2). + `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 open question 2). ## daysLate -11. **daysLate is whole days, floored.** For a shipment whose - `expectedDeliveryDate` is 2 days and 18 hours in the past, `daysLate` is - exactly 2. +11. **daysLate is a calendar-day difference.** For a shipment whose + `expectedDeliveryDate` is at 23:00 two calendar days ago, `daysLate` is + exactly 2 regardless of the time of day when the request runs. 12. **daysLate is never below the threshold.** Every row in `data` has `daysLate` >= the effective `minDaysLate` (1 when the parameter is omitted). @@ -83,23 +87,33 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`. 20. **Response envelope.** The body always carries `data`, `count`, `max`, `offset` and `totalCount`; `count` equals `data.length`. -21. **totalCount ignores pagination.** With at least 3 qualifying shipments, +21. **Default max is 50.** Called without `max`, the response echoes + `max` = 50. +22. **max above 500 is rejected.** Called with `max=501`, the endpoint + responds `400` with the shared validation error body (`errorCode` 400). +23. **totalCount ignores pagination.** With at least 3 qualifying shipments, `max=1` returns `count` 1 while `totalCount` stays equal to the number of qualifying shipments. -22. **offset pages.** With `max=1`, the row at `offset=1` differs from the row +24. **offset pages.** With `max=1`, the row at `offset=1` differs from the row at `offset=0`, and `offset` is echoed back unchanged. -23. **Default sort is daysLate descending.** Called without `sort`/`order`, +25. **Default sort is daysLate descending.** Called without `sort`/`order`, `daysLate` values across `data` are in non-increasing order (most overdue first). -24. **sort is honoured.** With `sort=expectedDeliveryDate&order=asc`, the +26. **sort is honoured.** With `sort=expectedDeliveryDate&order=asc`, the `expectedDeliveryDate` values across `data` are in non-decreasing order. -25. **Unsupported sort values are rejected.** `sort=carrier` responds `400` +27. **Location-name sorting is case-insensitive.** With + `sort=origin&order=asc`, the `origin.name` values across `data` are in + case-insensitive non-decreasing order. +28. **Unsupported sort values are rejected.** `sort=carrier` responds `400` (the parameter is a closed enum in the contract). ## Auth -26. **A session is required.** Called without the `JSESSIONID` cookie, the +29. **A session is required.** Called without the `JSESSIONID` cookie, the endpoint responds `401` with the shared error body. +30. **A warehouse is required.** Called with an authenticated session that has + no warehouse selected, the endpoint responds `400` with the shared + validation error body (`errorCode` 400). ## Open questions for the human @@ -109,13 +123,17 @@ session bound to a warehouse via `POST /api/chooseLocation/{locationId}`. CANCELLED event, and that event is the latest one". Confirm, or name the signal you actually want. 2. **Partially received shipments.** Criterion 10 reports them as still - overdue. Confirm — the alternative is to exclude anything with any receipt. + overdue only when there is neither a `RECEIVED` nor a `DELIVERED` event; + `dateDelivered()` resolves those events and exclusion takes precedence. + Confirm — the alternative is to exclude anything with any receipt. 3. **Inbound definition.** The contract defines inbound as `destination` = session warehouse (or a child location of it). Confirm that is the right notion of "relative to the requesting location", rather than, say, any location the user has access to. -4. **Time zone / clock.** `daysLate` is floored using the server time zone. - Confirm that is acceptable, or specify a client-supplied `asOfDate`. -5. **Overdue vs. never shipped.** A shipment still in status `CREATED` or - `PENDING` past its expected delivery date is reported (it is late). Confirm - you want those, or restrict to shipments that have actually shipped. +4. **Time zone / clock.** `daysLate` is a calendar-day difference using the + server time zone. Confirm that time zone is acceptable, or specify whether + a client-supplied `asOfDate` is wanted. +5. **Overdue vs. never shipped.** A shipment still in derived status `PENDING` + (not-yet-shipped) past its expected delivery date is reported (it is late). + Confirm you want those, or restrict to shipments that have actually + shipped. diff --git a/openapi/specs/shipment-exceptions-api.yaml b/openapi/specs/shipment-exceptions-api.yaml index b6c68f9b5d7..c999ff23124 100644 --- a/openapi/specs/shipment-exceptions-api.yaml +++ b/openapi/specs/shipment-exceptions-api.yaml @@ -20,9 +20,11 @@ info: cannot be swallowed by the existing generic mappings, which are declared ahead of any new mapping would matter: "/api/${resource}s/$id" and the catch-all "/api/$action/$id?" (ApiController) both match at most two - segments after /api, and "/api/shipments/$id" would otherwise capture a - two-segment path such as /api/shipments/overdue with id="overdue". No - existing mapping matches /api/shipments/exceptions/overdue (all declared + segments after /api, while "/api/${resource}s/$id/status" has three + segments but requires the literal third segment "status". The + "/api/shipments/$id" mapping would otherwise capture a two-segment path + such as /api/shipments/overdue with id="overdue". No existing mapping + matches /api/shipments/exceptions/overdue (all declared "/api/shipments/$id/" mappings require a different literal third segment), so the new mapping is unambiguous wherever it is declared. @@ -31,8 +33,10 @@ info: (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy): expectedShippingDate is required, expectedDeliveryDate is nullable, receipt/delivery is derived (actualDeliveryDate / dateDelivered()), and - currentStatus is a ShipmentStatusCode (CREATED, PENDING, SHIPPED, - PARTIALLY_RECEIVED, RECEIVED). There is no CANCELLED shipment status; a + currentStatus is a nullable ShipmentStatusCode (CREATED, PENDING, SHIPPED, + PARTIALLY_RECEIVED, RECEIVED). Row status is derived from getStatus(), which + can return PENDING, SHIPPED, PARTIALLY_RECEIVED or RECEIVED; CREATED is + unreachable via getStatus(). There is no CANCELLED shipment status; a cancellation is recorded as a shipment event with EventCode.CANCELLED. version: 0.1.0 servers: @@ -50,18 +54,29 @@ paths: warehouse selected on the session (POST /api/chooseLocation/{id}): expectedDeliveryDate is set, is in the past, the shipment has not been received or delivered, and it has not been cancelled. Inbound means - the shipment's destination is the session warehouse. + the shipment's destination is the session warehouse or one of its child + 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. - daysLate is whole days only (floor of the elapsed time between - expectedDeliveryDate and "now" in the server time zone), so a shipment - due yesterday reports daysLate = 1. Rows with daysLate below - minDaysLate (default 1) are excluded, which means a shipment that is - due today is never reported. + daysLate is the calendar-day difference in the server time zone: + expectedDeliveryDate and "now" are both truncated to midnight before + the difference is calculated. A shipment due yesterday always reports + daysLate = 1 regardless of the request time; a shipment due today + reports daysLate = 0 and is excluded by the default minDaysLate of 1. + Rows with daysLate below minDaysLate are excluded. The result set is paginated with the standard max/offset params and - sorted by daysLate descending (most overdue first) by default. + sorted by daysLate descending (most overdue first) by default. max + defaults to 50 when omitted; values above 500 are rejected with 400. + An authenticated session with no warehouse selected responds 400 with + the shared ValidationErrorResponse body. Invalid query parameter + values are validated through a Grails command object and surface + through ErrorsController.handleValidationErrors, rather than being + rendered by hand. parameters: - $ref: '#/components/parameters/origin' - $ref: '#/components/parameters/destination' @@ -120,7 +135,9 @@ components: name: sort in: query required: false - description: Row property to sort by. Defaults to daysLate. + description: > + Row property to sort by. Defaults to daysLate. For origin and + destination, rows are sorted by the location name, case-insensitively. schema: type: string default: daysLate @@ -162,7 +179,9 @@ components: description: Number of rows in this page. max: type: integer - description: Page size applied (the requested max, or the default). + description: > + Page size applied (the requested max, or 50 when omitted). + Values above 500 are rejected with 400. offset: type: integer description: Zero-based index of the first row in this page. @@ -217,14 +236,18 @@ components: type: integer minimum: 1 description: > - Whole days between expectedDeliveryDate and now, floored. Never - below the effective minDaysLate. + Calendar days between expectedDeliveryDate and now in the server + time zone, with both timestamps truncated to midnight. Never below + the effective minDaysLate. status: type: string - enum: [CREATED, PENDING, SHIPPED, PARTIALLY_RECEIVED] + enum: [PENDING, SHIPPED, PARTIALLY_RECEIVED] description: > - Current ShipmentStatusCode. RECEIVED never appears; a - PARTIALLY_RECEIVED shipment is still outstanding and is reported. + Derived status from Shipment.getStatus(); the nullable currentStatus + column is deliberately not used. RECEIVED never appears because + received or delivered shipments are excluded; a + PARTIALLY_RECEIVED shipment is reported only when it has neither a + RECEIVED nor a DELIVERED event. shipmentItemCount: type: integer description: Number of shipment items, for context on the exception list.