Suite E2E de flujos de dinero (staging)

Desde 2026-06-05 hay una suite E2E que valida los 18 flujos de dinero (P1–P18) de punta a punta contra el staging desplegado, sin depender de MercadoPago. Vive en tcgcards-api/tests/e2e-staging/.

Qué prueba de verdad: todo el movimiento de plata corre con el código real de prod (PaymentService, ledger, guards CAS, comisión/IVA, reembolsos, disputas, retiros, reconcile). Lo único simulado es la respuesta de MercadoPago — no un cobro real.

El seam `MP_FAKE_PAYMENTS`

El único paso que necesita MercadoPago es la confirmación del pago (getPayment). El seam envuelve el adaptador de MP (getPayment + refundPayment + createPreference) y, bajo el flag, fabrica pagos sintéticos:

El test confirma con un id sintético e2e:<outcome>:<externalReference> (ej. e2e:approved:order-abc). El server lee el totalPrice real de la orden/checkout, fabrica el pago (approved/rejected/pending, fee ~3.8%) y corre el flujo de dinero real.
Para cualquier id real, delega al MP real. El refund sintético es no-op; createPreference devuelve una preferencia falsa (evita la llamada lenta a MP).

Seguridad (doble fail-closed, en config.ts): el server aborta el arranque si MP_FAKE_PAYMENTS=true y (NODE_ENV=production o MONGODB_DB_NAME no contiene "staging"). El candado positivo a la DB hace imposible por construcción correr el seam contra la base de prod. Con el flag apagado (prod), el comportamiento es idéntico a hoy (probado por 612 unit tests + auditoría adversarial). Ver envs → flags solo-staging.

Cómo correrla

Requiere .env.staging.local (secrets de staging) en el repo de la API.

# toda la suite (los 18 flujos)
npx vitest run --config vitest.staging.config.ts

# un grupo
npx vitest run --config vitest.staging.config.ts tests/e2e-staging/refunds.e2e.ts

Corre serializada (single fork) contra el staging desplegado. El harness mintea JWTs internos, crea actores efímeros, y abre una conexión Mongo directa a staging (para backdating de fechas en flujos de timeout/ventana de reembolso).

Flujos cubiertos (P1–P18)

Archivo	Flujos
`happy-path`	P1 compra → pago · P3 completar → vendedor +sale + comisión · P18 reconcile
`refunds`	P4 reembolso a tarjeta (mp_api, dentro de ventana) · P5 reembolso a wallet (fuera de ventana)
`disputes`	P7 a favor comprador · P8 a favor vendedor · P9 dismissed · P10 abrir/responder
`withdrawals`	P15 retiro: solicitar → admin completa/cancela + guards
`multiseller`	P2 checkout combinado (crear→pagar→completar ambas) · P6 refund de suborden · rechazo combinado
`lifecycle`	P11 timeout · P12 webhook tardío · P13 rechazo · P14 SLA (auto-cancel/auto-complete)
`iva-system`	P16 IVA dentro de la comisión · P17 owner_draw / manual_credit·debit / iva_payment / admin forjado

Cada archivo cierra con un reconcile = 0 (la plata cuadra para todos los usuarios).

Realidad de MercadoPago en TEST (para no re-litigar)

Las tarjetas de prueba funcionan por el browser (fee real observado ~3.8%).
La API directa de pago está bloqueada con las credenciales de prueba ("Unauthorized use of live credentials"). Por eso la automatización usa el seam, no MP.
Para pruebas manuales con MP real en staging: usuario de test logueado en MP + “Dinero en cuenta” (siempre anda) o tarjeta.