ADR-021: Quién cierra una caja ajena
Date: 2026-10-06 Status: Accepted — decisiones D3-12 (B) y D3-13 (i) de Carlos (2026-10-05), implementadas el 2026-10-06 en la entrega G6.A y G6.B del plan de ajustes v3 (backend: G6.A1, G6.A2, G6.B1, G6.B2 y G6.B4; frontend: G6.A3, G6.B3 y el aviso de la baja de G6.B4). Dónde está explicado para quien opera y para quien analiza: el manual y el análisis funcional de Caja (flujos 2.1, 2.2 y 2.10, secuencia 3.6 y regla R20); el plan de prueba manual está en doc/qa. Supersedes in part: ADR-013 §5 — «el cierre no exige ser quien abrió» deja de valer. Todo lo demás de ADR-013 sigue vigente (el bloqueo en línea, el «día» de America/Guatemala, el aviso de la caja vencida, el reporte de Cierres por día). Extends: ADR-007 §5b (una sola caja abierta por usuario) y ADR-014 §6 (qué ve cada perfil de las cajas).
Context
Magaly (CIS-EC, 2026-10-02) pidió en tres líneas de la hoja de ajustes v2 que cada caja tenga un solo operador y que el sistema lo muestre:
- RV3-25. «El mismo operador que abre una caja debe ser el único autorizado a cerrarla»: hasta hoy un segundo usuario podía cerrar la caja abierta por otro. Es lo que ADR-013 §5 había decidido a propósito (si el cajero no vino, un compañero destraba la caja vencida) y lo que fijaba un test: «si algún día se agrega "solo cierra quien abrió", la caja vencida de un cajero ausente queda sin salida».
- RV3-26. «Si una caja está abierta, no puede abrirla otro usuario, para que no se crucen los saldos.» Eso ya estaba impedido (409
CASH_ALREADY_OPENy el índice único parcialcash_sessions_one_open_per_box). El cruce que sí era posible pasa por RV3-25: B cierra la caja de A y la abre él. A, que sigue creyendo que tiene su caja, recibeNO_CASH_BOX_OPEN_FOR_USERal pagar. - RV3-27. «Incluir el usuario en la caja, para saber quién opera en cada una»: el dato está en la sesión, pero la API de
GET /caja/disponiblestraía soloopened_by_user_id, sin el mail, y la tarjeta no lo mostraba.
La regla literal de RV3-25 («solo quien abrió») tiene un costo que el propio ADR-013 vio: la caja vencida de un cajero que no vino, se fue o fue dado de baja queda trabada (no paga, no fondea, no ajusta) y el índice cash_sessions_one_open_per_user le impide a esa persona abrir otra. Hace falta una salida y decidir quién la tiene (D3-12). Además, con perfiles mezclados (D3-T2: la unión de permisos de todas las asignaciones de una persona, sin selector de perfil) «el Supervisor» no se puede decidir mirando el país entero: ver P3-2.
Aparte, al revisar RV3-24 («Supervisor y Tesorería ven el saldo de todos los cajeros y PDV») apareció un hallazgo del mismo mecanismo, H3-03: canSeeBalance decidía por país y no por PDV. Un Supervisor del PDV A que además es Cajero del PDV B veía el saldo y los movimientos reales de las cajas de B, porque sumaba el fondeo_caja:read de una asignación y el alcance de caja:read de la otra. Se reprodujo con un test antes de corregirlo.
Decision
1. Cierra quien abrió, o un Supervisor o un Admin del PDV de la caja (D3-12 B)
cierre() devuelve 403 CASH_CLOSE_NOT_OWNER («Esta caja la abrió otra persona. Solo quien la abrió, un Supervisor o un Admin pueden cerrarla.») salvo que PermissionService::canCloseCashSession($user, $session) diga que sí: (1) quien abrió la sesión, o (2) quien tenga, dentro de UNA misma asignación que cubra el PDV de la caja, apertura_cierre_caja:write y fondeo_caja:read. Nadie más: ni otro Cajero del PDV, ni Tesorería (no tiene apertura_cierre_caja).
El control va después de encontrar la sesión y antes del control de documentos pendientes (ADR-013 §4, A6.3). Es deliberado: quien no es dueño ni supervisa no tiene por qué enterarse de qué pagos de otro tienen documentos sin subir. Para quien sí puede cerrar, el bloqueo por documentos rige igual que siempre: el Supervisor que cierra una caja ajena sigue frenado por PENDING_PAYMENT_DOCUMENTS y puede subir los soportes que faltan (ADR-011 §4) para destrabarla.
Que la persona pueda cerrar cajas en general (apertura_cierre_caja:write sobre ese PDV) lo siguen validando, antes, el middleware de la ruta y authorizeStationScope. canCloseCashSession responde solo la pregunta del dueño; por eso quien abrió la sesión pasa aunque hoy no tenga asignaciones, y lo que le cierra el paso en ese caso es el middleware. El can_close que viaja a la pantalla (§3) junta las dos preguntas, para que el botón no se ofrezca donde la ruta va a responder 403.
2. La capacidad se deriva de permisos existentes, sin tocar la matriz (D3-13 i)
No hay una celda «cerrar cajas ajenas»: apertura_cierre_caja:write más fondeo_caja:read en la misma asignación es exactamente lo que distingue al Supervisor y al Admin del Cajero (ADR-014), y reusa el patrón de isSupervisorTier y de los soportes de G5. Nada cambia en RoleSeeder::MATRIX ni en matriz-de-perfiles.json, así que ningún permiso de usuarios reales de Staging cambia con esta entrega.
La regla vive en PermissionService::assignmentHolds() (P3-2, creado por G5): una asignación del país que reúna las capacidades y cubra el PDV. Es lo que evita que alguien se vuelva supervisor por sumar asignaciones:
| Combinación | Cierra la caja que abrió otro en el PDV A | Por qué |
|---|---|---|
| Cajero de A | No | Tiene apertura_cierre_caja pero no fondeo_caja:read |
| Supervisor de A | Sí | Reúne las dos en una asignación que cubre A |
| Supervisor de B | No | No cubre A (el alcance por PDV lo corta antes: 403 PERMISSION_DENIED) |
| Cajero de A y Supervisor de B | No | Junta las dos capacidades, pero la que supervisa es la de B |
| Cajero (de A) y Tesorería (del país) | No | Una asignación tiene la apertura y la otra tiene fondeo_caja:read |
| Admin | Sí | Una asignación sin acotar con las dos |
«Es supervisor» no tiene una definición única en el sistema: cada uso declara las capacidades que le importan (los soportes, las dos de SUPERVISOR_DE_SOPORTES; los saldos, fondeo_caja:read; el cierre ajeno, las dos de arriba).
3. Lo que expone el backend (el front solo refleja, ADR-013 §6)
GET /caja/disponiblessuma a lasession:opened_by({id, email}: la tarjeta dice a quién pedirle que libere la caja) ycan_close(las dos preguntas que hacecierre(), en el mismo orden:apertura_cierre_caja:writesobre el PDV de la caja, y la regla del dueño decanCloseCashSession; así la pantalla no ofrece «Cerrar caja» donde el backend va a rechazar, tampoco a quien abrió la caja y hoy ya no tiene el permiso sobre ese PDV). Viajan también con el saldo oculto: saber quién la tiene no abre la plata. El mail es visible para todos los que ven la lista de cajas del PDV (QC-14, valor por defecto hasta que el cliente confirme).opened_by_supervisor_iddeja de viajar (endisponiblesy en la respuesta de la apertura): desde E4b.1 la apertura no lleva Supervisor y la columna es siemprenull. Se oculta en el modelo (CashSession::$hidden); la columna y las sesiones históricas quedan como están.- 409
CASH_ALREADY_OPENdice quién la tiene («La Caja 1 de Mixco Plaza la tiene abiertamail.»; si es la tuya, «Ya tenés abierta la Caja 1 de Mixco Plaza.»). Trae tambiénopened_by. La sesión del primero no se toca: el rechazo ocurre antes de escribir nada. - La auditoría de
CASH_SESSION_CLOSEDsumacierre_ajeno(booleano: cerró alguien que no abrió la sesión), junto afrom_previous_dayyopened_by_user_idde ADR-013 §5. Un booleano: ningún dato personal ni monto nuevos. La pantalla de Auditoría la rotula «Cierre de caja» (está en el filtro de acciones, así que el Admin puede listar los cierres del período) y su detalle dice si la caja la abrió otra persona, sin mostrar el saldo final que la metadata también guarda. - 409
USER_ALREADY_HAS_OPEN_CASH_BOX(una sola caja abierta por usuario, ADR-007 §5b): si quien intenta abrir otra ya no tieneapertura_cierre_caja:writesobre el PDV de la caja que dejó abierta (le cambiaron la asignación), el mensaje deja de decirle «cerrala»: le dice que la cierra un Supervisor o un Admin de ese PDV. - Aviso al dar de baja a un usuario que tiene una caja abierta (G6.B4): la respuesta de
PUT /admin/usuarios/{id}sumawarning(USER_HAS_OPEN_CASH_BOX, con las cajas y a quién le toca cerrarlas). No frena la baja (el usuario igual se va) y no cierra nada; solo en la baja (activo a inactivo), no cada vez que se edita al usuario.
4. Los saldos se ven por PDV, no por país (G6.A2, H3-03)
PermissionService::canSeeAllCashBoxes($user, $countryId, $stationId) pasa a mirar assignmentHolds con fondeo_caja:read y el PDV de la caja (antes: allows() sobre el país). canSeeBalance (saldo, historial y reporte de una caja) usa el PDV de la caja, y GET /caja/totales-pdv cruza el alcance de caja:read (que arma el universo de cajas) con el PDV de cada caja en fondeo_caja:read. El Supervisor del PDV A que es Cajero del PDV B ve el saldo real de A, balance: null en B, el historial de B da 403 CASH_BOX_BALANCE_HIDDEN y los totales por PDV traen solo A. Quien tiene Tesorería sobre el país entero sigue viendo todo (regresión probada).
5. La sesión y su operador se traen de a muchas cajas (H3-12)
CashBox::currentSession() es la sesión OPEN como relación (hasOne, con chaperone para que la sesión conozca su caja y su PDV sin consultas extra). scopedCashBoxes() la precarga junto con el operador (currentSession.openedBy:id,email) y CashBox::openSession() usa lo precargado si está. Antes disponibles, totales-pdv y el resumen del reporte de Cajas consultaban la sesión una vez por caja, y cada PDV puede sumar cajas desde el ABM. Un test por pantalla cuenta las consultas: disponibles (sesiones y operadores, y que cajas, PDV y sesiones no crezcan al pasar de 2 a 6 cajas, que es lo que prueba que can_close no dispara lazy-loads), totales-pdv y el resumen de Reportes → Cajas. totales-pdv precarga la sesión pero no el operador: no lo usa.
6. La pantalla (G6.A3, G6.B3 y la revisión)
- Perfiles mezclados.
GET /caja/totales-pdvsolo trae los PDV donde el usuario tienefondeo_caja:read(§4), pero la pantalla decide si mostrar los totales con la unión de sus permisos. Un Supervisor de A que es Cajero de B entraba por los totales y no tenía ninguna entrada a las cajas de B. Ahora las cajas dedisponiblesque ningún total alcanza se ofrecen aparte («Otras cajas a tu alcance», con las mismas tarjetas que el selector, sin saldo). No se arregló sumando esos PDV atotales-pdv: reabriría la fuga de H3-03. Si los totales fallan, todas las cajas se ofrecen así, para no dejar al operador sin salida. - El aviso de una caja vencida ajena. A quien mira una caja vencida que abrió otra persona el aviso no le habla como a su dueño («cerrala y abrila de nuevo», sus pagos pendientes): dice de quién es y, si puede cerrarla (Supervisor o Admin), que al cerrarla el saldo se mantiene y esa persona la abre de nuevo; si no puede (Cajero, Tesorería), a quién pedírselo. Que la reabra el que la cerró, a su nombre, es el cruce de saldos que G6 evita.
- El detalle de una caja ajena (403
CASH_BOX_BALANCE_HIDDEN) se dice («No podés ver el detalle de esta caja: solo se ve el de la que tenés abierta») en vez de mostrar «Sin movimientos todavía» y los botones de reporte. - Cerrar una caja que otro ya cerró (409
CASH_NOT_OPEN): con G6 dos personas pueden cerrar la misma, y la pantalla se pone al día igual que con el 403CASH_CLOSE_NOT_OWNER.
Lo que NO cambia (y por qué queda escrito)
- La respuesta del cierre ya no oculta el saldo (ADR-013 §5, primera precisión, que ocultaba el saldo a quien cerraba la caja de un compañero sin
fondeo_caja:read). Como ahora solo cierran el dueño, el Supervisor y el Admin, y los tres ven ese saldo porcanSeeBalance, la rama que lo ocultaba era inalcanzable y sin test: se sacó en la revisión de G6. Si se abre la regla del cierre (variante C), hay que restituirla, con su test, en el mismo cambio. - El cierre tardío sigue marcado en la auditoría (
from_previous_day,opened_by_user_id): ahora ademáscierre_ajeno. pay()de quien perdió la caja: a quien le cierran la cajapay()le respondeNO_CASH_BOX_OPEN_FOR_USER. Es el mensaje de siempre, y ahora es una consecuencia explícita y auditada de que un Supervisor o un Admin la cerró. La vuelve a abrir (hereda el saldo, ADR-007 §5) y sigue.- El resto de los permisos: una persona con
apertura_cierre_caja:writepuede abrir y cerrar su caja como siempre. - No se agrega ningún permiso a la matriz (ver arriba): una evolución posible es la celda explícita (alternativa ii).
Alternatives Considered
- (A) Estricto: solo quien abrió, más el Admin como escape. Deja a un Supervisor sin poder destrabar la caja de su propio PDV (el caso de todos los días: un cajero que se va sin cerrar) y lo manda a pedirle ayuda a un Admin global. Descartado.
- (C) Como (B), y además cualquier operador del PDV cuando la sesión está vencida. Es el comportamiento anterior limitado al caso trabado, y destraba PDV sin Supervisor. Se descartó por ahora porque el cliente pidió justamente que un compañero no toque la caja de otro (RV3-25) y la pregunta QC-12 («¿hay PDV sin Supervisor?») sigue sin respuesta. Si la respuesta es que sí, es el siguiente paso y es chico: en
canCloseCashSession, devolver tambiéntruesi$session->isFromPreviousDay()y el usuario tieneapertura_cierre_caja:writesobre el PDV (se vuelve a abrir el hueco de ADR-013 §5, pero solo para la vencida). - (ii) Una celda explícita (
apertura_cierre_caja:delete= cerrar cajas ajenas), editable desde Roles, con migración de datos para el Supervisor. Más configurable, pero cambia permisos de usuarios reales de Staging con el deploy y obliga a mantener la celda enRoleSeeder::MATRIX, enmatriz-de-perfiles.jsony en la migración. Queda como evolución si quieren configurarlo por perfil. - Decidir «es supervisor» sobre la unión de asignaciones (la forma anterior de
canSeeAllCashBoxes): es exactamente el hallazgo H3-03 y deja que un Cajero que suma Tesorería se eleve a supervisor por la plata que mueve Tesorería. Descartado (P3-2).
Consequences
- Positive: a cada caja se le sabe el operador (RV3-27) y nadie puede cerrársela sin que quede registrado y por una de las tres personas previstas. Se cierra el cruce de saldos de RV3-26.
- Positive: una sola función decide el cierre ajeno y la usan el 403 y el
can_closede la pantalla; no hay un segundo criterio. - Positive: se corrige una fuga de saldos real (H3-03) que solo aparecía con perfiles mezclados.
- Negative, y es el riesgo operativo de esta decisión: un PDV sin Supervisor con un cajero que se va sin cerrar deja la caja trabada hasta que un Admin la cierre. La mitigación es que el Admin siempre puede; la variante (C) queda lista si el cliente dice que es un caso real (QC-12).
- Negative: los operadores que hoy dependen de que un compañero les cierre la caja tienen que pedírselo a un Supervisor o a un Admin. Hay que avisarlo antes del deploy.
- Neutral, y es una nota de deploy: la regla rige desde el deploy. Las cajas que estén abiertas ese día solo las cierran quien las abrió, un Supervisor o un Admin; las vencidas de una prueba de QA con otro usuario se cierran con un Supervisor o el Admin. No hay migración ni cambio de permisos.
- Neutral:
opened_by_supervisor_iddeja de salir en la API; el campo del frontend (services/caja.ts) se quita en el mismo PR. - Abierto (pregunta #22, ver el análisis funcional de Caja): el aviso a quien hace el cambio solo existe en la baja de un usuario (G6.B4). Cambiarle o quitarle la asignación a un Cajero que tiene una caja abierta no avisa nada: esa caja deja de aparecer en su pantalla y solo la cierra un Supervisor o un Admin del PDV. Lo único que hace el sistema es que el 409 al abrir otra le diga a quién pedírsela (§3). Un aviso en la pantalla de asignaciones es una ampliación de G6 que no se hizo.
Si se revierte
A «cierra cualquiera con apertura_cierre_caja:write» (ADR-013 §5): sacar el control de canCloseCashSession en cierre() (el 403 CASH_CLOSE_NOT_OWNER); can_close pasa a true para quien tenga ese permiso. cierre_ajeno y opened_by pueden quedar: informan sin restringir. El test que se reescribió (test_un_companero_cajero_no_cierra_la_caja_vencida_de_otro) vuelve a su versión anterior (un compañero la cierra) y los de PerfilesAccesoApiTest cambian el esperado del Cajero a 200.
A la variante (C) (cualquier operador del PDV cierra la vencida): además de lo de arriba, restituir en cierre() el ocultamiento del saldo en la respuesta para quien cierra sin poder verlo, con el test que existía (quien cierra la caja de un compañero sin fondeo_caja:read recibe opening_balance y closing_balance en null).
A la celda explícita (ii): canCloseCashSession lee la celda en vez de CIERRA_CAJAS_AJENAS; hace falta la migración de datos (RolePermission::withoutEvents) y actualizar RoleSeeder::MATRIX y matriz-de-perfiles.json en el mismo commit.
Pruebas que lo fijan
CashBoxApiTest: el cierre ajeno por perfil (dueño, otro Cajero, Supervisor del PDV, Supervisor de otro PDV con suPERMISSION_DENIED, Cajero de este PDV que supervisa otro, Cajero con Tesorería, Tesorería sola, Admin); el 403 antes de los documentos pendientes; el cierre ajeno del Supervisor frenado porPENDING_PAYMENT_DOCUMENTS; la caja vencida de un cajero (el compañero 403, el Supervisor 200); el pago de quien perdió la caja;can_closepor perfil y para quien abrió la caja y ya no puede operarla;opened_by; el 409 con quién la tiene, también cuando lo decide el índice único (la carrera de dos aperturas, con y sin la sesión ganadora a la vista); el 409 de abrir otra a quien ya no puede cerrar la suya; el conteo de consultas dedisponiblesytotales-pdv; el caso de H3-03 y su regresión con Tesorería.CajaReportesApiTest: el resumen trae las sesiones abiertas en una consulta sin importar cuántas cajas hay.PerfilesAccesoApiTest: la filaPOST /caja/{abierta por otro}/cierre(Cajero 403, Supervisor 200, Tesorería 403, Admin 200, sobre una caja aparte) y el Supervisor de un PDV que es Cajero de otro, con los roles reales deRoleSeeder.PermissionServiceCajaTest:canSeeAllCashBoxesycanCloseCashSessionsolos, incluida la regla de la misma asignación.UserApiTest: el aviso de la baja con una caja abierta (y que no se repite).- Frontend:
CajaView.spec.ts(perfiles mezclados, el aviso según quién mira, el 409CASH_NOT_OPEN, el detalle oculto y las anclas del recorrido guiado),AvisoCajaVencida.spec.tsyAuditoriaView.spec.ts(el cierre de caja).

