backend phase 11

product/data-model/06-payments-ledger-and-refunds.html

@@ -111,6 +111,27 @@
 <tr><td><code>issued_at</code></td><td>DATETIME2</td><td></td></tr>
 </tbody></table></div>
 <p><strong>Relations:</strong> 1:1 → <code>bookings</code>; N:1 → <code>partner_centers</code> (when issuer).</p>
+<h3 id="as-built-backend-phase-11">As built (backend-phase-11) <a class="anchor" href="#as-built-backend-phase-11" aria-hidden="true">#</a></h3>
+<ul>
+<li><strong><code>refunds.refund_channel</code> canonical code is <code>manual</code></strong> (not <code>manual_bank</code>) for the out-of-band bank refund —</li>
+</ul>
+<p>  the two are the same channel; <code>manual</code> is the value stored and served. Set: <code>psp_card</code> | <code>bnpl_revert</code> | <code>manual</code>.</p>
+<ul>
+<li><strong><code>refunds.ticket_id</code></strong> ships as a <strong>nullable column with no FK</strong> (the <code>tickets</code> table arrives in b15); the</li>
+</ul>
+<p>  "ticket required" rule is gated by the <code>refund_ticket_required</code> config flag (default off).   <strong><code>nurse_clawbacks.original_payout_id</code> / <code>recovered_in_payout_id</code></strong> and <strong><code>invoices.partner_center_id</code></strong> are   likewise nullable, FK-less join points that b13 / b15 fill.</p>
+<ul>
+<li><strong><code>invoices.vat_irr = round(platform_commission_irr × vat_rate)</code></strong>, integer-only, on the commission line only; a</li>
+</ul>
+<p>  <code>vat_rate = 0</code> exemption yields <code>vat_irr = 0</code>.</p>
+<ul>
+<li><strong><code>invoices.invoice_number</code></strong> is drawn from a single-row <strong>counter table</strong> (<code>invoice_number_sequences</code>), locked</li>
+</ul>
+<p>  and committed with the invoice insert — gap-free, unique, portable across SQL Server / SQLite (no DB sequence),   never random/timestamp-derived. One issued invoice per booking (idempotent).</p>
+<ul>
+<li>The refund posts the balanced reversal via the b10 ledger helper; the <strong><code>refund_payable ↔ escrow_held</code> clearing</strong></li>
+</ul>
+<p>  posts immediately for a succeeded card refund and is deferred to reconciliation for a <code>processing</code> BNPL/manual   refund. Card and BNPL post the <strong>same</strong> reversal legs.</p>
   <a class="back-to-top" href="#">↑ Back to top</a>
 </div></main>
 </div>

product/data-model/06-payments-ledger-and-refunds.md

@@ -118,3 +118,19 @@ This is the most-changed domain. The previous model **inferred** money state fro
 | `issued_at` | DATETIME2 | |
 
 **Relations:** 1:1 → `bookings`; N:1 → `partner_centers` (when issuer).
+
+### As built (backend-phase-11)
+- **`refunds.refund_channel` canonical code is `manual`** (not `manual_bank`) for the out-of-band bank refund —
+  the two are the same channel; `manual` is the value stored and served. Set: `psp_card` | `bnpl_revert` | `manual`.
+- **`refunds.ticket_id`** ships as a **nullable column with no FK** (the `tickets` table arrives in b15); the
+  "ticket required" rule is gated by the `refund_ticket_required` config flag (default off).
+  **`nurse_clawbacks.original_payout_id` / `recovered_in_payout_id`** and **`invoices.partner_center_id`** are
+  likewise nullable, FK-less join points that b13 / b15 fill.
+- **`invoices.vat_irr = round(platform_commission_irr × vat_rate)`**, integer-only, on the commission line only; a
+  `vat_rate = 0` exemption yields `vat_irr = 0`.
+- **`invoices.invoice_number`** is drawn from a single-row **counter table** (`invoice_number_sequences`), locked
+  and committed with the invoice insert — gap-free, unique, portable across SQL Server / SQLite (no DB sequence),
+  never random/timestamp-derived. One issued invoice per booking (idempotent).
+- The refund posts the balanced reversal via the b10 ledger helper; the **`refund_payable ↔ escrow_held` clearing**
+  posts immediately for a succeeded card refund and is deferred to reconciliation for a `processing` BNPL/manual
+  refund. Card and BNPL post the **same** reversal legs.