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
| Entrega | Qué es | Estado |
|---|---|---|
| A1 | Arreglos rápidos del Excel | ✅ Aprobada |
| A2 | Cinco perfiles y reorganización del menú | ⏸ En espera, perfiles congelados |
| A3 | Datos del pago antes de confirmar + permisos de los soportes | ✅ Aprobada |
| A4 | Catálogos para los combos del pago | ✅ Aprobada |
| A5 | Transacciones y Caja según quién mira | ✅ Aprobada |
| A6 | Documentos pendientes después del pago | ✅ Aprobada |
| A7 | Prefondeo como estado de cuenta | ⏸ Bloqueada por el escenario de tesorería |
| A8 | Reporte 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 contramain, 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 |
|---|---|
| D1 | La búsqueda solo por MTCN aplica únicamente a Pago. Transacciones conserva la búsqueda por nombre. |
| D2 | La 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. |
| D3 | Para habilitar "Confirmar pago" son obligatorios todos los datos del pago salvo Notas. bank_account es obligatorio solo si el medio es TRANSFERENCIA. |
| D4 | Con 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. |
| D5 | Suben 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. |
| D6 | Que el pago exija datos completos se registra en ADR-011, en la línea de ADR-008. ADR-010 ya está ocupado. |
| D7 | Los 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. |
| D8 | Los 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. |
| D9 | Los 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. |
| D10 | El 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. |
| D11 | En 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. |
| D12 | Documentos 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ónde | Terminado cuando |
|---|---|---|---|
| A1.1 | Montos 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 reportes | Todos los montos de Reportes y exports salen como USD 1,234.56 y Chrome no ofrece traducir |
| A1.2 | Pago 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.vue | Test: buscar por nombre no devuelve resultados; por MTCN sí |
| A1.3 | Bug: 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.vue | Reabrir la tx pagada muestra lo que se guardó |
| A1.4 | Datos 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.vue | Test backend 409 para PAID y CANCELLED; en pantalla no hay forma de editar |
| A1.5 | Papeleta 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.php | Test del PDF o de los datos que arma el servicio |
| A1.6 | Exportar 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.vue | El Excel trae las mismas filas que la pantalla con los mismos filtros |
| A1.7 | Imprimir 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.vue | Un 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:
DatosPagoFormyDocumentacionPagoaparecen solo con PAID (PagoViewL296-315).- Con ACCEPTED solo están
DocumentacionPrePagoy el botón Pagar, que abreConfirmActionModal(L341-350). - El backend ya acepta los datos antes del pago; todos los campos son
nullable.
| # | Qué |
|---|---|
| A3.1 | ADR-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.2 | Pantalla (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.3 | Medio 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.4 | Backend: 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.5 | Guardado: 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.6 | Permisos 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.7 | Revisar 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.8 | Actualizar 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.1 | Modelo. 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.2 | Seed (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.3 | ABM (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.4 | Combos 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.5 | Validació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.6 | Verificar 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.1 | Backoffice 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.2 | Filtro "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.3 | Caja: 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.4 | Vista 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.5 | Manual 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.1 | Endpoint "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.2 | Aviso 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.3 | Bloqueo 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.4 | Lo 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
RoleSeedertiene que aplicarse a las filas existentes, no solo sembrar desde cero, y siempre dentro deRolePermission::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):
- 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.
- Confirmar que todos los datos del pago son obligatorios salvo Notas (D3).
- Confirmar el esquema de documentos pendientes: aviso más bloqueo del cierre de caja, sin bloquear el pago siguiente (D12).
- 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?
- Cancelación iniciada por Soterex (#2b): ¿llega por la API? Si no llega, cancela a mano el Backoffice.
- 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.
- Reporte de Cumplimiento: el formato con sus columnas, y si es el mismo que el reporte al regulador.
- Informes: qué va en la columna vacía marcada en rojo en la captura de Estado de Situación.
- 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
| Hoja | Pedido | Entrega |
|---|---|---|
| Dashboard | Sin cambios hasta definir el escenario de prefondeo | A7 |
| Pago | Buscar solo por MTCN | A1.2 |
| Pago | Pago solo para cajero y supervisor | A2 |
| Pago | Cancelar solo Backoffice si Soterex no cancela por API | A2 (+ #2b) |
| Pago | Datos del beneficiario y datos a completar antes de confirmar; confirmar deshabilitado hasta completar; medio de pago al confirmar | A3 |
| Pago | Combos para tipo de ID, país de ID, ciudad y provincia | A4 |
| Pago | Datos guardados bloqueados | A1.4 |
| Pago | Papeleta con teléfono y mail adicional | A1.5 |
| Pago | Documentos casi inmediatos: alerta o bloqueo de apertura/cierre | A6 |
| Pago | Tx pagada: datos solo lectura | A1.3 + A1.4 |
| Pago | Soportes solo quien pagó y supervisor; resto consulta | A3.6 |
| Pago | Papeleta siempre imprimible | A1.7 |
| Pago | ¿Cajas adicionales? ¿Apertura y cierre diarios? | §6.11 |
| TXs | Cajero ve solo sus txs | A5.1–A5.2 |
| TXs | Supervisor y Backoffice ven todo | Supervisor: por asignación, ya funciona. Backoffice central: A2 |
| TXs | Exportable a Excel | A1.6 |
| TXs | Nombre "Reporte individual" | A2 |
| Prefondeo | Solo Tesorería; pestaña Soterex y pestaña Fondeos a PDV/comisión/débitos; estado de cuenta con saldo corrido | A2 + A7 |
| Caja | Cajero ve solo su saldo; Supervisor y Tesorería todos | A5.3 |
| Caja | Nivel superior con totales por PDV | A5.4 |
| Caja | Nombre "Saldos" | A2 |
| Reportes | Solo Tesorería y Backoffice | A2 |
| Reportes | Reporte completo de Cumplimiento | A8 |
| Reportes | Formato de moneda de la comisión | A1.1 |
| Reportes | Columna marcada en rojo | §6.10 |
| Auditoría | Solo Backoffice / Administrador; pasar a Administración | A2 |
| Ubicaciones | Tipo de cambio a Tesorería; nombre "Parámetros" | A2 |
| Ubicaciones | Catálogos administrables desde acá | A4 |

