Skip to content

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 main en 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 en 2026-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/. Su README.md detalla 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, ver doc/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í:

#PuntoRespuesta del clienteQué hacemosEntrega
R1Listas 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 corrigeB1.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 visualB1.3
R4Documentos pendientes: aviso + bloqueo del cierre"Sí, confirmado"Nada. Queda como está—
R5Listas 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.5B1.5 ⏸ → ✅ parcial
R6Perfiles 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ú reorganizadoB6
R7Reportes: quién accede"Opción habilitada para todos los perfiles, excepto para el cajero"A la matrizB6
R8Auditoría: quién accede"Opción habilitada solo para el Administrador"A la matriz, y pasa al menú AdministraciónB6
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 verSupervisor queda en solo lectura de fondeosB6, B7
R10Escenario 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
R11Débitos bancarios, comisión, referencia"No tomen en cuenta los gastos bancarios en el flujo". El ejemplo muestra la comisión por transacciónSin gastos bancarios. Comisión como movimiento por cada pagoB7
R12Prefondeo como estado de cuentaCada movimiento con fecha, referencia (MTCN, débito, crédito) y saldo después del movimientoExtractos con saldo corridoB7
R13Reporte completo para CumplimientoAdjuntan el formato: las columnas marcadas "SE QUEDA" de la hoja Request Pilot List36 columnas, en ese orden y con esos nombresB4
R14Columna 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 corridoB2
R15Modelo de impresión (mail del 22/09)"El modelo de impresión aprobado para GT es A4", con cinco campos nuevosSe 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 ​

EntregaQué esPR
B1Arreglos de la revisión: catálogos, datos de referencia, campos obligatoriosPR 1
B2Estado de Situación con balance finalPR 1
B3Apertura y cierre diario de cajaPR 1
B4Fecha de nacimiento y nacionalidad en el pago (B4.0) + reporte de Cumplimiento (36 columnas) + ciudad y provincia del PDVPR 1
B5Recibo A4 y formato de recibo por paísPR 1
B6Perfiles y menú: Cajero, Supervisor, Tesorería, AdministradorPR 2
B7Tesorería como estado de cuentaPR 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ónFuente
C1Todos los datos del pago son obligatorios salvo Notas, y se marcan como obligatorios en pantallaMail 01/10
C2Documentos pendientes: aviso permanente + bloqueo del cierre de caja. El pago siguiente no se bloqueaMail 01/10
C3La apertura y el cierre de caja son diariosMail 01/10
C4Hay cuatro perfiles: Cajero, Supervisor, Tesorería y Administrador. El Backoffice de hoy pasa a ser Cajero. No hay perfil BackofficeMail 01/10
C5Reportes: todos los perfiles menos el Cajero. Auditoría: solo el AdministradorMail 01/10
C6El Supervisor no fondea cajas. Sí ve los movimientos de las cajas de su PDVMail 01/10
C7Tesorería opera con el escenario 1: Soterex → CIS Holding → CIS Guatemala → PDVExcel 22/09
C8Los gastos bancarios quedan fuera del sistemaMail 01/10
C9En los extractos, cada movimiento lleva fecha, referencia y saldo después del movimientoMail 01/10
C10El Estado de Situación lleva el balance final como última columnaMail 01/10
C11El reporte de Cumplimiento tiene las 36 columnas marcadas "SE QUEDA", con esos nombresExcel adjunto
C12El recibo de Guatemala es A4Mail 22/09
C13El 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 EfectivoCarlos

Propuestas del product owner ​

#DecisiónSi 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áticoUn 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ísHace falta la columna cuando entre un país con Caja en otra zona
P3Backoffice → Cajero es un renombre de la fila existente, no un rol nuevo. Las asignaciones de los usuarios se conservan—
P4Donde los documentos del cliente dicen "Backoffice" (central o regional), en la app es Admin. El rol sigue llamándose AdminSi quieren un quinto perfil, es una fila nueva en la matriz, sin código
P5Pagar 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 ReportesDarlo a otro perfil es una celda de la matriz
P8El 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
P10Los 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
P13Los 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ónQué cambia en las entregas
P1 ✅El cierre diario se fuerza bloqueando, sin cierre automáticoNada
P7 ✅El reporte de Cumplimiento es solo para AdminNada
P11 ✅La comisión del Dashboard la ve quien tiene prefondeo:read (Tesorería y Admin). El Supervisor deja de verlaNada
P6 ✏️El Admin cancela y paga. Cancelar sigue exigiendo transacciones:delete (solo Admin); pagar sigue exigiendo pago:writeB6: 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) El botón "Imprimir papeleta" baja el formato del país; un menú secundario ("Descargar en otro formato") baja el otro. Reemplazado por G5.5 (2026-10-06, plan v3, P3-4): dos botones siempre visibles, "Imprimir papeleta tirilla" e "Imprimir papeleta A4", cada uno con su formato explícito y el del país marcado "predeterminado". (c) El endpoint acepta ?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). Y el quinto inciso El quinto inciso se sacó en G9.6 (plan v3, RV3-94): el A4 lleva los cuatro de la tirillaB5: 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íaB4 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:

  1. El deploy a staging no siembra nada. deploy-staging.yml solo corre migrate --force. La fila de permiso abm_catalogos y 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:seed a mano el 2026-10-01. Con ese desplegable vacío no se podía pagar.
  2. La pestaña Catálogos abre en el país equivocado. CatalogosView.vue toma 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óndeTerminado cuando
