Resumen del alcance — Módulo Caja
Análisis Funcional: Módulo Caja — parte 1 de 7. Índice · Siguiente: Modelo de saldos →
El módulo Caja le agrega a la web app el control del efectivo físico de cada punto de venta: cuánta plata hay en el cajón, quién la puso, quién la sacó y contra qué transacción salió.
No reemplaza nada de lo que ya hacía la app — el Análisis Funcional original sigue vigente tal cual. Es una capa nueva que se enciende por país.
0.1 Qué problema resuelve y para quién
En Ecuador, cuando el cajero paga una transacción de Soterex, el efectivo lo controla el EPOS: el sistema propio de punto de venta que CIS ya opera ahí. La web app no necesita saber nada del cajón — le alcanza con descontar el prefondeo en USD y marcar la transacción como PAID.
Guatemala no tiene EPOS. Sin un sistema que lleve el efectivo del PDV, el cajero quedaba pagando contra un saldo que la app no conocía: la app sabía que la transacción se pagó, pero no si en el cajón había plata para pagarla ni cuánta quedó después. Eso es exactamente lo que el módulo Caja cubre.
Consecuencia de diseño, y es la regla más importante de todo el módulo:
El módulo Caja es opcional por país (flag
countries.modulo_caja, apagado por default). Con la bandera apagada, la app se comporta exactamente como antes de que el módulo existiera: no hay cajas, no hay apertura ni cierre, y el pago no valida ni escribe nada de caja. — Decisión #2 del plan v2 (2026-07-28), ADR-005. ✅ Implementado (TransactionController::pay()entra a la rama de caja solo si$country->modulo_caja).
Ecuador, que está en producción con su EPOS, no lo activa. Guatemala sí.
0.2 Qué incluye el módulo
| Capacidad | Estado |
|---|---|
| Varias cajas por sucursal, numeradas automáticamente — Caja 1, Caja 2… | ✅ Implementado |
| Apertura y cierre de caja, con sesión abierta como precondición para operar | ✅ Implementado |
| Fondeo: sumar efectivo a una caja, con motivo | ✅ Implementado |
| Ajuste: corregir el saldo registrado contra el arqueo físico, en más o en menos, con motivo | ✅ Implementado |
| Descuento automático de la caja al pagar una transacción | ✅ Implementado |
| Tipo de cambio por país, con historial inmutable y auditoría | ✅ Implementado |
| Listado de movimientos por caja + export Excel/PDF con membrete | ✅ Implementado |
| Reporte de Cajas en Reportes: resumen por caja + detalle de movimientos, exportables | ✅ Implementado |
| Prefondeo País como capa propia, y el pago validando solo la caja | ✅ Implementado |
| Moneda de pago configurable por país — Guatemala paga en dólares | ✅ Implementado |
| Catálogo cerrado de motivos de fondeo y ajuste, con filtro en listado y export | ✅ Implementado en la pantalla de Caja; falta el filtro por motivo en Reportes → Cajas |
0.3 Qué explícitamente NO incluye
- No hay conteo de denominaciones. El cierre es por monto total, no por billetes y monedas (decisión #14 del plan v2). Un arqueo que no cuadra se resuelve con un
AJUSTE, no contando en pantalla. - No hay aprobación de pagos por Supervisor. Se decidió explícitamente no implementarla (decisión #7 del plan v2). No es una omisión: el flujo de pago no tiene paso de autorización.
- Tampoco hay autorización de Supervisor para abrir o cerrar caja. La hubo hasta E4b y se eliminó en la revisión del 2026-08-05: el control quedó en el ledger inmutable, no en una firma en el momento (ver 0.4).
- No hay borrado ni edición de movimientos. El ledger es inmutable; un error se corrige con un movimiento nuevo que lo compensa, nunca editando el anterior (ver Modelo de saldos §1.8).
- No hay baja de cajas. Se agregan, no se dan de baja ni se renombran — la numeración nunca se reutiliza.
- No gestiona la logística del efectivo. Los blindados, las transferencias bancarias y la relación con el banco viven afuera; la app registra que la plata llegó a la caja, no cómo viajó. Teresa fue explícita: "no va a haber un lugar donde se pongan los blindados, simplemente el blindado va a estar cuando llegue a la caja" (reunión 2026-08-05).
- No emite todavía los comprobantes membretados de apertura y cierre. Están decididos (decisiones #14 y #15 del plan v2) y las columnas existen en la base, pero nadie los genera hoy — llegan con E5, junto con la papeleta. Ver Preguntas Abiertas #7.
- No toca la integración con Soterex. El módulo Caja es control interno; lo que se le reporta a Soterex sale de la capa Holding, no de la caja.
0.4 Reglas de negocio de más alto nivel
Cada regla dice de dónde sale. Las diecisiete rigen hoy en main: las R9 a R17 llegaron con E4b, mergeada el 2026-08-06.
| # | Regla | Estado | Fuente |
|---|---|---|---|
| R1 | El módulo se activa por país; apagado, cero cambios de comportamiento | ✅ | Decisión #2 del plan v2, 2026-07-28 · ADR-005 |
| R2 | Ningún saldo se almacena — todos se derivan sumando su ledger | ✅ | ADR-005, 2026-07-31 |
| R3 | Los movimientos de caja son inmutables: se corrige compensando, nunca editando | ✅ | ADR-005, 2026-07-31 |
| R4 | La comisión nunca toca la caja — de la caja sale solo el principal | ✅ | Decisión #10 del plan v2, corregida 2026-07-31 |
| R5 | Solo Supervisor y Admin pueden fondear o ajustar una caja | ✅ | Decisión #11 del plan v2 · RoleSeeder (fondeo_caja) |
| R6 | No se puede pagar con la caja cerrada — hace falta una sesión abierta a nombre del operador | ✅ | E4-multi, decisión #3, 2026-08-04 |
| R7 | Cada pago descuenta la caja que abrió el propio operador, no "la caja del PDV" | ✅ | E4-multi, decisión #3, 2026-08-04 |
| R8 | El cierre es por monto total: registra el saldo final y no genera ningún movimiento — la plata se queda en la caja | ✅ | Decisión #14 del plan v2 · ADR-007 §5 |
| R9 | El saldo inicial de apertura se hereda del cierre anterior de esa caja — no se tipea, ni siquiera como sugerencia | ✅ | Reunión 2026-08-05 · ADR-007 §5 |
| R10 | La apertura y el cierre los hace un solo usuario, sin autorización de Supervisor | ✅ | Reunión 2026-08-05 · ADR-007 §4 |
| R11 | El prefondeo tiene tres capas: Holding, País y Caja | ✅ | Reunión 2026-08-05 · ADR-007 §1 |
| R12 | Al pagar se valida solo la caja; el prefondeo deja de bloquear | ✅ | Reunión 2026-08-05 · ADR-007 §2 |
| R13 | El prefondeo del país admite saldo negativo — es información contable, no un error | ✅ | Reunión 2026-08-05 · ADR-007 §2 |
| R14 | Fondear una caja por encima del prefondeo del país avisa, no bloquea | ✅ | Reunión 2026-08-05 · ADR-007 §3 |
| R15 | La moneda de pago es configurable por país; Guatemala paga en dólares | ✅ | Reunión 2026-08-05 · ADR-007 §6 |
| R16 | Los motivos de fondeo y ajuste salen de una lista cerrada, no de texto libre | ✅ | Reunión 2026-08-05 · plan E4b, C8 |
| R17 | Un usuario puede tener una sola caja abierta a la vez; un cambio de turno es cerrar y volver a abrir | ✅ | ADR-007 §5b, 2026-08-06 · índice cash_sessions_one_open_per_user |
Sobre R10 y R9, que son las que más cambian la operatoria diaria, vale citar de dónde salieron:
- Diego Sánchez descartó la autorización del Supervisor al ver que cada movimiento queda auditado y es inmutable. Carlos lo cerró así en la reunión: "Sacamos los validadores para abrir caja y cerrar caja por parte de los supervisores".
- El saldo inicial heredado lo pidió Diego ("que le tome como saldo inicial el saldo del día anterior con el que haya cerrado esta caja") y Teresa lo justificó: "el que comience con el mismo saldo final del día anterior me parece que le da más seguridad al manejo del dinero". Ante la pregunta de Carlos de si convenía ofrecerlo como sugerencia editable, Diego fue tajante: "que lo tome automáticamente, no debería ser como sugerencia".
0.5 Actores
| Actor | Qué hace en este módulo | Permisos (seed real, RoleSeeder) |
|---|---|---|
| Backoffice / cajero | Abre su caja, paga transacciones contra ella, la cierra al terminar el turno. Es quien tiene el efectivo en la mano. | caja L·E · apertura_cierre_caja L·E · tipo_cambio L · sin fondeo_caja |
| Supervisor | Le suma efectivo a las cajas (fondeo) y corrige descuadres (ajuste). Edita el tipo de cambio. Ve todo lo del cajero. | caja L·E · apertura_cierre_caja L·E · fondeo_caja L·E · tipo_cambio L·E |
| Admin | Enciende el módulo en el país, define la moneda local, agrega cajas a una sucursal, y puede hacer todo lo anterior. | Todo, con Borrar |
| Tesorería (Teresa, Diego — CIS-EC) | Carga el prefondeo, concilia el saldo del país contra el extracto bancario, revisa los ajustes. Es el destinatario real de los reportes. | ⚠️ No es un rol del sistema. Hoy opera con rol Supervisor o Admin — ver Preguntas Abiertas #3 |
La matriz completa, con todos los módulos y no solo los de Caja, vive en Matriz de Roles y Permisos §2.1.
0.6 Glosario del dominio
Son términos que se parecen entre sí y se confunden fácil. Vale leerlos antes de seguir — el resto del paquete los usa sin volver a definirlos.
| Término | Qué es |
|---|---|
| Prefondeo Holding | Pool en USD de la sociedad holding, que es a quien Soterex le transfiere la plata. Es el ledger que ya existe (prefunding_entries). Descuenta principal + comisión de cada pago. |
| Prefondeo País | Pool en USD del país operativo. Descuenta solo el principal; nunca ve comisiones. Puede quedar negativo. Es lo que tesorería concilia contra el extracto bancario del país. |
| Caja operativa (o simplemente "caja") | El efectivo físico de una caja de un PDV. Su saldo es la suma de sus movimientos. Una sucursal puede tener varias. |
| Fondeo | Movimiento que suma efectivo a una caja: llegó plata nueva. Siempre positivo. Solo Supervisor/Admin. |
| Ajuste | Movimiento que corrige el saldo registrado para que coincida con la plata realmente contada. Puede ser positivo o negativo. Solo Supervisor/Admin. Carlos lo separó de fondeo en la reunión: "ojo, que esto es solo fondeo, todo aumenta; después están los ajustes, que esto puede ser positivo o negativo". |
| Apertura | Abrir la sesión de trabajo de una caja. Sin sesión abierta no se puede operar ni pagar. El saldo inicial se hereda del cierre anterior y no genera ningún asiento: la plata nunca salió de la caja. |
| Cierre | Cerrar la sesión. Registra el saldo final y no genera ningún asiento: la caja no queda en cero, el efectivo sigue ahí y la próxima apertura arranca con ese mismo saldo. |
| Arqueo | El conteo físico del efectivo del cajón. La app no lo hace: recibe su resultado en forma de ajuste (Faltante de arqueo / Sobrante de arqueo). |
| Blindado | El transporte de caudales que lleva efectivo hasta el PDV. En la app es un motivo de fondeo, no una entidad propia. |
| MTCN | Número de control de la transacción de Soterex. En Caja aparece en la línea de cada movimiento de tipo PAGO, para poder rastrear de qué transacción salió esa plata. |
| Principal | El monto de la transacción que se le entrega al beneficiario — transactions.amount. Es lo único que sale de la caja. |
| Comisión | Lo que Soterex le paga a CIS por la transacción — transactions.fee. La calcula y la devuelve Soterex, CIS no la configura (ADR-005). Es información restringida: nunca aparece en pantallas operativas, solo en Reportes y en el Dashboard de Supervisor. Nunca toca la caja ni el prefondeo del país. |
| TC (tipo de cambio) | Unidades de moneda local por 1 USD. Historial inmutable por país: editar es insertar un registro nuevo, nunca sobreescribir. Solo aplica al pago. |
0.7 Cómo sigue
El documento que sigue, Modelo de saldos, es el más importante del paquete: explica cómo se mueve la plata entre las capas, con el ejemplo numérico que el cliente validó en la reunión. Si vas a tocar el módulo o a operarlo, empezá por ahí.
Análisis Funcional: Módulo Caja — parte 1 de 7. Índice · Siguiente: Modelo de saldos →