Skip to content

Contract for overdue inbound shipments API (spec only, no implementation) - #1

Merged
devin-ai-integration[bot] merged 2 commits into
spec-demo-basefrom
devin/1787181157-shipment-exceptions-spec
Aug 19, 2026
Merged

devin-ai-integration[bot] merged 2 commits into
spec-demo-basefrom
devin/1787181157-shipment-exceptions-spec

Conversation

@matthewguerra-cog

@matthewguerra-cog matthewguerra-cog commented Aug 19, 2026 •

Copy link
Copy Markdown
Collaborator

✨ Description of Change

Link to GitHub issue or Jira ticket: n/a (spec-driven development rehearsal, Act 1)

Description:

Contract only — no implementation. Two new files, nothing else touched:

  • openapi/specs/shipment-exceptions-api.yaml — GET /api/shipments/exceptions/overdue
  • openapi/specs/shipment-exceptions-acceptance-criteria.md — 30 individually testable criteria + open questions

What you are being asked to approve

  1. The contract: the request/response shape of one read-only endpoint that lists inbound shipments whose expected delivery date has passed and that have not been received, with daysLate per row. Filters: origin, destination, minDaysLate (default 1), sort/order (default daysLate desc), plus the shared max/offset (max defaults to 50, values above 500 rejected with 400). Response is the standard paged envelope (data, count, max, offset, totalCount) used by e.g. cycle-count-api.yaml; errors reuse common.yaml's ValidationError/Unauthorized/ServerError (400s are expected to come from command-object validation via ErrorsController.handleValidationErrors, not hand-rolled); auth is the shared cookieAuth session scheme.
  2. The acceptance criteria: each is phrased so exactly one contract test under characterization/contract/ can prove it (seed/pick a shipment → call the endpoint → assert). They pin the exclusions (future date, due today, received or delivered, null expected date, cancelled, outbound), daysLate as whole calendar days, default threshold 1 day, and the pagination/sort defaults.

Semantics as pinned after review (these are the decisions a reviewer is signing off on)

  • Inbound = the shipment's destination is the session warehouse or one of its child locations.
  • daysLate = calendar-day difference in the server time zone, both expectedDeliveryDate and "now" truncated to midnight. So "due yesterday" is always 1 regardless of request time, and "due today" is 0 and therefore excluded by the default minDaysLate of 1.
  • Received/delivered wins over partially received: exclusion is based on dateDelivered() (RECEIVED event, falling back to a DELIVERED event), so either event excludes a shipment even when its derived status is PARTIALLY_RECEIVED.
  • status is the derived status from Shipment.getStatus() (never null; the nullable currentStatus column is deliberately unused), so the enum is [PENDING, SHIPPED, PARTIALLY_RECEIVED] — getStatus() cannot return CREATED, and RECEIVED rows are excluded.
  • An authenticated session with no warehouse selected responds 400 with the shared validation error body.

URL-mapping conventions the path must respect

grails-app/controllers/org/pih/warehouse/UrlMappings.groovy resolves by declaration order and has three generic mappings that can swallow new API paths:

  • "/api/${resource}s" and "/api/${resource}s/$id" (the standard REST block; "/api/${resource}s/$id/status" also exists but requires the literal third segment status)
  • "/api/$action/$id?" → ApiController (the catch-all documented in openapi/specs/api.yaml)
  • plus, specific to shipments, "/api/shipments/$id"

Yes, the obvious paths collide. /api/overdueShipments is captured by "/api/${resource}s" (→ overdueShipmentApi.list) and, failing that, by the catch-all (→ ApiController.overdueShipments, which does not exist). /api/shipments/overdue is captured by "/api/shipments/$id" with id="overdue" — it would resolve to ShipmentApiController.read and 404/500 rather than reaching a new action, unless a new literal mapping were declared above it (fragile, order-dependent).

