Arquitectura
Decisiones de stack (ADRs)
- ADR-001 — Frontend — Vue 3 + Vite, SPA sin SSR
- ADR-002 — Backend — Laravel 13 + PHP 8.5
- ADR-003 — Base de datos — Amazon Aurora (PostgreSQL-Compatible)
Decisiones de producto y modelo de datos (ADRs)
ADR-004 — SSO del portal de API — login Firebase compartido con la app
ADR-005 — Módulo Caja + doble saldo — ⚠️ superseded in part por ADR-007: ledgers inmutables y módulo opcional por país siguen vigentes; el modelo de dos saldos y la apertura con doble usuario, no
ADR-007 — Prefondeo en tres capas — Holding / País / Caja, el pago valida solo la caja, apertura sin Supervisor, moneda de pago configurable por país. ⚠️ En parte reemplazado por ADR-014: tesorería ya no opera con el rol Supervisor
ADR-008 — Documentos de identificación bloquean el pago — carta + anverso + reverso antes de confirmar
ADR-009 — Mecanismo del recorrido guiado — tour declarativo sobre la UI real, anclado con
data-tour, que explica y nunca ejecutaADR-010 — Avisos entre capas de prefondeo — repartir de más avisa y no bloquea, en las dos fronteras (Holding → País y País → Caja)
ADR-011 — Datos del pago obligatorios antes de pagar — se cargan sobre la transacción
ACCEPTEDypay()guarda y paga en una sola llamada atómicaADR-012 — Dirección de la integración y OAuth — Soterex llama a CIS (no al revés), con OAuth 2.0 Client Credentials. ⚠️ En parte reemplazado por ADR-017 y ADR-018: el contrato de SendRequest, Cancel y Notifications ya no es el del spec v1.4
ADR-013 — La caja opera solo el día en que se abrió — apertura y cierre diarios por bloqueo en línea, sin cierre automático; "día" en
America/Guatemala. ⚠️ En parte reemplazado por ADR-021 (§5: quién cierra una caja vencida)ADR-014 — Cuatro perfiles y separación de pagar y cancelar — Cajero, Supervisor, Tesorería y Admin; pagar es
pago:writey cancelartransacciones:delete; el Admin cancela y paga; la comisión del Dashboard sale por permiso, no por nombre de rol; el menú nuevo (Caja, Tesorería, Parámetros)ADR-015 — Los extractos de tesorería son vistas derivadas — cuatro extractos con saldo corrido (Soterex ↔ Holding, Holding, País y PDV) sobre los mismos ledgers: no cambia ningún saldo, reconcilia la planilla del cliente con el modelo de ADR-007 y aclara su relación con ADR-010
ADR-016 — Los datos personales en bloque salen solo por el reporte de Cumplimiento — el listado de Transacciones es una lista blanca, rate limit por usuario y los intentos fuera de alcance se auditan
ADR-017 — El contrato C2P es la especificación de Soterex — SendRequest, Cancel y Notifications se alinean a la especificación de Soterex: rechazos HTTP 200, replay
COD_009sin rechazo (el replay devuelve el estado real endtc_estatus), webhook firmado con HMAC,CANCELLEDen toda cancelación, el MTCN vence y los disparos a demanda del sandbox; registra los riesgos que Carlos decidió dejar abiertos (2026-10-05) y que el scheduler no se prende por ahora. ⚠️ En parte reemplaza a ADR-012ADR-018 — La comisión C2P la calcula CIS con un tarifario por país — tramos de monto por país con fijo, porcentaje o ambos;
feedeja de ser parte del request de SendRequest; la comisión se guarda al crear y cambiar el tarifario no toca lo ya creado; tarifario provisional de Guatemala de 50 USD fijos por transacción, sembrado también en producción y editable por país (decisión de Carlos, 2026-10-05, que reemplaza al 1 % solo fuera de producción). ⚠️ En parte reemplaza a ADR-005 y a la D13 de ADR-012ADR-019 — Los soportes de pago viven en un bucket S3 privado — el disco local del contenedor perdía los archivos en cada deploy (la fila quedaba, el archivo no): bucket privado por ambiente, cifrado y versionado, acceso por el task role sin
DeleteObject, orden de despliegue (imagen,apply, deploy, verificación) y qué queda sin cubrir. Cumple el diseño de E5a §2, que nunca se había construidoADR-020 — El PDV de un pago es el de la caja que pagó — con módulo Caja, el PDV de la caja de la que sale la plata llena el hueco cuando no hay PDV activo ni PDV único (el activo sigue ganando); el multi-PDV sin PDV activo ni caja se rechaza con 422; el orden de las asignaciones es fijo; los
PAIDhistóricos sin PDV se completan desde su movimientoPAGO. ⚠️ En parte reemplaza a E4-multi §2.3ADR-021 — Quién cierra una caja ajena — una caja la cierra quien la abrió, o un Supervisor o un Admin del PDV (403 para el resto); la capacidad se deriva de
apertura_cierre_caja:writeyfondeo_caja:readen una misma asignación, sin tocar la matriz; los saldos de las cajas se ven por PDV (H3-03); la sesión y su operador viajan endisponibles, y el 409 de apertura dice quién la tiene. ⚠️ En parte reemplaza a ADR-013 §5ADR-022 — Alta y baja de cajas — una caja se desactiva y se reactiva, nunca se borra (
cash_boxes.active); «caja operable» es un solo scope (activa, de un PDV activo y de un país con módulo Caja) que comparten Saldos y la apertura; no se desactiva con sesión abierta ni con plata en ninguna moneda (primero se la deja en cero con el motivo de ajuste «Retiro por baja de caja»);agregarCajay la baja de un PDV validan (H3-06); y la línea de país de Saldos (countries[]) reusa «Distribuido en cajas» y nunca suma entre países ni monedasADR-023 — Las reglas de formato del documento de identidad viven en el catálogo — el DPI (13 dígitos, emisor GT) y el Pasaporte (7 a 13 alfanuméricos) son cuatro columnas nullable de
catalog_itemssolo paraID_TYPE(caracteres, mínimo, máximo y país emisor), editables por el Admin y auditadas; sin regex que escriba una persona;datosPago()ypay()las hacen respetar contra el tipo efectivo y el tipo sin reglas no valida; estricto sin separadores y sin repetir el valor en el mensajeADR-029 — La bóveda del PDV y los traspasos entre cajas — cada PDV con Caja tiene una bóveda (la
CashBoxconnumber = 0, sin columna nueva) a la que Tesorería manda la plata y desde la que se reparte a las cajas; no tiene sesión (cash_session_idesnullsi y solo si la caja es la bóveda), no se abre ni se cierra y no paga; un traspaso son dos filasTRASPASOde suma cero (no cambia el saldo del país ni lo distribuido) bajo el permiso nuevotraspaso_caja(Supervisor de sus PDV, Tesorería y Admin; el Cajero no); los extractos del país y del PDV no los muestran; la bóveda con plata bloquea dar de baja un PDV. ⚠️ Cambia permisos de usuarios reales al desplegar. Numeración: 024 a 028 están reservados por la migración a Azure