B1.1Catá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 frontTest 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.2Los 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 deploybackend/database/migrations/, CatalogGuatemalaSeeder, CatalogCountrySeeder, RoleSeederTest: 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.3Campos 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 tresfrontend/src/components/DatosPagoForm.vue, ConfirmActionModal.vue, CancelReasonSelect.vueNotas es el único campo sin asterisco. Test del componente
B1.4Qué 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.vueCon 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.6Las 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 leerfrontend/src/layouts/TabbedSectionLayout.vueUn 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.1Columna 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.2Saldo 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.3Orden 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.4Con 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.5Calculalo 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.6Manual 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.1ADR-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.2Backend. 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.3Pantalla 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.4Pantalla Pago. El mismo aviso, con link a Caja. "Iniciar pago" deshabilitado con el motivo escrito. El backend manda: el front solo lo refleja
B3.5Cierres 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.6Aná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.0Fecha 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.1Ciudad 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.2Permiso 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.3Endpoint 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.4Las 36 columnas, con estos nombres y en este orden (tabla de abajo)
B4.5Auditoría del export (REPORT_EXPORTED, tipo reporte_cumplimiento) con país, rango, estado y cantidad de filas. Sin datos personales en la metadata
B4.6Manual: sección nueva del módulo reporte_cumplimiento
#ColumnaDe dónde sale
1Payment Beneficiary Namefirst_name
2Payment Beneficiary Last Namelast_name
3Payment Beneficiary DOBbirth_date, cargada por el cajero (B4.0), en d/m/Y. Vacía solo en pagos viejos, anteriores a B4.0
4Payment Beneficiary Nationalitynationality, cargada por el cajero (B4.0). Vacía solo en pagos viejos
5Payment Beneficiary Phone Numberphone_2, y si no hay, phone
6Payment Beneficiary Addressbeneficiary_address
7Payment Beneficiary Cityetiqueta de beneficiary_city
8Payment Beneficiary Stateetiqueta de beneficiary_state
9Payment Beneficiary Countrynombre del país de la transacción
10Payment Beneficiary Identification Typeetiqueta de identification_type
11Payment Beneficiary Identification Countrynombre del país de identification_country
12Payment Beneficiary Identification Numberidentification_number
13Payment Beneficiary Emailemail_2, y si no hay, email
14Principal Amount ($)amount
15Total Amount w/fee ($)amount + fee
16Destination Delivery Typedelivery_type: Cash o Bank transfer
17Cta Bancariabank_account
18Notesnotes
19Transaction Datefecha de created_at
20Transaction Timehora de created_at
21MTCN Numbermtcn. Desde G9.3 (plan v3) con el prefijo C- por configuración (cumplimiento.mtcn_prefix)
22PIN Numbermtcn (en la app el PIN es el MTCN). Sin prefijo, como en la carta
23Transaction StatusSent, 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?)
24Payer Namenombre de la entidad pagadora, de configuración. En la planilla del cliente es siempre "CISLatam" Reemplazado por G9.1 (plan v3, P3-8): un mapa por país en config/cumplimiento.php (payer_names); Guatemala dice "CIS Guatemala" y un país sin entrada sale vacío
25Payout Currencymoneda del movimiento de caja del pago. Sin Caja, la moneda de pago del país
26Ex. Ratetipo de cambio del movimiento de caja. Si pagó en USD, 1
27Beneficiary Destination Amountmonto del movimiento de caja, en positivo. Sin conversión, amount
28Transaction Expiration Dateexpires_at
29Transaction Status - UpdatePending, 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
30Transaction Status-Additional NotesPagada: código interno del PDV. Cancelada: el motivo Reemplazado por G9.2 (plan v3): siempre vacía, el cliente la pidió en blanco; se mantiene el encabezado
31Paid Datefecha de last_updated_at, solo si está pagada
32Paid Timehora de last_updated_at, solo si está pagada
33Paid at Branch Namenombre del PDV
34Paid at Branch Cityetiqueta de la ciudad del PDV (B4.1)
35Paid at Branch Stateetiqueta de la provincia del PDV (B4.1)
36Paid at Branch Countrynombre 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 en ReporteCumplimientoService.
  • El reporte tiene un tope propio de 1000 filas (exports.cumplimiento_max_rows), por debajo del exports.max_rows (5000) que nombraba el plan: con 36 columnas, PhpSpreadsheet gasta ~23 KB por fila y el memory_limit de la imagen es de 128 MB (medición en config/exports.php). Para períodos más largos hay que bajarlo en tramos; subir el tope exige subir el memory_limit del 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 formato dd/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:read pero sin reporte_cumplimiento recibe 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):

