User Flows

Análisis Funcional: Integración Soterex — parte 4 de 8. ← Roles y Permisos · Índice · Siguiente: Diagramas de Actividad →

⚠️ ACTUALIZADO (2026-08-07)

Los flujos de esta página son del 2026-07-24, con una corrección del 2026-07-25. Entre medio se entregaron E2 (pantalla Pago), E3 (permisos inline), E4/E4-multi/E4b (módulo Caja y prefondeo en tres capas) y E5a/E5b (datos y documentos del pago). Lo que cambió:

Flujo	Qué pasó
3.2 Pago	Reescrito. El Backoffice ya no arranca en el listado de Transacciones, y el saldo que valida el pago dejó de ser el prefondeo
3.3 Cancelación	Vigente. Se aclara desde dónde la dispara cada rol y que no toca la caja
3.4 Prefondeo	Corregido. Son dos pantallas y tres capas, no un pool por país
3.6 Roles y Permisos	Corregido. Dejó de ser una pantalla propia: se edita inline en la ficha del usuario
3.7 Asignación de roles	Corregido. Se mudó a la ficha del usuario
3.8 Búsqueda en Pago	Nuevo, y afloja a propósito una medida anti-enumeración de E2.1

Los flujos del módulo Caja —apertura, cierre, fondeo, ajuste, alta de cajas, tipo de cambio— no se duplican acá: viven en Flujos de Caja. El detalle del wizard documental vive en Pago con documentos.

3.1 Login (MVP1: solo usuario/password — SSO Google/Microsoft queda para Fase 2)

El usuario del sistema es el mail. El login con SSO Google y SSO Microsoft/O365 (el cliente ya usa Microsoft 365 con dominio propio) queda confirmado como Fase 2, fuera del MVP1.