Proposed path that avoids the collision: /api/shipments/exceptions/overdue. Three segments after /api, so it is outside the reach of the two-segment generic mappings and the catch-all; the only three-segment generic mapping requires the literal status, and every existing "/api/shipments/$id/<literal>" mapping requires a different literal third segment (comments, documents, events, items, receipt, …). Nothing matches it today, so the new mapping is unambiguous regardless of where it is declared. Still not implemented here — no controller, no URL mapping, no React, no contract test.

Deviation from the repo convention, called out on purpose

openapi/README.md says specs are descriptive: they pin current behavior of an existing *ApiController. This one is prescriptive — a contract agreed before the code exists. The spec's info.description says so explicitly so nobody mistakes it for a parity oracle. If you'd rather keep openapi/specs/ purely descriptive, say so and this file can move (e.g. openapi/proposals/), which would also mean it stops being linted by the openapi-lint CI job.

Verification

npx --yes @redocly/cli@1.34.2 lint --config openapi/redocly.yaml 'openapi/specs/*.yaml' openapi/components/common.yaml — 0 errors, 0 warnings (the exact command the openapi-lint CI job runs).

Open questions for the human (also listed at the end of the criteria doc)

  1. Cancellation: there is no CANCELLED ShipmentStatusCode — only EventCode.CANCELLED on a shipment event. The criteria assume "cancelled" = has a CANCELLED event as its latest event. Confirm the signal.
  2. Partially received: reported as still overdue when there is no RECEIVED/DELIVERED event. Confirm, vs. excluding anything with any receipt.
  3. "Inbound relative to the requesting location": defined as destination = session warehouse or a child of it. Confirm, rather than e.g. any location the user has access to.
  4. Clock: daysLate uses server-time-zone calendar days; no client-supplied asOfDate. Confirm the time zone, or ask for asOfDate.
  5. Never-shipped shipments: PENDING shipments past their expected delivery date are reported as late. Confirm, or restrict to shipments that have actually shipped.

Devin-Org: engineering

Link to Devin session: https://app.devin.ai/sessions/fac0eacd88a44c08b704f4eca4926851
Requested by: @matthewguerra-cog


Devin Review

Status Commit
🟢 Reviewed cbcc8c1
Open in Devin Review (Staging)

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
@matthewguerra-cog matthewguerra-cog self-assigned this Aug 19, 2026
@devin-ai-integration

Copy link
Copy Markdown

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment, CI, and merge conflict monitoring

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 10 potential issues.

Open in Devin Review

@@ -0,0 +1,243 @@
openapi: 3.0.3
info:
title: OpenBoxes - ShipmentExceptionApiController

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 New API spec file name does not follow the required naming convention

The new contract file is named with a plural noun (openapi/specs/shipment-exceptions-api.yaml) even though the documented convention requires the file to be named after the controller it documents (ShipmentExceptionApiController -> shipment-exception-api.yaml), so the automated contract-test naming derived from the file name will not line up with the controller.
Impact: Reviewers and tooling that map controllers to spec files by name will not find the spec for this controller.

Convention in openapi/README.md and the spec's own title

openapi/README.md states: "One file per controller under specs/, named after the controller in kebab-case with the Controller suffix dropped: StockMovementApiController -> stock-movement-api.yaml." The spec declares info.title: OpenBoxes - ShipmentExceptionApiController (openapi/specs/shipment-exceptions-api.yaml:3), which maps to shipment-exception-api.yaml. The contract-test convention (test_<spec-name-underscored>_contract.py) inherits the same mismatch. The companion acceptance-criteria markdown also sits in openapi/specs/, which the documented layout reserves for one YAML per controller.

Prompt for agents
openapi/README.md mandates that each spec file under openapi/specs/ be named after the controller it documents, in kebab-case with the Controller suffix dropped. This spec's info.title is "OpenBoxes - ShipmentExceptionApiController", so the file should be shipment-exception-api.yaml (singular), and the companion acceptance-criteria markdown should be renamed consistently (or moved out of specs/, which the documented layout reserves for per-controller YAML files). Rename to align the file name, the declared controller name, and the future contract-test module name.
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.

