Repository navigation
Correct domain-fact errors in the overdue inbound shipments contract #2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: spec-demo-base
Are you sure you want to change the base?
Changes from all commits
185d970
c05d067
4aa477c
6a76d42
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,16 +9,15 @@ info: | |
|
|
||
| NOTE ON INTENT: every other spec under openapi/specs/ is descriptive - it | ||
| pins the CURRENT behavior of an existing *ApiController (see | ||
| openapi/README.md). This one is different: it is a contract-first spec for | ||
| a NEW endpoint that does not exist yet, agreed before any implementation. | ||
| The controller (org.pih.warehouse.api.ShipmentExceptionApiController) and | ||
| its URL mapping are proposed, not present in | ||
| grails-app/controllers/org/pih/warehouse/UrlMappings.groovy. | ||
| openapi/README.md). This one was authored contract-first, and the endpoint | ||
| has since been implemented at org.pih.warehouse.api.ShipmentExceptionApiController | ||
| with a UrlMappings.groovy entry for "/api/shipments/exceptions/overdue". | ||
|
|
||
|
|
||
| PATH CHOICE: the path deliberately has three segments after /api so it | ||
| cannot be swallowed by the existing generic mappings, which are declared | ||
| ahead of any new mapping would matter: "/api/${resource}s/$id" and the | ||
| PATH CHOICE: the path deliberately has three segments after /api. | ||
| Declaration order in UrlMappings.groovy could matter for a two-segment | ||
| path because existing generic mappings might swallow it, but it does not | ||
| matter for this three-segment path: "/api/${resource}s/$id" and the | ||
|
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
|
||
| catch-all "/api/$action/$id?" (ApiController) both match at most two | ||
| segments after /api, while "/api/${resource}s/$id/status" has three | ||
| segments but requires the literal third segment "status". The | ||
|
|
@@ -58,7 +57,8 @@ paths: | |
| locations. Received/delivered exclusion is based on dateDelivered(), | ||
| which resolves a RECEIVED event and falls back to a DELIVERED event, so | ||
| either event excludes a shipment even when its derived status is | ||
| PARTIALLY_RECEIVED. | ||
| PARTIALLY_RECEIVED (actualDeliveryDate is transient and derives from | ||
| the RECEIVED event, so RECEIVED/DELIVERED events are the only signals). | ||
|
Comment on lines
59
to
+61
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 📝 Info: Claims about the merged implementation cross-check out Verified the accuracy corrections against the merged code: the endpoint and mapping do exist ( Was this helpful? React with 👍 or 👎 to provide feedback. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Matches my own cross-check — nothing to change here. |
||
|
|
||
|
|
||
| daysLate is the calendar-day difference in the server time zone: | ||
|
|
@@ -196,21 +196,27 @@ components: | |
| required: | ||
| - id | ||
| - shipmentNumber | ||
| - name | ||
| - origin | ||
| - destination | ||
| - expectedShippingDate | ||
|
staging-devin-ai-integration[bot] marked this conversation as resolved.
Resolved
Comment on lines
+199
to
+202
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 📝 Info: shipmentNumber requiredness is an endpoint guarantee that legacy rows can break The new note explains Was this helpful? React with 👍 or 👎 to provide feedback. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good catch on the constraint — Keeping it I am adding a one-line note to the field description recording that the column is nullable but populated by There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agreed on the mechanism — that's exactly why the note calls it an endpoint guarantee rather than a domain one, and I'm leaving On
Comment on lines
+199
to
+202
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔍 status is required and enum-constrained but derived from a nullable getter Unchanged by this PR, but relevant to its stated goal of aligning required/nullable claims with the implementation: the service emits Was this helpful? React with 👍 or 👎 to provide feedback. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Checked this one and it doesn't hold: The enum in the contract deliberately omits |
||
| - expectedDeliveryDate | ||
| - daysLate | ||
| - status | ||
| - shipmentItemCount | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔍 status is in required but the implementation can emit null The Was this helpful? React with 👍 or 👎 to provide feedback. Debug |
||
| properties: | ||
| id: | ||
| $ref: '../components/common.yaml#/components/schemas/Id' | ||
| shipmentNumber: | ||
| type: string | ||
| description: Human-readable shipment number shown on the shipment screens. | ||
| description: > | ||
| Human-readable shipment number shown on the shipment screens. The | ||
| underlying domain column is nullable, but ShipmentService.saveShipment | ||
| generates one via shipmentIdentifierService.generate for every | ||
| created shipment, so this field is required here. | ||
| name: | ||
| type: string | ||
| nullable: true | ||
| description: Shipment name (nullable in the domain). | ||
| description: Required shipment name. | ||
| shipmentType: | ||
| type: string | ||
| nullable: true | ||
|
|
@@ -250,7 +256,10 @@ components: | |
| RECEIVED nor a DELIVERED event. | ||
| shipmentItemCount: | ||
| type: integer | ||
| description: Number of shipment items, for context on the exception list. | ||
| description: >- | ||
| Formula-derived item count for the exception list. The endpoint | ||
| always populates it, falling back to the item collection size and | ||
| then 0, so it is always present. | ||
|
|
||
| LocationRef: | ||
| type: object | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📝 Info: dateDelivered()/actualDeliveryDate claim verified against the domain
Checked the corrected claim:
dateDelivered()resolves the RECEIVED event, falls back to DELIVERED, then toactualDeliveryDate(grails-app/domain/org/pih/warehouse/shipping/Shipment.groovy:677-683), andactualDeliveryDateis a transient (:108) whose getter returns the RECEIVED event date (:400-403). So the new wording — RECEIVED/DELIVERED events being the only exclusion signals, with no standalone column to seed — matches the domain, and the fallback is indeed redundant.Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Confirmed, thanks — that matches the line references this change is built on, no action needed.