Skip to content

Plan — Ajustes v1 pedidos por el cliente (Soterex GT) ​

Date: 2026-09-28

Fuente: Soterex_GT - ajustes v1.xlsx, enviado por el cliente. Tiene 9 hojas (Dashboard, Pago, TXs, Prefondeo, Caja, Reportes-Informes, Auditoría, Ubicaciones, Menús y perfiles) y 18 capturas de staging anotadas.

Qué es esto: el relevamiento de cada pedido del Excel contra el código, el alcance que aprobó Carlos y el plan de ejecución de las entregas aprobadas.

Decisiones de Carlos (2026-09-28):

  • Los perfiles no se tocan. Siguen los tres roles actuales: Backoffice, Supervisor y Admin. Donde el Excel dice "cajero", en este plan significa el rol Backoffice actual. Donde dice "supervisor", significa Supervisor.
  • Aprobado ahora: A1, A3, A4, A5 y A6.
  • En espera: A2, A7 y A8, hasta que el cliente responda (§6).
  • Las propuestas por defecto de §2 quedan aprobadas.

Estado del que se parte:

  • Plan v2 (E1–E5) mergeado.
  • Manual y recorrido guiado en staging.
  • Plan v3: F1 y F3 mergeados; F4 parcial.

1. Mapa de entregas ​

EntregaQué esEstado
A1Arreglos rápidos del Excel✅ Aprobada
A2Cinco perfiles y reorganización del menú⏸ En espera, perfiles congelados
A3Datos del pago antes de confirmar + permisos de los soportes✅ Aprobada
A4Catálogos para los combos del pago✅ Aprobada
A5Transacciones y Caja según quién mira✅ Aprobada
A6Documentos pendientes después del pago✅ Aprobada
A7Prefondeo como estado de cuenta⏸ Bloqueada por el escenario de tesorería
A8Reporte completo para Cumplimiento⏸ Bloqueada, falta el formato

Orden ​

A1 ──▶ A3 ──▶ A6
  │     ▲
  │     └── A4 (antes o después de A3; A3 usa los combos si A4 ya está, y texto libre si no)
  └──▶ A5 (independiente de A3/A4/A6)
  • A1 va primero porque es chica y toca archivos que después modifica A3 (DatosPagoForm, PagoView, PapeletaService).
  • A6 va después de A3, porque A3 cambia qué documentos pueden quedar pendientes.
  • Todo se trabaja en el branch docs/plan-ajustes-v1-gt (decisión de Carlos, 2026-09-28), el mismo que tiene este plan. Hay un solo PR contra main, y cada entrega es uno o más commits identificados con su prefijo (A1, A3…). Como es un solo branch, las entregas van en secuencia: A1 → A3 → A4 → A5 → A6, o A4 antes que A3 si conviene.

2. Decisiones aprobadas (valen para todo el plan) ​

