Skip to content
Merged
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
139 changes: 139 additions & 0 deletions openapi/specs/shipment-exceptions-acceptance-criteria.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# 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 or one of its child locations,
`expectedDeliveryDate` 3 days in the past and derived status `SHIPPED`
appears in `data`, keyed by its `shipmentNumber`.
Comment on lines +17 to +20

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: Criterion 1 says rows are "keyed by" shipmentNumber, but data is an array

The response schema defines data as an array of OverdueInboundShipment objects (openapi/specs/shipment-exceptions-api.yaml:173-176), so "appears in data, keyed by its shipmentNumber" is misleading for whoever writes the contract test; it should say the row is identified/located by matching shipmentNumber.

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.

Fair — data is an array, so "keyed by its shipmentNumber" is sloppy for whoever writes the test. Rewording to "identified by matching shipmentNumber" in the follow-up.

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 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 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
`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 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`, 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 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).
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=<location id of A>`, every row has
`origin.id` = A, and an otherwise-qualifying shipment from a different
origin is absent.
18. **destination filters.** With `destination=<session warehouse id>`, 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=<non-existent id>`, 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. **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.
24. **offset pages.** With `max=1`, the row at `offset=1` differs from the row
at `offset=0`, and `offset` is echoed back unchanged.
25. **Default sort is daysLate descending.** Called without `sort`/`order`,
`daysLate` values across `data` are in non-increasing order (most overdue
first).
26. **sort is honoured.** With `sort=expectedDeliveryDate&order=asc`, the
`expectedDeliveryDate` values across `data` are in non-decreasing order.
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

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

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 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 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.
Comment on lines +136 to +139

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: Criteria count and CREATED-status claims disagree with the PR description

The document contains 30 numbered criteria while the PR description says 26, and the description's open question 5 claims CREATED shipments past their expected delivery date are reported, whereas the spec correctly notes CREATED is unreachable via Shipment.getStatus() (confirmed at grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:437-458, which only ever returns RECEIVED/PARTIALLY_RECEIVED/SHIPPED/PENDING) and open question 5 here mentions only PENDING. The spec/criteria are the accurate versions; the description text is stale.

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.

Both discrepancies were the PR description being stale relative to the final commit; the description has since been updated to say 30 criteria and to phrase open question 5 in terms of PENDING rather than CREATED. Agreed that the spec/criteria were the accurate versions.

Loading
Loading