Skip to content

Arquitectura ​

Decisiones de stack (ADRs) ​

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 ejecuta

  • ADR-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 ACCEPTED y pay() guarda y paga en una sola llamada atómica

  • ADR-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:write y cancelar transacciones: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_009 sin rechazo (el replay devuelve el estado real en dtc_estatus), webhook firmado con HMAC, CANCELLED en 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-012

  • ADR-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; fee deja 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-012

  • ADR-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 construido

  • ADR-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 PAID históricos sin PDV se completan desde su movimiento PAGO. ⚠️ En parte reemplaza a E4-multi §2.3

  • ADR-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:write y fondeo_caja:read en 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 en disponibles, y el 409 de apertura dice quién la tiene. ⚠️ En parte reemplaza a ADR-013 §5

  • ADR-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»); agregarCaja y 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 monedas

  • ADR-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_items solo para ID_TYPE (caracteres, mínimo, máximo y país emisor), editables por el Admin y auditadas; sin regex que escriba una persona; datosPago() y pay() las hacen respetar contra el tipo efectivo y el tipo sin reglas no valida; estricto sin separadores y sin repetir el valor en el mensaje

  • ADR-029 — La bóveda del PDV y los traspasos entre cajas — cada PDV con Caja tiene una bóveda (la CashBox con number = 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_id es null si y solo si la caja es la bóveda), no se abre ni se cierra y no paga; un traspaso son dos filas TRASPASO de suma cero (no cambia el saldo del país ni lo distribuido) bajo el permiso nuevo traspaso_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

Infraestructura y proceso ​

Documentación viva — se actualiza junto con el código, no es un anexo aparte.