refinement phase 6

2026-07-13 17:03:45 +03:30
parent d4147342da
commit 70268ecc06
33 changed files with 7262 additions and 53 deletions
@@ -65,10 +65,29 @@ ISO-8601; `expected_customer_refund_eta` is a **date** (`"2026-08-24"`).
  Post-payout: `clawbackId` is set (a `pending` `nurse_clawbacks` row + a support alert were created).
 - **Failure cases:** `400` invalid amount/legs or missing percentage · `401` unauth · `403` non-admin ·
  `404` no captured payment for the booking · `409` **`Σ refunded > captured`** (over-refund) · `400` channel refused.
- **Notes:** whole money-path runs under `lock(booking:{id}:refund)`; posts the balanced ledger reversal via
-  b10's helper; the `refund_payable ↔ escrow_held` clearing posts immediately for a succeeded card refund and is
-  deferred to reconciliation for BNPL/manual. `ticketId` is required only when `refund_ticket_required` config is
-  on (off until b15). Notifies the customer.
+- **Notes:** whole money-path runs under `lock(booking:{id}:refund)`; the refund row is persisted (`approved`)
+  **before** the external channel executes (crash-window fix), then the balanced ledger reversal posts via b10's
+  helper; the `refund_payable ↔ escrow_held` clearing posts immediately for a succeeded card refund and is
+  **deferred to reconciliation for BNPL/manual** (settled later via `confirm_settlement`, below). `ticketId` is
+  optional — one is auto-opened when omitted (b15), so a refund is always ticket-anchored. Notifies the customer.
+
+### `POST api/v1/admin_refunds/{id}/confirm_settlement`
+- **Purpose:** reconciliation confirmed the customer cash-back for a `processing` BNPL/manual refund — transitions
+  it `processing → succeeded`, stamps the settled instant, and posts the deferred `refund_payable ↔ escrow_held`
+  clearing in the same commit. (Also reached automatically by the BNPL provider cash-back callback.)
+- **Auth:** admin · **Rate-limited:** yes (sensitive) · **Idempotent:** a replay against an already-`succeeded`
+  refund is a no-op success (the clearing never posts twice).
+- **Request body:** none (id in the route).
+- **Success `200` (`data`):** `RefundSettlement` — `{ "refundId": 7, "bookingId": 42, "status": "succeeded",
+  "completedAt": "2026-08-12T10:00:00Z" }`.
+- **Failure:** `404` refund not found · `409` refund not in `processing` (e.g. still `approved`, already `failed`).
+
+### `POST api/v1/admin_refunds/{id}/mark_failed`
+- **Purpose:** reconciliation reported the BNPL/manual customer cash-back did **not** land — transitions the
+  `processing` refund to `failed`. No ledger moves (the clearing was never posted for a processing refund).
+- **Auth:** admin · **Rate-limited:** yes · **Idempotent:** a replay against an already-`failed` refund is a no-op.
+- **Request body:** `{ "reason": "bank_rejected" }` (optional).
+- **Success `200` (`data`):** `RefundSettlement` (as above, `status: "failed"`). **Failure:** `404` · `409` not `processing`.

 ### `GET api/v1/admin_refunds?booking_id=&status=&page=&pageSize=`
 - **Purpose:** admin refund worklist — projected + paginated (`page` default 1, `pageSize` default 20 / max 100).
@@ -125,6 +144,11 @@ ISO-8601; `expected_customer_refund_eta` is a **date** (`"2026-08-24"`).

 ## Changelog
 - b11 — initial contract (create refund, list refunds, write-off clawback, issue invoice, refund status, get invoice).
+- refinement-phase-6 — added `POST admin_refunds/{id}/confirm_settlement` + `.../mark_failed` (the BNPL/manual
+  `processing → succeeded/failed` settlement, `RefundSettlement` shape), so the deferred `refund_payable ↔
+  escrow_held` clearing is now reachable. Refunds are persisted before the channel call (crash-window fix). The
+  `refund_ticket_required` gate was retired (a refund ticket is always auto-opened). Forward-dep FKs added on
+  `refunds.ticket_id`, `nurse_clawbacks.original_payout_id`/`recovered_in_payout_id`, `invoices.partner_center_id`.

 ---

@@ -3606,6 +3606,172 @@
        ]
      }
    },
+    "/api/v1/admin_refunds/{id}/confirm_settlement": {
+      "post": {
+        "tags": [
+          "AdminRefunds"
+        ],
+        "operationId": "AdminRefunds_ConfirmSettlement",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "x-position": 1
+          }
+        ],
+        "responses": {
+          "400": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResultOfDictionaryOfStringAndListOfString"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResult"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResult"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResult"
+                }
+              }
+            }
+          },
+          "200": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResultOfRefundSettlementResult"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "Bearer": []
+          }
+        ]
+      }
+    },
+    "/api/v1/admin_refunds/{id}/mark_failed": {
+      "post": {
+        "tags": [
+          "AdminRefunds"
+        ],
+        "operationId": "AdminRefunds_MarkFailed",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "x-position": 1
+          }
+        ],
+        "requestBody": {
+          "x-name": "body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MarkRefundFailedBody"
+              }
+            }
+          },
+          "required": true,
+          "x-position": 2
+        },
+        "responses": {
+          "400": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResultOfDictionaryOfStringAndListOfString"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResult"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResult"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResult"
+                }
+              }
+            }
+          },
+          "200": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiResultOfRefundSettlementResult"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "Bearer": []
+          }
+        ]
+      }
+    },
    "/api/v1/admin/reviews/moderation_queue": {
      "get": {
        "tags": [
@@ -17189,6 +17355,60 @@
          }
        }
      },
+      "ApiResultOfRefundSettlementResult": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/ApiResult"
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "data": {
+                "nullable": true,
+                "oneOf": [
+                  {
+                    "$ref": "#/components/schemas/RefundSettlementResult"
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      },
+      "RefundSettlementResult": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "refundId": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "bookingId": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "status": {
+            "type": "string"
+          },
+          "completedAt": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          }
+        }
+      },
+      "MarkRefundFailedBody": {
+        "type": "object",
+        "description": "The mark-failed body (the id comes from the route).",
+        "additionalProperties": false,
+        "properties": {
+          "reason": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
      "ApiResultOfPagedResultOfModerationQueueItemDto": {
        "allOf": [
          {