#Decisión
D1La búsqueda solo por MTCN aplica únicamente a Pago. Transacciones conserva la búsqueda por nombre.
D2La papeleta imprime teléfono adicional y mail adicional (phone_2, email_2). Si la transacción es vieja y no los tiene, usa como respaldo phone y email de Soterex.
D3Para habilitar "Confirmar pago" son obligatorios todos los datos del pago salvo Notas. bank_account es obligatorio solo si el medio es TRANSFERENCIA.
D4Con la transacción PAID, los datos del pago quedan inmutables para todos, Admin incluido. No hay flujo de corrección; si aparece el caso, se trata aparte.
D5Suben soportes: quien pagó (resolved_by_user_id), cualquier Supervisor con alcance sobre el PDV de la transacción, y Admin. El resto los ve y descarga pero no sube. La papeleta la imprime cualquiera que vea la transacción.
D6Que el pago exija datos completos se registra en ADR-011, en la línea de ADR-008. ADR-010 ya está ocupado.
D7Los catálogos arrancan con datos precargados, sin esperar a Cumplimiento: países ISO 3166-1, los 22 departamentos y 340 municipios de Guatemala (INE), y los tipos de identificación DPI y Pasaporte. Cuando Cumplimiento mande sus listas, se ajustan desde la pantalla, sin código.
D8Los catálogos se administran en una pestaña nueva de Ubicaciones ("Catálogos"). No se renombra el menú a "Parámetros": eso es A2. Permiso nuevo abm_catalogos, solo Admin (L/E/B = 1/1/1). Es un módulo nuevo en la matriz, no un perfil nuevo.
D9Los catálogos son por país. Ciudad depende de provincia. Los datos ya cargados en texto libre quedan como están; los combos rigen desde el deploy.
D10El cajero (Backoffice) pasa a ver Transacciones, acotado a las que resolvió él (PAID o CANCELLED con resolved_by_user_id = él). No ve la bolsa de ACCEPTED del país. Puede exportarlas a Excel.
D11En Caja, el cajero ve solo el saldo de la caja que tiene abierta. Para abrir una, el selector lista las cajas de su PDV sin saldos. Supervisor y Admin ven todas, más una vista nueva de totales por PDV que al entrar muestra el detalle por caja.
D12Documentos pendientes: un aviso visible siempre en Pago y en Caja con las transacciones del usuario que tienen obligatorios pendientes, más bloqueo del cierre de caja si la sesión tiene pagos con pendientes. No se bloquea el pago siguiente.

3. Entregas aprobadas ​

A1 — Arreglos rápidos ​

Commits: A1.

#QuéDóndeTerminado cuando
A1.1Montos con un solo formato. La mezcla "USD 78,05" / "154,84 dólares estadounidenses" de la captura casi seguro es Google Translate de Chrome: frontend/index.html declara lang="en" y el navegador ofrece "traducir del inglés". Poner lang="es". Agregar translate="no" (o la clase notranslate) en los montos. Unificar el formateo en un helper; hoy hay 3 variantes: Intl en SituacionView/VolumenView, utils/money.ts y CajasView sin moneda. Los exports del backend (ReportesController ~L107) deben usar el mismo formato. Antes de cambiar, verificá la hipótesis abriendo staging con Chrome en español.frontend/index.html, utils/money.ts, vistas de reportesTodos los montos de Reportes y exports salen como USD 1,234.56 y Chrome no ofrece traducir
A1.2Pago busca solo por MTCN (D1). Sacar la rama por nombre de PagoController::buscar (L80-133, LIKE en L120). Ajustar el placeholder y la ayuda de PagoView/TerminalSearchInput ("8834-201-9921 o Nombre Apellido"). La entrada no numérica responde "Ingresá un MTCN" sin consultar la base. Se mantienen el throttle y la auditoría PAGO_SEARCH.PagoController.php, PagoView.vueTest: buscar por nombre no devuelve resultados; por MTCN sí
A1.3Bug: el formulario de datos aparece vacío al reabrir una PAID. PagoView resetea datosPago a {} (L64-70) y PagoSearchResource no trae esos campos. Traer los campos de Transaction::CAMPOS_DEL_PAGO en la respuesta, solo para transacciones que el usuario puede operar; no ampliar la PII en resultados ajenos.PagoSearchResource, PagoView.vueReabrir la tx pagada muestra lo que se guardó
A1.4Datos del pago inmutables con PAID (D4). TransactionController::datosPago (L484) responde 409 PAYMENT_DATA_LOCKED si la tx no está ACCEPTED. En el front, DatosPagoForm en modo solo lectura (sin botón Guardar) cuando está PAID o CANCELLED.TransactionController.php, DatosPagoForm.vueTest backend 409 para PAID y CANCELLED; en pantalla no hay forma de editar
A1.5Papeleta con teléfono y mail adicional (D2). PapeletaService L69 hoy usa phone y no imprime mail. Usar phone_2 ?? phone. Agregar una línea de mail con email_2 ?? email.PapeletaService.php, pdf/papeleta.blade.phpTest del PDF o de los datos que arma el servicio
A1.6Exportar Transacciones a Excel. Botón en TransaccionesView. Endpoint que respeta exactamente los mismos filtros y el mismo alcance que el listado. Reusar phpoffice/phpspreadsheet como en Estado de Situación; no maatwebsite/excel (incompatible, ver CLAUDE.md). Auditar la exportación.TransactionController o un controller de export nuevo, TransaccionesView.vueEl Excel trae las mismas filas que la pantalla con los mismos filtros
A1.7Imprimir papeleta siempre habilitado (D5). Hoy el endpoint pide transacciones,write. Que alcance con poder ver la tx: read, o write con alcance. Revisar que el botón "Imprimir papeleta" no dependa de canWrite.api.php, DocumentacionPago.vueUn usuario que solo consulta puede imprimir

