ADR-020: El PDV de un pago es el de la caja que pagó
Date: 2026-10-06 Status: Accepted — decisiones D3-3 (a), D3-7 (b) y D3-8 de Carlos (2026-10-05), implementadas el 2026-10-06 en la entrega G4a del plan de ajustes v3 (G4.1, G4.2, G2.2 y G4.7). Supersedes in part: la cláusula «no se valida que coincidan» de E4-multi §2.3 — la caja ahora llena el PDV cuando no hay otro, pero no se obliga a que coincida (ver «Lo que NO cambia»). Aclara además la incoherencia de ADR-008 §1 sobre el usuario con más de un PDV.
Context
Un pago siempre ocurre en un punto de venta (PDV) y el sistema lo sabe: en los países con módulo Caja todo pago descuenta la caja que el propio operador abrió (TransactionController::applyCashBoxDiscount), y esa caja pertenece a un PDV. Pero ese PDV no se usaba para atribuir el pago: el PDV de la transacción se resolvía por separado, desde los permisos (el PDV activo de la persona, o el único de su alcance), y E4-multi §2.3 desacopló las dos cosas a propósito («si aparece como problema real en el uso, es un ajuste chico después»).
Apareció. Magaly (CIS-EC, 2026-10-02, RV3-17) señaló que no todas las transacciones muestran su PDV: dos de tres PAID con «—». Las causas son seis y esta decisión se ocupa de las que son un hueco:
- una
ACCEPTEDno tiene PDV, por diseño; - una
CANCELLEDpor la API de Soterex no tiene persona, y sin persona no hay PDV; - una
PAIDoCANCELLEDpor alguien con alcance ambiguo (2+ PDV sin PDV activo, o sin acotar: el Admin) dabanull; - el primer documento subido sobre una
ACCEPTED, igual; - datos viejos o de demo;
- no es un hueco: el PDV queda fijado por un camino (primer documento, PDV activo) y la plata sale de la caja que abrió quien paga, que puede ser de otro PDV. En las capturas de la cliente, un mismo operador (Cajero y Admin a la vez) pagó dos transacciones desde la misma caja de Central y una quedó con PDV «—» y la otra con «Mixco Plaza».
Una PAID sin PDV sale mal en todo lo que mira por PDV: la persona acotada no ve su propio pago en Reporte individual, el Dashboard no lo suma a los usuarios acotados, Cumplimiento (columnas 33 a 36, «dónde se pagó») sale con esas cuatro columnas vacías y los totales por PDV no cierran. Desde B6 hay más gente con alcance amplio que paga (el Admin, los Supervisores con varios PDV), así que el problema crece.
Aparte, PermissionService::defaultStationFor tomaba el primer default_station_id no nulo de las asignaciones del país sin ordenar (H3-08): con dos asignaciones y un PDV activo distinto en cada una, el PDV que se grababa podía cambiar de una corrida a otra.
Decision
1. El PDV de un pago sale de esta lista, en este orden (D3-7 b)
pay() graba station_id con ??= sobre esta cascada. La caja solo llena huecos: nunca pisa.
| # | Regla | Dónde |
|---|---|---|
| 1 | El PDV que ya tiene la transacción (lo fijó el primer documento, ADR-008 §1) | $locked->station_id ??= |
| 2 | El PDV activo de la persona en el país (role_assignments.default_station_id) | PermissionService::defaultStationFor |
| 3 | El único PDV de su alcance, si tiene uno solo | PermissionService::resolveStationForResolution |
| 4 | Nuevo. El PDV de la caja de la que sale la plata (países con módulo Caja) | applyCashBoxDiscount devuelve station_id |
| 5 | Sin ninguno: alcance sin acotar (Admin) y país sin Caja → null, como siempre | — |
Un país sin módulo Caja no cambia: no hay caja, y las reglas 1 a 3 y 5 son las de antes (más el rechazo del §3).
Con la regla 4, para un país con Caja el PDV nunca queda vacío: o ya lo resolvieron las reglas 1 a 3, o lo da la caja (y si no hay caja abierta, pay() ya rechazaba con NO_CASH_BOX_OPEN_FOR_USER).
2. El primer documento usa la misma regla
Al subir el primer documento de una ACCEPTED sin PDV, el PDV es el que dan las reglas 2 y 3 y, si no hay, el de la caja que la persona tiene abierta hoy y en el país de la transacción (CashBoxService::openStationIdFor). Dos cajas no cuentan:
- Una de otro país: no dice en qué PDV de este país está parada la persona.
- Una vencida (ADR-013, abierta un día anterior): no puede pagar, y el PDV que fijara el primer documento ya no se corrige al pagar (
station_id ??=). Quien se olvidó de cerrar ayer la caja de A y hoy trabaja en B habría dejado la transacción atribuida a A con la plata saliendo de B —la causa 6, generada por esta misma regla—. Se trata como si no hubiera caja: el multi-PDV recibe el 422 (cuyo mensaje le dice que, si la tiene abierta de un día anterior, la cierre y la abra de nuevo) y el alcance sin acotar sube sin PDV y lo completapay()con la caja de hoy. Se mira la misma sesión que mirapay()(CashSession::abiertaDe, la más reciente), así que las dos acciones nunca discrepan sobre cuál es «la caja de esta persona». Es la salida conservadora y reversible: si el cliente prefiere que la vencida desempate, se quita una condición deopenStationIdFor.
3. El multi-PDV sin PDV activo ni caja se rechaza (D3-3 a)
Cuando allowedStationIds da dos o más PDV, no hay PDV activo y la regla 4 no desempata, subir el primer documento responde 422 ACTIVE_STATION_REQUIRED en vez de guardar null en silencio; pagar responde lo mismo en un país sin Caja (con Caja, sin caja abierta, lo que responde es NO_CASH_BOX_OPEN_FOR_USER, ver abajo). Es lo que ADR-008 §1 ya decía («no puede ser el primero en subir») y el código no hacía.
El predicado es angosto a propósito, y cada punto tiene su test:
- Un alcance sin acotar no se rechaza (
allowedStationIds === null: el Admin, o un perfil sin PDV, o cualquier asignación del país sin PDVs).resolveStationForResolutiondevuelvenullpor dos razones —«2+ PDV sin activo» y «sin acotar»— y solo la primera es ambigua: por eso el rechazo vive enPermissionService::requiresActiveStation, no en esenull. - Una transacción que ya tiene PDV no se rechaza al pagar: el PDV no va a ser
null. - Con módulo Caja pagar sin caja abierta sigue dando
NO_CASH_BOX_OPEN_FOR_USER: es lo que hay que hacer primero, y al hacerlo se resuelve el PDV. El 422 nuevo, para pagar, solo sale en países sin Caja. - No deja nada escrito: sale antes de tocar saldos, caja, archivos o el PDV, y no genera evento de Auditoría.
- El alcance se mide con el permiso de cada acción: al subir el documento, con
transacciones:write(el permiso de esa ruta); al pagar, conpago:write. En la matriz de fábrica son el mismo alcance y por eso el aviso de la ficha de usuario mira solopago:write; si un Admin editara una de las dos celdas, las dos acciones podrían discrepar, y el aviso no lo vería.
Solo un Administrador puede fijar el PDV activo de una persona (su ficha de usuario), así que el mensaje lo dice; con módulo Caja nombra además la otra salida, abrir la caja desde Saldos (y, si la tiene abierta de un día anterior, cerrarla y abrirla de nuevo).
Cómo lo muestra la app. El frontend mapea el código, no el status: antes la subida de documentos leía cualquier 422 como «el archivo no es válido» y mandaba a revisar un PDF que estaba bien. Ahora la subida del primer documento, Pago y la ficha de la transacción muestran una notificación con el título «Falta tu PDV activo» y el mensaje del backend tal cual (dura 12 segundos, más que un error común: es largo y hay que poder actuar). En Pago y en la ficha cierra el modal de confirmación y la transacción sigue sin pagar. Y la ficha de usuario avisa antes (G4.6): un aviso ámbar no bloqueante junto a «PDV activo» que espeja esta regla en utils/pdvActivo.ts. Avisa en los dos casos de «sin PDV activo» —2+ PDV (el 422), o todos los PDV en un país sin Caja (el pago queda sin PDV)— y no avisa con Caja y alcance sin acotar, porque ahí pagar exige una caja abierta y su PDV llena el hueco. Mientras el catálogo de países no cargó, el aviso no afirma si el país tiene Caja (dice las dos cosas). Es un espejo para avisar, no una segunda fuente de verdad: si las dos discreparan, manda el backend.
4. El orden de las asignaciones es fijo (G4.2, H3-08)
defaultStationFor ordena las asignaciones del país por created_at y, si coinciden, por id: gana la más antigua. Es arbitrario pero estable, y la más antigua porque no se mueve cuando se edita otra asignación.
5. Los PAID históricos sin PDV se completan desde el ledger (D3-8)
La migración 2026_10_06_100000_g4_completar_el_pdv_de_los_pagos_viejos completa station_id en los PAID que lo tienen null y tienen un movimiento PAGO, con el PDV de la caja de ese movimiento. Es una atribución derivable del ledger de caja (inmutable), no un dato del pago: no choca con ADR-011 (los datos del pago no se reescriben) ni con el criterio de D3-4 (c). Lo que la hace segura:
- Cambia únicamente
station_id—niupdated_atnilast_updated_at, que es la fecha del pago que viaja a Soterex— y va con SQL directo, sin eventos del modelo. - No adivina: si los
PAGOde una transacción caen en cajas de dos PDV distintos, o el PDV de la caja es de otro país, no se toca. Un PDV que ya tenía (aunque no coincida con el de la caja: causa 6) tampoco. - Un PDV dado de baja también se atribuye: la plata salió de su caja, y
pay()tampoco filtra poractive. Consecuencia que queda escrita: el ranking de PDV del Dashboard y Volumen solo cuentan los PDV activos, así que ese pago deja de caer en «Sin PDV asignado» y no figura en ninguna fila del ranking, aunque el KPI «Pagado hoy» lo siga sumando (lo que ya pasa con cualquier pago de un PDV dado de baja). Lo fijaPdvDePagosViejosMigrationTest. - Deja UN evento de Auditoría
TRANSACTION_STATION_BACKFILLED, sin usuario, con el conteo y de dónde sale el dato, y nada más: ni ids de transacción, ni montos, ni datos del beneficiario. Solo si algo cambió. - Idempotente: una segunda corrida no encuentra nada, no escribe y no audita. Su
down()no deshace nada: no hay forma segura de saber cuáles filas completó esta corrida.
Lo que NO cambia (y por qué queda escrito)
La causa 6 de RV3-17 sigue siendo posible. Con (b), un operador con PDV activo en Mixco Plaza que paga con la caja de Central graba Mixco Plaza: el PDV activo gana, la plata sigue saliendo de Central y los totales por PDV, Cumplimiento y Volumen dicen Mixco para plata de Central. El comportamiento está fijado por un test que lo nombra (TransactionApiTest::test_pay_con_caja_el_pdv_activo_gana_sobre_el_pdv_de_la_caja) para que cambiarlo sea una decisión y no un accidente. Tampoco corrige el backfill (§5): su PDV no es null.
El PDV que fijó el primer documento manda también sobre la caja de quien paga, aunque el primer documento lo haya subido otra persona. Un Admin (alcance sin acotar) con su caja abierta en B sube la Carta de una ACCEPTED y la transacción queda en B (D3-3 a: la subida usa la regla de la caja); si después la paga un Cajero de A con la caja de A, queda PAID en B con la plata saliendo de A. Antes de G4 ese Admin dejaba la transacción sin PDV y pay() la completaba con el de quien pagaba. Es la causa 6 por otra puerta y el plan la prescribe así («con caja abierta, el PDV es el de esa caja»); lo fija PdvDelPagoApiTest::test_el_pdv_que_fijo_el_primer_documento_de_otra_persona_gana_sobre_la_caja_de_quien_paga. Si QC-9 contesta que el PDV es siempre el de la caja que pagó, esto se corrige junto con la causa 6; la salida conservadora mientras tanto sería no fijar el PDV desde la caja al subir cuando el alcance es sin acotar, y dejarlo para pay().
El PDV activo no está obligado a estar dentro del alcance. RoleAssignmentController solo valida que el PDV activo sea del país, no que esté entre los PDV de la asignación (y el selector de la ficha ofrece todos los del país). Un Supervisor acotado a {A, B} con PDV activo C paga con el PDV C —el activo gana sobre la caja—, y después no ve su propio pago en Reporte individual, que acota por allowedStationIds. La brecha es anterior a G4a, y cerrarla es una regla nueva del ABM de Asignación (y del selector, y de lo que hoy ya está cargado en Staging) que el plan no pidió; queda como deuda para cuando se toque ese ABM, con su test por API.
Cancelar desde la pantalla no cambia. Lo hace TransactionCancellationService (solo el Admin, transacciones:delete) con la resolución de siempre —el PDV activo o el único PDV del alcance, y null si no hay ninguno—: no hay caja que desempate y no se rechaza, porque cancelar no mueve plata. Una CANCELLED de un Admin sin PDV activo sigue sin PDV (causa 3).
Se eligió (b) por ser el cambio con menos sorpresa: solo llena huecos y no pisa el PDV activo que el cliente pidió el 2026-07-25.
Alternatives Considered
- (a) Siempre el PDV de la caja que pagó. Unifica todo, elimina la causa 6 y la ambigüedad de las asignaciones múltiples, y deja de depender del PDV activo en países con Caja. Se descartó por ahora porque cambia las cifras por PDV de lo ya reportado para quien tiene un PDV activo distinto de su caja, y el cliente no lo confirmó (QC-9: «¿el PDV de un pago es siempre el de la caja desde la que se pagó, aunque la persona tenga configurado otro PDV activo?»). Si QC-9 contesta que sí, es la opción a seguir y el cambio es chico: invertir la cascada del §1 en
pay()($cashStationId ?? $resolvedStationId) y una migración de datos para los pagos ya atribuidos a un PDV distinto del de su caja, con su evento de Auditoría. - (c) No tocar la lógica y exigir PDV activo en toda asignación ambigua que pague. No arregla los datos viejos, no ayuda al Admin (que no está acotado) y le suma una tarea de configuración a quien administra los usuarios.
- No rechazar al multi-PDV (aceptar
nully confiar en la excepción del pagador de G2.1). El pagador recupera el acceso, pero la transacción sigue saliendo mal de todo lo que mira por PDV. Se descartó (D3-3 a). - Rechazar sobre el
nullderesolveStationForResolution. Rechazaría también al Admin y a cualquier alcance sin acotar, que hoy pagan y suben sin PDV a propósito. De ahírequiresActiveStation.
Consequences
- Positive: la persona acotada ve su propio pago en Reporte individual, el Dashboard lo suma, Cumplimiento trae las columnas 33 a 36 llenas y los totales por PDV cierran, desde el primer día y también para los pagos viejos (§5).
- Positive: el PDV de una transacción deja de depender del orden en que la base devuelva las asignaciones.
- Negative: el multi-PDV sin PDV activo en un país sin Caja no puede pagar ni subir el primer documento hasta que un Administrador le fije el PDV activo. Hay que listar antes en Staging quién cae en el caso (la consulta (b) del runbook de Staging):
supervisor@(dos PDV, sin PDV activo) es uno, y en un país con Caja se destraba abriendo su caja. Los tests que armaban esa combinación se ajustaron; los datos de demo no cambian a propósito:supervisor@conserva sus dos PDV sin PDV activo para poder ver el caso (ver dev.md), y lasPAIDsin PDV queDemoTransactionSeederle atribuye siguen siendo el ejemplo histórico de la causa 3. - Negative: la causa 6 queda documentada y viva (ver arriba).
- Neutral: no toca la integración C2P: una
CANCELLEDpor la API de Soterex sigue sin PDV (causa 2), no hay persona. - Neutral: no cambia ningún saldo ni el ledger: lo único que se escribe es
transactions.station_idy un evento de Auditoría.
Pruebas que lo fijan
TransactionApiTest (el gemelo con Caja del test de multi-PDV, el del PDV activo contra el de la caja, el del PDV único y el que no pisa un PDV ya fijado), PdvDelPagoApiTest (el 422 al subir y al pagar, todo lo que no se rechaza, la caja vencida, la caja de otro usuario y de otro país, la más reciente entre dos sesiones, el PDV fijado por otra persona y la cadena «pagar y verlo en el listado, la ficha y el Dashboard»), ReporteCumplimientoApiTest (las columnas 33 a 36 de ese pago), PermissionServiceTransactionScopeTest (el orden fijo y el predicado requiresActiveStation), NotificationPayloadTest (el paying_office del pago real, que desde G4.1 trae el PDV de la caja) y PdvDePagosViejosMigrationTest (la migración de datos: qué toca, qué no, el evento sin datos personales y la idempotencia).