Keeping the plural file name. openapi/specs/shipment-exceptions-api.yaml (and the -acceptance-criteria.md companion) is the exact path the task asked for, so renaming it to shipment-exception-api.yaml would be me overriding an explicit instruction. Worth noting the convention argument is also weaker here than for the descriptive specs: those are named after an existing *ApiController, whereas this contract's controller doesn't exist yet, so the file name isn't yet pinned to anything. Happy to rename if the human reviewer prefers matching the singular-controller convention.

Comment on lines +10 to +16
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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Prescriptive contract added to a directory the project reserves for descriptive specs

A contract for an endpoint that does not exist yet was added to the directory the project reserves for specs that pin only current API behavior (openapi/specs/shipment-exceptions-api.yaml), so the parity oracle built from that directory now contains an unimplemented endpoint.
Impact: Anyone using the spec directory to verify the migrated backend against today's behavior will see a documented endpoint that cannot be verified.

Rule text and where the deviation happens

openapi/README.md states: "OpenAPI 3.0 specs that pin the current behavior of the OpenBoxes REST API (grails-app/controllers/**/*ApiController.groovy), one spec file per controller" and "These specs are descriptive, not aspirational." The new spec's own description (openapi/specs/shipment-exceptions-api.yaml:10-16) acknowledges the controller org.pih.warehouse.api.ShipmentExceptionApiController and its URL mapping do not exist. The openapi-lint CI job globs openapi/specs/*.yaml, so the unimplemented contract is also linted alongside real specs. If the repository wants prescriptive contracts, the README/layout should be amended or the file placed elsewhere (e.g. openapi/proposals/).

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.

Acknowledged and deliberate — the task specified openapi/specs/ as the location, and the spec's own info.description calls out that it is prescriptive rather than descriptive, so anyone using the directory as a parity oracle can see it. If the project wants a home for contract-first specs, openapi/proposals/ plus a README amendment is the right follow-up; that's a repo-layout decision for the human, not something I'll make inside a contract-only PR.

Comment on lines +19 to +27
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/<literal>" mappings require a different literal third
segment), so the new mapping is unambiguous wherever it is declared.

@devin-ai-integration devin-ai-integration Bot Aug 19, 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: URL-mapping collision analysis holds against the current mappings

Verified the path claim: grails-app/controllers/org/pih/warehouse/UrlMappings.groovy has /api/shipments/$id (line 1287) and many /api/shipments/$id/<literal> mappings (comments, documents, events, items, receipt, …), plus the generic /api/${resource}s//api/${resource}s/$id (2346, 2356), /api/${resource}s/$id/status (2351, literal third segment), the catch-all /api/$action/$id? (2364), and /api/products/$id/$action / /api/locations/$id/$action (775, 874 — not shipments). None of these matches /api/shipments/exceptions/overdue, so the three-segment path is unambiguous today. Note the spec's claim that the generic mappings "both match at most two segments after /api" is slightly imprecise given /api/${resource}s/$id/status, but the conclusion is unaffected.

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.

Fixed in cbcc8c1 — the wording was imprecise. The description now notes that /api/${resource}s/$id/status matches three segments but requires the literal third segment status, so the "at most two segments" claim is dropped. The conclusion is unchanged: no declared mapping matches /api/shipments/exceptions/overdue.

Comment on lines +163 to +171
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.

@devin-ai-integration devin-ai-integration Bot Aug 19, 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.

🔍 max default 50 / max 500 are only prose, not declared on the parameter