A3 — Datos del pago antes de confirmar ​

Commits: A3. Depende de A1.

Qué pidió el cliente:

  • Una sola pantalla con todos los datos del beneficiario que manda Soterex y, debajo, los que completa el operador.
  • "Confirmar pago" deshabilitado hasta completar todo.
  • El medio de pago se elige al confirmar.

Hoy:

  • DatosPagoForm y DocumentacionPago aparecen solo con PAID (PagoView L296-315).
  • Con ACCEPTED solo están DocumentacionPrePago y el botón Pagar, que abre ConfirmActionModal (L341-350).
  • El backend ya acepta los datos antes del pago; todos los campos son nullable.
#Qué
A3.1ADR-011 "Los datos del pago son obligatorios antes de pagar" (D3, D4, D6): contexto (reporte al regulador), la decisión, que no hay corrección posterior, y la relación con ADR-008.
A3.2Pantalla (ACCEPTED): un bloque de solo lectura con lo que manda Soterex: nombre, teléfono, email, nacionalidad, fecha de nacimiento, remitente, país y moneda de origen, monto, alien number, viaja con menores / nombre del menor (ver openapi.yaml L141-188 y Transaction). Debajo, DatosPagoForm editable sin Medio de pago, y después DocumentacionPrePago. Mantener los data-tour que usa el recorrido guiado de Pago, o actualizar los pasos (ADR-009).
A3.3Medio de pago en el modal de confirmación. Efectivo o Transferencia; con Transferencia, cuenta bancaria. Se envía junto con el pago (pay()), no por datosPago.
A3.4Backend: pay() valida que los datos obligatorios (D3) estén guardados antes de pagar. Si faltan, 422 MISSING_PAYMENT_DATA con la lista de campos, igual que MISSING_REQUIRED_DOCUMENTS (L207-214). Espejo en el front, igual que services/transactionDocuments.ts L33, para deshabilitar el botón con el motivo. El backend manda.
A3.5Guardado: autoguardado o botón "Guardar" antes de confirmar, a elección, pero confirmar nunca puede pagar con datos sin guardar. Recomendado: el modal de confirmación guarda y paga en una sola llamada, con un pay() que recibe los datos. Así se evitan dos requests y la carrera entre ellos. Si se elige esto, documentarlo en ADR-011.
A3.6Permisos de soportes (D5). En TransactionDocumentController::store (L48), subir exige ser quien pagó, Supervisor con alcance o Admin. Antes del pago, con ACCEPTED, puede subir cualquiera con transacciones:write y alcance, porque todavía no hay quien pagó. Listar y descargar sigue abierto para quien ve la tx. En la interfaz, el botón "Subir" se oculta para los demás.
A3.7Revisar documentoDe() (composables/useTransactionDocuments.ts L38): usa find sin un orden garantizado. Con varios documentos del mismo tipo, tiene que mostrar el último. Ordenar explícito en el backend o en el front.
A3.8Actualizar el análisis funcional de doc/functional/2026-08-07-pago-con-documentos/ y la sección de Pago del manual de usuario (/documentacion/manual-usuario, el Markdown del módulo pago).

