Skip to content

ADR-022: Alta y baja de cajas ​

Date: 2026-10-06 Status: Accepted — decisión D3-14 (a) de Carlos (2026-10-05) y valores por defecto de QC-15 y QC-16, implementada el 2026-10-06 en la entrega G7 del plan de ajustes v3 y en la línea de país de G6.C. Qué está hecho: el backend completo (G7.1 a G7.4 y G6.C1: la columna, el PATCH, la «caja operable», las validaciones de H3-06, el motivo de ajuste nuevo y el bloque countries[] de totales-pdv), la etiqueta de Auditoría, la pantalla (el panel «Administrar» de Estaciones/PDV y la etiqueta «Inactiva» de Reportes → Cajas, §6, y la línea de país de Saldos, §7) y la documentación: el manual de usuario (30-caja.md, 31-caja-apertura-cierre.md, 32-caja-fondeo.md, 60-reportes.md, 83-admin-estaciones.md y 90-auditoria.md), el análisis funcional de Caja (las reglas R21 a R23, 1.10, 2.4, 2.7, 4.5 y 4.6, y las preguntas abiertas #23 y #24) y el plan de prueba manual. Qué queda abierto: nada de implementación. Dos confirmaciones, con su comportamiento por defecto ya implementado: la aprobación de Tesorería del motivo «Retiro por baja de caja» y de rechazar la baja con saldo (QC-16), y la del cliente de que la línea de país es el total de las cajas (QC-15). Están como las preguntas #23 y #24 de 06-preguntas-abiertas-caja. El plan de ajustes v3 llama a este ADR «ADR-018» (numeración provisoria): la definitiva es 022. Revisión (2026-10-07): la revisión independiente de la entrega encontró que sacar de Saldos a las cajas de un PDV inactivo o de un país sin módulo Caja (§2) dejaba un hueco que el plan no contemplaba: desactivar un PDV, mudarlo de país o apagar el módulo del país escondía una caja abierta o con plata sin que nadie pudiera cerrarla ni retirarla. Se aplicó la regla de §4 a esas tres vías (§5): no se rechazaba nada y ahora se rechaza (409), con su code. Es una extensión de D3-14 (a) que el plan no pedía; el resto de la revisión (la razón de «no operable» atada a su definición, el texto de la confirmación con el PDV inactivo, el foco del panel, la nota del efectivo en otra moneda, los tests de carrera que sí distinguen la implementación) está en las secciones que corresponden. Extends: ADR-005 y ADR-007 (el saldo se deriva del ledger; esta entrega no guarda ningún saldo) y ADR-021 (la sesión y su operador).

Context ​

Magaly (CIS-EC, 2026-10-02) pidió dos cosas sobre las cajas de un PDV, en la hoja de ajustes v2:

  • RV3-29 y RV3-30. «Habilitar una opción para administrar cajas: agregar, activar, desactivar.» Agregar ya existía desde E4-multi («+ agregar caja» en Parámetros → Estaciones/PDV, auditado). Activar y desactivar no: cash_boxes tenía solo id, station_id, number y los timestamps, y una caja existía para siempre, aparecía en Saldos y en Reportes → Cajas y se podía abrir.
  • RV3-28. Una línea de país arriba de las tarjetas por PDV de Saldos. El cliente la dibujó sobre la captura: «GUATEMALA · USD 24878.53», que es la suma de las tres tarjetas y el mismo número que «Distribuido en cajas» de Fondeo PDVs (Prefondeo País).

Al darle baja a las cajas aparecieron tres huecos que ya estaban (H3-06): desactivar un PDV no tocaba sus cajas, agregarCaja no validaba que el país tuviera módulo Caja ni que el PDV estuviera activo, y mover un PDV a un país con módulo Caja no le creaba la Caja 1. Y quedaba el problema de fondo de toda baja contable: la plata que tiene adentro la caja que se da de baja.

Decision ​

1. Una caja se desactiva y se reactiva; no se borra (G7.1) ​

cash_boxes.active (boolean, default true): las cajas que ya existen quedan activas, así que el deploy no le saca nada a nadie. Es configuración del PDV y no un saldo: no toca ADR-005 ni ADR-007, el saldo de una caja sigue derivándose de cash_movements y la caja conserva su number y todo su ledger. Reactivarla es volver a poner el booleano en true: vuelve con su número y su historia. El número no se reutiliza: CashBoxService::addCashBoxForStation() toma el max(number) + 1 de TODAS las cajas del PDV, también las inactivas, así que agregar una caja después de desactivar la última no le devuelve su número a la que se fue.

2. «Caja operable» es una sola definición (G7.3) ​

CashBox::scopeOperable(): la caja está activa, es de un PDV activo y ese PDV es de un país con módulo Caja. La usan los dos lugares que tienen que coincidir en «qué cajas existen para operar»:

  • Saldos (GET /caja/disponibles y GET /caja/totales-pdv, ambos por scopedCashBoxes()): una caja que no es operable no aparece, y total_cash_boxes cuenta solo las operables. Un PDV que solo tiene cajas de baja no sale en los totales.
  • La apertura (POST /caja/{id}/apertura): una caja que no es operable da 422 CASH_BOX_INACTIVE. El código es uno solo y el texto dice cuál de las tres razones es («está desactivada», «su PDV está inactivo», «su país no opera con módulo Caja») para que quien la intenta sepa a quién pedírselo; la definición de «operable» no está en el mensaje, solo la explicación de por qué no se cumplió.

Dos escrituras de la misma definición, atadas por un test. El scope es SQL (qué cajas lista Saldos y cuáles abre la apertura); CashBox::motivoNoOperable() es la misma definición en PHP para UNA caja, en el orden en que se le explica a la persona, y es lo que arma el texto del 422. Un test (CashBoxApiTest) las cruza en las ocho combinaciones de caja, PDV y país: si una regla nueva toca una sola, falla ahí. StationController::agregarCaja pregunta por el PDV y por el país sin pasar por ninguna de las dos, a propósito y con códigos propios (CASH_MODULE_DISABLED, STATION_INACTIVE): la caja que va a crear todavía no existe, así que no hay una fila a la que aplicarle el scope, y sus dos condiciones son un subconjunto de la definición (falta solo «la caja está activa», que una caja nueva cumple siempre).

Lo que NO usa el scope, a propósito: todo lo que lee el ledger. Reportes → Cajas (resumen, detalle y Cierres por día), los cuatro extractos de Tesorería de B7 y CountryPrefundingService::distributedInCashBoxes() siguen viendo las cajas dadas de baja, porque su historia no desaparece. El resumen de Reportes → Cajas las muestra marcadas: la fila trae active: false y el export dice «Inactiva» en la columna Estado (manda sobre abierta/cerrada).

3. Desactivar y reactivar: PATCH /admin/estaciones/{station}/cajas/{cashBox} (G7.2) ​

Cuerpo { "active": bool } (obligatorio). Gate perm:abm_estaciones,write, el mismo que «+ agregar caja» (P3-15: no se crea un módulo de permiso; si piden otro perfil para esto es una celda de la matriz). Una caja que no es del PDV de la URL da 404 CASH_BOX_NOT_FOUND.

PedidoRespuesta
Desactivar una caja cerrada y en cero200, data.active = false, auditoría CASH_BOX_DEACTIVATED
Desactivar con una sesión OPEN409 CASH_BOX_HAS_OPEN_SESSION
Desactivar con plata adentro en cualquier moneda409 CASH_BOX_HAS_BALANCE
Reactivar200, data.active = true, auditoría CASH_BOX_ACTIVATED
Pedir el estado que la caja ya tiene200, sin cambios y sin evento de auditoría
Sin abm_estaciones:write403
active ausente o no booleano422
  • Cualquier moneda. CashBoxService::balance() mira solo la moneda de pago vigente del país, y el efectivo que quedó en una anterior (el país cambió de moneda) solo sale por residualBalances(). Una caja con quetzales adentro y dólares en cero tiene el cajón lleno y balance() en cero: CashBoxService::hasBalance() mira las dos fuentes, y un test lo fija.
  • El rechazo no dice cuánto hay. Quien administra PDV (abm_estaciones) no es por eso quien ve los saldos de las cajas (A5.3, D11); el 409 de saldo dice qué hacer, no cuánto.
  • La auditoría no lleva montos: la metadata es {station_id, number}. La etiqueta legible («Caja desactivada», «Caja activada», «Caja agregada») está en la pantalla de Auditoría, con «Caja N» como detalle.
  • Se serializa con la apertura. El PATCH toma lockForUpdate de la fila de la caja ANTES de mirar sesiones o saldo y antes de escribir; la apertura toma el mismo lock y recién con la caja bloqueada comprueba que sea operable (una lectura nueva, no la caja que resolvió la ruta). Si gana la apertura, el PATCH ve la sesión abierta y responde 409; si gana el PATCH, la apertura lee active = false y responde 422. Una carrera real no se reproduce de forma determinística en un test: se prueba lo que la hace posible (el orden de las consultas y que cada lado decida con la caja bloqueada y no con la que resolvió la ruta), como en CountryFeeTierConcurrencyTest. Del lado del PATCH son tres tests: el lock va primero; el PATCH mira las sesiones al decidir; y entre que la ruta resolvió la caja y el PATCH la bloqueó otra request ya la desactivó, así que pedir «inactiva» no es un cambio y pedir «activa» reactiva de verdad (esos dos fallan si el controlador decide con la caja de la ruta).

4. Una caja con saldo no se da de baja: primero se la deja en cero (D3-14 a, QC-16) ​

La plata de la caja que se da de baja no puede quedar en un limbo: si se permitiera desactivarla con saldo (la alternativa b), el total del PDV de Saldos tendría que seguir sumándola para no discrepar del extracto del PDV de B7, y la caja «dada de baja» seguiría teniendo plata sin que nadie pudiera operarla. Se rechaza (409 CASH_BOX_HAS_BALANCE) y el camino es un motivo de ajuste nuevo del catálogo cerrado: «Retiro por baja de caja».

  • Es el único camino limpio: el único ajuste que existía para sacar plata era «Faltante de arqueo», que miente (no es un faltante).
  • Es negativo. Con ese motivo, el ajuste exige un monto negativo (422 si no): los demás motivos de ajuste no tienen signo, pero este existe para vaciar una caja y uno positivo la llenaría más. Solo es motivo de AJUSTE: el fondeo lo rechaza como cualquier motivo fuera de su catálogo. Se filtra en el historial por motivo como los demás (el filtro acepta cualquier string).
  • No hay migración de datos. El catálogo de motivos es una constante del dominio (CashMovement::MOTIVOS_AJUSTE, como lo dice CashBoxController::motivos(): si tesorería necesita uno nuevo, se agrega en CashMovement), no una tabla: agregarlo es tocar la constante. La pregunta abierta #2 del análisis funcional de Caja (qué motivos existen) era de Tesorería; Carlos aprobó este (D3-14).
  • Qué mueve en los saldos. Baja el saldo de la caja y, con él, lo distribuido en cajas del país; el saldo del país no cambia (un ajuste no es un pago), así que sube el disponible para distribuir (saldo del país = distribuido + disponible, ADR-015 §6: un ajuste que baja la caja sube lo disponible). El retiro figura en el extracto País de Fondeo PDVs como un movimiento con su signo. La plata vuelve contablemente al pool del país; el movimiento físico del efectivo queda afuera del sistema.
  • Obliga a abrir la caja, porque el ajuste exige una sesión abierta del día (ADR-013): la abre un Cajero, un Supervisor o un Admin (Tesorería tiene fondeo_caja:write pero no apertura_cierre_caja), se ajusta con fondeo_caja:write (Tesorería o Admin), se cierra, y recién ahí se desactiva. Es incómodo a propósito: sacar plata de una caja deja la traza de siempre (el ledger inmutable y la auditoría).

5. Los tres huecos de H3-06 (G7.4) ​

  • POST /admin/estaciones/{id}/cajas da 422 CASH_MODULE_DISABLED si el país del PDV no tiene módulo Caja y 422 STATION_INACTIVE si el PDV está inactivo: antes agregaba una caja que ninguna pantalla podía mostrar.
  • Desactivar un PDV con una caja abierta (PUT /admin/estaciones/{id} con active: false) da 409 STATION_HAS_OPEN_CASH_BOX, y con plata adentro de alguna caja, en cualquier moneda, 409 STATION_HAS_CASH_BALANCE (revisión, ver abajo). Solo cuando ese guardado lo desactiva: el formulario reenvía active en cada guardado y un PDV que sigue activo —o que ya estaba inactivo— no se frena por tener una caja abierta. El control bloquea las cajas del PDV (en orden de id) antes de mirar sesiones o saldo, por lo mismo que el PATCH. Desactivar un PDV no desactiva sus cajas (no se cascadea): la caja sigue activa pero deja de ser operable por el PDV, y si el PDV se reactiva vuelve sola. Las dos banderas son independientes, y scopeOperable() pide las dos.
  • Mover un PDV a un país con módulo Caja le crea la Caja 1 (ensureCashBoxForStation, idempotente). Solo cuando cambia de país: una Caja 1 que un Admin dio de baja a propósito no se «resucita» al renombrar el PDV. Y solo si el PDV no tiene ninguna caja: el firstOrCreate por número encuentra la Caja 1 dada de baja y no crea nada, así que un PDV con cajas pero todas de baja que pasa a un país con módulo queda sin ninguna operable, sin aviso; hay que activar una o agregar otra. Un PDV que ya está en un país con módulo Caja y no tiene ninguna caja (la hipótesis de Escuintla Norte: el seeder lo creó sin pasar por store) no se arregla acá: «+ agregar caja» le crea la Caja 1 (el max de ninguna caja es 0).

La baja de una caja no es la única vía por la que una caja deja de ser operable (revisión, 2026-10-07). Desactivar su PDV, mudar el PDV de país y apagar el módulo Caja del país también la sacan de Saldos y de la apertura (§2), y antes de esta revisión ninguna miraba lo que la caja tenía adentro: una caja abierta quedaba sin forma de cerrarse desde la pantalla (el Cajero no la ve, y su 409 USER_ALREADY_HAS_OPEN_CASH_BOX le pedía cerrarla) y una caja con plata desaparecía de las tarjetas mientras la línea de país y el extracto del PDV seguían contándola: el mismo descuadre por el que §4 descarta la alternativa (b). Se aplica la regla de §4 a las tres vías, con un solo control (CashBoxService::bloqueoParaDejarSinOperar(), que bloquea las cajas y mira sesiones y hasBalance()):

VíaRechazo (409)
Desactivar un PDV (PUT /admin/estaciones/{id} con active: false)STATION_HAS_OPEN_CASH_BOX · STATION_HAS_CASH_BALANCE
Cambiar de país a un PDV (PUT /admin/estaciones/{id} con otro country_id)los mismos, con «antes de moverlo de país». Se frena también si el país nuevo tiene módulo Caja: balance() mira la moneda de pago del país donde está, y la plata cargada en la del anterior pasaría a verse solo como residuo, sin salida por el retiro de §4
Apagar el módulo Caja de un país (PUT /admin/paises/{id} con modulo_caja: false)COUNTRY_HAS_OPEN_CASH_BOX · COUNTRY_HAS_CASH_BALANCE
  • Solo cuando las cajas HOY son operables por esa vía: un PDV activo de un país con módulo Caja (para el país, sus PDV activos). Las cajas de un PDV ya inactivo o de un país sin módulo ya están ocultas y no se pueden abrir para vaciarlas: frenar por ellas dejaría al Admin sin salida.
  • Los rechazos no dicen cuánto hay (quien administra PDV o países no ve los saldos, A5.3) y dicen el camino: el mismo de §4.
  • Es una extensión de D3-14 (a) que el plan no pedía. Se eligió rechazar y no «seguir mostrando las cajas no operables que tienen plata o una sesión abierta» (la otra solución que sugirió la revisión) porque esa choca con G7.3: Saldos y la apertura comparten UNA definición de caja operable (§2), y una excepción en el listado la parte en dos. Si Carlos prefiere solo avisar, se saca el control de StationController::update y de CountryController::update, y la nota «Neutral» de abajo pasa a describir el estado normal.
  • El deploy no arregla lo que ya existe (ver la nota de «Consequences» y la consulta previa del plan de pruebas).

6. Lo que expone el backend para el panel (el front solo refleja) ​

  • GET /admin/estaciones/{station}/cajas suma a cada caja active y opened_by ({id, email} de quien la tiene abierta ahora, o null). Es lo que el panel necesita para no ofrecer «Desactivar» sobre una caja abierta. Las inactivas se listan igual: es el único lugar desde donde se reactivan. El mail lo ve quien tiene abm_estaciones:read (el Admin); es el mismo dato que ya sale en Saldos (QC-14).
  • POST …/cajas devuelve la caja con active: true.
  • GET /reportes/cajas (resumen) suma active por fila.

El panel «Administrar» (AdministrarCajas.vue, G7.5) solo refleja eso, sin reglas propias:

  • La celda «Cajas» de Parámetros → Estaciones/PDV dice «N cajas · M inactivas · Administrar» (cuenta solo las activas) y conserva el botón «+ agregar caja» de siempre. Quien solo puede leer ve «Ver», y el mismo panel sin botones de cambio.
  • Se pide la lista cada vez que se abre: «quién la tiene abierta» no puede ser el dato de cuando se cargó la pantalla.
  • Lo único que se anticipa es lo que ya se sabe que no va a andar: una caja abierta (opened_by distinto de null) no ofrece «Desactivar», dice quién la tiene y que primero hay que cerrarla, y un PDV inactivo deshabilita «+ agregar caja». Lo demás lo contesta el backend.
  • Desactivar y activar piden confirmación en la misma fila, no en un segundo diálogo encima del panel: el 409 que sigue tiene que quedar leíble al lado de la caja de la que habla. El 409 se muestra con el texto del backend; el de saldo (CASH_BOX_HAS_BALANCE) suma los cuatro pasos de §4 y el de sesión abierta (CASH_BOX_HAS_OPEN_SESSION) vuelve a pedir la lista, que quedó vieja. Un 422 de validación de Laravel (sin code) no filtra su texto en inglés.
  • Para teclado y lector de pantalla: el resultado («Caja 2 desactivada.») se anuncia en una región role="status", el rechazo es un role="alert" en la fila de la caja, y al cerrarse la confirmación el foco vuelve al botón de esa caja en vez de perderse. El panel se anuncia como diálogo y le pide el foco a «Cerrar» al abrirse.
  • Desactivar un PDV con una caja abierta o con plata (STATION_HAS_OPEN_CASH_BOX, STATION_HAS_CASH_BALANCE) muestra el motivo del backend arriba de la tabla; el de un cambio de país, en el aviso del formulario. Los rechazos de una acción puntual ya no ocupan el lugar de la tabla (antes el error reemplazaba el listado de PDV) y se van al empezar a editar o guardar otro PDV (un «Estación actualizada» no puede convivir con el rechazo de OTRA).
  • Activar una caja de un PDV inactivo no promete lo que no pasa: la confirmación y el anuncio dicen que queda activa pero no aparece en Saldos ni se puede abrir mientras el PDV esté inactivo. Tras un 409 que refresca la lista y le saca el botón a la fila, el foco va al aviso de esa caja (y, si la fila ya no está, a «Cerrar»), no a un elemento desmontado dentro del diálogo.
  • Los pasos para dejarla en cero dicen que abre un Cajero, un Supervisor o un Admin y suman una nota para el único caso que no resuelven: efectivo en una moneda anterior del país (el ajuste escribe en la moneda vigente), donde hay que pedir soporte.
  • El formulario de Ajuste de Saldos avisa, al elegir Retiro por baja de caja, que el monto va en negativo (el 422 del backend sigue siendo el que manda).
  • Reportes → Cajas rotula «Inactiva» (manda sobre «Abierta» o «Cerrada», como el export).

7. La línea de país de Saldos (G6.C1, RV3-28, QC-15) ​

GET /caja/totales-pdv suma al data de siempre un bloque countries[]: una línea por país del alcance del usuario, con country {id, iso_code, name}, currency (la moneda de pago vigente del país), total y scope_complete. QC-15 por defecto: el total es la plata que hay en las cajas del país, no el disponible para distribuir; si el cliente quiere además el disponible, se suma una segunda cifra solo para quien tiene prefondeo_pais:read, reusando CountryPrefundingService::availableToDistribute().

  • Nunca suma entre países ni entre monedas: quien opera Guatemala y Ecuador recibe dos líneas, cada una en su moneda.
  • Con el alcance completo, el total ES CountryPrefundingService::distributedInCashBoxes(), el mismo número que Fondeo PDVs (Prefondeo País) llama «Distribuido en cajas»: una definición, no dos que algún día discrepen. Eso incluye la plata de un PDV inactivo, que no tiene tarjeta porque sus cajas no son operables: la línea puede ser mayor que la suma de las tarjetas. Desde la revisión no se desactiva un PDV con plata (§5), así que solo pasa con un PDV que ya estaba inactivo antes de G7 (consulta previa del plan de pruebas); un test fija este comportamiento. Si el cliente prefiere la línea igual a la suma de las tarjetas aun en ese caso, la línea pasa a sumar solo las cajas operables y deja de ser «Distribuido en cajas» (pregunta #24). Con el alcance parcial, el total son solo las cajas operables de los PDV que el usuario ve (la suma de sus tarjetas), y scope_complete es false: la pantalla lo rotula «Total de tus PDV», no con el nombre del país. El del país entero mostraría la plata de PDV que no puede ver.
  • El alcance es completo cuando el usuario ve TODOS los PDV del país que tienen alguna caja, aunque esté de baja (su historia suma en el ledger, y el total del país la incluye), con la misma pregunta que decide los saldos de las tarjetas: caja:read sobre el PDV y fondeo_caja:read en una asignación que lo cubra (canSeeAllCashBoxes, ADR-021 §4). Se pregunta por PDV con permisos, no mirando qué tarjetas salieron: un PDV de baja que el usuario sí cubre no tiene tarjeta y no por eso lo deja afuera. Un Supervisor del PDV A que además es Cajero del B tiene el alcance parcial.
  • La ve quien ya ve totales-pdv (fondeo_caja:read: Supervisor, Tesorería y Admin). Un país sin cajas visibles no tiene línea.
  • En la pantalla va arriba de las tarjetas por PDV, una franja por país: «Guatemala · USD 24,878.53», con el formato de moneda de toda la app. Con el alcance parcial el rótulo es «Total de tus PDV» y, si hay más de un país, «Total de tus PDV en Guatemala» (dos líneas con el mismo rótulo no se podrían distinguir). Al bajar a las cajas de un PDV la línea no se muestra: es de la pantalla de totales.

Lo que NO cambia (y por qué queda escrito) ​

  • Ningún saldo. Se deriva del ledger, hoy y mañana (ADR-005, ADR-007). distributedInCashBoxes, los extractos, Cierres por día y el Dashboard leen el mismo ledger que antes.
  • pay(), fondeo y ajuste no miran operable. Los tres exigen una sesión abierta, y una caja que no es operable no puede abrirse ni (con las reglas de §3 y §5: la baja de la caja, la de su PDV, el cambio de país del PDV y el apagado del módulo se rechazan con una sesión abierta) tener una abierta al dejar de serlo. No hace falta un segundo control para lo que se haga de ahora en más: una caja que ya estaba abierta cuando su PDV se desactivó, o su país apagó el módulo, antes de este deploy sí puede seguir pagando sin que su operador la vea; ver la nota «Neutral» de «Consequences».
  • La matriz de permisos. Ninguna celda cambia: no hay una migración de datos de permisos, así que ningún permiso de usuarios reales de Staging cambia con esta entrega. El único cambio de datos es la columna con su default true.
  • El cierre de una caja que no es operable sigue andando. cierre() no mira operable: una caja con sesión abierta siempre se puede cerrar.

Alternatives Considered ​

  • (b) Permitir desactivar con saldo: la caja queda inactiva con su plata, que sigue sumando en los totales del PDV y los extractos, marcada. Descartada por ahora (D3-14 a): deja plata en una caja que nadie puede operar, y obliga a que el total del PDV de Saldos incluya cajas que Saldos no muestra. Si el cliente la prefiere (QC-16), es la alternativa.
  • (c) Permitir y ignorar el saldo. Rompe la conciliación con el extracto del PDV de B7. Descartada.
  • Dejar que Saldos siga mostrando las cajas no operables con plata o con sesión abierta (la otra solución a que desactivar un PDV las esconda). Descartada: parte en dos la definición de «operable» (§2), que es justamente lo que G7.3 pidió evitar. Se rechaza la causa (§5), no se compensa el efecto en el listado.
  • Cascadear la baja del PDV a sus cajas. Reactivar el PDV tendría que saber cuáles de sus cajas estaban de baja antes y cuáles se desactivaron con él. Con dos banderas independientes no hace falta saberlo.
  • Un módulo de permiso propio (abm_cajas). No hay un perfil que lo pida: agregar, desactivar y reactivar quedan en abm_estaciones (solo Admin). Es una celda de la matriz si piden otro (P3-15).
  • Agregar el motivo con una migración de datos. El catálogo no es una tabla: no hay filas que sembrar.
  • Una línea de país con availableToDistribute (QC-15 b/c). Se implementa el total de las cajas, que es lo que el cliente dibujó; la segunda cifra queda descripta arriba por si contestan.

Consequences ​

  • Positive: el panel de Estaciones puede dar de baja una caja sin perder su historia, y Saldos y la apertura dejan de ofrecer cajas que no existen para operar. Un solo scope decide las dos cosas.
  • Positive: los tres huecos de H3-06 quedan cerrados con sus 422 y su 409, cada uno con su test.
  • Positive: la línea de país coincide por construcción con «Distribuido en cajas» y no le muestra a nadie plata que no puede ver.
  • Negative, y es el costo de D3-14 (a): dar de baja una caja con plata son cuatro pasos (abrir, retirar, cerrar, desactivar) y los hace gente distinta (un Cajero, un Supervisor o un Admin abre; Tesorería o un Admin ajusta). Es lo que pidió Carlos: que quede traza.
  • Negative, un callejón sin salida que hay que conocer: el ajuste escribe siempre en la moneda de pago vigente del país. Una caja que conserva efectivo en una moneda anterior (el país cambió de moneda) no se puede dejar en cero con «Retiro por baja de caja» y, por lo tanto, tampoco desactivar. Hoy ningún país cambió de moneda; si pasa, se resuelve con una entrega aparte (ajuste con moneda explícita), no con un atajo en el control.
  • Neutral, una nota de deploy: una caja que ya estaba abierta en un PDV que se desactivó antes de este cambio (hasta ahora se podía) deja de aparecer en Saldos del operador, porque su PDV no es operable, y no hay cómo cerrarla desde la pantalla. La destraba un Admin reactivando el PDV. A partir de ahora el 409 STATION_HAS_OPEN_CASH_BOX impide crearlas. Lo mismo vale, por las otras dos vías, para una caja abierta en un país con el módulo Caja apagado y para plata en las cajas de un PDV inactivo o de un país sin módulo (la franja de país va a ser mayor que la suma de las tarjetas): la destraba reactivar el PDV o el módulo. Mirar antes de desplegar a Staging si existe alguna (las tres consultas están en el plan de pruebas).
  • Neutral: scope_complete es conservador: cuenta también los PDV con cajas de baja. Un Supervisor que cubre todos los PDV vivos de su país pero no uno de baja ve «Total de tus PDV». Es un rótulo, nunca un monto de más.

Si se revierte ​

A «una caja existe para siempre»: sacar el scope de scopedCashBoxes() y el control de apertura(), y el PATCH. La columna puede quedar (default true, inofensiva) o salir con el down() de la migración, que solo la borra.

A permitir desactivar con saldo (alternativa b): sacar el 409 CASH_BOX_HAS_BALANCE del PATCH y hacer que el total del PDV de Saldos sume también las cajas de baja (balanceForStation ya lo hace, porque lee el ledger); el motivo «Retiro por baja de caja» puede quedar: informa sin restringir.

A solo avisar al desactivar un PDV, mudarlo o apagar el módulo: sacar el control de StationController::update y de CountryController::update (bloqueoParaDejarSinOperar); lo demás de la revisión no depende de eso.

Sacar el motivo: quitarlo de CashMovement::MOTIVOS_AJUSTE no afecta a los movimientos ya cargados (el filtro por motivo acepta cualquier string y el historial muestra el texto guardado).

Pruebas que lo fijan ​

  • StationApiTest: el PATCH (permiso, activar y desactivar con su auditoría sin montos, sesión abierta, saldo, residuo en otra moneda, caja de otro PDV con su code, idempotencia, el número que no se reutiliza), agregarCaja en un país sin módulo y en un PDV inactivo (código y texto), desactivar un PDV o mudarlo de país con una caja abierta o con plata (también la de otra moneda; sin montos en el texto), que un PDV ya inactivo o de un país sin módulo no se frene, que el lock va antes de mirar sesiones o saldo, mover un PDV a un país con módulo Caja, el listado con active y opened_by, y los tests de serialización del PATCH (el lock va primero; mira las sesiones al decidir; la decisión es la de la caja bloqueada, para desactivar y para reactivar).
  • CountryApiTest: apagar el módulo Caja con una caja abierta o con plata (también la de otra moneda), con las cajas en cero, sin que lo frene un PDV inactivo.
  • PerfilesAccesoApiTest: el listado del panel, el alta y la baja de una caja dan 403 a Cajero, Supervisor y Tesorería y funcionan para el Admin.
  • CashBoxApiTest: disponibles y totales-pdv sin cajas inactivas, de un PDV inactivo ni de un país sin módulo; total_cash_boxes; la apertura de una caja inactiva (422, con el texto de cada una de las tres razones) y su test de carrera; el scope y la razón del rechazo cruzados en las ocho combinaciones; el motivo nuevo (catálogo, signo, no es de fondeo, filtro del historial); el flujo completo de la baja de una caja con plata; y el bloque countries[] (coincide con distributedInCashBoxes y con las tarjetas, alcance parcial, perfiles mezclados, nunca suma entre países ni monedas).
  • CajaReportesApiTest: el resumen incluye la caja inactiva con su marca y el export la rotula «Inactiva»; Cierres por día, el detalle, el PDF y distributedInCashBoxes siguen viendo la caja de baja.
  • Frontend: EstacionesView.spec.ts (la celda «N cajas · Administrar», el panel con sus estados y quién la tiene abierta, la confirmación, los 409 con los pasos para dejarla en cero, el alta desde el panel y desde la celda, y desactivar un PDV con una caja abierta), cajasEstacion.spec.ts (el resumen de la celda y la traducción de cada rechazo), CajasView.spec.ts de Reportes («Inactiva») y CajaView.spec.ts (la línea de país: el rótulo completo y parcial, varios países sin sumar monedas, y que no se dibuje sin países ni para quien no ve totales).

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