BloqueCampos
Encabezado"SOTEREX", el logo de CIS, "PARA RECIBIR DINERO"
BeneficiarioBeneficiario · Tipo de identificación · No. de identificación · ★ País de emisión
OrigenRemitente · País de origen
TransacciónMTCN · Fecha/Hora (la del pago)
Domicilio del beneficiario★ Provincia/Estado · ★ Ciudad · ★ Dirección · Teléfono · ★ Mail
AgenciaAgencia (nombre del PDV) · Ciudad (la del PDV, de B4.1) · Operador
MontosMonto enviado · Monto recibido · Total · Moneda de pago · Tasa de cambio
EstadoTransacción fija: "Sí / No", impreso tal cual para marcar a mano · Tipo de transacción: PAGADO
PieDeclaración del cliente (cinco incisos los cuatro de la tirilla desde G9.6) · Firma del cliente · Firma del operador
#Qué
B5.1Plantilla 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.2Etiquetas, 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.3La declaración del cliente pasa de cuatro incisos a cinco. El texto del quinto es: "Haber leído y aceptado el tratamiento de mis datos personales, para fines normativos, comerciales, de marketing" Revertido por G9.6 (plan v3, RV3-94): el cliente pidió que la declaración del A4 sea la de la tirilla, cuatro incisos
B5.4El 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.5Actualizá 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.6Formato 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.7Pantalla. El botón "Imprimir papeleta" (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". Reemplazado por G5.5 (2026-10-06): dos botones, "Imprimir papeleta tirilla" e "Imprimir papeleta A4"; el rótulo del formato pasó de "Térmica 58 mm" a "Tirilla 58 mm". Manual 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 a4 baja A4 por defecto y la tirilla con ?formato=termico; una de un país en termico, al revés. Un formato invá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óduloCajeroSupervisorTesorería (nuevo)Admin
pagoL EL E—L E (Carlos, 2026-10-02: el Admin cancela y paga)
transaccionesL EL E—L E B
cajaL EL ELL E B
apertura_cierre_cajaL EL E—L E B
fondeo_caja—L (sin E)L EL E B
prefondeo——L EL E B
prefondeo_pais——L EL E B
tipo_cambioLL (sin E)L EL E B
reportes—LLL
reporte_cumplimiento (B4)———L
dashboard—LLL
auditoria———L
abm_* (los siete)———L E B

Qué significa cada fila que cambia de sentido (P5):

  • Pagar exige pago:write. Hoy exige transacciones:write.
  • Cancelar exige transacciones:delete. Hoy exige transacciones: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ÍtemHoy se llamaPermiso
GeneralDashboardigualdashboard
Caja (antes "Operación")Pagoigualpago
Reporte individualTransaccionestransacciones
SaldosCajacaja
Tesorería (nuevo)Prefondeo SoterexPrefondeo Holdingprefondeo
Fondeo PDVsPrefondeo Paísprefondeo_pais o fondeo_caja
Tipo de cambiopestaña de Ubicacionestipo_cambio
ReportesReportesigualreportes
AdministraciónUsuarios y Accesosigualigual
ParámetrosUbicacionespaíses, estaciones, catálogos
Configuraciónigualigual
Auditoríaestaba en Operaciónauditoria
Documentaciónigualigual—

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.1ADR-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.2Migració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.3Separar 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.4Menú 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.5Sacar 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.6La 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.7Usuarios 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.8Documentació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::MATRIX con 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:

PantallaPestañaCréditosDébitosEl saldo corrido esPermiso
Prefondeo SoterexSoterex ↔ CIS HoldingPrefondeo recibido de SoterexCada pago: principal + comisión. Referencia: MTCNLo que queda del prefondeo de Soterex. Es el saldo global de hoyprefondeo
Prefondeo SoterexCIS HoldingPrefondeo recibido · la comisión de cada pago (referencia: MTCN)Cada envío a un paísLo que tiene la Holding sin repartir, más lo ganadoprefondeo
Fondeo PDVsPaísPrefondeo recibido de la HoldingCada fondeo a una caja (referencia: PDV y caja). Los ajustes, con su signoEl disponible para distribuir del paísprefondeo_pais
Fondeo PDVsPDVFondeos a las cajas del PDVCada pago (referencia: MTCN). Los ajustes, con su signoLo que tiene el PDV en sus cajasfondeo_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.1ADR-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.2Referencia 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.3Backend 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.4Los extractos no muestran datos del beneficiario. Solo MTCN y montos: Tesorería no tiene permiso sobre transacciones
B7.5Pantallas. 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.6Export a Excel y PDF de cada extracto, auditado
B7.7Manual (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:

PasoSoterex ↔ HoldingCIS HoldingPaís GT (disponible)PDV1PDV2
Prefondeo de 50.000 a la Holding50.00050.000
Envío de 30.000 a Guatemala20.00030.000
Fondeo de 5.000 a PDV125.0005.000
Fondeo de 18.000 a PDV27.00018.000
Pago de 1.000, comisión 10, en PDV148.99020.0104.000
Pago de 2.500, comisión 30, en PDV146.46020.0401.500
Pago de 4.500, comisión 54, en PDV241.90620.09413.500
Pago de 5.000, comisión 60, en PDV236.84620.1548.500
Pago de 4.500, comisión 54, en PDV232.29220.2087.0001.5004.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.

EntregaAnálisis funcionalManual de usuarioOtros
B1Pago: 02-datos-y-documentos.md (campos marcados, aviso de catálogo vacío)10-pago.md, 85-admin-catalogos.mddoc/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
B2General: 05-secuencias-pantalla.md (Estado de Situación con balance final)60-reportes.md—
B3Caja: 00-resumen-caja.md (la regla nueva del cierre diario), 02-flujos-caja.md, 03-diagramas-actividad-caja.md, 04-secuencias-pantalla-caja.md30-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
B4General: 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)
B5Pago: 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)—
B6General: 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.mdTodos: 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.mdADR-014 · doc/environments/dev.md y staging.md (usuarios de prueba) · textos del recorrido guiado que nombran pantallas
B7Caja: 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.mdADR-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.md y en doc/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:build en doc/. Un link roto corta el deploy de la documentación.