Terminado cuando:

  • Con ACCEPTED, la pantalla muestra los datos de Soterex y el formulario.
  • "Confirmar pago" queda deshabilitado mientras falte un dato obligatorio o un documento de ADR-008, y el motivo se ve en pantalla.
  • El backend rechaza un pay() directo sin datos: está testeado.
  • Con PAID, todo es solo lectura.
  • Un Backoffice que no pagó la tx no puede subir soportes: 403, testeado.

A4 — Catálogos para los combos ​

Commits: A4. Antes o después de A3.

#Qué
A4.1Modelo. Una tabla de catálogos genérica, por ejemplo catalog_items: country_id (nullable para listas globales como la de países ISO), type (ID_TYPE, STATE, CITY), code, label, parent_id (ciudad → provincia), active, timestamps. Único por (country_id, type, code). La tabla es la recomendación; si se elige otro diseño, explicarlo en el PR.
A4.2Seed (D7): países ISO 3166-1 alpha-2 con nombre en español; departamentos y municipios de Guatemala (fuente INE/RENAP, citada en el seeder); DPI y Pasaporte para GT. Idempotente (updateOrCreate). Sumarlo a demo:reseed si corresponde.
A4.3ABM (D8): pestaña "Catálogos" en Ubicaciones, con permiso abm_catalogos (Admin 1/1/1; el resto 000). Se agrega a RoleSeeder::MATRIX dentro de withoutEvents y a firstAllowedRoute. Alta, edición y activar/desactivar. No se borra un ítem, porque rompería la referencia de datos históricos: se desactiva. Auditar los cambios.
A4.4Combos en DatosPagoForm: Tipo de identificación y Provincia vienen del país de la tx (el del PDV); Ciudad, filtrada por la provincia elegida; País de la identificación, de la lista ISO. Se guarda el código, no la etiqueta. Evaluar si hacen falta columnas nuevas o si alcanzan las de texto actuales.
A4.5Validación backend: exists contra ítems activos del país correcto y, para ciudad, con la provincia correcta. Los datos viejos en texto libre (D9) no se validan retroactivamente; al mostrarlos, si no matchean un código, se muestran tal cual.
A4.6Verificar que el reporte regulatorio futuro (A8) y el export de A1.6 muestren la etiqueta, no el código.

Terminado cuando:

  • Admin crea una ciudad nueva y aparece en el combo del pago.
  • Desactivar una ciudad la saca del combo, pero no rompe una tx vieja que la usa.
  • El backend rechaza un código inexistente o de otro país.

A5 — Transacciones y Caja según quién mira ​

Commits: A5. Independiente de A3, A4 y A6.

#Qué
A5.1Backoffice ve Transacciones (D10). En RoleSeeder::MATRIX, transacciones de Backoffice pasa a read=1. ⚠️ Leé el comentario de RoleSeeder::run (~L124-133): en E2 tener read=true "hacía que la pantalla Pago nunca se activara". Reproducí qué dependía de eso (landing, firstAllowedRoute, algún v-if) antes de cambiarlo, y cubrilo con un test. El seed tiene que actualizar la fila existente en staging, no solo crear.
A5.2Filtro "resueltas por mí" en TransactionController::index (L64-166): si el usuario es Backoffice, where resolved_by_user_id = user y sin ACCEPTED. Definí la regla por permiso o capacidad, no por nombre de rol, siguiendo el patrón de PermissionService. Por ejemplo, un flag en la asignación o "no tiene pago read = ve todo". Documentá la elección. El detalle (show) y el export de A1.6 aplican el mismo filtro. No se tiene que poder abrir por URL una tx ajena.
A5.3Caja: el cajero ve solo la suya (D11). GET /caja/disponibles (CashBoxController::disponibles L49) no devuelve saldos de cajas que no son la sesión abierta del usuario, salvo para quien tiene fondeo_caja read (Supervisor y Admin). Cualquier otro endpoint que exponga saldos de caja tiene que respetar lo mismo.
A5.4Vista de totales por PDV (D11) para Supervisor y Admin: primer nivel con una tarjeta por PDV (saldo total sumando sus cajas, cuántas abiertas); al entrar, la grilla por caja de hoy (CajaView.vue L368-388). El saldo se deriva del ledger (ADR-005/007), no se materializa.
A5.5Manual de usuario: secciones Transacciones y Caja.

