Plan — Ajustes v2: respuesta del cliente a la entrega v1 (Soterex GT)
Date: 2026-10-01
Estado de la ejecución (2026-10-02). B1 a B7 están hechas; B1.5 sigue bloqueada (falta el adjunto del cliente; actualización del 2026-10-07: el adjunto llegó y B1.5 se cerró en el plan v3, G10 y G11, para países y tipos de ID). B1 a B5, verificadas, están mergeadas a
mainen el PR #67 y desplegadas a Staging con el #69. B6 (cuatro perfiles y menú) está en el PR #71 y B7 (tesorería como estado de cuenta) en el PR #72, apilado sobre el de B6; los dos esperan el merge de Carlos, en ese orden. Carlos había parado el plan en B5 y lo retomó el mismo día: las especificaciones de ejecución de B6 y B7 que se usaron están en2026-10-02-ajustes-v2-b6-b7-especificaciones/. Lo que quedó abierto para el cliente de B7 (seis preguntas, ninguna bloqueante) está en ADR-015.
Fuentes:
- Mail de Magaly Benavides (CIS-EC), 2026-10-01, "Herramienta Soterex Guatemala": respuesta punto por punto a la entrega de los ajustes v1 y a las preguntas que les dejamos. Adjunta
Soterex - Reporte completo.xlsx(formato del reporte de Cumplimiento). - Mail de Alexis Aguilar y Magaly, 2026-09-22/23, "Entrenamiento personal Guatemala": la definición formal del módulo de tesorería (
Soterex - GT Definición de módulo de tesorería.xlsx) y el modelo de recibo A4 aprobado para Guatemala. Este pedido es anterior al plan v1 y nunca entró a ningún plan. - Material guardado en
doc/reference/2026-10-01-respuesta-ajustes-v1/. SuREADME.mddetalla qué no se subió por tener datos personales.
Qué es esto: la reconciliación de esas dos fuentes contra el plan v1 y el código de main, las decisiones que salen de ahí, y el plan de ejecución para cerrar todo lo que el cliente pidió.
Estado del que se parte:
- Ajustes v1: A1, A3, A4, A5 y A6 mergeados y en staging. El cliente los probó y dio el OK, con tres observaciones (§1).
- A2, A7 y A8 estaban en espera de respuestas del cliente. Las respuestas llegaron: este plan los destraba como B6, B7 y B4.
- Integración C2P entrante (ADR-012) en staging. No se toca en este plan.
⚠️ Falta un adjunto. El mail del 2026-10-01 cita un documento con las pestañas "módulo tesorería" (perfiles correctos), "catálogos" (listas de Cumplimiento) y "los puntos aún pendientes de corrección". No llegó con el mail que tenemos. Lo que depende de él está marcado en §7. El plan no se frena por eso: lo que se sabe alcanza para B1 a B7, salvo B1.5.
✅ Actualización del 2026-10-07: el adjunto llegó el 2026-10-02 (
Soterex GT - ajustes v2.xlsx, verdoc/reference/2026-10-02-respuesta-ajustes-v2/) y B1.5 se cerró en el plan v3 (G10 y G11) para países y tipos de ID.
1. Reconciliación: qué respondió el cliente
Los puntos con "OK" y sin comentario no generan trabajo. Los que sí:
| # | Punto | Respuesta del cliente | Qué hacemos | Entrega |
|---|---|---|---|---|
| R1 | Listas desplegables (catálogos) | OK, pero "no tenemos opción para crear los tipos de Identificación, parámetro no está creado" | Es un defecto nuestro, con dos causas (§B1). Se corrige | B1.1, B1.2 |
| R2 | ¿Apertura y cierre diarios? | "Sí se requiere que haya una apertura y cierre diario de caja para control de saldos finales por día" | Regla nueva: la caja opera solo el día en que se abrió | B3 |
| R3 | ¿Todos los datos del pago obligatorios salvo Notas? | "Sí, todos son obligatorios salvo notas y deben marcarse como tal" | La regla ya está (ADR-011). Falta la marca visual | B1.3 |
| R4 | Documentos pendientes: aviso + bloqueo del cierre | "Sí, confirmado" | Nada. Queda como está | — |
| R5 | Listas de Cumplimiento para los desplegables | "Adjuntas en el documento adjunto pestaña catálogos" | No tenemos el adjunto. Bloqueado. El adjunto llegó el 2026-10-02 y B1.5 se cerró en el plan v3 (G10 y G11) para países y tipos de ID; ver B1.5 | B1.5 ⏸ → ✅ parcial |
| R6 | Perfiles y menús | "El backoffice de hoy pasa a ser cajero, ya no se necesita perfil de backoffice porque los permisos los tiene el Administrador" | Cuatro perfiles y menú reorganizado | B6 |
| R7 | Reportes: quién accede | "Opción habilitada para todos los perfiles, excepto para el cajero" | A la matriz | B6 |
| R8 | Auditoría: quién accede | "Opción habilitada solo para el Administrador" | A la matriz, y pasa al menú Administración | B6 |
| R9 | ¿El supervisor puede fondear cajas? | "No". Lo que piden es una pestaña en Tesorería con los movimientos de cada PDV, que el supervisor pueda ver | Supervisor queda en solo lectura de fondeos | B6, B7 |
| R10 | Escenario de tesorería | "Tomar en cuenta el documento adjunto pestaña módulo tesorería" | El documento define el escenario 1 (con Holding). Coincide con lo implementado (ADR-007) | B7 |
| R11 | Débitos bancarios, comisión, referencia | "No tomen en cuenta los gastos bancarios en el flujo". El ejemplo muestra la comisión por transacción | Sin gastos bancarios. Comisión como movimiento por cada pago | B7 |
| R12 | Prefondeo como estado de cuenta | Cada movimiento con fecha, referencia (MTCN, débito, crédito) y saldo después del movimiento | Extractos con saldo corrido | B7 |
| R13 | Reporte completo para Cumplimiento | Adjuntan el formato: las columnas marcadas "SE QUEDA" de la hoja Request Pilot List | 36 columnas, en ese orden y con esos nombres | B4 |
| R14 | Columna en rojo del Estado de Situación | "Cada línea debe traer el saldo final luego de dicha operación (balance final), como columna final del reporte" | Columna nueva de saldo corrido | B2 |
| R15 | Modelo de impresión (mail del 22/09) | "El modelo de impresión aprobado para GT es A4", con cinco campos nuevos | Se suma el recibo A4 y convive con la tirilla de 58 mm; el formato se define por país (decisión de Carlos, 2026-10-02) | B5 |
Lo que este mail deja sin efecto del plan v1:
- "Los perfiles no se tocan" (decisión de Carlos del 2026-09-28) valía para la entrega v1. Ahora los perfiles sí cambian, en una entrega propia (B6).
- La pregunta #2b y el punto "cancelar a mano si Soterex no cancela por la API" ya no aplican: Soterex cancela por la API (
POST /api/c2p/v1/Cancel, ADR-012).
2. Mapa de entregas
| Entrega | Qué es | PR |
|---|---|---|
| B1 | Arreglos de la revisión: catálogos, datos de referencia, campos obligatorios | PR 1 |
| B2 | Estado de Situación con balance final | PR 1 |
| B3 | Apertura y cierre diario de caja | PR 1 |
| B4 | Fecha de nacimiento y nacionalidad en el pago (B4.0) + reporte de Cumplimiento (36 columnas) + ciudad y provincia del PDV | PR 1 |
| B5 | Recibo A4 y formato de recibo por país | PR 1 |
| B6 | Perfiles y menú: Cajero, Supervisor, Tesorería, Administrador | PR 2 |
| B7 | Tesorería como estado de cuenta | PR 3 |
Orden y branches
PR 1 docs/plan-ajustes-v2-gt B1 ──▶ B2 ──▶ B3 ──▶ B4 ──▶ B5
│
PR 2 feature/ajustes-v2-perfiles-menu └──▶ B6
│
PR 3 feature/ajustes-v2-tesoreria └──▶ B7- Tres PRs separados por riesgo. B6 cambia quién puede hacer qué y B7 agrega pantallas de plata; se revisan y se mergean por separado de los arreglos.
- Son PRs apilados. El branch de PR 2 sale de la punta del branch de PR 1, y su PR tiene como base ese branch (así el diff muestra solo B6). Lo mismo PR 3 sobre PR 2. Se mergean en orden.
- B4 va antes que B5 porque el recibo imprime la ciudad de la agencia, que B4 agrega al PDV.
- B6 va antes que B7 porque B7 necesita el rol Tesorería y el Supervisor en solo lectura.
- B2 arma el cálculo de saldo corrido que después reusa B7. Hacelo reutilizable desde B2.
3. Decisiones
Las C vienen del cliente y están cerradas. Las P son propuestas del product owner para lo que el cliente no definió: quedan aprobadas cuando Carlos lanza la ejecución, y cada una dice qué cambiaría si se revierte.
Confirmadas por el cliente
| # | Decisión | Fuente |
|---|---|---|
| C1 | Todos los datos del pago son obligatorios salvo Notas, y se marcan como obligatorios en pantalla | Mail 01/10 |
| C2 | Documentos pendientes: aviso permanente + bloqueo del cierre de caja. El pago siguiente no se bloquea | Mail 01/10 |
| C3 | La apertura y el cierre de caja son diarios | Mail 01/10 |
| C4 | Hay cuatro perfiles: Cajero, Supervisor, Tesorería y Administrador. El Backoffice de hoy pasa a ser Cajero. No hay perfil Backoffice | Mail 01/10 |
| C5 | Reportes: todos los perfiles menos el Cajero. Auditoría: solo el Administrador | Mail 01/10 |
| C6 | El Supervisor no fondea cajas. Sí ve los movimientos de las cajas de su PDV | Mail 01/10 |
| C7 | Tesorería opera con el escenario 1: Soterex → CIS Holding → CIS Guatemala → PDV | Excel 22/09 |
| C8 | Los gastos bancarios quedan fuera del sistema | Mail 01/10 |
| C9 | En los extractos, cada movimiento lleva fecha, referencia y saldo después del movimiento | Mail 01/10 |
| C10 | El Estado de Situación lleva el balance final como última columna | Mail 01/10 |
| C11 | El reporte de Cumplimiento tiene las 36 columnas marcadas "SE QUEDA", con esos nombres | Excel adjunto |
| C12 | El recibo de Guatemala es A4 | Mail 22/09 |
| C13 | El medio de pago es siempre efectivo (Carlos, 2026-09-30). No se diseña nada nuevo sobre transferencia. Implementada en el plan v3 (G3, 2026-10-05): el backend responde 422 a otro medio y la pantalla solo ofrece Efectivo | Carlos |
Propuestas del product owner
| # | Decisión | Si se revierte |
|---|---|---|
| P1 ✅ | El cierre diario se fuerza bloqueando, no cerrando solo. Una caja abierta un día anterior no paga ni recibe fondeos o ajustes hasta que alguien la cierre y la vuelva a abrir. No hay cierre automático | Un cierre automático necesita prender el scheduler en staging (Terraform, costo) y definir qué pasa con el bloqueo por documentos pendientes. Es otra entrega |
| P2 | "Día" es la fecha calendario en la zona horaria de la app (America/Guatemala). No se agrega zona horaria por país | Hace falta la columna cuando entre un país con Caja en otra zona |
| P3 | Backoffice → Cajero es un renombre de la fila existente, no un rol nuevo. Las asignaciones de los usuarios se conservan | — |
| P4 | Donde los documentos del cliente dicen "Backoffice" (central o regional), en la app es Admin. El rol sigue llamándose Admin | Si quieren un quinto perfil, es una fila nueva en la matriz, sin código |
| P5 | Pagar y cancelar dejan de ser el mismo permiso. Pagar exige pago:write. Cancelar exige transacciones:delete. Cargar datos del pago y subir soportes sigue en transacciones:write | — |
| P6 ✏️ | Pago queda para Cajero, Supervisor y Admin (Carlos, 2026-10-02: "cancela y paga"). Cancelar queda solo para Admin. Ver "Decisiones de Carlos del 2026-10-02" | Es una celda de la matriz, editable desde la app |
| P7 ✅ | El reporte de Cumplimiento tiene permiso propio (reporte_cumplimiento), sembrado solo para Admin. Trae datos personales de todos los beneficiarios: no viaja con el permiso general de Reportes | Darlo a otro perfil es una celda de la matriz |
| P8 | El PDV pasa a tener ciudad y provincia, elegidas de los catálogos del país. Las piden el reporte de Cumplimiento y el recibo | — |
| P9 ✏️ | El recibo A4 convive con la tirilla de 58 mm y el formato se define por país (Carlos, 2026-10-02; la versión original decía "reemplaza"). Una hoja A4 con dos copias idénticas (cliente y agencia). Ver "Decisiones de Carlos del 2026-10-02" | Quitar la columna formato_recibo y dejar un solo formato |
| P10 | Los extractos de tesorería no cambian el modelo contable (ADR-007): ningún saldo se materializa y fondear una caja sigue sin descontar el país. El extracto del país muestra el disponible para distribuir como saldo corrido, que es exactamente la columna de la planilla del cliente (§B7) | — |
| P11 ✅ | La comisión del Dashboard deja de decidirse por el nombre del rol. La ve quien tiene prefondeo:read (Tesorería y Admin) | — |
| P12 ✏️ | Las columnas del reporte que no tienen dato propio se resuelven como dice la tabla de §B4. Fecha de nacimiento y nacionalidad las carga el cajero en los datos del pago (Carlos, 2026-10-02): no salen vacías ni vienen de Soterex. Ver "Decisiones de Carlos del 2026-10-02" | Dejarlas fuera del formulario y que el reporte las lleve vacías |
| P13 | Los datos de referencia y los permisos nuevos llegan con el deploy, por migración de datos. No dependen de que alguien corra un seeder a mano | — |
Decisiones de Carlos del 2026-10-02
Carlos revisó las propuestas P antes de dormirse. Mandan sobre cualquier otra mención de este documento. ✅ = confirmada tal cual, ✏️ = confirmada con cambios.
| # | Decisión | Qué cambia en las entregas |
|---|---|---|
| P1 ✅ | El cierre diario se fuerza bloqueando, sin cierre automático | Nada |
| P7 ✅ | El reporte de Cumplimiento es solo para Admin | Nada |
| P11 ✅ | La comisión del Dashboard la ve quien tiene prefondeo:read (Tesorería y Admin). El Supervisor deja de verla | Nada |
| P6 ✏️ | El Admin cancela y paga. Cancelar sigue exigiendo transacciones:delete (solo Admin); pagar sigue exigiendo pago:write | B6: en la matriz, pago de Admin pasa de L a L E (era — en la versión original de este plan). El criterio "Admin no puede pagar (403)" se invierte: Admin paga y cancela; Cajero y Supervisor pagan pero no cancelan |
| P9 ✏️ | El recibo A4 no reemplaza a la tirilla: el formato se define por país y se pueden bajar los dos. (a) Columna countries.formato_recibo (a4 | termico), editable por el Admin en Países; Guatemala queda en a4 por migración de datos y los demás países en termico, que es lo que hacen hoy. (b) ?formato=a4|termico opcional; sin él usa el del país. (d) La tirilla de 58 mm queda exactamente como está hoy: los cinco campos nuevos y las etiquetas van solo en el A4 (decisión del product owner, la más conservadora). | B5: no se borra la plantilla de 58 mm ni sus constantes. Se suma la migración de datos y el campo en el ABM de Países. Se agregan al manual 82-admin-paises.md y se documentan los dos formatos |
| P12 ✏️ | Fecha de nacimiento y nacionalidad las carga el cajero en los datos del pago, no vienen de Soterex. Se reusan las columnas transactions.birth_date y nationality (sin migración de esquema), entran a CAMPOS_DEL_PAGO y CAMPOS_OBLIGATORIOS_PAGO (obligatorios por C1 y ADR-011, con asterisco) y salen del bloque de solo lectura de Soterex. La nacionalidad es texto libre (decisión del product owner; un combo de países sería un cambio chico). La fecha es una fecha pasada, sin edad mínima. Los valores no se escriben en logs ni en la metadata de auditoría | B4 arranca con B4.0 (captura). Las columnas 3 y 4 del reporte salen de ahí, en d/m/Y. Se actualiza ADR-011 con una nota de esta fecha. Las transacciones ACCEPTED que ya esperan en staging piden estos dos datos antes de pagarse |
4. Entregas
Las referencias archivo:línea salen de leer main el 2026-10-01. Verificalas antes de apoyarte en ellas.
B1 — Arreglos de la revisión
Commits: B1.
Por qué el cliente no pudo crear tipos de identificación (R1). Dos causas, las dos nuestras:
- El deploy a staging no siembra nada.
deploy-staging.ymlsolo corremigrate --force. La fila de permisoabm_catalogosy los ítems de catálogo (DPI, Pasaporte, departamentos, municipios) existen solo en seeders. Staging tuvo A4 desplegado unas 40 horas sin la pestaña Catálogos accesible y con el desplegable "Tipo de identificación" vacío, hasta que se corriódb:seeda mano el 2026-10-01. Con ese desplegable vacío no se podía pagar. - La pestaña Catálogos abre en el país equivocado.
CatalogosView.vuetoma el primer país de la lista, ordenada alfabéticamente y sin filtrar activos: "El Salvador". El Admin ve "Sin ítems cargados" y, si crea "DPI" ahí, queda en El Salvador y nunca aparece en un pago de Guatemala.
| # | Qué | Dónde | Terminado cuando |
|---|---|---|---|
| B1.1 | Catálogos abre en un país que sirve. El selector lista solo países activos y arranca en el país del usuario (el de su asignación; si tiene varios, el primero activo). Si el tipo y país elegidos no tienen ítems, el vacío lo dice con el nombre del país ("Guatemala no tiene tipos de identificación cargados") | frontend/src/views/admin/CatalogosView.vue, CountryController::index o un filtro en el front | Test con tres países (uno inactivo que ordena primero): abre en el activo. Un Admin de GT crea un tipo de identificación y aparece en el desplegable del pago |
| B1.2 | Los datos de referencia llegan con el deploy (P13). Una migración de datos, idempotente, deja en cualquier base: la fila de permiso de cada módulo nuevo y los ítems base de catálogo (países ISO, departamentos y municipios de GT, DPI y Pasaporte). Crea lo que falta y no pisa lo que existe: un ítem editado o desactivado por el Admin queda como está. Escribí role_permissions sin disparar los eventos del modelo (ver §5). No toques los workflows de deploy | backend/database/migrations/, CatalogGuatemalaSeeder, CatalogCountrySeeder, RoleSeeder | Test: sobre una base migrada y sin db:seed, existen los catálogos de GT y el permiso abm_catalogos de Admin. Correr la migración sobre una base con un ítem desactivado no lo reactiva |
| B1.3 | Campos obligatorios marcados (C1). Asterisco y aria-required en los ocho campos obligatorios de DatosPagoForm, más una leyenda "* obligatorio". La lista sale de CAMPOS_OBLIGATORIOS_PAGO, no se duplica. El patrón de asterisco ya existe copiado a mano en ConfirmActionModal.vue y CancelReasonSelect.vue: extraé un componente chico de label y usalo en los tres | frontend/src/components/DatosPagoForm.vue, ConfirmActionModal.vue, CancelReasonSelect.vue | Notas es el único campo sin asterisco. Test del componente |
| B1.4 | Qué falta para pagar se lee en pantalla. En Pago, el motivo por el que "Iniciar pago" está deshabilitado es hoy solo un title del botón: en una tablet no se ve. Mostralo como texto, igual que ya lo hace el detalle de la transacción. Si el formulario tiene cambios sin guardar, el texto dice que hay que guardar. Si el desplegable de tipo de identificación viene vacío, el formulario lo dice en vez de mostrar solo "Elegí uno" | PagoView.vue, MatchResultCard.vue, DatosPagoForm.vue | Con un dato faltante se lee cuál. Con el catálogo vacío se lee que falta cargarlo |
| B1.5 | ✅ Listas de Cumplimiento — cerrada para países y tipos de ID (2026-10-07, plan de ajustes v3, G10 y G11). Estaba bloqueada: las listas están en la pestaña "catálogos" del adjunto, que llegó el 2026-10-02 (mail de Magaly, Soterex GT - ajustes v2.xlsx). Llegaron 2 de las 4 listas: países (255 filas) y tipos de ID (con su formato y país emisor). Países: se cargaron con una migración de datos como la de B1.2 (2026_10_07_100000_g10_paises_de_cumplimiento): 23 renombres, Kosovo y Antillas Holandesas, y 251 ítems en total; quedan fuera, esperando al cliente (QC-27), Chipre del Norte, Irlanda del Norte, Somalilandia y "Santo Tomas". Tipos de ID: DPI (13 números, emisor GT) y Pasaporte (7 a 13 alfanuméricos, sin emisor) viven como cuatro columnas del catálogo, editables por el Admin (ADR-023). Siguen sin validar contra Cumplimiento los departamentos y los municipios: el cliente no mandó esas listas (QC-29) y se usan las ya cargadas (los 22 departamentos del INE y unos 338 municipios sin cotejar) | — | — |
| B1.6 | Las pestañas de TabbedSectionLayout se dibujan aunque el usuario no tenga permiso, y al entrar el guard lo manda a otra pantalla sin avisar. Ocultá las pestañas que el usuario no puede leer | frontend/src/layouts/TabbedSectionLayout.vue | Un usuario sin abm_catalogos no ve la pestaña Catálogos |
B2 — Estado de Situación con balance final
Commits: B2. Decisión C10.
Hoy el reporte lista transacciones (los tres estados) y asientos de prefondeo del país, con las columnas Fecha / Movimiento / Detalle / Monto / Comisión, en orden descendente y sin desempate (ReportesController::loadSituacionData, ~L269-390). El "Saldo actual" de la tarjeta es el saldo de la capa Holding atribuible al país: asientos menos (principal + comisión) de cada pago.
| # | Qué |
|---|---|
| B2.1 | Columna final "Balance final" en pantalla, Excel y PDF: el saldo de prefondeo del país después de esa operación. Los asientos suman. Los pagos restan principal más comisión. Las transacciones aceptadas y canceladas no mueven el saldo: repiten el de la fila anterior |
| B2.2 | Saldo anterior. El corrido arranca del saldo al inicio del rango (asientos y pagos anteriores a from), que se muestra como primera fila "Saldo anterior". El balance de la última operación del rango tiene que coincidir con el saldo al final del rango |
| B2.3 | Orden determinístico. Hoy dos movimientos en el mismo segundo quedan en orden indefinido. Agregá el desempate por id y calculá el corrido en orden cronológico, aunque la pantalla siga mostrando lo más nuevo arriba |
| B2.4 | Con filtro de PDV, la columna no se muestra, y la pantalla lo explica: el filtro deja afuera los asientos y los pagos de otros PDVs, así que un corrido sobre esas filas no reconcilia con nada |
| B2.5 | Calculalo en un solo lugar reutilizable (un servicio o helper de saldo corrido: movimientos ordenados + saldo de apertura → movimientos con saldo). B7 lo usa para cuatro extractos. Derivado, nunca guardado (ADR-007) |
| B2.6 | Manual de usuario, sección Reportes |
Terminado cuando:
- Con 1000 de prefondeo y un pago de 200 con 7 de comisión, la fila del pago muestra 793, igual que la tarjeta (es el caso que ya fija
ReportesApiTest). - El Excel trae la misma columna con los mismos valores que la pantalla.
- Un test con dos movimientos en el mismo segundo da siempre el mismo orden.
- Un rango que empieza después del primer asiento muestra el saldo anterior correcto.
B3 — Apertura y cierre diario de caja
Commits: B3. Decisiones C3, P1, P2. ADR nuevo: ADR-013.
Hoy nada obliga a cerrar: pay() busca la sesión abierta del usuario y no mira cuándo se abrió (TransactionController::applyCashBoxDiscount, ~L543). Se puede pagar hoy con una caja abierta hace un mes. El reporte de Cajas muestra el saldo actual, no el de cada día.
| # | Qué |
|---|---|
| B3.1 | ADR-013 "La caja opera solo el día en que se abrió": contexto (el cliente pide saldos finales por día), la decisión (bloqueo en línea, sin cierre automático), por qué no un cron (scheduler apagado en staging, y un cierre automático no puede esperar a la papeleta firmada), y la definición de "día" (P2) |
| B3.2 | Backend. Si la sesión abierta del usuario tiene opened_at de un día anterior, pay() responde 422 CASH_SESSION_FROM_PREVIOUS_DAY. Lo mismo fondeo y ajuste sobre esa caja. Lo único que se puede hacer con esa sesión es cerrarla. Subir documentos pendientes sigue permitido: es lo que destraba el cierre |
| B3.3 | Pantalla Caja. Mostrá fecha y hora de apertura de la sesión. Si es de un día anterior: aviso fijo "Esta caja quedó abierta desde el (fecha). Cerrala y abrila de nuevo para operar hoy", con el botón de cierre a mano. El formulario de fondeo y ajuste queda deshabilitado con el motivo |
| B3.4 | Pantalla Pago. El mismo aviso, con link a Caja. "Iniciar pago" deshabilitado con el motivo escrito. El backend manda: el front solo lo refleja |
| B3.5 | Cierres por día en Reportes → Cajas. Una vista nueva sobre cash_sessions: por caja y por día, hora de apertura y quién abrió, saldo inicial, fondeos, ajustes, cantidad y total de pagos, hora de cierre y quién cerró, saldo final. Las sesiones sin cerrar se ven como tales. Exportable a Excel y PDF con el servicio de exports que ya existe, y auditada como el resto |
| B3.6 | Análisis funcional de Caja (doc/functional/2026-08-05-modulo-caja/), manual (31-caja-apertura-cierre.md) y, si corresponde, el paso del recorrido guiado de Caja |
Ojo con la combinación con C2: una caja de ayer con una papeleta firmada sin subir no se puede cerrar, y ahora tampoco se puede pagar con ella. Es lo que el cliente confirmó (el cierre exige la documentación). El aviso de B3.3 tiene que decir las dos cosas cuando pasan juntas, con el link a los pagos pendientes.
Terminado cuando:
- Con una sesión abierta ayer: pagar, fondear y ajustar dan 422 con el código nuevo; cerrar funciona; abrir de nuevo hereda el saldo; pagar vuelve a funcionar. Todo testeado, incluido el borde de medianoche en
America/Guatemala. - El reporte de cierres muestra el saldo final de cada día y coincide con el saldo inicial del día siguiente.
B4 — Reporte de Cumplimiento
Commits: B4. Decisiones C11, P7, P8, P12 (ver "Decisiones de Carlos del 2026-10-02").
Existe un branch viejo, origin/feature/e6-reporte-regulatorio, con un reporte de 36 columnas propias, en español y en otro orden. No está en main y quedó 63 commits atrás. No lo mergees. Sirve como material: mirá su controller y sus tests antes de escribir los nuevos.
| # | Qué |
|---|---|
| B4.0 | Fecha de nacimiento y nacionalidad en los datos del pago (P12, decisión de Carlos del 2026-10-02). Van primero, porque el reporte las necesita. Backend: se suman birth_date y nationality a Transaction::CAMPOS_DEL_PAGO y a CAMPOS_OBLIGATORIOS_PAGO, con validación (birth_date: fecha pasada; nationality: texto corto) en datosPago() y el 422 MISSING_PAYMENT_DATA de pay(). Frontend: dos campos en DatosPagoForm con asterisco (sale de CAMPOS_OBLIGATORIOS_PAGO, no se duplica la lista) y se sacan del bloque de solo lectura DatosSoterexReadOnly. Las columnas ya existen y nadie las escribe; si Soterex las mandara algún día, el formulario las muestra precargadas. El C2P entrante no se toca. Nada de estos valores en logs ni en auditoría. Nota en ADR-011. Tests de backend (obligatorios, inmutables con PAID) y de frontend |
| B4.1 | Ciudad y provincia del PDV (P8). Columnas nuevas en stations, elegidas de los catálogos STATE y CITY del país del PDV (se guarda el código, se muestra la etiqueta). Editables en Estaciones/PDV. Nullable: un PDV viejo sin dato no rompe nada |
| B4.2 | Permiso reporte_cumplimiento (P7), solo lectura, sembrado para Admin. Llega por migración de datos (B1.2). Se suma a la lista de módulos editables de la ficha de usuario y a firstAllowedRoute |
| B4.3 | Endpoint y export. Pestaña nueva "Cumplimiento" en Reportes. Filtros: país (obligatorio), rango por fecha de la transacción, estado (todos, pendiente, pagada, cancelada). Solo Excel. Usa ReportExportService y el tope exports.max_rows. Los montos van como número, no como texto. Las fechas, d/m/Y. Los códigos de catálogo se exportan con su etiqueta |
| B4.4 | Las 36 columnas, con estos nombres y en este orden (tabla de abajo) |
| B4.5 | Auditoría del export (REPORT_EXPORTED, tipo reporte_cumplimiento) con país, rango, estado y cantidad de filas. Sin datos personales en la metadata |
| B4.6 | Manual: sección nueva del módulo reporte_cumplimiento |
| # | Columna | De dónde sale |
|---|---|---|
| 1 | Payment Beneficiary Name | first_name |
| 2 | Payment Beneficiary Last Name | last_name |
| 3 | Payment Beneficiary DOB | birth_date, cargada por el cajero (B4.0), en d/m/Y. Vacía solo en pagos viejos, anteriores a B4.0 |
| 4 | Payment Beneficiary Nationality | nationality, cargada por el cajero (B4.0). Vacía solo en pagos viejos |
| 5 | Payment Beneficiary Phone Number | phone_2, y si no hay, phone |
| 6 | Payment Beneficiary Address | beneficiary_address |
| 7 | Payment Beneficiary City | etiqueta de beneficiary_city |
| 8 | Payment Beneficiary State | etiqueta de beneficiary_state |
| 9 | Payment Beneficiary Country | nombre del país de la transacción |
| 10 | Payment Beneficiary Identification Type | etiqueta de identification_type |
| 11 | Payment Beneficiary Identification Country | nombre del país de identification_country |
| 12 | Payment Beneficiary Identification Number | identification_number |
| 13 | Payment Beneficiary Email | email_2, y si no hay, email |
| 14 | Principal Amount ($) | amount |
| 15 | Total Amount w/fee ($) | amount + fee |
| 16 | Destination Delivery Type | delivery_type: Cash o Bank transfer |
| 17 | Cta Bancaria | bank_account |
| 18 | Notes | notes |
| 19 | Transaction Date | fecha de created_at |
| 20 | Transaction Time | hora de created_at |
| 21 | MTCN Number | mtcn. Desde G9.3 (plan v3) con el prefijo C- por configuración (cumplimiento.mtcn_prefix) |
| 22 | PIN Number | mtcn (en la app el PIN es el MTCN). Sin prefijo, como en la carta |
| 23 | Transaction Status | Sent, constante: es el estado con el que la transacción llega de Soterex. El cliente contestó el 2026-10-02 «Send» (plan v3, RV3-89): una letra de diferencia en un archivo regulatorio, así que no se toca hasta que conteste QC-19 (¿cuál es el literal de su planilla?) |
| 24 | Payer Name | config/cumplimiento.php (payer_names); Guatemala dice "CIS Guatemala" y un país sin entrada sale vacío |
| 25 | Payout Currency | moneda del movimiento de caja del pago. Sin Caja, la moneda de pago del país |
| 26 | Ex. Rate | tipo de cambio del movimiento de caja. Si pagó en USD, 1 |
| 27 | Beneficiary Destination Amount | monto del movimiento de caja, en positivo. Sin conversión, amount |
| 28 | Transaction Expiration Date | expires_at |
| 29 | Transaction Status - Update | Pending, Paid o Cancelled, según status. El cliente lo escribió en español, «pendiente, pagada o cancelada» (plan v3, RV3-91): queda en inglés hasta que conteste QC-20 |
| 30 | Transaction Status-Additional Notes | |
| 31 | Paid Date | fecha de last_updated_at, solo si está pagada |
| 32 | Paid Time | hora de last_updated_at, solo si está pagada |
| 33 | Paid at Branch Name | nombre del PDV |
| 34 | Paid at Branch City | etiqueta de la ciudad del PDV (B4.1) |
| 35 | Paid at Branch State | etiqueta de la provincia del PDV (B4.1) |
| 36 | Paid at Branch Country | nombre del país del PDV |
Las columnas 5 y 13 siguen la regla D2 del plan v1 (el dato adicional primero). Las columnas 23, 24, 29 y 30 son la lectura del product owner de cómo el cliente llena hoy esa planilla a mano; se validan con ellos (§7, pregunta 3). El cliente contestó el 2026-10-02 (plan v3, G9): la 24 y la 30 cambiaron (ver la tabla), la 21 lleva el prefijo C-, y la 23 y la 29 no se tocan hasta QC-19 y QC-20.
Decisiones de la revisión de B4 (2026-10-02), tomadas sin consultar a Carlos y revertibles:
- Las columnas 33 a 36 (Paid at Branch) solo se llenan en las pagadas. La tabla de arriba no las condicionaba al estado, pero una pendiente puede tener PDV (lo toma con el primer documento que sube el cajero, ADR-008) y una cancelada por un usuario también: ninguna se pagó ahí. Se valida junto con la pregunta 3 del §7. Revertir es sacar el
$pagada ?de esas cuatro celdas enReporteCumplimientoService. - El reporte tiene un tope propio de 1000 filas (
exports.cumplimiento_max_rows), por debajo delexports.max_rows(5000) que nombraba el plan: con 36 columnas, PhpSpreadsheet gasta ~23 KB por fila y elmemory_limitde la imagen es de 128 MB (medición enconfig/exports.php). Para períodos más largos hay que bajarlo en tramos; subir el tope exige subir elmemory_limitdel task o escribir el Excel en streaming. Si el volumen mensual de Guatemala se acerca a 1000, resolverlo antes de staging. - El listado de Transacciones pasa a ser una lista blanca, el límite de descargas es por usuario y el intento fuera de alcance se audita: ADR-016.
- Las fechas del reporte van como texto
d/m/Y, no como fecha de Excel (la de nacimiento no tiene cota de edad validada). Si el cliente quiere ordenar y filtrar por fecha en Excel, las columnas 19, 28 y 31 se pueden pasar a fecha real con formatodd/mm/yyyy; la de nacimiento conviene dejarla como texto.
Terminado cuando:
- El Excel trae exactamente esas 36 columnas, con esos encabezados y en ese orden: hay un test que compara la lista entera.
- Una transacción pagada con Caja sale con moneda, tipo de cambio y monto destino del movimiento.
- Un usuario con
reportes:readpero sinreporte_cumplimientorecibe 403 y no ve la pestaña. - El registro de auditoría del export no contiene ningún dato del beneficiario.
- Un pago hecho después de B4.0 sale con fecha de nacimiento y nacionalidad en las columnas 3 y 4;
pay()rechaza (422) un pago sin esos dos datos, y con PAID quedan inmutables.
B5 — Recibo A4
Commits: B5. Decisiones C12, P9 (versión de Carlos del 2026-10-02: dos formatos, por país). Depende de B4.1.
Hoy PapeletaService genera un ticket de 58 × 200 mm. El modelo aprobado para Guatemala es una hoja A4 vertical con dos copias idénticas del recibo, una para el cliente y otra para la agencia. La tirilla no se borra: el formato lo define el país y se pueden bajar los dos (ver P9 en "Decisiones de Carlos del 2026-10-02"). Todo lo que sigue describe el A4, salvo B5.1, B5.4, B5.6 y B5.7.
Cada copia lleva, en este orden (los marcados con ★ son nuevos respecto de la tirilla):
| Bloque | Campos |
|---|---|
| Encabezado | "SOTEREX", el logo de CIS, "PARA RECIBIR DINERO" |
| Beneficiario | Beneficiario · Tipo de identificación · No. de identificación · ★ País de emisión |
| Origen | Remitente · País de origen |
| Transacción | MTCN · Fecha/Hora (la del pago) |
| Domicilio del beneficiario | ★ Provincia/Estado · ★ Ciudad · ★ Dirección · Teléfono · ★ Mail |
| Agencia | Agencia (nombre del PDV) · Ciudad (la del PDV, de B4.1) · Operador |
| Montos | Monto enviado · Monto recibido · Total · Moneda de pago · Tasa de cambio |
| Estado | Transacción fija: "Sí / No", impreso tal cual para marcar a mano · Tipo de transacción: PAGADO |
| Pie | Declaración del cliente ( |
| # | Qué |
|---|---|
| B5.1 | Plantilla A4 nueva, con las dos copias separadas por una línea de corte. No reemplaza la de 58 mm: la plantilla de la tirilla y sus constantes se conservan tal cual (P9). PapeletaService elige la plantilla según el formato y comparte el armado de los datos |
| B5.2 | Etiquetas, no códigos. Hoy el recibo imprime el código del tipo de identificación (DPI). Tipo de identificación, país de emisión, provincia y ciudad se imprimen con la etiqueta del catálogo. Teléfono y mail siguen la regla D2 del plan v1 |
| B5.3 | |
| B5.4 | El endpoint y los permisos no cambian: se suma un parámetro opcional formato (a4 | termico) que, si falta, toma el del país de la transacción. La auditoría (PAPELETA_GENERATED) suma el formato usado a su metadata, sin datos personales. El documento "papeleta firmada" que se sube después no cambia |
| B5.5 | Actualizá doc/functional/2026-08-07-pago-con-documentos/03-papeleta.md (los dos formatos y qué decisión del plan v2 queda parcialmente reemplazada) y el manual de Pago |
| B5.6 | Formato por país (P9, Carlos). Columna countries.formato_recibo (a4 | termico, no nula). Una migración de datos deja Guatemala en a4 y los demás países en termico (sin pisar un valor ya editado). Editable por el Admin en Administración → Países (formulario, validación y test del controller; auditado como el resto de los cambios del país). El recibo se resuelve por el país de la transacción |
| B5.7 | Pantalla. DocumentacionPago) baja el formato del país; un menú secundario ("Descargar en otro formato") baja el otro. Desktop y celular. Los textos dicen "A4" y "Térmica 58 mm".82-admin-paises.md explica el campo |
Terminado cuando:
- El PDF A4 de una transacción pagada es una hoja con las dos copias, todos los campos de la tabla, y entra en una sola página aun con nombre y dirección largos. Abrilo y miralo: un test de que "genera un PDF" no alcanza.
- El PDF de la tirilla de 58 mm sale igual que antes de B5 (mismo contenido y tamaño).
- Una transacción de un país en
a4baja A4 por defecto y la tirilla con?formato=termico; una de un país entermico, al revés. Unformatoinválido da 422. Lo cubre un test por API. - El Admin cambia el formato de un país desde Países y el cambio se ve en la siguiente papeleta.
B6 — Perfiles y menú
Commits: B6. Branch feature/ajustes-v2-perfiles-menu, PR 2. Decisiones C4, C5, C6, P3–P6, P11. ADR nuevo: ADR-014. Pasa por security antes del PR.
La matriz objetivo
L leer, E escribir, B borrar. En negrita, lo que cambia respecto de hoy.
| Módulo | Cajero | Supervisor | Tesorería (nuevo) | Admin |
|---|---|---|---|---|
pago | L E | L E | — | L E (Carlos, 2026-10-02: el Admin cancela y paga) |
transacciones | L E | L E | — | L E B |
caja | L E | L E | L | L E B |
apertura_cierre_caja | L E | L E | — | L E B |
fondeo_caja | — | L (sin E) | L E | L E B |
prefondeo | — | — | L E | L E B |
prefondeo_pais | — | — | L E | L E B |
tipo_cambio | L | L (sin E) | L E | L E B |
reportes | — | L | L | L |
reporte_cumplimiento (B4) | — | — | — | L |
dashboard | — | L | L | L |
auditoria | — | — | — | L |
abm_* (los siete) | — | — | — | L E B |
Qué significa cada fila que cambia de sentido (P5):
- Pagar exige
pago:write. Hoy exigetransacciones:write. - Cancelar exige
transacciones:delete. Hoy exigetransacciones:write. Ese permiso ya existe, hoy lo tiene solo Admin y no lo consulta nadie. - Cargar datos del pago, subir y ver soportes siguen en
transacciones:write. - La cancelación que pide Soterex por la API (
C2PController) no pasa por estos permisos y no cambia.
El menú objetivo
| Grupo | Ítem | Hoy se llama | Permiso |
|---|---|---|---|
| General | Dashboard | igual | dashboard |
| Caja (antes "Operación") | Pago | igual | pago |
| Reporte individual | Transacciones | transacciones | |
| Saldos | Caja | caja | |
| Tesorería (nuevo) | Prefondeo Soterex | Prefondeo Holding | prefondeo |
| Fondeo PDVs | Prefondeo País | prefondeo_pais o fondeo_caja | |
| Tipo de cambio | pestaña de Ubicaciones | tipo_cambio | |
| Reportes | Reportes | igual | reportes |
| Administración | Usuarios y Accesos | igual | igual |
| Parámetros | Ubicaciones | países, estaciones, catálogos | |
| Configuración | igual | igual | |
| Auditoría | estaba en Operación | auditoria | |
| Documentación | igual | igual | — |
Cambian las etiquetas y la agrupación. No cambian las claves de módulo, los name de las rutas ni los data-tour. Renombrar una clave tocaría rutas, controllers, la base, el manual y todos los tests, y no aporta nada.
| # | Qué |
|---|---|
| B6.1 | ADR-014 "Cuatro perfiles y separación de pagar y cancelar": los perfiles, la matriz, P3 a P6, y que reemplaza las decisiones anteriores que contradice (tesorería operando como Supervisor, Auditoría visible para Backoffice, tipo de cambio editado por Supervisor) |
| B6.2 | Migración de datos de los perfiles (P13). En este orden: renombra la fila Backoffice a Cajero (P3); crea el rol Tesorería con su fila por módulo; aplica celda por celda los cambios en negrita de la matriz. Idempotente, sin disparar los eventos del modelo, y sin tocar las celdas que no están en la lista. RoleSeeder::MATRIX y DESCRIPTIONS quedan iguales al resultado, para las bases nuevas |
| B6.3 | Separar pagar de cancelar (P5). Gate de pay a pago:write, gate de cancel a transacciones:delete, en la ruta y en el controller. En el front: los botones de Pago, MatchResultCard y TransaccionDetalleView siguen al permiso nuevo. El backend manda |
| B6.4 | Menú según la tabla: grupos, etiquetas, Auditoría a Administración, Tipo de cambio a Tesorería con ruta propia (la vieja redirige). Títulos de pantalla, barra mobile, y firstAllowedRoute |
| B6.5 | Sacar las decisiones por nombre de rol. DashboardController::isSupervisorForCountry compara role->name === 'Supervisor': pasa a permiso (P11). Revisá el resto de los usos por nombre: el manual en PDF por rol tiene que generar cuatro, con "Tesorería" incluida |
| B6.6 | La ficha de usuario edita todos los módulos. UsuariosView.vue tiene la lista a mano con 15 de 18: faltan pago, prefondeo_pais y abm_catalogos, que hoy no se pueden editar desde la app. Con P6 eso deja de ser tolerable. Que la lista salga del backend. Corregí los textos "los 3 roles son fijos" |
| B6.7 | Usuarios de prueba. DevUserSeeder y StagingTestUsersSeeder: el usuario de backoffice pasa a rol Cajero sin cambiar el mail (lo usan los seeders de demo y ya existe en Firebase), y se agrega un usuario de Tesorería. Correr el seeder de staging lo decide Carlos |
| B6.8 | Documentación. Análisis funcional (matriz de roles y mapa de pantallas), los Markdown del manual que nombran roles o pantallas, doc/environments/dev.md y staging.md. Un Markdown nuevo del manual para lo que hoy no tiene |
Terminado cuando:
- Sobre una base con la matriz vieja y usuarios asignados a Backoffice, la migración deja la matriz objetivo, el rol renombrado y las mismas asignaciones. Correrla dos veces da lo mismo.
- Un test compara
RoleSeeder::MATRIXcon el resultado de la migración: no pueden diferir. - Cajero: entra en Pago, paga, no puede cancelar (403 por API), ve solo sus transacciones, no ve Reportes ni Auditoría.
- Supervisor: tiene Pago, no puede cancelar (403 por API), no puede fondear ni ajustar (403), ve saldos y movimientos de las cajas de su PDV, no ve Prefondeo.
- Tesorería: fondea cajas, carga prefondeos y tipo de cambio, ve Reportes; no ve Pago ni transacciones, y no accede por URL ni por API.
- Admin: cancela y paga (decisión de Carlos, 2026-10-02), ve Auditoría.
- Cada uno cae en una pantalla que puede ver al loguearse, en desktop y en mobile.
B7 — Tesorería como estado de cuenta
Commits: B7. Branch feature/ajustes-v2-tesoreria, PR 3. Decisiones C7–C9, P10. ADR nuevo: ADR-015.
El cliente quiere ver la plata como un extracto bancario: una línea por movimiento, con el saldo que quedó después. Hoy las pantallas de prefondeo muestran un saldo total y la lista de asientos; los pagos no aparecen como movimientos, se restan por atrás.
No se toca cómo se calculan los saldos (P10). Se agregan cuatro extractos que muestran los mismos números de otra forma:
| Pantalla | Pestaña | Créditos | Débitos | El saldo corrido es | Permiso |
|---|---|---|---|---|---|
| Prefondeo Soterex | Soterex ↔ CIS Holding | Prefondeo recibido de Soterex | Cada pago: principal + comisión. Referencia: MTCN | Lo que queda del prefondeo de Soterex. Es el saldo global de hoy | prefondeo |
| Prefondeo Soterex | CIS Holding | Prefondeo recibido · la comisión de cada pago (referencia: MTCN) | Cada envío a un país | Lo que tiene la Holding sin repartir, más lo ganado | prefondeo |
| Fondeo PDVs | País | Prefondeo recibido de la Holding | Cada fondeo a una caja (referencia: PDV y caja). Los ajustes, con su signo | El disponible para distribuir del país | prefondeo_pais |
| Fondeo PDVs | PDV | Fondeos a las cajas del PDV | Cada pago (referencia: MTCN). Los ajustes, con su signo | Lo que tiene el PDV en sus cajas | fondeo_caja + alcance por PDV |
Columnas de los cuatro: Fecha · Concepto · Referencia · Débito · Crédito · Saldo. El de PDV suma la columna Caja.
Por qué esto cierra una contradicción vieja. En la planilla del cliente, fondear un PDV baja el saldo de CIS Guatemala (30.000 → 25.000 → 7.000). En la app el saldo del país no baja al fondear (ADR-007, decisión de Carlos del 2026-08-07). Los dos números son correctos: el de la planilla es nuestro disponible para distribuir y el "saldo final" de la planilla (12.500) es nuestro saldo del país. El extracto del país muestra el primero como corrido y el segundo en el encabezado.
| # | Qué |
|---|---|
| B7.1 | ADR-015 "Los extractos de tesorería son vistas derivadas": los cuatro extractos, de qué ledger sale cada movimiento, P10, la reconciliación con la planilla del cliente, y la relación con ADR-010 (sigue en "Proposed" y sin implementar: su pregunta abierta sobre el disponible de la Holding se responde acá con la fórmula de la planilla: recibido − enviado a países + comisiones) |
| B7.2 | Referencia en los asientos de la Holding. prefunding_entries no tiene ningún campo de referencia. Agregá uno opcional, y el campo en el formulario, como ya lo tiene el prefondeo del país |
| B7.3 | Backend de los cuatro extractos, sobre el helper de B2.5: saldo anterior, rango de fechas, orden determinístico, paginación que no rompa el corrido. Cada uno con su permiso. El de PDV respeta el alcance por PDV de la asignación: un Supervisor ve los suyos y nada más |
| B7.4 | Los extractos no muestran datos del beneficiario. Solo MTCN y montos: Tesorería no tiene permiso sobre transacciones |
| B7.5 | Pantallas. Las dos pantallas pasan a tener pestañas. El formulario de alta de asiento y el de fondeo siguen donde están, para quien tiene escritura. Los saldos negativos, en rojo |
| B7.6 | Export a Excel y PDF de cada extracto, auditado |
| B7.7 | Manual (40-prefondeo.md, 41-prefondeo-pais.md), análisis funcional de Caja, y el recorrido guiado de Prefondeo si se mueve algún data-tour |
Alcance acotado: los extractos de País y PDV se hacen para países que pagan en USD, que es Guatemala. Si el país paga en moneda local (hoy ninguno), el extracto muestra los movimientos sin saldo corrido y lo dice. Mezclar monedas en un corrido es MVP2.
Terminado cuando un test reproduce la planilla del cliente (hoja Módulo tesorería, filas 19 a 34) y da los mismos saldos:
| Paso | Soterex ↔ Holding | CIS Holding | País GT (disponible) | PDV1 | PDV2 |
|---|---|---|---|---|---|
| Prefondeo de 50.000 a la Holding | 50.000 | 50.000 | |||
| Envío de 30.000 a Guatemala | 20.000 | 30.000 | |||
| Fondeo de 5.000 a PDV1 | 25.000 | 5.000 | |||
| Fondeo de 18.000 a PDV2 | 7.000 | 18.000 | |||
| Pago de 1.000, comisión 10, en PDV1 | 48.990 | 20.010 | 4.000 | ||
| Pago de 2.500, comisión 30, en PDV1 | 46.460 | 20.040 | 1.500 | ||
| Pago de 4.500, comisión 54, en PDV2 | 41.906 | 20.094 | 13.500 | ||
| Pago de 5.000, comisión 60, en PDV2 | 36.846 | 20.154 | 8.500 | ||
| Pago de 4.500, comisión 54, en PDV2 | 32.292 | 20.208 | 7.000 | 1.500 | 4.000 |
Y el saldo del país (el contable, no el disponible) da 12.500.
Además: un Supervisor de PDV1 pide el extracto de PDV2 y recibe 403.
Documentación: qué se actualiza en cada entrega
Una entrega no está terminada si su documentación no está al día. Va en los mismos commits que el código, no en un pase al final. Esta tabla manda sobre las menciones sueltas de cada entrega: si una fila lista un archivo, se actualiza aunque la entrega no lo nombre.
Los tres análisis funcionales viven en doc/functional/: el general (2026-07-24-soterex-integracion/), el de Caja (2026-08-05-modulo-caja/) y el de pago (2026-08-07-pago-con-documentos/). El manual, en doc/manual/, un Markdown por módulo.
| Entrega | Análisis funcional | Manual de usuario | Otros |
|---|---|---|---|
| B1 | Pago: 02-datos-y-documentos.md (campos marcados, aviso de catálogo vacío) | 10-pago.md, 85-admin-catalogos.md | doc/environments/staging.md y dev.md: los datos de referencia llegan por migración, ya no hay que correr db:seed después de un deploy |
| B2 | General: 05-secuencias-pantalla.md (Estado de Situación con balance final) | 60-reportes.md | — |
| B3 | Caja: 00-resumen-caja.md (la regla nueva del cierre diario), 02-flujos-caja.md, 03-diagramas-actividad-caja.md, 04-secuencias-pantalla-caja.md | 30-caja.md, 31-caja-apertura-cierre.md, 10-pago.md (el aviso nuevo), 60-reportes.md (cierres por día) | ADR-013 · recorrido guiado de Caja si cambia un paso |
| B4 | General: 01-sitemap.md (pestaña nueva), 02-roles-permisos.md (módulo nuevo), 05-secuencias-pantalla.md. Pago: 04-preguntas-abiertas.md (el reporte y la fecha de nacimiento / nacionalidad dejan de estar pendientes), 02-datos-y-documentos.md (los dos campos nuevos del formulario del pago) | Markdown nuevo del módulo reporte_cumplimiento, 83-admin-estaciones.md (ciudad y provincia del PDV), 10-pago.md (fecha de nacimiento y nacionalidad obligatorias) | Nota en ADR-011 (los dos campos nuevos son obligatorios) |
| B5 | Pago: 03-papeleta.md (los dos formatos y el formato por país), 01-flujo-del-pago.md (incluye redibujar los diagramas Mermaid §1.1, §1.4 y §1.5, que B1 dejó con un aviso de desactualización) | 10-pago.md, 82-admin-paises.md (campo formato de recibo) | — |
| B6 | General: 01-sitemap.md (el menú nuevo, con su diagrama), 02-roles-permisos.md (la matriz de cuatro perfiles entera), 03-user-flows.md (un flujo por perfil: cambian Cajero, Supervisor y Admin, y se agrega Tesorería), 05-secuencias-pantalla.md | Todos: revisá cada Markdown por nombres de rol ("Backoffice") y de pantalla ("Caja", "Transacciones", "Ubicaciones", "Prefondeo Holding", "Prefondeo País"). Seguro: 00-primeros-pasos.md, 10-pago.md, 20-transacciones.md, 30-caja.md, 32-caja-fondeo.md, 50-dashboard.md, 70-tipo-cambio.md, 80-admin-usuarios.md, 81-admin-asignacion.md, 85-admin-catalogos.md, 90-auditoria.md | ADR-014 · doc/environments/dev.md y staging.md (usuarios de prueba) · textos del recorrido guiado que nombran pantallas |
| B7 | Caja: 01-modelo-de-saldos.md (los cuatro extractos y la reconciliación con la planilla del cliente, con un diagrama: es la deuda que ADR-007 dejó anotada), 04-secuencias-pantalla-caja.md. General: 01-sitemap.md (pestañas nuevas) | 40-prefondeo.md, 41-prefondeo-pais.md, 32-caja-fondeo.md | ADR-015 · recorrido guiado de Prefondeo si se mueve un data-tour |
Además, para todas:
- Los diagramas Mermaid del análisis funcional (mapa de pantallas, flujos, matriz) se actualizan, no solo el texto que los rodea.
- El manual en PDF por perfil se genera con
php artisan manual:generar-pdf. Después de B6 tienen que salir cuatro, uno por perfil, y cada uno con solo las secciones que ese perfil puede ver. Abrí los cuatro. - El manual dentro de la app (
/documentacion/manual-usuario) se mira logueado con cada perfil: muestra las secciones según los permisos del usuario. - Los ADRs nuevos van al índice
doc/architecture/index.md. ADR-014 marca qué decisiones anteriores reemplaza. - Al cerrar el último PR, poné al día el estado del proyecto en
CLAUDE.mdy endoc/README.md(que tiene la tabla del 2026-08-05): qué entregas de este plan están hechas y en qué PR. Sin tocar lo que no es de este plan. - Corré
npm run docs:buildendoc/. Un link roto corta el deploy de la documentación.
5. Riesgos
- Escribir
role_permissionscon los eventos del modelo prendidos. El hooksavingfuerzacan_delete ⇒ can_write ⇒ can_read. Ya rompió la pantalla Pago una vez (comentario deRoleSeeder::run). B1.2 y B6.2 escriben permisos: siempre sin eventos. - Renombrar el rol por el camino equivocado.
RoleSeederbusca el rol por nombre: cambiar la clave deMATRIXsin renombrar antes la fila crea un rol nuevo y deja a todos los usuarios en "Backoffice", con los permisos viejos. El renombre es de la fila (B6.2) y va primero. RoleSeederpisa lo editado desde la app cada vez que alguien lo corre. Por eso los cambios de B6 viajan por migración y no por "correr el seeder en staging".- Quién es "supervisor" se decide por
fondeo_caja:read, en seis lugares. Tesorería lo recibe. Revisá cada uno: no tiene que ganar acceso a transacciones ni a soportes por ese camino. firstAllowedRoutey la barra mobile ya dejaron a un rol sin pantalla de inicio dos veces. Cada perfil nuevo o modificado se prueba logueándose.- B6 cambia permisos de usuarios reales de staging en el momento del deploy. El cliente está probando. El deploy necesita el ok de Carlos, como siempre, y conviene avisarle a Magaly antes.
- Saldo corrido y paginación. Calcular el corrido sobre la página en vez de sobre el rango da números que parecen bien y están mal. El helper de B2.5 se testea con más de una página.
- B5 es visual. Un recibo que desborda a dos páginas pasa todos los tests.
6. Fuera de alcance (a propósito)
- Cierre automático de caja y cualquier cosa que necesite el scheduler en staging.
- Alerta de reposición al 30 % y la columna de porcentaje de la planilla de tesorería. Está en el Excel desde agosto; el mail no la pide. Queda anotada.
- Tabla de comisiones por tramos. La comisión la sigue mandando Soterex por transacción (decisión del 2026-08-07).
- Cambios al Dashboard, salvo P11. El cliente dijo que dependían del escenario; ya está definido y todavía no dijo qué quiere (§7, pregunta 7).
- Caja principal del PDV y transferencias entre cajas. El extracto por PDV suma sus cajas; no se agrega un nivel de saldo nuevo.
- F2 del plan v3 (aviso de sobregiro de la Holding, ADR-010). B7 cambia el terreno sobre el que estaba pensada: no la ejecutes hasta cerrar B7.
- Fecha de nacimiento y nacionalidad en la API de Soterex (
SendRequest): no se piden. Las carga el cajero en el formulario del pago (B4.0, decisión de Carlos del 2026-10-02). - La integración C2P, el deploy a staging y cualquier cosa de producción.
7. Pendientes del cliente y dependencias
| # | Qué falta | De quién | Qué bloquea | Mientras tanto |
|---|---|---|---|---|
| 1 | El adjunto del mail del 01/10: pestañas "módulo tesorería" (perfiles), "catálogos" y "puntos aún pendientes de corrección" | Carlos lo baja del mail de las 15:57 | B1.5. Puede traer pedidos que este plan no ve | Se avanza con B1 a B7. ✅ Llegó el 2026-10-02 (plan v3); B1.5 cerrada para países y tipos de ID (G10 y G11); departamentos y municipios sin respuesta (QC-29) |
| 2 | ✅ Resuelta por Carlos (2026-10-02): fecha de nacimiento y nacionalidad las carga el cajero en los datos del pago (B4.0). Queda por avisarle al cliente que el formulario del cajero tiene dos campos obligatorios más | — | — | — |
| 3 | Cuatro columnas del reporte que el cliente hoy llena a mano: Transaction Status, Payer Name, Transaction Status - Update y Additional Notes. Validar la lectura de §B4. Y si el MTCN lleva el prefijo "C-" que tiene en su planilla | Magaly | Nada: se ajusta | Como dice §B4. ✅ Contestada el 2026-10-02 (plan v3, G9): Payer Name "CIS Guatemala" por país, Additional Notes en blanco, MTCN con "C-" por configuración; quedan abiertos "Send" o "Sent" (QC-19) y el idioma del Update (QC-20) |
| 4 | Perfiles: confirmar que son cuatro y que "Backoffice Regional" de la captura es el Administrador | Magaly | Nada: es una fila de la matriz | P4 |
| 5 | Quién accede al reporte de Cumplimiento | Magaly | Nada: es una celda | Solo Admin (P7) |
| 6 | Recibo A4: qué significa "Transacción fija: Sí / No" y si se marca a mano | Alexis | Un renglón del recibo | Impreso tal cual. Sin respuesta al 2026-10-07 (plan v3, QC-24): se sigue imprimiendo como hoy |
| 7 | Dashboard: qué quieren cambiar ahora que el escenario está definido | Magaly | Cambios al Dashboard | Sin cambios |
| 8 | La comisión suma al saldo de la Holding: así está en su planilla; confirmar que es lo que tesorería quiere ver | Teresa | Una pestaña de B7 | Como la planilla |
Cuando llegue el adjunto (1): guardarlo en doc/reference/2026-10-01-respuesta-ajustes-v1/, comparar su fila de perfiles contra la matriz de B6, cargar las listas de B1.5, y pasar los "puntos pendientes de corrección" por la tabla de §1: cada uno es "ya cubierto", "falta" o "contradice". Los que contradicen se resuelven con Carlos antes de tocar código.
✅ Hecho (2026-10-07, plan v3): el adjunto llegó el 2026-10-02 y se guardó en
doc/reference/2026-10-02-respuesta-ajustes-v2/(sin el Excel, por los datos personales de sus capturas); las listas de B1.5 se cargaron para países y tipos de ID (G10 y G11); los "puntos pendientes de corrección" son los RV3 del plan v3.
Anexo — Lo que encontramos al relevar y no es de este plan
Para que no se pierda:
CLAUDE.mddice que existe un commit "E6 — reporte regulatorio". Ese commit no está enmain: vive enorigin/feature/e6-reporte-regulatorio, sin mergear.doc/README.mdtiene la tabla de estado del 2026-08-05 ydoc/environments/staging.mddice que Terraform desde CI no funciona y que no hay integración con Soterex. Las dos cosas cambiaron.- ADR-010 está en "Proposed" y nada de lo que propone está en
main. transactions.birth_dateno la escribe nadie ynationalitysolo el seeder de demo, pero la pantalla de Pago las muestra como datos de Soterex.- No existe
paid_at: la fecha de pago eslast_updated_at, que hoy solo se mueve al pagar o cancelar. Alcanza, pero es frágil.

