Repository navigation
Contract for overdue inbound shipments API (spec only, no implementation) - #1
Conversation
Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
| @@ -0,0 +1,243 @@ | |||
| openapi: 3.0.3 | |||
| info: | |||
| title: OpenBoxes - ShipmentExceptionApiController | |||
There was a problem hiding this comment.
🟡 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
🟡 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/).
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
🔍 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| @@ -0,0 +1,243 @@ | |||
| openapi: 3.0.3 | |||
| info: | |||
| title: OpenBoxes - ShipmentExceptionApiController | |||
There was a problem hiding this comment.
🟡 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
| 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. |
There was a problem hiding this comment.
🟡 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
| name: | ||
| type: string | ||
| nullable: true | ||
| description: Shipment name (nullable in the domain). |
There was a problem hiding this comment.
🟡 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).
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
There was a problem hiding this comment.
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.
| shipmentItemCount: | ||
| type: integer | ||
| description: Number of shipment items, for context on the exception list. |
There was a problem hiding this comment.
🔍 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()).
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
Co-Authored-By: Matthew Guerra <matthew.guerra@cognition.ai>
e9692ad
into
spec-demo-base
| shipmentItemCount: | ||
| type: integer | ||
| description: Number of shipment items, for context on the exception list. |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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`. |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
📝 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
🟡 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.
Was this helpful? React with 👍 or 👎 to provide feedback.
✨ 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/overdueopenapi/specs/shipment-exceptions-acceptance-criteria.md— 30 individually testable criteria + open questionsWhat you are being asked to approve
daysLateper row. Filters:origin,destination,minDaysLate(default 1),sort/order(defaultdaysLatedesc), plus the sharedmax/offset(maxdefaults 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 reusecommon.yaml'sValidationError/Unauthorized/ServerError(400s are expected to come from command-object validation viaErrorsController.handleValidationErrors, not hand-rolled); auth is the sharedcookieAuthsession scheme.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),daysLateas 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)
destinationis the session warehouse or one of its child locations.daysLate= calendar-day difference in the server time zone, bothexpectedDeliveryDateand "now" truncated to midnight. So "due yesterday" is always 1 regardless of request time, and "due today" is 0 and therefore excluded by the defaultminDaysLateof 1.dateDelivered()(RECEIVED event, falling back to a DELIVERED event), so either event excludes a shipment even when its derived status isPARTIALLY_RECEIVED.statusis the derived status fromShipment.getStatus()(never null; the nullablecurrentStatuscolumn is deliberately unused), so the enum is[PENDING, SHIPPED, PARTIALLY_RECEIVED]—getStatus()cannot returnCREATED, andRECEIVEDrows are excluded.URL-mapping conventions the path must respect
grails-app/controllers/org/pih/warehouse/UrlMappings.groovyresolves 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 segmentstatus)"/api/$action/$id?"→ApiController(the catch-all documented inopenapi/specs/api.yaml)"/api/shipments/$id"Yes, the obvious paths collide.
/api/overdueShipmentsis captured by"/api/${resource}s"(→overdueShipmentApi.list) and, failing that, by the catch-all (→ApiController.overdueShipments, which does not exist)./api/shipments/overdueis captured by"/api/shipments/$id"withid="overdue"— it would resolve toShipmentApiController.readand 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 literalstatus, 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.mdsays specs are descriptive: they pin current behavior of an existing*ApiController. This one is prescriptive — a contract agreed before the code exists. The spec'sinfo.descriptionsays so explicitly so nobody mistakes it for a parity oracle. If you'd rather keepopenapi/specs/purely descriptive, say so and this file can move (e.g.openapi/proposals/), which would also mean it stops being linted by theopenapi-lintCI 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 theopenapi-lintCI job runs).Open questions for the human (also listed at the end of the criteria doc)
CANCELLEDShipmentStatusCode— onlyEventCode.CANCELLEDon a shipment event. The criteria assume "cancelled" = has a CANCELLED event as its latest event. Confirm the signal.destination= session warehouse or a child of it. Confirm, rather than e.g. any location the user has access to.daysLateuses server-time-zone calendar days; no client-suppliedasOfDate. Confirm the time zone, or ask forasOfDate.PENDINGshipments 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
cbcc8c1