Terminado cuando:

  • Un Backoffice ve en Transacciones solo lo que pagó o canceló él; la URL de una tx ajena da 404 o 403; Pago sigue siendo su pantalla de inicio.
  • En Caja no ve saldos ajenos.
  • Un Supervisor ve los totales por PDV y entra al detalle.

A6 — Documentos pendientes ​

Commits: A6. Después de A3.

Después de A3, carta e identificación ya se exigen antes de pagar (ADR-008). Lo que puede quedar pendiente después del pago es la Papeleta firmada y, con Transferencia, los 4 documentos de REQUERIDOS_TRANSFERENCIA.

#Qué
A6.1Endpoint "mis pendientes": tx PAID resueltas por el usuario con obligatorios que faltan, con MTCN, fecha y qué falta. Supervisor y Admin pueden ver los de su alcance.
A6.2Aviso persistente, no bloqueante, en Pago y en Caja (D12): "Tenés N pagos con documentación pendiente", con link a cada tx. Se actualiza al subir un documento.
A6.3Bloqueo del cierre de caja (D12). CashBoxController::cierre (L221) responde 422 PENDING_PAYMENT_DOCUMENTS si algún pago de esa sesión tiene obligatorios pendientes, con la lista. La apertura no se bloquea. El pago siguiente no se bloquea.
A6.4Lo mismo en el recorrido guiado y el manual, si corresponde.

Terminado cuando:

  • Pagar sin subir la papeleta firmada muestra el aviso.
  • Intentar cerrar la caja se rechaza con la lista.
  • Subir la papeleta libera el cierre.
  • Todo testeado.

4. Riesgos ​

  • A5.1 (read de transacciones a Backoffice) ya rompió algo en E2. Es el cambio más delicado del plan: reproducir primero.
  • A3 cambia un flujo que el cliente está probando en QA. Avisar antes del deploy a staging, que igual requiere el ok de Carlos.
  • La matriz de permisos en staging: cualquier cambio a RoleSeeder tiene que aplicarse a las filas existentes, no solo sembrar desde cero, y siempre dentro de RolePermission::withoutEvents().

5. Fuera de alcance (a propósito) ​

  • A2: perfiles nuevos (Cajero, Backoffice central, Tesorería), menú reorganizado, renombres ("Parámetros", "Saldos", "Reporte individual"), "Pago solo para cajero y supervisor" y "cancelar solo Backoffice".
  • A7: prefondeo como estado de cuenta, comisión como movimiento, débitos bancarios. Cambios al Dashboard.
  • A8: reporte completo de Cumplimiento.
  • Forzar apertura y cierre diario de caja: el cliente solo preguntó.
  • La integración real con Soterex (M5) y el punto #2b.

6. Pendientes del cliente (para destrabar todo lo demás) ​

Para lo aprobado (no frenan el arranque; se ajusta cuando llegan):

  1. Las listas de Cumplimiento para cada combo: tipos de identificación, departamentos y municipios, países. Se les puede mandar la precarga (D7) para que la validen.
  2. Confirmar que todos los datos del pago son obligatorios salvo Notas (D3).
  3. Confirmar el esquema de documentos pendientes: aviso más bloqueo del cierre de caja, sin bloquear el pago siguiente (D12).
  4. Si en Guatemala se usa transferencia como medio de pago o solo efectivo.