PRECISADO (2026-07-28, decisión #1 del plan v2): el destino después del login no se decide por nombre de rol. El guard recorre el sitemap en orden de prioridad y manda al usuario a la primera ruta cuyo módulo puede Leer (firstAllowedRoute(), frontend/src/router/index.ts). Que el Backoffice caiga en Pago es consecuencia de que tiene dashboard:read = false y transacciones:read = false, no de un caso especial escrito para ese rol. Si no puede leer nada, cae en /sin-acceso.

3.2 Flujo core — el Backoffice paga una transacción

⚠️ REESCRITO (2026-08-07). La versión anterior arrancaba en "Backoffice entra a Listado de Transacciones" y validaba el pago contra el saldo de prefondeo del país. Las dos cosas dejaron de ser ciertas:

1. El Backoffice no tiene el listado de Transacciones. Entra por la pantalla Pago y encuentra la transacción buscándola (3.8), no eligiéndola de una bolsa que ve entera. La bolsa compartida por país sigue existiendo conceptualmente —cualquier operador del país puede resolver cualquier ACCEPTED— pero se accede de a una, por búsqueda. Decisión #1 del plan v2.
2. El prefondeo dejó de bloquear el pago en países con módulo Caja: la única validación de saldo es la caja del operador (ADR-007 §2).

Lo que no cambió y sigue vigente de la corrección del 2026-07-25: el PDV no viene con la transacción, se asigna recién al resolverla, y hay re-chequeo de estado con lock justo antes de confirmar (ver §2.4).

Lo que hay que retener de este flujo, porque es donde más se equivoca la intuición:

• La comisión no aparece en ninguna parte de la pantalla. Ni en la ficha, ni en el modal de confirmación, ni en el error de saldo — el error de prefondeo omite a propósito el monto requerido, porque restándolo del monto visible se deduciría la comisión (§2.5).
• De qué caja sale la plata lo decide quién paga, no el PDV. Cada pago descuenta la caja que ese mismo operador abrió a su nombre. Detalle en Flujos de Caja §2.5.
• Todo pasa en una sola transacción de base de datos. Si la caja no alcanza, no queda ni movimiento ni transacción pagada.
• Ningún saldo se guarda: los tres se derivan de su ledger. Por eso el diagrama dice "se recalculan solos" y no "se descuentan".

3.3 Flujo — Cancelación bidireccional

Actualizado 2026-07-25: re-chequeo de estado + PDV asignado recién acá.

PRECISADO (2026-08-07): el flujo en sí no cambió, pero sí desde dónde se dispara y qué no toca. El Backoffice cancela desde la ficha de la pantalla Pago, no desde un detalle de transacción que ya no ve; Supervisor y Admin siguen cancelando desde /transacciones/:id. Los dos pegan al mismo endpoint, gateado por transacciones:write.

Una aclaración que vale porque se pregunta seguido:

• Cancelar no toca ninguna caja ni ningún prefondeo. Los saldos se derivan de las transacciones PAID; una CANCELLED nunca entró en la cuenta, así que no hay nada que devolver.

3.4 Flujo — Se carga prefondeo

⚠️ CORREGIDO (2026-08-05, ADR-007). El flujo original era uno solo: "Supervisor entra a Prefondeo, completa país, monto y fecha, y el sistema suma al saldo pool del país". Hoy hay dos pantallas y tres capas, y una de las tres —la caja— no se carga por acá sino con un fondeo.

Además, el campo "fecha" nunca existió: el asiento se graba con la fecha del momento de la carga y no es editable. Contradicción documentación↔código que ya venía anotada en el paquete del módulo Caja y que sigue sin resolverse.

• Quién carga qué: ni la Holding ni el País tienen un rol propio. Los carga tesorería (Teresa y Diego, de CIS-EC) operando con rol Supervisor o Admin — se decidió explícitamente no crear un rol "Tesorería" (Carlos, 2026-08-06).
• CIS EC administra la caja de CIS GT (confirmado 2026-08-07): quien carga el prefondeo de Guatemala es un usuario de Ecuador con alcance sobre ese país.
• El ejemplo numérico completo de cómo se mueve la plata entre las tres capas está en Modelo de saldos.

3.5 Flujo — Admin gestiona un ABM (patrón genérico: Países / Usuarios / Estaciones / Configuración)

PRECISADO (2026-08-07): el patrón sigue siendo este, pero dos ABMs ganaron efectos laterales que no son "guardar un registro" y conviene tener presentes:

• ABM Países: activar el módulo Caja exige tener moneda local configurada (si no, error) y crea automáticamente la Caja 1 de cada sucursal del país que todavía no tenga ninguna. El campo % comisión ya no existe; en su lugar están el flag de módulo Caja, la moneda local y la bandera de moneda de pago.
• ABM Estaciones/PDV: dar de alta una sucursal en un país con módulo Caja crea su Caja 1. Desde la ficha del PDV se agregan cajas adicionales, numeradas solas y sin baja posible.

Ver Flujos de Caja §2.7.

3.6 Flujo — Admin edita los permisos de un usuario

⚠️ CORREGIDO (2026-07-28, E3.1 del plan v2). El flujo original era "Admin entra a ABM Roles y Permisos y ve una grilla Módulo × Rol × L/E/B". Esa pantalla ya no existe: los permisos se editan inline en la ficha del usuario, sobre los roles que ese usuario ya tiene asignados. El permiso abm_roles_permisos sigue siendo el gate, y la dependencia Borrar→Escribir sigue vigente tal cual se definió.

• El cambio sigue siendo por rol, no por usuario individual: editar la matriz desde la ficha de Ana afecta a todos los usuarios que compartan ese rol. La ficha es el lugar desde donde se edita, no el alcance de lo editado. Vale decirlo porque la UI invita a leerlo al revés.
• El guardado es atómico: usuario y permisos, o ninguno de los dos.

3.7 Flujo — Admin asigna roles multipaís / multi-PDV a un usuario

⚠️ CORREGIDO (2026-07-28, E3 del plan v2). El flujo es el mismo, pero cambió de lugar: ya no hay una pantalla "ABM Asignación de Roles" donde se busca un usuario por mail. Las asignaciones se editan en la sección "Roles y Asignaciones" de la ficha del usuario, dentro de Usuarios y Accesos. La solapa que hoy se llama "Roles" pasó a contener propiedades del rol (el timeout de sesión), no asignaciones.

El PDV activo (role_assignments.default_station_id) es lo que resuelve qué sucursal se graba cuando el usuario paga o cancela teniendo más de un PDV asignado — ver Pregunta Abierta #14.

3.8 Flujo — Búsqueda en la pantalla Pago (NUEVO)

El Backoffice no tiene un listado: tiene un buscador. Todo lo que hace arranca acá.

⚠️ Esto afloja a propósito una medida de seguridad de E2.1 — dejarlo dicho importa más que la prolijidad del flujo. El diseño original hizo la búsqueda exacta justamente como medida anti-enumeración: había que acertar el MTCN completo con sus ceros a la izquierda, o el nombre y apellido enteros. En uso real resultó impracticable — la carta que tiene el operador delante muestra el MTCN sin ceros y el nombre como lo escribió Soterex, y cualquier diferencia de tilde, segundo nombre o apellido compuesto devolvía cero resultados sin explicar por qué.

Los tres cambios del 2026-08-07 (pedido de Carlos) y lo que cuesta cada uno:

Cambio	Antes	Ahora	Qué se pierde
Nombre	Exacto, nombre y apellido	Parcial, nombre o apellido, mínimo 3 letras	Buscar "rodriguez" devuelve una lista, no un acierto
MTCN	Exacto, con ceros a la izquierda	Comparación numérica — "26" encuentra "0000000026"	Se puede barrer el rango de MTCN de a uno
Alcance	ACCEPTED del país + solo las PAID/CANCELLED propias	Todo el país, resueltas por quien sea	Un operador puede mapear el padrón de beneficiarios de su país

El alcance se amplió porque el material de CIS-EC pide expresamente que, ante una transacción ya pagada, el operador corrobore los soportes del pago para eliminar posibilidades de error — y eso es imposible si solo ve las propias, porque el pago que hay que corroborar casi siempre lo hizo otro.

Qué defensas quedan en pie: el throttle de 10 búsquedas por minuto con bucket propio, la auditoría de todo intento (incluidos los que no devuelven nada, que es la señal que detecta un barrido), el acotamiento por país, el mínimo de 3 caracteres, y que el resultado no expone documento, email, teléfono, fecha de nacimiento ni comisión.

Esto queda explícitamente marcado como el punto más fuerte a revisar en la auditoría de seguridad (E6). Es una decisión de negocio consciente y fechada, no un descuido.

Hallazgos

Cosas que aparecieron al contrastar estos flujos contra el código, y que no resolví acá porque no las cubre ninguna decisión documentada.

1. Un usuario que solo tenga prefondeo_pais no puede entrar a ningún lado. La lista de prioridad del guard (firstAllowedRoute(), frontend/src/router/index.ts) no incluye prefondeo-pais: un usuario cuyo único módulo legible sea ese cae en /sin-acceso aunque la pantalla exista y él tenga permiso. Con el seed actual no se da (quien tiene prefondeo_pais tiene también Dashboard), pero es una bomba de tiempo para cualquier rol nuevo o recortado. La misma lista sigue nombrando admin-roles-permisos, que es una ruta que ya no existe.
2. El asiento de prefondeo no acepta fecha, en ninguna de las dos capas, pese a que el flujo 3.4 original la pedía. Ya venía anotado en el paquete del módulo Caja; sigue igual.
3. El motivo de cancelación es texto libre y no tiene código de Soterex asociado. Los motivos "de fábrica" coinciden con los sub_status que define Soterex (1000/1001/1002), pero un motivo nuevo escrito por el usuario no mapea a ninguno. Cómo resolverlo para el Cancel API real queda abierto para M5.

---

← Roles y Permisos · Índice · Siguiente: Diagramas de Actividad →