docs: sync from backend 3a50dc4 - promote postgres integration

02 - Data Models/Payment.md

@@ -6,7 +6,7 @@ aliases: [Payment Record, Escrow, IPayment]
 
 # Payment
 
-> **Last updated:** 2026-05-29 — aligned with code (see [Doc vs Code Audit Report](../09%20-%20Audits/Doc%20vs%20Code%20Audit%20Report%20-%202026-05-29.md))
+> **Last updated:** 2026-05-31 — added AMN scanner provider, oracle quote mirror, and Postgres `payment_quotes` linkage.
 
 Records every monetary movement in the marketplace: buyer pay-ins, seller payouts, and refunds. The current model is centered on Request Network pay-in, in-house checkout metadata, on-chain transaction verification, escrow state, and provider request IDs. The `provider` and `direction` discriminators let one collection hold incoming buyer payments, outgoing seller releases, refunds, and legacy/other provider records.
 
@@ -17,11 +17,8 @@ Records every monetary movement in the marketplace: buyer pay-ins, seller payout
 > [!warning] Mixed types
 > `purchaseRequestId`, `sellerOfferId`, and `sellerId` use `Schema.Types.Mixed`. They are usually `ObjectId`s, but the template-checkout flow passes string ids that do not yet exist in the database, so the schema accepts both.
 
-> [!warning] `provider` values (schema enum vs reality)
-> The declared schema enum for `provider` is only `['request.network', 'other']`, yet production code writes additional values. The full set of providers that actually appear is: `request.network`, `shkeeper`, `decentralized`, `test`, `other`.
-> - `paymentCoordinator.ts` and `RequestTemplateService.ts` create `Payment` docs with `provider: 'shkeeper'`.
-> - The decentralized/on-chain flow uses `decentralized`.
-> - ⚠️ **Frontend type bug:** the frontend `PaymentProvider` TypeScript type (`frontend/src/types/payment.ts`) is `'request.network' | 'test' | 'other'` — it is **missing `shkeeper` and `decentralized`**, so the client cannot represent payments created by those providers.
+> [!note] `provider` values
+> The current backend schema accepts `request.network`, `amn.scanner`, `shkeeper`, and `other`. `amn.scanner` is the in-house scanner provider used for direct on-chain monitoring. Older docs and some frontend types may still mention historical values such as `test` or `decentralized`; treat those as legacy until their active routes are audited again.
 
 > [!warning] `confirmed` vs `completed` — stats undercount
 > Payment stats (`paymentService.getPaymentStats`) only increment `successfulPayments` for status **`confirmed`**:
@@ -43,7 +40,7 @@ Records every monetary movement in the marketplace: buyer pay-ins, seller payout
 | `sellerId` | Mixed (ObjectId or String) | yes | — | — | yes (compound) | Seller receiving (or template seller). |
 | `amount.amount` | Number | yes | — | — | — | Numeric amount. |
 | `amount.currency` | String | yes | `USDT` | — | — | Settlement currency. |
-| `provider` | String | no | `request.network` | enum (declared): `request.network` / `other`. Values written in practice: `request.network`, `shkeeper`, `decentralized`, `request.network`, `test`, `other` | yes (compound, partial) | Payment processor. ⚠️ See provider note below — code writes `shkeeper` and `decentralized` even though they are not in the declared schema enum, and the frontend `PaymentProvider` type is missing both. |
+| `provider` | String | no | `request.network` | enum: `request.network` / `amn.scanner` / `shkeeper` / `other` | yes (compound, partial) | Payment processor. `amn.scanner` is the in-house scanner pay-in rail. |
 | `direction` | String | no | `in` | enum: `in` / `out` / `refund` | yes (compound, partial) | Flow direction. |
 | `blockchain.network` | String | no | — | — | — | Network identifier. |
 | `blockchain.transactionHash` | String | no | — | — | yes (sparse) | On-chain tx hash. |
@@ -81,6 +78,22 @@ Records every monetary movement in the marketplace: buyer pay-ins, seller payout
 | `metadata.payoutType` | String | no | — | — | — | Payout sub-type. |
 | `metadata.error` | String | no | — | — | — | Last error message. |
 | `metadata.failedAt` | Date | no | — | — | — | When it failed. |
+| `quote.quoteId` | String | no | — | — | — | PG `payment_quotes.id` when a Postgres quote row exists. |
+| `quote.pricingCurrency` | String | no | — | — | — | Seller offer currency used for the quote. |
+| `quote.offerAmount` | String | no | — | decimal string | — | Seller obligation in `pricingCurrency`. |
+| `quote.invoiceUSD` | String | no | — | decimal string | — | `offerAmount × fxRate` at quote time. |
+| `quote.fxRate` | String | no | — | decimal string | — | Pricing currency to USD rate. |
+| `quote.fxSource` | String | no | — | — | — | FX provider id. |
+| `quote.tokenPriceUsd` | String | no | — | decimal string | — | Settlement token USD price used for depeg protection. |
+| `quote.depegSource` | String | no | — | — | — | Depeg/token-price provider id. |
+| `quote.rawSettleAmount` | String | no | — | decimal string | — | Exact `invoiceUSD / tokenPriceUsd` before rounding. |
+| `quote.settleAmount` | String | no | — | decimal string | — | Final token amount after seller-protective rounding. |
+| `quote.roundingBps` | Number | no | — | integer bps | — | Upward rounding applied. |
+| `quote.depegAdjustmentBps` | Number | no | — | integer bps | — | Absolute deviation from USD peg. |
+| `quote.token` | String | no | — | — | — | Settlement token symbol. |
+| `quote.chainId` | Number | no | — | — | — | Settlement chain id. |
+| `quote.fetchedAt` | Date | no | — | — | — | Oracle rate timestamp. |
+| `quote.expiresAt` | Date | no | — | — | — | Quote expiry. |
 | `createdAt` | Date | auto | `Date.now` | — | yes (compound) | Mongoose timestamp. |
 | `processedAt` | Date | no | — | — | — | When processing started. |
 | `completedAt` | Date | no | — | — | — | When fully settled. |
@@ -106,6 +119,10 @@ Defined at `backend/src/models/Payment.ts:174-188`:
 - `{ providerPaymentId: 1 }` (sparse) — provider idempotency.
 - `{ buyerId: 1, purchaseRequestId: 1, provider: 1, direction: 1 }` (unique, partial: `provider === 'shkeeper' && direction === 'in' && status === 'pending'`, name `uniq_pending_shkeeper_by_buyer_session`) — guards against duplicate pending invoices.
 
+## Postgres Quote Table
+
+The Postgres money-core branch stores oracle quotes in `payment_quotes`, a 1:1 child table keyed by `payment_id → payments.id`. Amount/rate columns use `numeric(38,18)` and the route resolves the PG parent through `payments.legacy_object_id` or `id_map` during the Mongo/PG dual-write window. If the PG payment row is missing, the quote is mirrored to this Mongo `quote` subdocument and a `pg_dualwrite_gaps` row is recorded for reconciliation.
+
 ## Pre/Post Hooks
 
 None declared.