Documentación del sistema - 2026-11-18
Billetera Municipal en el POS de CYRE
Un gateway de pagos que permite a los terminales de punto de venta de CYRE, en los comercios adheridos al programa municipal de Villa Allende, aceptar la billetera municipal como una tarjeta más.
Cliente
Cordiez / CYRE S.A.
Integrador
Tipre S.A.
Corrida del ledger
20261116-220858
actualizada el 2026-11-18 17:56 UTC
Puesta en producción
Sin fecha definida. No se ha comprometido ninguna fecha (SPEC).
Utilice el selector Comercial / Técnica de la parte superior. Las flechas del teclado permiten avanzar entre diapositivas y la tecla Esc abre el índice.
Comercial 1
Qué hace
La Municipalidad está reemplazando el vale en papel por una billetera digital. Este sistema permite que la caja existente de un comercio acepte esa billetera sin una segunda aplicación de teléfono y sin conciliación manual.
1. La caja muestra un QR
Al momento del pago, el POS de CYRE muestra un código QR por el importe exacto de la venta.
2. El empleado paga
Un empleado municipal lo escanea con la aplicación de billetera de la Municipalidad. Esa aplicación no forma parte de este desarrollo.
3. La caja recibe el resultado
El POS toma conocimiento de que el pago fue aprobado, venció o fue cancelado, y la venta se cierra como con cualquier otro medio de pago.
4. Todo queda registrado
Cada operación se almacena para poder verificarse luego. Una consola web de administración muestra los intentos, las alertas y la configuración de los comercios.
Un pago puede cancelarse desde la caja. Una venta nunca se cancela. Las credenciales municipales del comercio permanecen en el gateway y nunca llegan a la caja.
Comercial 2
Cómo funciona una venta, en términos simples
- Si el cliente no puede pagar (por ejemplo, por saldo insuficiente), la caja sigue mostrando "en espera" hasta que el QR venza o el cajero presione Esc. Se trata de una limitación de la API municipal (RISKS R-04).
- Si la conexión se corta durante la venta, el gateway nunca informa "denegado" a la caja mientras el resultado sea desconocido. Informa "en espera" hasta poder confirmarlo (CONSTITUTION C5).
- Nunca se crea un segundo cobro para el mismo intento, ni siquiera tras reintentos o un reinicio (CONSTITUTION C4).
Comercial 3
Valor y estado
Terminado y verificado
- Flujo de pago, manejo de fallas y reglas de tiempos (AC-01 a AC-18, AC-23, AC-25 a AC-30 y AC-33 tildados)
- Cinco cambios en el POS de CYRE, verificados sobre el binario real del POS en un banco de pruebas, 2026-11-18
- Runbook (manual de operación) para la instalación, el despliegue y las operaciones
En curso / aún sin tildar
- Criterios de aceptación de la consola de administración (AC-19, 20, 21)
- Panel de pruebas de extremo a extremo (AC-22)
- Pantalla de conciliación diaria (AC-24), condicionada a datos municipales reales
- Manejo de diferencias de importe e intentos retenidos (AC-31, AC-32)
Fuente: casillas de ACCEPTANCE.md, 26 de 33 tildadas.
Postura frente a los riesgos
- Todavía no se capturó tráfico municipal real; el comportamiento se apoya en el documento de la API (R-01, Alto)
- Un pago QR ya abonado no puede revertirse desde la caja; la Municipalidad no ofrece una API de devolución (R-02, Alto)
- Un reinicio de la caja durante el cierre fiscal puede perder una línea de pago QR abonada (R-09, Alto, POS de CYRE)
- Una falla en el decodificador Base64 del entorno de ejecución de Java (R-10, Alto, mitigada con un parámetro de arranque hasta instalar el JDK corregido)
Aún no se probó contra el sandbox municipal real ni contra un POS de CYRE real en un comercio. Toda la evidencia del POS proviene de un banco de pruebas en DOSBox-X.
Comercial 4
Calidad de un vistazo
91,4 RELEASE CANDIDATE
Puntaje de preparación de la última medición registrada en el ledger (2026-11-18 02:51 UTC), tomada cuando contabilizaba 29 de 33 criterios; ACCEPTANCE.md tilda 26 a la fecha. Verde es 80 o más. El motivo del tope no se recalculó para esta presentación.
614
pruebas automatizadas, todas aprobadas
Última ejecución registrada, 2026-11-18. 0 fallas, 0 errores, 0 omitidas.
95,98 %
cobertura de código
2.318 cubiertas, 97 no cubiertas (JaCoCo). Umbral: 90 % en dominio, 80 % global.
100+
revisiones independientes
Revisión de código, revisión adversarial por dos jueces ciegos y relevamientos de mejora, registrados en el ledger al 2026-11-18.
0
escalamientos a una persona
El ledger no registra escalamientos abiertos, hallazgos de producción ni solicitudes de cambio de especificación.
Las revisiones se cuentan a partir del ledger; los conteos por herramienta de problemas encontrados y corregidos no se registran en una forma que esta presentación pudiera utilizar.
Comercial 5
Decisiones y dependencias
| Tema | Por qué importa | Responsable |
|---|---|---|
| Credenciales de sandbox y muestras de tráfico real (R-01) | El gateway se construyó a partir de los ejemplos del documento de la API. Las muestras reales lo confirman. | Operador, junto con la oficina de modernización municipal |
| API de devolución para pagos abonados (R-02) | Hoy un pago QR abonado solo puede revertirse manualmente con la Municipalidad. | Operador, consultar a la Muni |
| Notificaciones en tiempo real (R-07) | La v1 consulta cada 5 segundos; el aviso instantáneo es parte de la v2 y su interfaz no está especificada. | Muni |
| Reinicio de la caja durante el cierre fiscal (R-09) | Posible doble cobro tras una caída entre la aprobación del QR y el fin del cierre fiscal. | CYRE (POS) |
| Actualización del entorno de ejecución de Java (R-10) | El servicio se ejecuta con un parámetro que evita el código Base64 defectuoso hasta instalar el JDK corregido; el CPU del servidor determina si la falla puede activarse. | Operador, consultar a CYRE el modelo de CPU |
| Parámetros de despliegue en cada caja (R-08) | Una caja con la configuración por defecto abandona cobros QR que aún podían pagarse. | Operador, mediante la lista de verificación del runbook |
Técnica 1
Arquitectura
- Estructura hexagonal derivada de GatewayPrismaQR (ADR-001); una prueba de ArchUnit la protege. Paquetes:
adapter/in/{pos,admin},adapter/out/{muni,persistence,security},application,domain,config. - El enlace punteado entre la API municipal y el emulador indica que el emulador la reemplaza en el banco de pruebas; el gateway solo cambia su URL base.
- Stack (ADR-002): Java 25 LTS, Spring Boot 4.1.x, Hibernate 7.4, mssql-jdbc 13, Flyway, React 19, Vite 8, Node 26 LTS (solo para la compilación). SQL Server 2022 es la única base de datos certificada; la 2016 es "compatible, no certificada".
Técnica 2
Contratos y puntos de integración clave
POS hacia gateway (contrato PAGOQR existente, ADR-001, sin autenticación por diseño en una VPN privada)
| Operación | Comportamiento |
|---|---|
POST /api/trxid | Asigna el identificador local del intento para un comercio + sucursal configurados. Sucursal desconocida: 404 "Sucursal no configurada". |
POST /api/trxpago | Crea el cobro municipal y devuelve de inmediato PAGO_ENVIADO junto con el nuevo campo qrdata. Idempotente por id (C4). |
GET /api/trxes/{id} | Estado actual mapeado al estado de PAGOQR; incluye qrdata mientras el cobro todavía pueda pagarse. |
POST /api/trxanulacion | Cancela un cobro pendiente. Si ya fue abonado, se deniega (no existe API municipal de devolución). |
Mapeo de estados que ve el POS
| Estado local | estado devuelto |
|---|---|
| CREATING / PENDING / UNCERTAIN / ISSUED | PAGO_ENVIADO (sigue esperando) |
| PAID, PAID_UNCONFIRMED | PAGO_APROBADO |
| EXPIRED, CANCELLED, REJECTED | REFUND_DENEGADO con el motivo en mensajevarios |
| AMOUNT_MISMATCH, CLOSED_BY_ADMIN | REFUND_DENEGADO "NO cobrar de nuevo" |
REFUND_DENEGADO es deuda heredada: es la única cadena de denegación que el POS respeta hoy.
Gateway hacia la API municipal
Crear, consultar y cancelar con el encabezado X-Api-Key. La clave de idempotencia referenciaExterna = {branch}-{pos}-{trxid} (D1). El entorno (sandbox / producción) se fija por intento y se verifica antes de cada llamada (C6, D5).
Técnica 3
Modelo de estados y tiempos (ADR-003)
Simplificado. Los intentos retenidos y los trabados (diferencia de comercio, MUNI_STUCK) solo terminan mediante un cierre por parte del administrador (D7). Los estados finales nunca se reabren.
| Regla | Valor | Fuente |
|---|---|---|
Vigencia del cobro (muni.charge-ttl-seconds) | 120 s (máximo de la API: 600 s) | ADR-003 |
Consulta municipal periódica (muni.poll-interval-seconds) | 5 s | ADR-003 |
| Consulta final tras el vencimiento (gracia) | 10 s; si sigue PENDIENTE, se cancela antes de cualquier denegación | ADR-003, AC-30 |
Abandono del POS (pos.abandon-after-seconds) | 20 s sin consulta del POS cancelan el cobro | ADR-003, AC-13 |
TIMEOUT_RX del POS (tecla 496) | al menos 210, se recomienda 240 | RUNBOOK sección 6 |
Técnica 4
Comportamiento ante fallas y reglas inviolables
Casos de falla
- E1 tiempo de espera al crear: UNCERTAIN, se reintenta con la misma
referenciaExterna, el POS ve PAGO_ENVIADO. - E2 400/401 municipal: el intento termina, la primera consulta recibe REFUND_DENEGADO con el mensaje municipal; un 401 genera una alerta en el cockpit.
- E3 se rechaza un cashback > 0.
- E4 el saldo insuficiente es invisible para el gateway (R-04).
- Carrera Esc contra el pagador: la cancelación devuelve 409, el intento queda PAID, la consulta final del POS recibe PAGO_APROBADO (AC-23).
Constitución (su incumplimiento es bloqueante)
- C1 importes al centavo, DECIMAL(12,2)
- C2 la clave de API nunca sale del gateway ni se registra en logs
- C3 el número de empleado del pagador nunca se registra en logs
- C4 nunca un segundo cobro para un mismo trxid
- C5 nunca denegar mientras el resultado sea incierto
- C6 nunca mezclar entornos
- C7 los eventos son de solo incorporación (append-only)
- C8 sin credenciales por defecto en el cockpit, BCrypt
Valores operativos por defecto
- Bloqueo del administrador: 5 contraseñas incorrectas, 15 minutos
- MUNI_STUCK tras 12 rechazos consecutivos, luego se consulta cada 300 s
- Retención del registro de mensajes: 90 días, depuración cada hora
- Alertas: PAID_UNCONFIRMED, MUNI_UNAUTHORIZED, AMOUNT_MISMATCH, MUNI_STUCK, ENVIRONMENT_MISMATCH
Técnica 5
Resultados de QA
91,4 RELEASE CANDIDATE
Bloque measured del ledger, 2026-11-18 02:51 UTC. Fase pr-ready, 16 ciclos, sin estancamiento. Motivo del tope: no recalculado para esta presentación (solo captura del ledger).
| Métrica | Valor | Fuente |
|---|---|---|
| Pruebas (última captura 2026-11-18 13:54 UTC) | 614 en total, 614 aprobadas, 0 fallidas, 0 errores, 0 omitidas | captura del ledger, TR-28 PASSED |
| Pruebas en la primera captura | 317 (2026-11-17 02:13 UTC) | captura del ledger |
| Cobertura (JaCoCo, gateway + emulador) | 95,98 % (2.318 cubiertas, 97 no cubiertas); primera captura 94,15 % | captura del ledger |
| Tamaño | 11.330 LOC de producción en 267 archivos; 18.454 LOC de pruebas en 134 archivos | captura del ledger |
| Pruebas por kLOC (derivado) | aproximadamente 54 (614 / 11,33) | calculado a partir de las dos filas anteriores |
| Ejecuciones de pruebas registradas | 28, todas PASSED (mvn -q -DskipITs=false verify) | test_runs del ledger |
| Revisiones registradas | más de 100 (revisiones de código, judgment-day y mejora) | reviews del ledger, 2026-11-18 |
| Controles estáticos | 6 registrados, el último gate:operability | steps del ledger |
| Escalamientos | 0 | ledger |
| Criterios de aceptación | 26 de 33 tildados en ACCEPTANCE.md | ACCEPTANCE.md |
No registrados como números: cobertura de la capa de dominio (el umbral es 90 %, impuesto por una regla de compilación de JaCoCo) y los conteos por herramienta de reportados / corregidos / diferidos / suprimidos.
Técnica 6
Evidencia de extremo a extremo del POS (AC-29, AC-33)
El POS de CYRE es un programa de MS-DOS que ninguna prueba del repositorio puede manejar. Estos criterios se cerraron con ejecuciones registradas del binario real del POS bajo DOSBox-X contra el gateway y el emulador, con la compilación del POS c3ef254 (repositorio S4 del POS). Evidencia: docs/evidence/2026-11-18/.
| Caso | Observado |
|---|---|
QR a partir de qrdata (cambio 1) | Se muestra en la pantalla del POS. |
| Intervalo de consulta desde la tecla 564 (cambio 2) | Consultas separadas por 6,4 s con la tecla 564 = 3; por 5,4 s con 564 = 2. |
| Esc cancela (cambio 3) | trxanulacion aprobada, cobro cancelado, intentos en CANCELLED. |
Respuesta de trxpago perdida (cambio 5) | Primera consulta 11,2 s después del trxpago que traía el QR; pagado. Dos ejecuciones. |
Gateway caído al enviar trxpago (cambio 4) | El POS reenvió el mismo trxpago; QR; pagado. Tres ejecuciones, un cobro por referencia. |
| No ejercitado | El límite de 3 reenvíos. |
Compilación: toda la salida de co.bat (POS_MAIN.EXE y cada POS_*.DLL), con hashes en pos_build.txt; fuentes idénticas al commit c3ef254. Se debe entregar el conjunto completo: el cambio 1 desplaza los ordinales de exportación del EXE y las DLL importan por ordinal. El emulador devuelve un cobro existente ante una referencia repetida, por lo que los archivos del emulador por sí solos no pueden mostrar una segunda creación; "nunca un segundo cobro" se apoya en las pruebas de AC-06.
Técnica 7
Riesgos abiertos, expuestos con claridad
R-09 Alto - el reinicio del POS durante el cierre fiscal pierde una línea de pago QR abonada
Observado en el banco de pruebas del POS, 2026-11-18. Se aprobó un pago QR; el POS se reinició durante su cierre fiscal (unos 23 a 25 s en el banco cuando el servicio CAE no está disponible). El ticket restaurado conservó el artículo pero perdió la línea de pago PAGO QR abonada, y el importe se cobró nuevamente.
En producción la ventana se ubica entre la aprobación del QR y el cierre fiscal. La Muni le cobra al pagador mientras el POS vuelve a solicitar el dinero. El gateway mantiene el intento en PAID y el cockpit lo muestra, pero nada impide el segundo cobro en la caja.
Comportamiento preexistente del POS de CYRE, ajeno al gateway. Regla provisoria: tras un reinicio que restaura un ticket con una línea de PAGO QR, verificar en el cockpit si existe un intento PAID antes de volver a cobrar. Próximo paso: reproducir en un POS real y decidir si un ticket restaurado debe releer su estado de PAGO QR. Responsable: CYRE (POS). Sin mitigar.
Presupuesto de abandono de 20 s (RUNBOOK sección 6)
El gateway cancela un cobro pendiente sin consulta del POS durante 20 s; el corte se produce entre los 20 y unos 26 s. Con la tecla 564 = 2, los intervalos medidos o calculados entre consultas son:
- respuesta perdida: 13 s
- solicitud perdida tras conectar: 18,4 s
- falla la conexión: 18,4 s cuando la siguiente conexión es rápida; las conexiones fallidas tardaron de 7 a 11 s en el banco y una conexión a un gateway en arranque tardó 6 s, de modo que un par lento excede el presupuesto
- dos consultas perdidas seguidas, o una respuesta de
trxpagoperdida seguida de una primera consulta perdida: unos 24 s, fuera del presupuesto con cualquier configuración
Fuera del presupuesto, una venta cancelada se deniega y el cajero reintenta. Si el pagador ya había pagado, la cancelación se rechaza, el intento termina en PAID_UNCONFIRMED con una alerta en el cockpit, y la siguiente consulta devuelve PAGO_APROBADO. El costo de ciclo de 3,4 s se midió en DOSBox-X; debe medirse nuevamente en el primer POS real.
R-10 Alto - falla de Base64 en el JDK (CVE-2026-114938, "Java4Shell")
Afecta a Temurin 25 en CPU con AVX-512 VBMI. La exposición es baja: el gateway decodifica Base64 solo para sus propias claves, aunque no puede descartarse una biblioteca que decodifique datos provistos por un atacante. Mitigado: el servicio arranca con -XX:-UseBASE64Intrinsics (RUNBOOK 4.3). Siguiente paso: verificar el CPU del servidor e instalar el JDK corregido.
R-01 Alto - sin corpus municipal real
Todos los payloads provienen de los ejemplos del documento de la API. 19 comportamientos son supuestos provisorios marcados como ASSUMPTION (RISKS R-06) en el código y se verificarán contra el sandbox cuando exista.
R-02 Alto - sin API de devolución
Un pago QR abonado no puede cancelarse desde el POS. Se gestiona manualmente con la Muni hasta que exista una API.
Medio / Bajo
- R-04 el saldo insuficiente es invisible para el gateway
- R-06 comportamientos indefinidos de la API municipal
- R-08 cada POS necesita un
TIMEOUT_RXde 210 o más y la tecla de consulta configurada - R-07 notificación en tiempo real sin especificar (fuera del alcance de la v1)
Atendidos o cerrados
R-03 (tiempo de espera local menor que el vencimiento del servidor) está atendido por ADR-003 y el cambio 3 del POS. R-05 (QR fijo o dinámico) se resolvió el 2026-11-17: QR dinámico.
Técnica 8
Temas diferidos (ISSUES-DEFERRED.md)
Los hallazgos por debajo del umbral de severidad (BLOCKER, CRITICAL, HIGH) no bloquean el ciclo de QA; se registran, no se ocultan.
- Circuito del dinero, primero para la próxima pasada de endurecimiento (teórico, judgment-day ronda 2): una cancelación del POS que lanza una excepción no registra ninguna solicitud de cancelación, por lo que un pago realizado dentro de los 20 s podría terminar silenciosamente en PAID; y
recordCancelRequestno incrementa la versión, por lo que un poller con una copia desactualizada aún podría guardar PAID. - Puntos teóricos permanentes: un POS que se cae mientras el pagador paga dentro de los 20 s deja un PAID silencioso; bucle posterior al vencimiento sin alerta si la Muni sigue respondiendo PENDIENTE y la cancelación sigue fallando; la recuperación de arranque se ejecuta después de que la API ya está sirviendo.
- A la espera del corpus del sandbox (R-06): valores de estado municipales desconocidos, falta de
expira, reintento sin límite de una creación UNCERTAIN. - Medio / bajo: un 401 en consulta o cancelación no genera alerta; las copias posicionales de registros son frágiles; la revalidación de administración y algunas lecturas no están optimizadas; el cockpit corre sobre HTTP simple bajo el modelo de confianza de la VPN; la compilación requiere internet para Node y npm; no hay una prueba de humo automatizada con navegador sin interfaz.
- Runbook S5 (2026-11-18): dos hallazgos de judgment-day corregidos en
docs/RUNBOOK.mdy confirmados por una persona en el ledger (2 confirmaciones de diferimiento). Todavía requieren validación en el servidor de CYRE con una ejecución con privilegios elevados.
Técnica 9
Lista de verificación de humo (RUNBOOK sección 5)
Después de cada instalación y actualización, únicamente contra un comercio de SANDBOX. Nunca probar con una clave de producción.
- Inicio de sesión en el cockpit desde una dirección permitida; una dirección no permitida recibe 403.
- Crear un comercio y una sucursal de sandbox; la clave de API se muestra una sola vez y nunca más.
- Contrato del POS contra el sandbox:
trxid,trxpago(QR enqrdata), iniciar el bucle de consulta de inmediato, pagar, esperarPAGO_APROBADO. - Cancelar un segundo intento sin pagar dentro de los 20 s de su
trxpago:AUTORIZACION_DE_ANULACION_APROBADA. - La sección "Intentos" del cockpit lista ambos intentos con una línea de tiempo de eventos; "Alertas" está vacía.
- Una sucursal desconocida responde 404 "Sucursal no configurada".
- Desactivar el comercio de prueba o mantenerlo en SANDBOX.
- Verificación del gestor de contraseñas en la puesta en producción: nunca debe ofrecer la clave de API del comercio ni la contraseña de otro usuario.
Despliegue del POS, por terminal (sección 6)
Tecla 543 = 1 (cancelación con Esc); tecla 496 al menos 210, se recomienda 240; tecla 497 = 10; tecla 498 = 5; tecla 564 = 2 (o 1); compilación del POS con los cambios 1 a 5 (commit S4 c3ef254 o posterior); cashback deshabilitado para este medio de pago; un pago de prueba más una cancelación con Esc en un comercio de SANDBOX.