Para A2, A7 y A8: 5. Escenario de tesorería: 1 (con Holding) o 2 (sin Holding). Abierto desde el 2026-08-07 (2026-08-07-analisis-definiciones-cis-ec.md §4, Teresa). Bloquea A7, el Dashboard y el menú de Reportes. 6. Perfiles: confirmar los 5 (Cajero, Supervisor, Backoffice, Tesorería, Administrador) y qué hace el Backoffice central. Resolver las contradicciones del Excel:

  • Prefondeo: una hoja dice "solo Tesorería"; la otra, Tesorería y Backoffice.
  • Reportes: una hoja dice Tesorería y Backoffice; la otra suma a Supervisor. Hay además una fila suelta "Backoffice" bajo Reportes.
  • Auditoría: una hoja dice "solo Backoffice"; la otra, Administrador.
  • Fondeo a PDVs: ¿el Supervisor de PDV puede fondear cajas?
  1. Cancelación iniciada por Soterex (#2b): ¿llega por la API? Si no llega, cancela a mano el Backoffice.
  2. Estado de cuenta de tesorería: qué son los débitos bancarios y quién los registra; si la comisión se asienta por transacción o como un solo movimiento periódico; qué formato tiene la referencia de cada movimiento.
  3. Reporte de Cumplimiento: el formato con sus columnas, y si es el mismo que el reporte al regulador.
  4. Informes: qué va en la columna vacía marcada en rojo en la captura de Estado de Situación.
  5. Respuestas a sus consultas:
    • Cajas adicionales: sí, las crea el Admin desde Ubicaciones → Estaciones/PDV.
    • Apertura y cierre: son por caja, con el saldo inicial heredado del cierre anterior, pero nada obliga a que sean diarios. ¿Lo quieren forzado?

Anexo — Relevamiento completo del Excel ​

HojaPedidoEntrega
DashboardSin cambios hasta definir el escenario de prefondeoA7
PagoBuscar solo por MTCNA1.2
PagoPago solo para cajero y supervisorA2
PagoCancelar solo Backoffice si Soterex no cancela por APIA2 (+ #2b)
PagoDatos del beneficiario y datos a completar antes de confirmar; confirmar deshabilitado hasta completar; medio de pago al confirmarA3
PagoCombos para tipo de ID, país de ID, ciudad y provinciaA4
PagoDatos guardados bloqueadosA1.4
PagoPapeleta con teléfono y mail adicionalA1.5
PagoDocumentos casi inmediatos: alerta o bloqueo de apertura/cierreA6
PagoTx pagada: datos solo lecturaA1.3 + A1.4
PagoSoportes solo quien pagó y supervisor; resto consultaA3.6
PagoPapeleta siempre imprimibleA1.7
Pago¿Cajas adicionales? ¿Apertura y cierre diarios?§6.11
TXsCajero ve solo sus txsA5.1–A5.2
TXsSupervisor y Backoffice ven todoSupervisor: por asignación, ya funciona. Backoffice central: A2
TXsExportable a ExcelA1.6
TXsNombre "Reporte individual"A2
PrefondeoSolo Tesorería; pestaña Soterex y pestaña Fondeos a PDV/comisión/débitos; estado de cuenta con saldo corridoA2 + A7
CajaCajero ve solo su saldo; Supervisor y Tesorería todosA5.3
CajaNivel superior con totales por PDVA5.4
CajaNombre "Saldos"A2
ReportesSolo Tesorería y BackofficeA2
ReportesReporte completo de CumplimientoA8
ReportesFormato de moneda de la comisiónA1.1
ReportesColumna marcada en rojo§6.10
AuditoríaSolo Backoffice / Administrador; pasar a AdministraciónA2
UbicacionesTipo de cambio a Tesorería; nombre "Parámetros"A2
UbicacionesCatálogos administrables desde acáA4

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