Supplier Request Pause/Cancel - Controller Overview

Goal: Give ops a safe, reversible way to halt supplier-side activity when a borrowing request fails after a supplier request has already been placed, without kicking off re-resolution. Once the upstream error is fixed, ops can explicitly reactivate participation in re-resolution.

Scope (what changed vs core)

New admin-only controller with two endpoints:
- POST /suppliers/requests/{supplierRequestId}/cancel - pause + cancel at supplier.
- PATCH /suppliers/requests/{supplierRequestId}/active - toggle participation in re-resolution.
Only core code change: add a null-safe guard in HandleSupplierRequestCancelled:
- If SupplierRequest.isActive == false, skip the handler.
- isActive is nullable; treat null as true (default), so existing behavior is unchanged.

No other behavior changes to resolution/cancellation logic.

Why this matters

When borrowing fails after the supplier request was placed, the supplier may still ship. We need to:

Stop the supplier (cancel hold),
Pause re-resolution to avoid churn while fixing the root cause,
Resume deliberately once the error is addressed (or keep paused / close out).

This reduces accidental shipments, avoids re-resolution loops, and gives ops a clear, auditable playbook.

Endpoints

1) Cancel and pause

POST /suppliers/requests/{supplierRequestId}/cancel
Body (optional):
{
  "reason": "free-text (optional)"
}

Behavior

Sets isActive=false immediately (pauses re-resolution).
Builds context from the linked PatronRequest (via the SupplierRequest UUID).
Calls SupplyingAgencyService.cancelHold(ctx).
Verification (simple):
- If supplier returns a record with status CANCELLED - cancelled=true.
- If supplier returns no record - supplierStatus="MISSING", cancelled=true.
- Anything else - cancelled=false.
- Errors / missing IDs - cancelled=null with an informational message.

200 Response (example)

{
  "supplierRequestId": "f8a6…",
  "patronRequestId": "6d4b…",
  "paused": true,
  "supplierStatus": "CANCELLED",   // or "MISSING", "PLACED", etc.
  "cancelled": true,               // true|false|null (unknown)
  "message": null
}

Notes

Request body is optional (Swagger reflects this).
We do not flip isActive back automatically; staying paused is the point.

2) Reactivate (or keep paused)

PATCH /suppliers/requests/{supplierRequestId}/active
Body:
{ "active": true | false }

200 Response

{
  "supplierRequestId": "f8a6…",
  "activeNow": true
}

When to use

Set true after fixing the borrowing-side error to allow re-resolution and place a fresh supplier request if appropriate.
Leave as false to keep the request suppressed.

Security & Docs

Endpoints are admin-scoped.
Fully documented via Swagger/OpenAPI. https://openlibraryenvironment.github.io/dcb-service/openapi/
Cancel endpoint’s request body is explicitly optional.