5. Riesgos ​

  • Escribir role_permissions con los eventos del modelo prendidos. El hook saving fuerza can_delete ⇒ can_write ⇒ can_read. Ya rompió la pantalla Pago una vez (comentario de RoleSeeder::run). B1.2 y B6.2 escriben permisos: siempre sin eventos.
  • Renombrar el rol por el camino equivocado. RoleSeeder busca el rol por nombre: cambiar la clave de MATRIX sin 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.
  • RoleSeeder pisa 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.
  • firstAllowedRoute y 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é faltaDe quiénQué bloqueaMientras tanto
1El 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:57B1.5. Puede traer pedidos que este plan no veSe 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———
3Cuatro 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 planillaMagalyNada: se ajustaComo 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)
4Perfiles: confirmar que son cuatro y que "Backoffice Regional" de la captura es el AdministradorMagalyNada: es una fila de la matrizP4
5Quién accede al reporte de CumplimientoMagalyNada: es una celdaSolo Admin (P7)
6Recibo A4: qué significa "Transacción fija: Sí / No" y si se marca a manoAlexisUn renglón del reciboImpreso tal cual. Sin respuesta al 2026-10-07 (plan v3, QC-24): se sigue imprimiendo como hoy
7Dashboard: qué quieren cambiar ahora que el escenario está definidoMagalyCambios al DashboardSin cambios
8La comisión suma al saldo de la Holding: así está en su planilla; confirmar que es lo que tesorería quiere verTeresaUna pestaña de B7Como 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.md dice que existe un commit "E6 — reporte regulatorio". Ese commit no está en main: vive en origin/feature/e6-reporte-regulatorio, sin mergear.
  • doc/README.md tiene la tabla de estado del 2026-08-05 y doc/environments/staging.md dice 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_date no la escribe nadie y nationality solo el seeder de demo, pero la pantalla de Pago las muestra como datos de Soterex.
  • No existe paid_at: la fecha de pago es last_updated_at, que hoy solo se mueve al pagar o cancelar. Alcanza, pero es frágil.

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