Criteria 21 and 22 (openapi/specs/shipment-exceptions-acceptance-criteria.md:90-93) assert max defaults to 50 and that max=501 returns 400, but the operation reuses ../components/common.yaml#/components/parameters/max, whose schema is a bare type: integer with no default or maximum (openapi/components/common.yaml:31-37). By contrast minDaysLate declares minimum: 1 and default: 1 inline. A schema-driven contract test cannot prove the page-size rules from the contract alone; consider declaring a local max parameter (or adding constraints in common.yaml) so the documented behaviour is machine-checkable.

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 fixed in cbcc8c1. max now defaults to 50 when omitted and values above 500 are rejected with 400 (stated in the operation description and the envelope's max description, with criteria asserting the echoed 50 and the 501 rejection). An authenticated session with no warehouse selected now responds 400 with the shared validation error body, also declared in the description and covered by a new criterion.

@staging-devin-ai-integration staging-devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 7 potential issues.

Open in Devin Review (Staging)
Debug

Playground

@@ -0,0 +1,243 @@
openapi: 3.0.3
info:
title: OpenBoxes - ShipmentExceptionApiController

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 New spec file name does not match the required naming convention

The spec file is named with a plural word (shipment-exceptions-api.yaml for ShipmentExceptionApiController at openapi/specs/shipment-exceptions-api.yaml:3) instead of the exact kebab-case controller name required by the repository conventions, so the spec, its future test module and the controller no longer line up.
Impact: Reviewers and tooling that map a spec to its controller (and the required test_<spec-name-underscored>_contract.py module) get an inconsistent name.

Naming rule in openapi/README.md

openapi/README.md states: "One file per controller under specs/, named after the controller in kebab-case with the Controller suffix dropped: StockMovementApiController -> stock-movement-api.yaml." For ShipmentExceptionApiController (the class named in info.title) the file should be shipment-exception-api.yaml; the criteria doc reference at openapi/specs/shipment-exceptions-acceptance-criteria.md:3 would need the same rename.

Prompt for agents
openapi/README.md requires each spec file under openapi/specs/ to be named after its controller in kebab-case with the Controller suffix dropped (StockMovementApiController -> stock-movement-api.yaml). The new spec declares info.title 'OpenBoxes - ShipmentExceptionApiController' but the file is openapi/specs/shipment-exceptions-api.yaml (plural 'exceptions'), which would also make the required contract-test module name (test_<spec-name-underscored>_contract.py) inconsistent with the controller. Either rename the file (and the reference in openapi/specs/shipment-exceptions-acceptance-criteria.md) to match the singular controller name, or rename the proposed controller so the two agree.
Open in Devin Review (Staging)

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

Debug

Playground

Comment on lines +10 to +16
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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Spec directory rule requiring specs to describe existing behavior is broken by an aspirational spec

A spec for an endpoint that does not exist yet is added to the folder reserved for descriptions of current behavior (see the intent note at openapi/specs/shipment-exceptions-api.yaml:10-16), so the folder can no longer be trusted as a record of what the system actually does.
Impact: Anyone using these specs as the verification baseline for the migration will be checking against an endpoint that returns nothing, producing misleading results.

Rule and consequences

openapi/README.md states specs "pin the current behavior" of an existing *ApiController and that "These specs are descriptive, not aspirational." The proposed controller and URL mapping do not exist (grails-app/controllers/org/pih/warehouse/UrlMappings.groovy has no /api/shipments/exceptions/overdue). The README also requires each spec'd operation to be exercised by a module under characterization/contract/, which cannot be satisfied here. The author acknowledges the deviation and offers to move the file (e.g. openapi/proposals/), which would also keep it out of the openapi-lint glob's descriptive set.

Additionally, openapi/specs/shipment-exceptions-acceptance-criteria.md is a markdown file in a directory the README documents as containing one YAML per controller.

Open in Devin Review (Staging)

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

Debug

Playground

Comment on lines +191 to +194
name:
type: string
nullable: true
description: Shipment name (nullable in the domain).

@staging-devin-ai-integration staging-devin-ai-integration Bot Aug 19, 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.

🟡 Contract wrongly says shipment name can be missing

The shipment name is documented as optional and possibly empty (nullable: true at openapi/specs/shipment-exceptions-api.yaml:191-194) even though the system always requires one, so implementers and tests will allow a value the data can never contain.
Impact: The agreed contract misstates the data model, so the response shape can drift from what the application really returns.

Domain constraint

grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:169 declares name(nullable: false, blank: false, maxSize: 255), i.e. shipment name is mandatory. The spec's parenthetical "(nullable in the domain)" is therefore incorrect; name should be non-nullable (and is a candidate for the required list, per the README rule to mark keys that are always present).

Open in Devin Review (Staging)

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

Debug

Playground

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, and thanks — name(nullable: false, blank: false, maxSize: 255) (Shipment.groovy:169) makes my "(nullable in the domain)" parenthetical simply wrong. PR #1 is already merged, so this is going into a follow-up: name loses nullable: true, gets an accurate description, and joins the required list.

Comment on lines +228 to +230
shipmentItemCount:
type: integer
description: Number of shipment items, for context on the exception list.

@staging-devin-ai-integration staging-devin-ai-integration Bot Aug 19, 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.

🔍 shipmentItemCount is nullable in the domain but non-nullable here

shipmentItemCount is declared as a plain integer, while the domain field is shipmentItemCount(nullable: true) (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:206) and is a denormalised counter that can be null on older rows. If the implementation simply echoes the domain field, a null value would violate this schema in the contract tests; either mark it nullable: true or specify that the endpoint computes the count (e.g. shipmentItems.size()).

Open in Devin Review (Staging)

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

Debug

Playground

Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
@devin-ai-integration
devin-ai-integration Bot merged commit e9692ad into spec-demo-base Aug 19, 2026
8 of 9 checks passed

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 5 new potential issues.

Open in Devin Review

Comment on lines +251 to +253
shipmentItemCount:
type: integer
description: Number of shipment items, for context on the exception list.

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: shipmentItemCount / expectedShippingDate nullability vs the domain

shipmentItemCount is declared type: integer with no nullable: true, but the domain field is a derived formula constrained nullable: true (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:67,206), so a real rendering could carry null and fail schema validation; openapi/README.md explicitly asks for nullable: true "liberally". Similarly expectedShippingDate is described as "required in the domain, so always present" yet is omitted from the required list while expectedDeliveryDate is included — worth making the two consistent.

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 valid, and both going into the follow-up. shipmentItemCount is a derived formula field constrained nullable: true (Shipment.groovy:67, 160, 206), so it gets nullable: true; and expectedShippingDate is described as always present yet omitted from required while expectedDeliveryDate is in it — I'll add it so the two agree.

Comment on lines +17 to +20
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`.

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.

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

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.

Comment on lines +21 to +24
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, while "/api/${resource}s/$id/status" has three
segments but requires the literal third segment "status". The

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: URL-mapping non-collision claim verified; description sentence is garbled

I checked grails-app/controllers/org/pih/warehouse/UrlMappings.groovy: the generic patterns are two-segment (/api/${resource}s, /api/${resource}s/$id, catch-all /api/$action/$id?), the only three-segment generics require a literal (/api/${resource}s/$id/status, /api/products/$id/$action, /api/locations/$id/$action), and every /api/shipments/$id/<literal> mapping uses a different literal, so /api/shipments/exceptions/overdue is indeed unmatched today. The sentence "which are declared ahead of any new mapping would matter" is garbled and should be rewritten.

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.

Thanks for the independent check on the mapping analysis — and you're right that the sentence is garbled ("declared ahead of any new mapping would matter" is a mangled clause). The factual content stands; the wording is being fixed in the follow-up. Useful addition that /api/products/$id/$action and /api/locations/$id/$action are the other literal-requiring three-segment generics.

Comment on lines +57 to +61
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.

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: Exclusion via dateDelivered() also picks up actualDeliveryDate

The prose says the received/delivered exclusion "resolves a RECEIVED event and falls back to a DELIVERED event", but Shipment.dateDelivered() additionally falls back to the actualDeliveryDate column (grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:677-683). A shipment with no RECEIVED/DELIVERED event but a set actualDeliveryDate would also be excluded, which criteria 5 and 10 do not cover; worth spelling out so the test for criterion 10 seeds the fixture correctly.

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: actualDeliveryDate is a transient (declared in static transients, Shipment.groovy:108) whose getter derives from the RECEIVED event (getActualDeliveryDate(), :400-403). So the ?: actualDeliveryDate tail of dateDelivered() resolves through that getter, not a persisted column — there is no state where a shipment has no RECEIVED/DELIVERED event but a "set actualDeliveryDate", and criteria 5 and 10 aren't missing a case. Your underlying point about fixture clarity is still worth acting on, so the follow-up adds a parenthetical saying exactly that, so nobody seeds a phantom column.

@staging-devin-ai-integration staging-devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

Open in Devin Review (Staging)
Debug

Playground

Comment on lines +72 to +79
The result set is paginated with the standard max/offset params and
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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Page-size rules in the new contract contradict the shared paging behaviour used by the rest of the API

The contract promises a default page size of 50 and a rejection for page sizes above 500 (max description at openapi/specs/shipment-exceptions-api.yaml:73-74), but the shared paging helper every other API endpoint uses defaults to 10 and silently caps at 100, so the promised behaviour cannot be delivered without new paging code.
Impact: Anyone implementing or testing this endpoint against the agreed contract will see different page sizes than promised, and the two paging acceptance criteria will fail.

Mismatch with PaginationCommand defaults and clamping semantics

src/main/groovy/org/pih/warehouse/api/PaginationCommand.groovy:8-17 defines DEFAULT_MAX = 10 and ABSOLUTE_MAX = 100, and returns Math.min(super.max ?: DEFAULT_MAX, ABSOLUTE_MAX) — an oversized max is clamped, never rejected. The spec text at openapi/specs/shipment-exceptions-api.yaml:76-79 explicitly says invalid query parameter values are "validated through a Grails command object" and surfaced via ErrorsController.handleValidationErrors, i.e. the shared machinery, which contradicts both the 50 default (openapi/specs/shipment-exceptions-api.yaml:183) and the 400-on-501 rule. The acceptance criteria bake the same numbers in: criterion 21 (openapi/specs/shipment-exceptions-acceptance-criteria.md:90-91) asserts max echoes 50 when omitted, and criterion 22 (openapi/specs/shipment-exceptions-acceptance-criteria.md:92-93) asserts max=501 responds 400. Against an implementation built on PaginationCommand both tests fail (10 echoed, 200 with clamped 100). Either align the contract with 10/100-clamped, or state explicitly that a new pagination command with different bounds is required.

Prompt for agents
The contract for GET /api/shipments/exceptions/overdue specifies max defaults to 50 and values above 500 are rejected with 400 (openapi/specs/shipment-exceptions-api.yaml, plus the max property description and acceptance criteria 21 and 22). The repository's shared pagination command, src/main/groovy/org/pih/warehouse/api/PaginationCommand.groovy, defaults max to 10 and clamps it to an absolute maximum of 100 rather than returning a validation error. The spec simultaneously claims parameter validation goes through a Grails command object and ErrorsController.handleValidationErrors, so the two statements are mutually inconsistent. Decide which semantics are intended and make the spec description, the max property description, and the acceptance criteria consistent: either adopt the shared 10/100-clamped behaviour, or state clearly that this endpoint requires a dedicated pagination command with a 50 default and a hard 500 limit that produces a 400.
Open in Devin Review (Staging)

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

Debug

Playground

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant