Skip to content

ADR-015: Los extractos de tesorería son vistas derivadas ​

Date: 2026-10-02 Status: Accepted — decisiones C7 a C9 y P10 del plan de ajustes v2 (doc/plans/2026-10-01-ajustes-v2-cliente-gt.md). Implementado en la entrega B7 del plan (PR 3). Las seis preguntas abiertas no bloquean nada, cada una con el comportamiento por defecto ya elegido (ver Preguntas abiertas): desde G12, dos están contestadas para Guatemala (3 y 4), una quedó cerrada por defecto (1) y quedan tres abiertas (2, 5 y 6). Updated: 2026-10-07 (G12, plan de ajustes v3, D3-19 b): la tarjeta de Prefondeo Soterex sigue el mismo alcance que los extractos de la Holding (§5), un país inactivo sin movimientos ya no vuelve «parcial» el extracto, y la hoja «Módulo tesorería» que mandó el cliente el 2026-10-02 contestó las preguntas 3 y 4. Extends: ADR-007 — no cambia el modelo de tres capas, lo muestra de otra forma. Answers: la pregunta abierta de ADR-010 sobre el saldo de la Holding para el extracto. ADR-010 sigue en Proposed y sin implementar; ver el punto 4.

Context ​

El cliente (Teresa Ortiz y Diego Sánchez, tesorería) no lee el dinero como lo mostraba la app —un saldo por capa y una lista de asientos— sino como un estado de cuenta bancario: una línea por movimiento, con la fecha, una referencia, el débito o el crédito, y el saldo que quedó después de ese movimiento. Lo pidieron en el mail del 2026-10-01 (decisión C9 del plan) y lo mostraron en dos hojas: la pestaña Módulo tesorería del Excel de Guatemala, con la Holding, el país y dos PDV, y el Financial Report de Ecuador, con la «Bóveda» de Soterex.

Hasta ahora los pagos no aparecían como movimientos en ninguna pantalla de prefondeo: se restaban por atrás. Y había una contradicción a la vista que nadie había terminado de cerrar, porque la app y la planilla no cuentan lo mismo:

Paso de la planilla de GuatemalaPlanilla, «CIS Guatemala»App, saldo del país (ADR-007)
Envío de 30.000 a Guatemala30.00030.000
Fondeo de 5.000 al PDV125.00030.000
Fondeo de 18.000 al PDV27.00030.000

En la planilla, fondear un PDV baja el saldo de Guatemala. En la app no: mover plata del país a una caja es distribución, no gasto, y el saldo del país solo baja cuando se paga (ADR-007 §1, decisión de Carlos del 2026-08-07, y la razón por la que ese saldo es conciliable contra el banco del país). ADR-007 dejó anotado, en sus consecuencias, que los tres saldos eran deuda de documentación: había que explicar el circuito con un diagrama y no con prosa. Este ADR es la parte de decisión de esa deuda; el diagrama va al análisis funcional del módulo Caja.

Restricciones que mandan:

  • P10: el modelo contable no cambia. Ningún saldo se materializa (ADR-005, ADR-007) y fondear una caja sigue sin descontar el país. Los extractos muestran los mismos números de otra forma.
  • Los gastos bancarios quedan fuera (C8, mail del 2026-10-01: «no tomen en cuenta los gastos bancarios en el flujo»).
  • Tesorería no tiene permiso sobre transacciones (ADR-014): los extractos no pueden mostrar quién cobró.

Decision ​

1. Cuatro extractos, cada uno una vista de un ledger que ya existe ​

Todos tienen las mismas columnas: Fecha · Concepto · Referencia · Débito · Crédito · Saldo. El del PDV suma la columna Caja y los de la Holding la columna País (la pantalla la dibuja solo si el alcance tiene más de un país). Un crédito suma al saldo corrido y un débito resta.

ExtractoCréditosDébitosEl saldo corrido esServicio con el que cierraPermiso
Soterex ↔ CIS HoldingCada asiento de prefondeo recibido de SoterexCada pago: principal más comisión (referencia: MTCN)Lo que queda del prefondeo de SoterexPrefundingService::globalBalance()prefondeo:read
CIS HoldingCada asiento recibido, y la comisión de cada pago (referencia: MTCN; un pago con comisión cero no mueve este saldo y no es una línea)Cada envío a un paísLo que tiene la Holding sin repartir, más lo que ganó: recibido − enviado a países + comisiones(ninguno: ver el punto 4)prefondeo:read
PaísCada asiento de prefondeo del país (lo que baja la Holding)Cada fondeo a una caja (referencia: PDV y caja). Los ajustes, con su signoEl disponible para distribuir del paísCountryPrefundingService::availableToDistribute()prefondeo_pais:read
PDVLos fondeos a las cajas del PDVCada pago (referencia: MTCN). Los ajustes, con su signoLo que tiene el PDV en sus cajasΣ CashBoxService::balance() de sus cajasfondeo_caja:read + alcance por PDV

El último saldo corrido de cada extracto es exactamente el que ya calcula el servicio de la columna «Servicio con el que cierra» cuando el rango llega hasta hoy. No es una aspiración: hay un test por extracto, y el del país y el del PDV se prueban también contra un ledger con toda su historia (ver el punto 6).

2. Cómo se calculan: fuentes, saldo anterior, y el corrido sobre TODO el rango ​

El cálculo vive en App\Services\TreasuryStatementService y es igual para los cuatro:

  1. Cada extracto es una lista de fuentes: una consulta sobre una tabla del ledger, la columna de fecha que ya usa el servicio de saldos para esa tabla (created_at en los asientos y los movimientos de caja, last_updated_at en un pago PAID, porque no existe paid_at) y la expresión SQL de cuánto mueve el saldo, con signo.
  2. De cada fuente salen dos cosas con la misma consulta base: las filas del rango y la suma de todo lo anterior a from (el saldo anterior). Una sola definición por fuente es lo que impide que las filas y el saldo anterior se desacomoden. Para Soterex ↔ Holding el saldo anterior sale de PrefundingService::balanceBeforeForCountries(), que es balanceBefore() del Estado de Situación (B2) con un whereIn: una sola cuenta para los dos lugares.
  3. Las filas de todas las fuentes se ordenan por fecha, tipo e id y recién ahí se les aplica RunningBalance (el helper de B2) sobre todo el rango. Paginar es cortar después: el saldo de la primera fila de la página siguiente sale del de la última de la anterior, nunca de una apertura recalculada sobre la página.
  4. El orden es determinístico. La base guarda segundos, así que varios movimientos caen en el mismo; entre ellos se ordena por tipo con un rango fijo que pone primero lo que suma (los asientos, las comisiones, los fondeos), después los ajustes y al final los pagos y los envíos —un crédito del mismo instante no puede dejar un saldo transitorio negativo— y el id desempata. El mismo pedido da siempre las mismas filas en el mismo orden. Lo de «primero lo que suma» vale para los extractos de la Holding y del PDV, donde cada tipo siempre suma o siempre resta; en el del País el signo de un tipo depende del extracto (un fondeo de caja resta lo disponible, un ajuste o un pago de caja suelto pueden sumarlo), así que el rango es fijo por tipo y no por signo: sigue siendo determinístico, el cierre es exacto, y un saldo transitorio negativo ahí es solo cosmético porque el país admite negativo (ADR-007).
  5. Los montos viajan en centavos enteros de punta a punta (ver el docblock de RunningBalance): sumar float arrastra una deriva que en un extracto largo deja el último saldo distinto de la suma de sus movimientos.

Ningún saldo se guarda. Hay dos índices nuevos para que el corte «todo lo anterior a from» no barra la tabla: prefunding_entries (country_id, created_at) y cash_movements (transaction_id); los demás ledgers ya los tenían.

3. Reconciliación con la planilla del cliente ​

Los dos números de la planilla son correctos, y cada uno es una columna distinta de este modelo:

  • El «CIS Guatemala» de la planilla (30.000 → 25.000 → 7.000) es nuestro disponible para distribuir: lo que queda del país para mandar a una caja. Es el saldo corrido del extracto País.
  • El «saldo final» de la planilla (12.500) es nuestro saldo del país: 30.000 enviados menos 17.500 de principales pagados. Es lo que se concilia contra el banco, no baja al fondear, y va en el encabezado del extracto del país (breakdown.balance), junto con lo repartido en cajas y el disponible.
saldo del país (12.500) = Σ asientos − Σ principales pagados
distribuido en cajas    = Σ movimientos de las cajas del país                 (5.500 al final: 1.500 + 4.000)
disponible (7.000)      = saldo del país − distribuido en cajas

El test de B7 reproduce la hoja Módulo tesorería (filas 19 a 34) paso a paso, con los mismos movimientos por API —prefondeo, envío, dos aperturas de caja, dos fondeos y cinco pagos pagados desde las cajas—, y después de cada paso afirma los cinco saldos en los cuatro extractos:

PasoSoterex ↔ HoldingCIS HoldingPaís (disponible)PDV1PDV2
Prefondeo de 50.000 a la Holding50.00050.000000
Envío de 30.000 a Guatemala50.00020.00030.00000
Fondeo de 5.000 a PDV150.00020.00025.0005.0000
Fondeo de 18.000 a PDV250.00020.0007.0005.00018.000
Pago de 1.000, comisión 10, en PDV148.99020.0107.0004.00018.000
Pago de 2.500, comisión 30, en PDV146.46020.0407.0001.50018.000
Pago de 4.500, comisión 54, en PDV241.90620.0947.0001.50013.500
Pago de 5.000, comisión 60, en PDV236.84620.1547.0001.5008.500
Pago de 4.500, comisión 54, en PDV232.29220.2087.0001.5004.000

Los pagos no mueven el disponible del país: el principal que baja el saldo del país es el mismo que sale de la caja, y los dos se anulan (ver el punto 6). Es la misma propiedad que ADR-010 §2 destacó un nivel más arriba.

4. Relación con ADR-010: dos fórmulas para la Holding, y por qué no se contradicen ​

ADR-010 (Proposed, sin implementar) preguntó cuál era el «disponible de la Holding» y recomendó F − Fe − D. La planilla del cliente usa otra cuenta. Con F = lo recibido de Soterex, D = lo enviado a los países y Fe = las comisiones de lo pagado:

FórmulaQué mideDónde está en la planillaCon los números de §3
Extracto «CIS Holding» (este ADR)F − D + FeLo que tiene la Holding sin repartir (F − D), más lo que ganó en comisionesLa columna «CIS Holding»50.000 − 30.000 + 208 = 20.208
ADR-010 §2F − Fe − DCuánto del prefondeo de Soterex queda sin asignar a ningún país, ya descontada la comisiónNo es una columna: es Soterex ↔ Holding − saldo del país (32.292 − 12.500)50.000 − 208 − 30.000 = 19.792

Difieren solo en el signo de la comisión, y no es un error de uno de los dos: miran a la Holding desde lados distintos. La planilla cuenta la comisión como algo que la Holding ganó (suma, ADR-007: «se queda con la comisión»). ADR-010 parte de globalBalance() —que ya descontó la comisión del prefondeo de Soterex— y le resta lo que tienen los países, así que la comisión queda reservada y no se puede mandar a un país. La diferencia entre las dos es siempre 2 × Fe (416 en el ejemplo), y no hay ninguna columna de la planilla contra la cual ADR-010 se pueda verificar.

Qué se decide acá. La pregunta abierta de ADR-010 era sobre el número que la tesorería lee, y eso lo contesta la planilla: el saldo de la Holding que se muestra es recibido − enviado a países + comisiones. El extracto lo calcula así, y como suma comisiones y no hay un servicio que las sume, el único extracto sin un servicio contra el cual cerrar es éste: su test lo compara contra una cuenta hecha a mano sobre el ledger (ΣF − ΣD + ΣFe).

Qué no se decide. ADR-010 sigue Proposed: nadie implementó su aviso OVER_HOLDING_PREFUNDING. Cuando alguien lo haga, tiene que elegir contra qué número compara. La recomendación es la del extracto —el que la tesorería ve en la pantalla—, porque un aviso que dispara con un umbral distinto del número que se está mirando es un aviso que nadie entiende. Que la comisión sume al saldo de la Holding es una lectura de la planilla que todavía no confirmó Teresa (punto 8 de las preguntas abiertas del plan): si quiere verla al revés, cambia el signo de una fuente de TreasuryStatementService::holding() y el test de la planilla lo vuelve a decir. (2026-10-07, G12: la hoja «Módulo tesorería» que mandó el cliente el 2026-10-02 la muestra sumando, así que para Guatemala está contestada; ver la pregunta 4.)

5. Alcance, moneda y permisos ​

Los dos extractos de la Holding cubren los países que el usuario puede leer. El saldo de la Holding es global (ADR-007 §1), pero ver cada línea de otro país es más que ver el total. Por eso:

  • Con prefondeo:read en todos los países que cuentan, el extracto es la Holding global y cierra exactamente con globalBalance() (scope.partial = false).
  • Con acceso a algunos, el extracto incluye solo los movimientos de esos países, cierra con la suma de sus saldos por país, y lo dice (scope.partial = true, con un mensaje listo para mostrar). Ni una línea de los demás.
  • Qué países cuentan (G12, H3-10): los activos y los que tienen movimientos de los que muestran las pestañas de la Holding —un asiento de prefondeo, un envío al país o un pago PAID—. Un país inactivo y sin ningún movimiento no cuenta: no hay nada que ocultar, y contarlo volvía «parcial» a una Tesorería asignada a todos los países reales (El Salvador y Honduras se siembran inactivos). Uno inactivo con movimientos sí cuenta, porque su plata está en el saldo global. La regla es de PrefundingService::isPartialScope(), una sola para los dos extractos y para la tarjeta.
  • La tarjeta de Prefondeo Soterex sigue la misma regla (G12, H3-11, D3-19 b): GET /prefondeo devuelve el saldo global si el usuario cubre todos los países que cuentan y la suma de sus países si no, con scope.partial, scope.countries (solo los suyos) y scope.message. Antes devolvía siempre el global, y la tarjeta no coincidía con las pestañas de su propia pantalla; la respuesta del alta (POST /prefondeo) usa el mismo alcance. Revierte en parte ADR-007 §1 (ver su Actualización). Los países que lee son los mismos que los de los extractos: la lista sale de PermissionService::wholeCountryIds(), que descarta los países con la asignación acotada por PDV (más abajo), y la usan la tarjeta, el alta y los extractos. Para la tarjeta eso quiere decir que un país acotado por PDV tampoco suma, que pedirlo con GET /prefondeo?country_id=… es 403 y que sin ningún país de país entero no hay saldo que mostrar (balance y scope en null).
  • country_id es opcional y pide el desglose de un país: el extracto cubre solo ese país y sale partial = true mientras existan otros. Uno al que no se tiene acceso responde 403. La pantalla no lo manda por defecto: sin él es el extracto de todos los países que el usuario lee.

País: exige prefondeo_pais:read en el país pedido (403 si no). Sin country_id hay default solo si el usuario tiene un único país; con más de uno, 422 COUNTRY_REQUIRED.

Los tres extractos «de país» (las dos Holding y País) son de país entero y no respetan un alcance por PDV. Listan cada pago y cada fondeo de todos los PDVs del país —MTCN, monto, «PDV · Caja N», motivo—, que es más de lo que le da una asignación acotada a algunos PDVs. Antes de B7 las pantallas de prefondeo mostraban solo saldos del país y acotar por PDV no cambiaba nada ahí; ahora sí. Por eso un país donde la asignación del usuario está acotada por PDV queda fuera de estos tres extractos: para ellos es un país que el usuario no lee (si es el único, 403 en el extracto y en su export; si hay otros, el extracto de la Holding sale parcial sin él; pedirlo a mano con country_id también responde 403). Alcanza con que una asignación del país no esté acotada. Con la matriz sembrada no cambia nada —Tesorería y Admin no van acotados—, y el extracto del PDV sí sigue el alcance por PDV, que es para lo que existe. Es la lectura restrictiva, elegida porque la contraria deja ver más de lo que el alcance autoriza; si el cliente quiere que una asignación acotada lea la Holding, es una decisión de permisos (pregunta 5 de Preguntas abiertas) y se revierte en PermissionService::wholeCountryIds(), la regla que comparten los extractos y la tarjeta de la Holding (G12).

PDV: exige fondeo_caja:read y respeta el alcance por PDV de la asignación. Un Supervisor del PDV1 que pide el PDV2 recibe 403, por API y no solo con la pestaña oculta. Un PDV que no existe responde igual que uno ajeno: no se pueden sondear ids. El saldo anterior sale del ledger de ese PDV y de nada más: el extracto no deja ver un total de país que el usuario no puede ver.

Moneda: con saldo corrido solo si el país paga en USD (hoy, Guatemala). El disponible del país resta lo repartido en cajas —en la moneda de pago— a un saldo en USD, y con otra moneda esa resta no significa nada; el saldo de un PDV en moneda local sí sería un número válido, pero mezclar monedas en un corrido es MVP2 y el cliente pidió el mismo comportamiento para los dos. En un país que paga en moneda local el extracto devuelve los movimientos sin balance, cada uno con su moneda, y con un aviso explícito (warning.code = NO_RUNNING_BALANCE_LOCAL_CURRENCY). Los extractos de la Holding son siempre en USD y siempre tienen saldo.

6. Dónde el plan y el código discrepan, manda el código (P10) ​

La instrucción del plan fue: si discrepan —por ejemplo, en cómo entran los ajustes al disponible del país—, el extracto cierra con el servicio y se anota la decisión.

availableToDistribute() es Σ asientos − Σ principales pagados − Σ movimientos de las cajas del país, y para que el extracto cierre en todos los casos y no solo en el feliz, el del país lo lee así:

  • Crédito: cada asiento de prefondeo del país.
  • Cada movimiento de caja que no es un pago, con el signo cambiado: un fondeo resta lo que queda para repartir; un ajuste, con su signo (un faltante de arqueo, que baja la caja, sube lo disponible); y los viejos DEPOSITO_APERTURA y RETIRO_CIERRE también, con un concepto legible.
  • Un pago PAID baja el saldo del país en su principal y el movimiento PAGO de la caja que lo cubrió lo sube por lo mismo, así que se anulan y no son una línea. Lo que no se anula sí lo es: un pago sin movimiento de caja (un país sin módulo Caja, o pagado antes de que existiera) resta su principal, y un movimiento PAGO que no corresponde a ningún pago de ese país lo suma. Sin esto el extracto de un país sin cajas —Ecuador— daría un número distinto del que el sistema usa para validar sus pagos.
  • Los ajustes positivos restan lo disponible en el extracto aunque hoy ajuste() no avise de nada (ADR-010 §4, sin implementar): el extracto cierra con el servicio, no con lo que el aviso debería hacer cuando exista.

El extracto del PDV es más simple: sus movimientos son el ledger de la caja, y cierra con la suma de los saldos de sus cajas, filtrados por la moneda de pago vigente como hace CashBoxService::balance() (la plata que quedó en una moneda anterior no entra al corrido, igual que no entra al saldo).

7. Qué muestran y qué no (B7.4) ​

  • Nada del beneficiario. De una transacción salen el MTCN (en la referencia), el monto, la comisión y la fecha; nunca el nombre, el documento, el teléfono ni nada más. Tesorería no tiene permiso sobre transacciones y para conciliar le alcanza con el MTCN y los montos. Un test afirma las claves de cada fila y que el JSON no contenga ni un dato de la transacción fuera de esos. Si alguien pide los nombres en el extracto, es una decisión de permisos y privacidad, no un cambio de implementación.
  • Ya no se muestra «Cargado por». Las dos listas viejas de asientos (Prefondeo Holding y Prefondeo País) tenían una columna con el email de quien cargó cada asiento. Los extractos usan las columnas que pidió el cliente —Fecha, Concepto, Referencia, Débito, Crédito, Saldo— y no la traen: se perdió esa vista para Tesorería, que no tiene permiso sobre Auditoría. El dato sigue guardado (created_by del asiento) y en Auditoría (PREFUNDING_ENTRY_CREATED) para el Admin. Es una decisión de trazabilidad que el plan no cubría (pregunta 6 de Preguntas abiertas): devolverla es agregar el email de created_by a las filas de asiento de la Holding y del país en TreasuryStatementService, una columna en ExtractoTesoreria.vue y en el export, y sumarlo al test de claves permitidas (B7.4).
  • Sin gastos bancarios (C8). En el Financial Report de Ecuador el banco descuenta una comisión cuando llega cada transferencia (se notifican 2.600, entran 2.570, costo 30) y el saldo de la hoja usa el monto notificado. El extracto hereda ese criterio: el crédito de un prefondeo es lo que se cargó en el asiento y no se modela ningún costo bancario.
  • Una referencia de texto libre por asiento de la Holding (prefunding_entries.motivo, 255, opcional), con el mismo nombre y la misma validación que el del país. En el Financial Report cada prefondeo lleva dos (REF BAN, la del banco, y REF INT, la interna): por defecto se escriben las dos juntas en el mismo campo. La auditoría del alta no cambia (país y monto): la referencia queda en el asiento, que es inmutable.
  • El RS-xxxxx de los pagos de Ecuador no se modela. No existe en ningún lugar del repo y no sabemos si Soterex lo manda en SendRequest: no se agrega una columna especulativa. La referencia de un pago es el MTCN.

8. Contrato de la API ​

Todos son GET, con token, bajo /tesoreria/extractos/. El saldo y el orden se calculan en el servidor; la pantalla dibuja lo que recibe.

ExtractoRutaPermiso de la rutaParámetros propios
Soterex ↔ CIS Holdingsoterex-holdingprefondeo:readcountry_id (opcional: el desglose de un país)
CIS Holdingholdingprefondeo:readcountry_id (opcional)
Paíspaisprefondeo_pais:readcountry_id (obligatorio salvo un único país)
PDVpdvfondeo_caja:readstation_id (obligatorio)

Comunes: from y to (fechas; el día completo, los dos inclusivos; por defecto los últimos 30 días con hoy incluido), page (1 a 100.000), per_page (1 a 100, 25 por defecto) y order (asc, el de un estado de cuenta, o desc). Cada uno tiene su …/export?format=xlsx|pdf con los mismos filtros, sin paginar. Los cuatro exports comparten un tope de 10 pedidos por minuto por usuario (429 TOO_MANY_REQUESTS), como el reporte de Cumplimiento.

La respuesta trae extract, currency, filters, scope (partial, los países cubiertos, el país o el PDV, y un message cuando es parcial), balance_available, warning, summary (opening_balance, closing_balance, current_balance, total_debit, total_credit), data y meta (total, per_page, current_page, last_page). El de la Holding («CIS Holding») suma commissions_total (G12.3, RV3-66): la suma de sus líneas PAYMENT_FEE del rango —«de los cuales comisiones»—, que sale de la misma fuente que esas líneas, así que no puede dar otra cosa que ellas; con los números de la planilla del cliente es 208. El del país suma breakdown (saldo del país, distribuido en cajas y disponible; en un país que paga en moneda local solo trae el saldo y los otros dos van en null, y el breakdown de GET /prefondeo-pais —el que lee la tarjeta de Fondeo PDVs— dice lo mismo: CountryPrefundingService::breakdown() es el único que lo arma, y la tarjeta oculta las dos filas). summary.current_balance es el que da el servicio de saldos hoy y es el «Monto actual» del encabezado; closing_balance es el último saldo corrido del rango, y los dos coinciden si el rango llega hasta hoy.

Cada fila de data: id, type, date (ISO 8601), concept, reference (null si no hay), debit y credit (positivos; el que no aplica, null), balance (null si el extracto no tiene saldo corrido), currency y, según el extracto, country (Holding: el código ISO) o cash_box ({id, number}, PDV). Los type: PREFUNDING_ENTRY, PAYMENT, PAYMENT_FEE, COUNTRY_TRANSFER, COUNTRY_ENTRY, PAYMENT_WITHOUT_CASH y CASH_FONDEO / CASH_AJUSTE / CASH_PAGO / CASH_DEPOSITO_APERTURA / CASH_RETIRO_CIERRE.

Errores: 403 PERMISSION_DENIED (sin el permiso, país o PDV fuera de alcance), 422 COUNTRY_REQUIRED, 422 de validación (rango invertido, per_page fuera de rango, station_id faltante) y 422 EXPORT_TOO_LARGE.

9. Exports ​

Cada extracto exporta a Excel y a PDF con ReportExportService. El Excel lleva los montos como número (con formato #,##0.00, para poder operarlos) y el PDF, apaisado, con el formato USD 1,234.56 de toda la app. Con saldo corrido arrancan con la fila «Saldo anterior». Sin él (país en moneda local) llevan una columna Moneda en vez de Saldo.

Un extracto parcial se reconoce en el archivo (G12, revisión). Los exports traen solo lo del alcance del usuario —la misma regla que la pantalla— y el PDF lo dice en el membrete: el alcance nombra los países y agrega «parcial: no incluye los demás países»; con un país pedido y nada que ocultar nombra el país en vez de «Todos los países». El Excel no lleva aviso: es una tabla de columnas y filas pensada para operarse (ni título ni totales), y le agregaría una fila que rompe esa lectura; lo que lo identifica es la columna País y el nombre del archivo, que lleva los códigos de los países cubiertos.

Se rechaza con 422 EXPORT_TOO_LARGE lo que supere exports.max_rows, en vez de truncar: un archivo «completo» al que le faltan filas es peor que ninguno. El tope se chequea antes de traer las filas: se cuentan las de cada fuente con la misma consulta base y, si la suma lo pasa, no se trae ninguna (TreasuryStatementTooLarge) — un tope que se compara después de armar todo en memoria no protege la memoria. El pedido se audita antes de armar el archivo (REPORT_EXPORTED, con un tipo por extracto: extracto_soterex_holding, extracto_holding, extracto_pais, extracto_pdv) con el formato, los países, el PDV, el rango y la cantidad de filas. Ni el contenido ni un MTCN.

10. Pantallas, menú y permisos (B7.5) ​

La API de arriba la dibuja un solo componente, ExtractoTesoreria.vue, que no recalcula ningún saldo: todo lo que muestra sale de la respuesta, pagina pidiéndole la página al backend y descarta una respuesta vieja si llegó otra más nueva. Las dos pantallas de prefondeo pasan a tener pestañas:

Pantalla (ruta)PestañasPermiso de cada una
Prefondeo Soterex (/prefondeo)Soterex ↔ CIS Holding y CIS Holdingprefondeo:read
Fondeo PDVs (/prefondeo-pais)País y PDVprefondeo_pais:read y fondeo_caja:read
  • «Fondeo PDVs» se abre a fondeo_caja. Es la deuda que ADR-014 §9 dejó anotada: el ítem y la ruta seguían solo a prefondeo_pais porque no había nada que mostrarle al Supervisor, que lee fondeo_caja pero no prefondeo_pais. Con la pestaña PDV sí lo hay. La ruta conserva su name y meta.module = 'prefondeo_pais' (el módulo principal, el que usa el «?» para elegir la sección del manual y el recorrido) y suma meta.modules = ['prefondeo_pais', 'fondeo_caja'], la lista que la habilita. puedeLeerRuta() es el helper que comparten el guard y firstAllowedRoute(); el ítem del menú se filtra con su propia isVisible(), que aplica la misma regla sobre la lista modules del ítem, y un spec de AppLayout afirma que todo enlace visible de cada perfil lleva a una pantalla que puedeLeerRuta() deja abrir. No cambia ninguna clave de módulo, ningún name de ruta ni ningún data-tour.
  • Cada pestaña aparece con su permiso y con una sola no se dibuja la barra: el Supervisor entra y ve directamente la de sus PDVs, y la pantalla no pide nada de /prefondeo-pais, que le respondería 403. Su «?» va a la sección #fondeo_caja del manual, no a una que su perfil no tiene.
  • El selector de PDV sale de las asignaciones del usuario (los PDVs de la lista si la asignación está acotada, todos los del país si no). Es la misma regla del backend y no la reemplaza: un PDV ajeno responde 403 igual.
  • El alta de asiento sigue donde estaba, con el campo Referencia opcional en los dos (en la Holding es prefunding_entries.motivo). Al guardar se recargan el saldo y el extracto que se mira.
  • Recorrido guiado de Prefondeo Soterex: no se movió ningún data-tour. prefondeo-saldo y prefondeo-asientos conservan su nombre; el segundo ahora envuelve las pestañas y el extracto, y cambiaron el título y el texto de ese paso («Extractos de la Holding»). No hay recorrido de Fondeo PDVs.
  • En el celular el Supervisor suma un séptimo destino (Fondeo PDVs): la barra muestra cinco y Tipo de cambio y Reportes pasan al panel «Más». (Desde G8, 2026-10-07, el Supervisor ya no tiene Tipo de cambio: vuelve a tener seis destinos, entran todos en la barra y no hay «Más»; ADR-014, actualización de G8.)

Alternatives Considered ​

  • Materializar el saldo corrido en una columna de cada ledger. Dejaría el extracto como una lectura simple y rápida. Descartado por ADR-005 y sin razones nuevas para reabrirlo: un saldo guardado puede desincronizarse del ledger, y que el último saldo del extracto sea exactamente el del servicio es lo que el cliente va a auditar.
  • Calcular el corrido en SQL (UNION ALL de las fuentes y una función de ventana), paginando en la base. Escala mejor con millones de filas y evita traer todo el rango a memoria. Se descartó por ahora: el plan pide reusar RunningBalance (B2), el volumen de un rango razonable son cientos de filas y el cálculo en PHP queda en un solo lugar y testeable. Es el camino si algún extracto pasa del tope de exportación como uso normal.
  • Que fondear una caja descuente el país, como en la planilla. Hace que la planilla y la app muestren lo mismo sin explicarlo. Descartado: ADR-007 §1 fijó lo contrario por una razón contable —el saldo del país tiene que ser conciliable contra el banco— y Carlos lo confirmó el 2026-08-07. El extracto del país muestra el número de la planilla como disponible, no como saldo.
  • El extracto del país con el saldo contable como corrido. Es lo que conciliaría contra el banco, pero no es la columna de la planilla: ahí fondear baja. El saldo contable va en el encabezado, que es donde el cliente lo busca.
  • Un extracto global de la Holding para cualquiera con prefondeo:read en algún país. Es lo que hacía la pantalla con el saldo hasta G12 (§5), y es más simple. Descartado: el saldo es un total, pero el extracto lista cada pago de cada país con su MTCN y su monto, y eso es más de lo que ese permiso le da sobre los países que no ve.
  • Un módulo de permiso nuevo por extracto. Cuatro filas más en la matriz. Se descartó: los tres permisos que ya existen (prefondeo, prefondeo_pais, fondeo_caja) dicen exactamente quién maneja cada capa, y la matriz de ADR-014 ya los reparte entre Tesorería, Supervisor y Admin.

Consequences ​

  • Positive: la planilla del cliente y la app dejan de ser dos relatos: cada número de la planilla tiene su lugar y un test que lo reproduce, y el último saldo de cada extracto es auditable contra el servicio de siempre. Los pagos pasan a verse como movimientos. El Supervisor ve los de su PDV sin tocar el prefondeo, y un test lo afirma por API.
  • Positive: cero cambios en cómo se calcula un saldo: ninguna migración de datos, ninguna regla nueva sobre el pago ni sobre la caja. Lo único que se escribe es la referencia opcional de un asiento.
  • Negative: el corrido se calcula en memoria sobre todo el rango y recién después se pagina, así que un rango de años de un ledger grande trae todas sus filas. Los exports cuentan antes y cortan en exports.max_rows sin traer nada; la pantalla no tiene tope de rango: el default es de 30 días, pero quien tiene el permiso puede pedir un rango de años y cada página repite el cálculo (el resto de Reportes tampoco acota el rango). Es el costo de no recalcular el saldo de un pedazo, y la alternativa en SQL queda anotada arriba; si la pantalla pasa a ser lenta, el camino es un tope de rango o esa alternativa.
  • Negative: dos números de la Holding conviven en la documentación (F − D + Fe en el extracto, F − Fe − D en ADR-010). Están explicados y no se contradicen, pero el día que se implemente el aviso de ADR-010 hay que volver a elegir contra cuál se compara.
  • Negative: un usuario que ve solo algunos países ve un extracto de la Holding que no cierra con el saldo global de la Holding. Es a propósito —no ve esas líneas— y viaja con un aviso (scope.message) para mostrar. (Hasta G12 la tarjeta de la pantalla le mostraba, además, ese saldo global y no coincidía con sus pestañas; desde G12 la tarjeta muestra el de sus países, y lo único que no cierra es contra un número que esa persona no ve.)
  • Neutral: el extracto de un país en moneda local sale sin saldo hasta que el producto soporte más de una moneda en un corrido (MVP2). Hoy ningún país está en ese caso.

Preguntas abiertas ​

Las cuatro primeras son para Magaly y Teresa; la 5 y la 6 son de permisos y trazabilidad y las decide Carlos. Ninguna bloquea B7: cada una tiene un comportamiento por defecto, conservador y reversible, y cambiarlo es un cambio chico.

Actualización (2026-10-07, G12). El cliente contestó el 2026-10-02 con la hoja «Módulo tesorería» y un mail que dice que, para el estado de cuenta de cada entidad, rige esa pestaña y se descarta cualquier otra información (RV3-96 y RV3-97 del plan de ajustes v3). Lo que eso resuelve, pregunta por pregunta (el estado vigente y el detalle están en las Preguntas abiertas del módulo Caja, sección 6.3, #16 a #21):

  • 1 (REF BAN y REF INT): cerrada por defecto. La pestaña no trae columnas de referencia bancaria ni interna y la hoja de Prefondeo pide una «Referencia» en singular: se queda una referencia. Es una inferencia de su respuesta, no un sí explícito; si la quieren en dos, el cambio es el de siempre.
  • 2 (RS-xxxxx): abierta. El cliente fijó una regla —si Soterex lo manda, se mantiene en el reporte; si no, se elimina— que depende de una respuesta de Soterex que todavía no hay.
  • 3 (débito de un pago = principal más comisión): contestada para Guatemala. El ejemplo de la hoja (el de Guatemala) resta a Soterex el principal más la comisión, igual que PrefundingService::balance(). La versión de Ecuador está en un bloque oculto de la hoja, que no se toma como requisito: Ecuador sigue por defecto y sin confirmar.
  • 4 (la comisión suma al saldo de la Holding): contestada para Guatemala. La hoja muestra a «CIS Holding» sumando la comisión de cada pago, que es lo que calcula el extracto.
  • 5 y 6: abiertas. Son de Carlos, no del cliente.
  1. ¿Quieren REF BAN y REF INT como dos campos separados en el asiento de la Holding, o alcanza uno? Por defecto, uno. Separarlos son dos columnas opcionales (bank_reference, internal_reference), dos campos en el formulario y dos columnas en el extracto.

  2. ¿Necesitan ver el RS-xxxxx de Soterex como referencia de cada pago? Si sí, primero hay que preguntarle a Soterex si el dato existe y en qué mensaje viaja. Por defecto, la referencia del pago es el MTCN.

  3. ¿El débito de cada pago en «Soterex ↔ CIS Holding» es principal más comisión también en Ecuador? La planilla de Guatemala lo hace así (50.000 − 1.010 = 48.990) y es lo que hace PrefundingService::balance(); falta confirmar que el Financial Report de Ecuador cuenta igual.

  4. ¿La comisión suma al saldo de la Holding? Ya estaba anotada en el plan (punto 8). Que la comisión sume es la lectura de la planilla; falta que Teresa confirme que es lo que quiere ver (punto 4 de este ADR). Si lo quiere al revés, se cambia el signo de una fuente del extracto CIS Holding y el test de la planilla lo vuelve a decir.

  5. ¿Una asignación acotada por PDV tiene que poder leer los extractos «de país entero» (los dos de la Holding y el de País)? Por defecto, no: esos tres listan cada pago y cada fondeo de todos los PDVs del país, más de lo que da una asignación acotada, así que para ellos ese país no cuenta como leído (§5). Con la matriz sembrada no cambia nada (Tesorería y Admin no van acotados). Se revierte en PermissionService::wholeCountryIds() (la regla que comparten los extractos y la tarjeta de la Holding, G12). Decide Carlos: es una decisión de permisos.

  6. ¿Tesorería necesita ver quién cargó cada asiento («Cargado por»)? Por defecto, no se muestra (§7): el dato sigue en created_by del asiento y en Auditoría para el Admin, y Tesorería no tiene permiso sobre Auditoría. Devolverla es agregar el email de created_by a las filas de asiento de la Holding y del país en TreasuryStatementService, una columna en ExtractoTesoreria.vue y en el export, y sumarlo al test de claves permitidas. Decide Carlos: es una decisión de trazabilidad.

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