Skip to content

Ambiente: Staging ​

Status: 🟢 Aplicado y en uso — en AWS, con deploys automáticos andando. Última actualización: 2026-10-07 (G9: cómo cargar los tres PDV reales de Guatemala por la pantalla, por qué StationSeeder los pisa y cómo apagar el prefijo «C-» del MTCN en Cumplimiento; antes, el mismo día, G8: el tipo de cambio sale del Cajero y del Supervisor — migración que cambia permisos de usuarios reales, avisar antes; antes, 2026-10-06, G1: soportes de pago en un bucket S3 privado — runbook de despliegue, prueba de humo de subida y documentos:verificar; antes, 2026-10-05: plan de alineación de la API C2P al contrato de Soterex — pasos de despliegue, notifications:retry y estados del outbox; decisiones de Carlos del mismo día: tarifario provisional de 50 USD fijos también en producción y scheduler apagado hasta que Soterex mande la URL y el secret; antes, 2026-10-02: B6, cuatro perfiles, y quién hace tesorería pierde accesos hasta que se le asigne Tesorería; y B3, las cajas abiertas de días anteriores quedan vencidas)

Esta página estuvo mal durante diez días. Decía "nada de esto está creado todavía" con Staging ya arriba y ocho deploys exitosos encima. Se corrigió el 2026-08-07. Si estás por creerle a un documento de ambientes, cruzalo contra gh run list --workflow=deploy-staging.yml.

Dónde vive ​

AWS, la infraestructura de infra/terraform/environments/staging/: ECS Fargate (servicio web

  • servicio queue, este último en desired_count = 0 desde el plan de reducción de costos AWS del 2026-09-21 — ver más abajo), Aurora PostgreSQL Serverless v2 con auto-pause, ALB con WAFv2 adelante, secretos en Secrets Manager. Los soportes de pago van a un bucket S3 privado (ADR-019), pero el bucket existe recién cuando Carlos corre el apply y el deploy siguiente (runbook de G1): hasta entonces esos archivos siguen en el disco del contenedor y se pierden en cada deploy. Sin ElastiCache (se sacó en el mismo plan: cache y colas usan Postgres/sync en vez de Redis). El frontend y las dos documentaciones van a Firebase Hosting, que es independiente del cloud del backend.

Hubo un ADR para migrar todo esto a Azure (ADR-006). Se frenó el 2026-08-07: seguimos en AWS. El Terraform de Azure quedó escrito y sin mergear en el branch feature/migracion-azure, por si el pedido vuelve.

URLs ​

ComponenteURL
Web app principalhttps://soterex.stag.cislatam.net
Backend / APIhttps://api.soterex.stag.cislatam.net
Documentación funcional (VitePress)https://docs.soterex.stag.cislatam.net
Referencia de API (Scalar)https://docs.api.soterex.stag.cislatam.net

Cómo se deploya ​

Push al branch staging. Nada más. .github/workflows/deploy-staging.yml se dispara solo y corre cuatro jobs en paralelo: frontend, documentación funcional, referencia de API, y backend.

El de backend es el que importa: construye la imagen, la sube a ECR taggeada con el SHA, registra la revisión nueva de la task definition, corre las migraciones como un RunTask puntual antes de tocar el servicio (si fallan, el deploy se corta y el servicio viejo sigue sirviendo), y recién después actualiza web y queue. Un deploy completo tarda entre 8 y 22 minutos.

La base se pausa y el RunTask de migraciones espera a que despierte. Aurora de Staging es Serverless v2 con auto-pause (15 min sin uso). Con la base dormida, la primera conexión vence el timeout de PDO (30 s) y migrate moría en su primer query (SQLSTATE[08006] … timeout expired): el 2026-10-04 el deploy de B6/B7 se cortó así, sin migrar nada. Por eso el comando del RunTask no es php artisan migrate --force sino backend/docker/migrar-esperando-la-base.sh: lo corre y, solo si el error es de conexión (SQLSTATE[08…]), espera 15 s y reintenta, hasta 8 intentos o 300 s desde que arranca el script (lo que ocurra primero), por debajo de los 10 minutos que espera aws ecs wait tasks-stopped (el arranque de Fargate y las migraciones largas también cuentan). Corta al primer intento: un error real de migración, y los errores de conexión que no se arreglan esperando (contraseña mala, base inexistente, falta de regla en pg_hba.conf; PDO los etiqueta igual SQLSTATE[08006]). La salida de migrate sigue llegando en vivo a CloudWatch. Reintentar es seguro porque las migraciones de este repo tienen que ser idempotentes (las de datos "crean lo que falta y no pisan"; las de esquema chequean hasColumn / hasIndex): el único hueco teórico es una caída entre el COMMIT de una migración y el INSERT que la registra.

Si el deploy igual falla por la base: abrir la app e iniciar sesión (despierta Aurora) y reintentar con "Re-run failed jobs", verificando antes que la tarea de migración anterior esté STOPPED (si el waiter de 10 minutos venció, la tarea de ECS puede seguir viva y un segundo RunTask correría en paralelo). Producción no lo necesita: su Aurora no es serverless.

No hay terraform apply en el pipeline: Terraform gestiona la infraestructura, el pipeline gestiona qué imagen corre. Son dos cosas separadas a propósito. Para cambios de infraestructura están terraform-plan.yml y terraform-apply.yml.

⚠️ Esa separación no estaba realmente implementada, y rompió Staging el 2026-08-10. Los servicios de ECS no tenían ignore_changes = [task_definition], así que un terraform apply que venía a agregar un VPC endpoint —nada que ver con ECS— registró revisiones nuevas apuntando a :initial, el tag que solo existió antes del primer deploy, y apuntó los servicios ahí. Las tasks no pueden bajar esa imagen.

Corregido y aplicado el 2026-08-10: ignore_changes = [task_definition] para que no vuelva a pasar, y deployment_circuit_breaker con rollback para que, si pasa cualquier otra cosa, ECS vuelva solo a la última revisión buena en vez de reintentar en silencio.

El apply que lo trajo sirve además como prueba de que funciona: mostró 0 to add, 2 to change, 0 to destroy —los dos servicios, sólo el circuit breaker— y ni una línea sobre task definitions, sobre exactamente la misma infraestructura que unas horas antes había arrasado con las dos.

Los datos de referencia llegan con el deploy ​

El deploy corre migrate --force y nada más: no corre seeders. Hasta el 2026-10-01 eso dejaba afuera todo dato de referencia que viviera solo en un seeder. Le pasó a A4: la fila de permiso abm_catalogos y los catálogos base (tipos de identificación, departamentos, municipios) existían únicamente en RoleSeeder y en los Catalog*Seeder, así que Staging tuvo A4 desplegado unas 40 horas con la pestaña Catálogos inaccesible y el desplegable "Tipo de identificación" vacío —y con ese desplegable vacío no se puede pagar— hasta que alguien corrió db:seed a mano.

Desde B1.2 (doc/plans/2026-10-01-ajustes-v2-cliente-gt.md) esos datos viajan por migración de datos: 2026_10_01_100000_b1_datos_de_referencia_y_permiso_abm_catalogos.php. En una base que ya tiene roles deja la fila de permiso abm_catalogos (Admin lectura/escritura/borrado; el resto de los roles en 0); si además tiene países, deja los catálogos:

  • los 249 países ISO (desde G10, 251 y con los nombres del cliente: ver «Antes y después del deploy de G10 y G11»), los 22 departamentos y 338 municipios de Guatemala (cada municipio colgado de su departamento) y los tipos de identificación DPI y PASAPORTE de Guatemala (desde G11, con su formato).

Los municipios son una lista de trabajo sin cotejar con INE/RENAP (suma 338, no los 340 oficiales): Cumplimiento no mandó las listas de departamentos y municipios (QC-29), así que se ajustan desde la pantalla Catálogos cuando las mande.

Lo que hay que saber de cómo se comporta:

  • Crea lo que falta y no pisa lo que existe. Un ítem que el Admin editó o desactivó queda como está; una fila de permiso editada desde la app, también. Los ítems de catálogo no se borran, se desactivan, y un deploy no puede deshacer eso. El límite: cada ítem se reconoce por su code, así que si el Admin le cambió el código a un ítem base (el ABM lo permite), la migración vuelve a crear el original al lado y deja el editado como está. Se resuelve desactivando el sobrante.
  • Deja rastro en Auditoría de cada permiso que otorga: un evento ROLE_PERMISSION_GRANTED_BY_MIGRATION por fila, sin usuario (lo otorgó el deploy), con rol, módulo y marcas. Las filas en 0/0/0 no otorgan nada y no se registran.
  • Es idempotente. Correrla otra vez no cambia nada. Sobre una base con roles y países tarda alrededor de 100 ms.
  • Salta lo que no puede ubicar (sin roles, sin países, sin el país GT) y no falla. Nunca crea roles ni el país Guatemala: eso es de RoleSeeder y CountrySeeder.
  • Escribe role_permissions sin disparar los eventos del modelo (el hook saving fuerza can_delete ⇒ can_write ⇒ can_read y ya rompió la pantalla Pago una vez).
  • No tiene down() a propósito: borrar ítems rompería las transacciones que ya guardaron su código.

Ya no hay que correr db:seed después de un deploy. Tampoco conviene, y lo más serio no son los catálogos: RoleSeeder usa updateOrCreate sobre cada celda de role_permissions, así que un db:seed completo revierte la matriz de permisos a la del seeder y deshace cualquier permiso que un Admin haya editado desde la app, una revocación incluida. Los seeders de catálogo hacen lo mismo con las etiquetas y el estado de los ítems. db:seed sigue siendo el camino de desarrollo y de las bases nuevas (ver dev.md); sobre una base que ya tiene roles, no.

StationSeeder también pisa lo que un Admin cargó a mano. Usa updateOrCreate por internal_code y reescribe nombre, dirección, ubicación y estado active de GT-CAP-001, GT-QUE-002, GT-MIX-003 y GT-ESC-004: correrlo a mano en Staging —solo o dentro de un db:seed completo— revierte los datos reales de un PDV a los de fixture. No lo corras sobre una base donde ya se cargaron los puntos de venta reales.

Para el próximo módulo nuevo en la matriz de permisos, o el próximo ítem de catálogo, el camino es otra migración de datos con los helpers de backend/app/Support/DataMigrations/ (EnsureRolePermissions, EnsureCatalogItems). Agregarlo a RoleSeeder::MATRIX o a backend/database/data/*.php no alcanza: las bases que ya corrieron la migración no lo reciben.

Cargar los tres puntos de venta reales de Guatemala (G9.7, D3-17) ​

  • Estado: sin ejecutar (2026-10-07). Es un procedimiento para un Admin de Staging; lo decide Carlos. No hay migración ni seeder que lo haga, a propósito.
  • Cuándo: una vez, después de desplegar G9 a Staging (así la verificación ya mira el A4 de cuatro incisos y las columnas nuevas de Cumplimiento), y cada vez que el cliente sume un PDV.
  • Tiempo: unos 30 minutos, con la prueba de pago.
  • Riesgo: bajo. Son ediciones desde la pantalla, auditadas y reversibles. Lo único que se nota hacia atrás: un PDV renombrado cambia cómo se reimprimen los recibos viejos y los reportes históricos, porque leen el nombre vigente. Editar nombre, dirección y ubicación no exige cerrar las cajas del PDV.
  • Quién: un Admin con escritura sobre Estaciones / PDV. Para verificar hacen falta además el Cajero y el Supervisor de prueba, y alguien de Tesorería o un Admin que fondee la caja nueva.

Se hace por la pantalla y no por migración ni seeder: un INSERT por fuera se saltea la caja del PDV y la auditoría, y un seeder (StationSeeder, que es updateOrCreate) pisaría lo que se cargó (ver la advertencia de arriba).

Los datos ​

Salen de la respuesta del cliente del 2026-10-02 (Magaly, tabla «Nombre de la Sucursal / Dirección / Ciudad / Departamento»). Son datos de la empresa, no de personas. Se cargan literales, con las mayúsculas y los errores de tipeo que traen:

Qué se haceCódigo internoNombreDirecciónProvinciaCiudad
Editar el PDV que ya existeGT-CAP-001CIS EXPRESS CIUDAD DE GUATEMALA9 CALLE 15 45 ZONA 13, EDIFICIO PLAZA TRAFALGAR NIVEL 3GuatemalaGuatemala
Editar el PDV que ya existeGT-QUE-002CIS EXPRESS QUETZALTENANGO9 CALLE 24-38, MVEL 2 PLAZA ASTORGA, ZONA 7QuetzaltenangoQuetzaltenango
Crear (no existe en ningún ambiente)GT-CHI-005 (propuesto)CIS EXPRESS CHIMALTENANGO3 CALLE 9-8-42 LOCAL 6, KM 56 CARRETERA NTERAMERICANA ZONA 4ChimaltenangoChimaltenango
  • Provincia y ciudad se eligen del combo, no se escriben. Las etiquetas de la tabla son las del catálogo de Guatemala (departamento 01 / municipio 01-01, 04 / 04-01 y 09 / 09-01; lo que vale es lo que dice el combo). Se elige primero la provincia: la ciudad se habilita después.
  • La capital (G9.8, hecho el 2026-10-07). El cliente escribió la ciudad como «CIUDAD DE GUATEMALA» y el catálogo llamaba «Guatemala» al municipio (se llamaba igual que el departamento). Carlos pidió renombrarlo —no es producción y los datos son simulados— y una migración de datos del deploy (g98_ciudad_de_guatemala) lo hace: el municipio 01-01 pasa a «Ciudad de Guatemala» solo si su etiqueta sigue siendo la sembrada y está activo (si un Admin ya la editó, no se toca) y deja un evento «Municipio renombrado por un deploy» en Auditoría. Es retroactivo en reimpresiones y reexports (cambia la ciudad del beneficiario en el A4 y en Cumplimiento de todos los pagos de ese municipio); el código guardado no cambia. Si el cliente quisiera otro nombre, un Admin lo edita desde Parámetros › Catálogos. Al cargar los PDV, elegí «Ciudad de Guatemala» en la ciudad de la sucursal de la capital.
  • Las direcciones se cargan tal cual (QC-22). Dos traen errores de tipeo evidentes («NTERAMERICANA», «MVEL 2»). No se completan ni se corrigen de memoria: se carga lo que mandaron y se les consulta; corregirlas después es una edición más.
  • El código de Chimaltenango es una propuesta. Sigue la convención de los cuatro que ya existen (GT-CAP-001, GT-QUE-002, GT-MIX-003, GT-ESC-004). El sistema lo guarda en mayúsculas, tiene que ser único y no conviene cambiarlo después. Si Carlos prefiere otro, sirve cualquiera.
  • Los correos de notificación no vienen en el mail del cliente. Al editar, los que ya tienen GT-CAP-001 y GT-QUE-002 (de fixture, @cislatam.test) se dejan como están, y Chimaltenango se crea sin correos hasta que el cliente los mande.
  • GT-MIX-003 (Mixco Plaza) y GT-ESC-004 (Escuintla Norte) no están en la lista del cliente. Se dejan activos y sin tocar hasta que el cliente apruebe la muestra (D3-23): no se desactivan, no se renombran y no se usan como si fueran los reales.

Antes de empezar ​

  • [ ] El deploy con G9 ya está en Staging (el A4 sale con cuatro incisos y Cumplimiento trae el MTCN con C-).
  • [ ] Un Admin de Staging con el permiso de escritura sobre Estaciones / PDV.
  • [ ] La tabla de arriba (o el mail del cliente) a mano para cotejar cada dato.
  • [ ] Anotados los valores actuales de GT-CAP-001 y GT-QUE-002 para volver atrás. Los de fixture son Ciudad de Guatemala — Central / 6a Avenida 12-25, Zona 1, Ciudad de Guatemala y Quetzaltenango Centro / 4a Calle 11-30, Zona 3, Quetzaltenango, pero en Staging pueden haberse editado: vale lo que ves en la pantalla.
  • [ ] Nadie corrió StationSeeder ni un db:seed completo después de cargar los datos reales (revierte los dos PDV que se editaron).

Pasos ​

  1. Editar GT-CAP-001. Entrá como Admin a Parámetros › Estaciones / PDV, apretá Editar en la fila, cambiá Nombre, Provincia, Ciudad y Dirección con los de la tabla y apretá Guardar cambios. No toques el código interno (lo usan StagingTestUsersSeeder, DemoTransactionSeeder y las asignaciones de los usuarios de prueba), ni el país. Esperado: «Estación actualizada.» y la columna Ciudad / provincia de la fila deja de ser un guion.
  2. Editar GT-QUE-002, igual.
  3. Crear Chimaltenango. En Nueva estación completá Código interno, Nombre, País (Guatemala), Provincia, Ciudad y Dirección, y apretá Crear estación. El sistema valida que la ciudad cuelgue de la provincia, crea la Caja 1 (Guatemala usa Caja) y deja un evento STATION_CREATED en Auditoría. Esperado: «Estación creada.» y la fila nueva con una caja.
  4. Asignarla. admin@ y tesoreria@ ya ven todos los PDV de Guatemala. A los usuarios de prueba que la necesiten sumales el PDV desde Administración › Usuarios y Accesos › Usuarios (la ficha, en Roles y asignaciones). Ojo: quien tiene dos o más PDV y ninguno activo solo paga con una caja abierta (el PDV del pago es el de esa caja, ADR-020).
  5. Verificar con un pago de prueba en cada PDV (abajo).

Verificación: un pago de prueba por PDV ​

  1. La persona de prueba abre la caja del PDV desde Saldos. La de Chimaltenango arranca en cero: Tesorería o un Admin la fondea antes de pagar (ver Fondeo de caja).
  2. Paga una transacción ACCEPTED de prueba desde Pago (completando los datos del pago y los documentos que bloquean). Si Staging no tiene ninguna, se crea con un SendRequest de la sandbox (ver la integración).
  3. Baja la papeleta A4. En la línea Agencia salen el nombre del PDV y su ciudad (la Ciudad del domicilio del beneficiario es otra, más arriba).
  4. Como Admin, Reportes › Cumplimiento: país Guatemala, el día de hoy y estado Pagada, y Descargar Excel. En la fila del pago, columnas AG a AJ (33 a 36, Paid at Branch).
PDVA4: AgenciaA4: Ciudad de la agenciaExcel: AG, NameAH, CityAI, StateAJ, Country
GT-CAP-001CIS EXPRESS CIUDAD DE GUATEMALAGuatemalaigualGuatemalaGuatemalaGuatemala
GT-QUE-002CIS EXPRESS QUETZALTENANGOQuetzaltenangoigualQuetzaltenangoQuetzaltenangoGuatemala
ChimaltenangoCIS EXPRESS CHIMALTENANGOChimaltenangoigualChimaltenangoChimaltenangoGuatemala

En la misma fila del Excel, de paso: U (21) con C- más los 10 dígitos, V (22) con el número solo, X (24) CIS Guatemala y AD (30) vacía. El detalle paso a paso está en el plan de pruebas de G9.

Si algo no coincide: una agencia sin ciudad o sin provincia sale con un guion en el A4 y con la celda vacía en Cumplimiento (faltó completarla en el paso 1, 2 o 3); la agencia sale vacía en Cumplimiento si la transacción no está pagada o es un pago viejo que nunca tuvo PDV; y un pago rechazado con ACTIVE_STATION_REQUIRED es una persona con dos PDV, sin PDV activo y sin caja abierta (paso 4).

Rollback ​

Cada edición deja un STATION_UPDATED en Auditoría con el valor anterior y el nuevo (código, nombre, dirección, responsable, país, provincia, ciudad y estado). Para volver atrás, Editar el PDV con los valores anteriores. No uses StationSeeder para deshacerlo: reescribe los cuatro PDV de una vez. Chimaltenango, si hay que sacarlo, se desactiva, no se borra: antes hay que cerrar su caja y dejarla en cero (ver Estaciones).

Contacto ​

Si algo del procedimiento no cierra, Carlos. Si es el dato del cliente (una dirección dudosa, la ciudad de la capital), las preguntas son QC-22 y QC-23 del plan de ajustes v3, §6.

Apagar o cambiar el prefijo C- del MTCN en Cumplimiento (G9.3, D3-18) ​

  • Cuándo: Soterex contesta que ya no usa el prefijo (S-2) o el cliente pide otro (QC-21). Mientras no contesten, queda C-, que es lo que pidió el cliente («mantenerlo como ahora, salvo que Soterex ya no lo use»).
  • Alcance: solo la columna 21 (MTCN Number) del reporte de Cumplimiento. El PIN (22) va sin prefijo siempre; el MTCN guardado, la API, los recibos y los extractos no se tocan.
  • Quién: Carlos (toca Terraform).

En AWS las variables de entorno no sensibles están escritas en infra/terraform/modules/ecs/main.tf (common_environment); no hay una variable de Terraform ni un secreto para esta.

  1. Agregar a common_environment la entrada { name = "CUMPLIMIENTO_MTCN_PREFIX", value = "" } (vacía apaga el prefijo; con otro texto, ese texto es el prefijo) y correr el terraform apply de Staging a mano, como el resto: el workflow terraform-apply.yml todavía no anda (ver «Terraform desde CI: no funciona todavía», más abajo).
  2. El apply registra una revisión nueva de la task definition, pero los servicios la toman en el próximo deploy: el pipeline arma la task definition desde la última revisión de la familia y le cambia la imagen (el servicio tiene ignore_changes = [task_definition], ver arriba).
  3. Verificar bajando un Excel de Cumplimiento: la columna U trae los 10 dígitos sin prefijo (o con el nuevo).

No hace falta tocar código. Rollback: sacar la entrada (vuelve el default C-, de backend/config/cumplimiento.php) y repetir el apply y el deploy.

Antes y después del deploy de G10 y G11: la lista de países y el formato del documento de identidad ​

  • Estado: sin ejecutar (2026-10-07). Las migraciones corren solas con el deploy de la rama; lo que sigue es lo que Carlos mira antes y después.
  • Cuándo: una vez, con el deploy que lleva G10 y G11 (van juntas: comparten el ABM de Catálogos y el estilo de migración).
  • Tiempo: unos 15 minutos, con el pago de prueba.
  • Riesgo: bajo para los datos, medio para el mostrador. Las migraciones solo agregan y renombran ítems de catálogo y no tocan ninguna transacción. Lo que se nota es que una ACCEPTED con un DPI cargado antes que no cumple el formato no se puede pagar hasta que el operador lo corrija (ver abajo).
  • Quién: Carlos para las consultas y el deploy; un Admin de Staging y un Cajero de prueba para el pago.

Qué hace el deploy (tres migraciones, en este orden; migrate --force, y si una falla corta el deploy):

  1. 2026_10_07_100000_g10_paises_de_cumplimiento crea Kosovo (XK) y Antillas Holandesas (AN), renombra 23 países al nombre del cliente y alinea la etiqueta del DPI (DPI (Documento Personal de Identificación)). Renombra solo donde la etiqueta sigue siendo la sembrada y el ítem está activo; no desactiva nada (Antártida queda) ni toca transacciones. Idempotente; en una base sin países no hace nada.
  2. 2026_10_07_110000_g11_columnas_de_formato_de_identificacion agrega las cuatro columnas nullable de formato a catalog_items y sus tres CHECK.
  3. 2026_10_07_110100_g11_reglas_de_dpi_y_pasaporte fija DPI (numérico, 13, emisor GT) y PASAPORTE (alfanumérico, 7 a 13, sin emisor) de Guatemala, solo si sus cuatro columnas están en null (lo que un Admin editó no se pisa). Idempotente.

Las migraciones 1 y 3 dejan un evento de Auditoría sin usuario si cambiaron algo; la 2 es de esquema y no deja ninguno.

Antes de desplegar (opcional): cuántos pagos viejos quedan fuera de formato. Es la consulta 8 de G0.6 del plan, de solo lectura y de solo conteos (ni un número de documento sale en el resultado). Este repo no documenta un canal para correr SQL contra la base de Staging y, por lo mismo que en G4a, no sirve run-artisan-command.yml (arma el comando con split(' ') y deja la salida sin enmascarar en CloudWatch). El canal previsto es el comando diagnostico:v3 del PR 0b, que todavía no existe en el repo: hasta que exista, se corre con el acceso a la base que ya tenga quien hace el deploy. Sin canal, no se frena el deploy: la consulta solo sirve para dimensionar el aviso a los operadores.

sql
SELECT t.status,
       count(*) FILTER (WHERE t.identification_type = 'DPI'
                          AND t.identification_number <> ''
                          AND t.identification_number !~ '^[0-9]{13}$')           AS dpi_numero_fuera_de_formato,
       count(*) FILTER (WHERE t.identification_type = 'DPI'
                          AND t.identification_country IS NOT NULL
                          AND t.identification_country <> 'GT')                   AS dpi_con_emisor_distinto_de_gt,
       count(*) FILTER (WHERE t.identification_type = 'PASAPORTE'
                          AND t.identification_number <> ''
                          AND t.identification_number !~ '^[A-Za-z0-9]{7,13}$')   AS pasaporte_fuera_de_formato
FROM transactions t
JOIN countries c ON c.id = t.country_id AND c.iso_code = 'GT'
WHERE t.status IN ('PAID', 'ACCEPTED')
GROUP BY t.status;

Cómo se lee, fila por fila:

  • PAID: no hay nada que hacer. Una pagada es inmutable (ADR-011) y sigue exportando en Cumplimiento tal cual quedó, sin error: sirve para saber cuántas filas del Excel van a salir con un número que hoy no pasaría, por si el cliente pregunta.
  • ACCEPTED: son las que el operador va a tener que corregir antes de pagar. Al abrirlas ven el aviso con el motivo escrito y «Iniciar pago» deshabilitado; el servidor también las rechaza con 422 si llegan a pay(). No hay forma de saberlo sin la consulta: el seeder de demo anterior a G11 generaba DPI con espacios, así que en una base con datos de demo viejos pueden salir varias. Si da más de cero, avisar al cliente que alguien tiene que abrirlas y corregir el número.
  • Un valor dpi_con_emisor_distinto_de_gt mayor que cero en una ACCEPTED pasa lo mismo: el formulario completa y bloquea el país en Guatemala apenas se elige DPI, y hay que guardar de nuevo.

Después del deploy. Con admin@ y las consultas de solo lectura de siempre:

  1. Países. El combo de Parámetros › Catálogos › País de la identificación y la consulta:

    sql
    SELECT count(*) FROM catalog_items WHERE type = 'COUNTRY' AND country_id IS NULL AND active;

    Tiene que dar 251 si nadie desactivó ni agregó países a mano (los 249 de B1.2 más Kosovo y Antillas Holandesas). Otro número no es un error por sí mismo (un Admin pudo desactivar o crear países), pero hay que poder explicarlo.

  2. Cinco etiquetas, más las dos nuevas (el spot-check):

    sql
    SELECT code, label, active FROM catalog_items
    WHERE type = 'COUNTRY' AND country_id IS NULL AND code IN ('NL','QA','SZ','MK','CZ','XK','AN')
    ORDER BY code;

    Esperado: AN Antillas Holandesas · CZ República Checa · MK Macedonia · NL Holanda · QA Qatar · SZ Suazilandia · XK Kosovo, las siete activas. Si una dice todavía el nombre viejo (Países Bajos, Catar…), ese ítem estaba desactivado y la migración no lo toca a propósito; si dice otra cosa, un Admin la había editado.

  3. El formato de los dos tipos:

    sql
    SELECT code, label, id_charset, id_min_length, id_max_length, id_issuing_country
    FROM catalog_items WHERE type = 'ID_TYPE' ORDER BY code;

    Esperado: DPI · numeric · 13 · 13 · GT, y PASAPORTE · alphanumeric · 7 · 13 · vacío. En pantalla, la columna Formato de la lista de tipos de identificación dice 13 dígitos, solo números · Lo emite Guatemala y Entre 7 y 13 caracteres, solo letras y números.

  4. Auditoría. Filtrar por las acciones Lista de países actualizada por un deploy (esperado: 2 país(es) creado(s): XK, AN · 23 renombrado(s): … · 1 tipo(s) de identificación renombrado(s), con los códigos de los países que creó y de los que renombró) y Reglas de formato de identificación cargadas por un deploy (esperado: 2 tipo(s) de identificación: DPI, PASAPORTE). Con un número menor, hay algo que un Admin ya había tocado: no es un error. Si una migración no tenía nada que hacer, no deja evento.

  5. Un pago de prueba (Cajero de prueba, una ACCEPTED de prueba, en Pago):

    1. En País de la identificación buscar Kosovo: tiene que estar. Elegir tipo Pasaporte, país Kosovo, número AB123456 y Guardar datos: se guarda sin error (es el caso del plan, y prueba que un código XK de 2 letras viaja bien).
    2. Cambiar el tipo a DPI: el país pasa solo a Guatemala y queda bloqueado, con la nota «El DPI lo emite Guatemala.». Escribir 2999 99999 012 (12 dígitos): el campo se marca y el aviso dice «El número de DPI tiene que tener 13 dígitos, solo números.», y Guardar datos no deja. Completar 2999 99999 0123 (los espacios se sacan solos): guarda.
    3. Subir los documentos que bloquean y pagar. Con el A4, comprobar que el tipo sale como DPI (Documento Personal de Identificación) y el país de emisión como Guatemala.
    4. Como Admin, Reportes › Cumplimiento del día: en esa fila, la columna J (10) dice DPI (Documento Personal de Identificación), la K (11) Guatemala y la L (12) 2999999990123, sin espacios. (Para ver Kosovo en la K, el pago de prueba tiene que ser con Pasaporte y país Kosovo.)
  6. Una reimpresión vieja (opcional): reimprimir el A4 de un pago de antes del deploy cuyo país de identificación fuera, por ejemplo, Países Bajos: sale Holanda. Es el efecto retroactivo esperado (QC-26): cambia el nombre, no el país.

Dos cosas que se pueden ver y no son un error: (a) el combo ordena alfabéticamente por etiqueta con el collation de la base, que el Terraform no fija (en Aurora, no determinado): un nombre con tilde (Åland, Islas Aland) puede caer en otro lugar que en dev; (b) un pago de prueba con un número que no cumple el formato se rechaza con 422 aunque el formulario lo deje pasar si alguien edita la regla a mitad de camino: el servidor es quien manda.

Rollback. Las migraciones no tienen down() de datos a propósito. Volver a la imagen anterior no hace falta deshacerlas: las columnas nuevas son nullable y el código anterior no las lee. Lo que sí se puede revertir desde la pantalla (queda auditado):

  • Un nombre que el cliente no quiere: Parámetros › Catálogos › País de la identificación › Editar y volver a escribir el nombre anterior.
  • Una regla que frena el mostrador (un pasaporte real de 6 caracteres, por ejemplo): Editar el tipo y bajar el mínimo, o poner Caracteres permitidos en Cualquiera y los largos y el país emisor vacíos: el tipo vuelve a no validar nada. No hace falta un deploy.

Lo que no se cargó y espera al cliente (no bloquea nada): Chipre del Norte, Irlanda del Norte, Somalilandia y «Santo Tomas» (QC-27), y la confirmación de si el DPI se acepta con separadores (QC-30). Mientras no contesten rige el valor por defecto del plan. Las preguntas están en el plan de ajustes v3, §6, y el plan de pruebas en G10 y G11.

Después del deploy de B3: las cajas abiertas de QA quedan vencidas ​

B3 (ADR-013) hace que la caja opere solo el día en que se abrió. No hay migración que lo avise: la regla se evalúa en cada consulta, así que en el momento del deploy toda caja que esté abierta desde un día anterior pasa a "vencida" y no puede pagar, fondear ni ajustar hasta que se la cierre y se la abra de nuevo. En Staging suelen quedar sesiones de las pruebas de QA abiertas. No es un bug.

Después de desplegar, entrá a Caja con un usuario con permiso de cierre sobre cada PDV y cerrá las cajas que figuren como vencidas (el saldo se hereda al abrir). Si una no se deja cerrar, es por papeletas firmadas sin subir: el aviso lista cuáles. El Supervisor ve de un vistazo qué PDV tiene cajas vencidas en la pantalla de totales por PDV. Los datos recién sembrados con demo:reseed abren sus sesiones "hoy", así que ese día no molestan; al día siguiente quedan vencidos como cualquier otra caja (ver dev.md). Lo mismo vale para producción el día que se despliegue.

Antes y después del deploy de G4a: el PDV de los pagos y los usuarios con más de un PDV ​

G4a (ADR-020, plan de ajustes v3) cambia dos cosas que se notan, y una de ellas puede frenar a usuarios reales de Staging.

1. Una migración de datos completa el PDV de los pagos viejos (2026_10_06_100000_g4_completar_el_pdv_de_los_pagos_viejos, la corre el deploy con migrate). Los PAID sin PDV que tienen un movimiento de caja PAGO toman el PDV de esa caja. No toca los datos del pago, ni un PDV ya fijado, ni los que tienen movimientos en dos PDV distintos, ni los que tienen la caja en un país distinto del de la transacción. Es idempotente y no tiene down() de datos. Cambia solo station_id (ni updated_at ni last_updated_at, que es la fecha del pago que viaja a Soterex).

2. Quien tiene dos o más PDV y ningún PDV activo ya no puede subir el primer documento ni pagar sin una caja abierta (422 ACTIVE_STATION_REQUIRED). supervisor@ (GT-CAP-001 y GT-QUE-002, sin PDV activo) es uno. Los Admin y los perfiles sin PDV acotados no se ven afectados.

Antes de desplegar. Dos consultas de solo lectura (no modifican nada), equivalentes a las consultas 4 y 5 de G0.6 del plan. Este repo no documenta un canal para correr SQL contra la base de Staging (Aurora está en una subred privada): se corren con el acceso a la base que ya tenga quien hace el deploy. No con run-artisan-command.yml: no sirve para SQL (arma el comando con split(' ') y lo antepone con php artisan) y vuelca la salida sin enmascarar en CloudWatch y en el log de Actions, y la consulta (b) imprime mails. El canal previsto es el comando de solo lectura diagnostico:v3 del PR 0b del plan (conteos e ids, nunca mails): todavía no existe en el repo, y cuando exista solo va a estar en Staging después de promoverlo.

Si no hay canal antes del deploy, no se frena el deploy, pero cambia cómo se verifica: el conteo previo (a) no se puede tomar, así que el evento de Auditoría pasa a ser el único registro de cuántos pagos se completaron (sin cruce contra nada); y la lista (b) se reemplaza por entrar, después del deploy, a las fichas de los Supervisores y Cajeros con más de un PDV (muestran el aviso ámbar «Sin PDV activo» de G4.6) y avisarles. Mientras tanto, la salida ante un reclamo es la de siempre: fijarles el PDV activo.

a) Cuántos pagos sin PDV va a completar la migración. Anotar el número de que_completa_la_migracion: es el que tiene que aparecer después en Auditoría.

sql
SELECT count(*)                                                          AS paid_sin_pdv,
       count(*) FILTER (WHERE p.pdv_distintos = 1 AND p.mismo_pais)      AS que_completa_la_migracion,
       count(*) FILTER (WHERE p.transaction_id IS NULL)                  AS sin_movimiento_pago,
       count(*) FILTER (WHERE p.transaction_id IS NOT NULL
                          AND NOT (p.pdv_distintos = 1 AND p.mismo_pais)) AS ambiguas_no_se_tocan
FROM transactions t
LEFT JOIN (
    SELECT cm.transaction_id,
           COUNT(DISTINCT cb.station_id)           AS pdv_distintos,
           BOOL_AND(st.country_id = tx.country_id) AS mismo_pais
    FROM cash_movements cm
    JOIN cash_boxes cb   ON cb.id = cm.cash_box_id
    JOIN stations st     ON st.id = cb.station_id
    JOIN transactions tx ON tx.id = cm.transaction_id
    WHERE cm.type = 'PAGO'
    GROUP BY cm.transaction_id
) p ON p.transaction_id = t.id
WHERE t.status = 'PAID' AND t.station_id IS NULL;

Las sin_movimiento_pago (las PAID de los seeders de demo no tienen movimiento de caja, ni las de un país sin módulo Caja) y las ambiguas_no_se_tocan quedan como están: la migración no adivina. Las que completa son los pagos hechos a mano en Staging con una caja abierta y sin PDV (es el caso de las capturas de la cliente en RV3-17: un Admin que pagó desde la caja de Central y quedó con «—»), así que el número no tiene por qué ser 0: depende de cuántos pagos de prueba se hicieron así. Si da 0, el deploy no deja ningún evento. Un pago de la caja de un PDV dado de baja también se completa (la plata salió de ahí): deja de figurar en «Sin PDV asignado» del Dashboard y de Volumen, y como esos rankings solo cuentan los PDV activos, no aparece en ninguna fila de ellos (el KPI «Pagado hoy» lo sigue sumando).

b) Quién cae en el 422. Usuarios con un rol que puede pagar (pago:write), dos o más PDV en un país y ninguna asignación de ese país con PDV activo. Una asignación que paga sin acotar por PDV (típicamente el Admin) los exime, y la consulta ya la descarta.

sql
WITH paga AS (
    SELECT ra.id, ra.user_id, ra.country_id
    FROM role_assignments ra
    JOIN role_permissions rp ON rp.role_id = ra.role_id AND rp.module = 'pago' AND rp.can_write
)
SELECT u.email, c.iso_code AS pais, c.modulo_caja, count(DISTINCT s.station_id) AS pdv
FROM paga p
JOIN users u     ON u.id = p.user_id
JOIN countries c ON c.id = p.country_id
JOIN role_assignment_station s ON s.role_assignment_id = p.id
WHERE NOT EXISTS (SELECT 1 FROM role_assignments x
                  WHERE x.user_id = p.user_id AND x.country_id = p.country_id
                    AND x.default_station_id IS NOT NULL)
  AND NOT EXISTS (SELECT 1 FROM paga q
                  WHERE q.user_id = p.user_id AND q.country_id = p.country_id
                    AND NOT EXISTS (SELECT 1 FROM role_assignment_station z WHERE z.role_assignment_id = q.id))
GROUP BY u.email, c.iso_code, c.modulo_caja
HAVING count(DISTINCT s.station_id) >= 2;

Cada fila es una persona a avisar antes del deploy. Con modulo_caja en t se destraba abriendo su caja (el PDV de la transacción pasa a ser el de esa caja); en cualquier país, con un PDV activo que un Admin fije en su ficha de usuario. Hay una salvedad: la subida del primer documento mide el alcance con transacciones:write y el pago con pago:write; en la matriz de fábrica son el mismo alcance, pero si alguien editó una de las dos celdas la consulta no lo ve.

Después del deploy.

  1. Entrar como Admin a Auditoría y filtrar por la acción «Pagos completados con su PDV». El evento sale con usuario «Sistema», la fecha del deploy y el detalle «N pago(s) sin PDV completado(s) con el PDV de su caja»: ese N tiene que ser el que_completa_la_migracion de la consulta (a). Si ese número era 0, no tiene que haber evento (es lo esperable en la demo de Staging). Sin el conteo previo (no hubo canal), alcanza con que el evento exista o no exista, y que la consulta (a) dé 0 en el paso siguiente.
  2. Volver a correr la consulta (a): que_completa_la_migracion tiene que dar 0. sin_movimiento_pago y ambiguas_no_se_tocan siguen igual.
  3. Entrar con una de las personas que dio la consulta (b), sin caja abierta, y subir el primer documento de una ACCEPTED: tiene que salir la notificación «Falta tu PDV activo». Con la caja abierta, tiene que subir y el PDV de la transacción es el de esa caja.

Volver atrás no tiene down() de datos: los PDV completados quedan (es información derivable del ledger). Si el 422 estorba antes de que los usuarios estén avisados, la salida es fijarles el PDV activo, no revertir el código.

Para el cliente (no es parte del deploy): la consulta de abajo cuenta los PAID cuyo PDV no coincide con el de su caja (la causa 6 de RV3-17, que la migración no corrige). Sirve para dimensionar la pregunta QC-9 al cliente («¿el PDV de un pago es siempre el de la caja?»), no para verificar nada.

sql
SELECT count(DISTINCT t.id) AS paid_con_pdv_distinto_del_de_su_caja
FROM transactions t
JOIN cash_movements cm ON cm.transaction_id = t.id AND cm.type = 'PAGO'
JOIN cash_boxes cb     ON cb.id = cm.cash_box_id
WHERE t.status = 'PAID' AND t.station_id IS NOT NULL AND t.station_id <> cb.station_id;

Antes del deploy de G6: quién va a poder cerrar las cajas que están abiertas ​

G6 (ADR-021, plan de ajustes v3) cambia quién puede cerrar una caja: desde el deploy la cierra quien la abrió, un Supervisor o un Admin del PDV, y ya no cualquier compañero con el permiso de cerrar cajas. No hay migración ni cambio de permisos: la regla se evalúa en cada pedido, así que rige en el momento del deploy sobre las sesiones que estén abiertas.

Lo que se nota: un cajero que hoy depende de que un compañero le cierre la caja tiene que pedírselo a un Supervisor o a un Admin. Y un PDV sin Supervisor con una caja abierta por alguien que no va a venir solo la destraba un Admin (pregunta #22 del análisis funcional de Caja).

Antes de desplegar, una consulta de solo lectura que lista las cajas abiertas, quién las abrió y cuántas otras personas de ese país y ese PDV reúnen lo que hace falta para cerrarlas (apertura_cierre_caja:write y fondeo_caja:read en una misma asignación que cubra el PDV). Una fila con 0 es una caja que, si su dueño no la cierra antes, solo va a poder cerrar un Admin. Las mismas salvedades de la de G4a: este repo no documenta un canal para correr SQL contra la base de Staging, y no se corre con run-artisan-command.yml (no sirve para SQL y volcaría los correos sin enmascarar en el log de Actions); se corre con el acceso a la base que ya tenga quien hace el deploy. Si no hay canal, no se frena el deploy: después, en Saldos como admin@, se mira qué cajas figuran abiertas y se le avisa a cada dueño.

sql
WITH cierran AS (
    SELECT ra.id, ra.user_id, ra.country_id
    FROM role_assignments ra
    JOIN users cu ON cu.id = ra.user_id AND cu.active
    WHERE EXISTS (SELECT 1 FROM role_permissions rp
                  WHERE rp.role_id = ra.role_id AND rp.module = 'apertura_cierre_caja' AND rp.can_write)
      AND EXISTS (SELECT 1 FROM role_permissions rp
                  WHERE rp.role_id = ra.role_id AND rp.module = 'fondeo_caja' AND rp.can_read)
)
SELECT st.internal_code AS pdv, cb.number AS caja, u.email AS la_abrio, cs.opened_at,
       (SELECT count(DISTINCT c.user_id)
          FROM cierran c
         WHERE c.country_id = st.country_id
           AND c.user_id <> cs.opened_by_user_id
           AND (NOT EXISTS (SELECT 1 FROM role_assignment_station z WHERE z.role_assignment_id = c.id)
                OR EXISTS (SELECT 1 FROM role_assignment_station z
                            WHERE z.role_assignment_id = c.id AND z.station_id = st.id))) AS otros_que_pueden_cerrarla
FROM cash_sessions cs
JOIN cash_boxes cb ON cb.id = cs.cash_box_id
JOIN stations st   ON st.id = cb.station_id
JOIN users u       ON u.id = cs.opened_by_user_id
WHERE cs.status = 'OPEN'
ORDER BY st.internal_code, cb.number;

Cada fila con otros_que_pueden_cerrarla en 0 es una persona a avisar antes del deploy (que cierre su caja antes de irse). Las cajas abiertas que quedan de pruebas de QA se cierran, antes o después, con admin@.

Después del deploy. Entrar a Saldos como Cajero sobre una caja abierta por otro: no tiene que ofrecer Cerrar caja y tiene que decir quién la abrió. Como Supervisor del PDV, sí. El detalle por caso está en el plan de pruebas de G6. Volver atrás es revertir el código (ADR-021, «Si se revierte»): no queda nada en la base que deshacer.

Antes y después del deploy de B6: cambian los permisos de usuarios reales ​

B6 (ADR-014) cambia quién puede hacer qué en el momento en que corre la migración 2026_10_02_130000_b6_perfiles_y_matriz_de_cuatro_roles.php, y en Staging el cliente está probando. No hay manera de desplegarlo "sin que se note": conviene avisar antes y tener las asignaciones listas.

Qué hace la migración (la corre el deploy, sin seeders):

  • Renombra el rol Backoffice a Cajero. Es la misma fila: los usuarios conservan su asignación, su país, sus PDVs y el timeout de sesión del rol.
  • Crea el rol Tesorería, con una fila por módulo.
  • Fija solo las celdas que cambian, aunque un Admin las haya editado (son nueve): el Cajero gana la escritura de pago y pierde Auditoría; el Supervisor gana pago (lectura y escritura), pierde Prefondeo (los dos) y Auditoría, y deja de editar el tipo de cambio y los fondeos (conserva su lectura; la de G8, más abajo, se la saca); el Admin gana la escritura de pago. Pagar pasa a exigir pago·E y cancelar transacciones·B (solo Admin).
  • Deja rastro: un evento de Auditoría sin usuario por cada cambio (Rol renombrado por un deploy, Rol creado por un deploy, Permiso cambiado por un deploy, Permiso otorgado por un deploy).
  • Es idempotente, escribe sin los eventos del modelo y no tiene down() (volver a Backoffice no es un estado que se quiera).

Antes del deploy:

  1. Avisarle a Magaly (CIS-EC) qué cambia: nombres de pantallas, que el Cajero y el Supervisor no cancelan, que el Supervisor deja de fondear.

  2. Saber quién hace hoy la tesorería con rol Supervisor (Teresa, Diego): al desplegar pierden prefondeos, fondeo de cajas y edición del tipo de cambio hasta que se les asigne el rol Tesorería. Los permisos de un usuario son la suma de sus asignaciones, así que si no tienen que operar transacciones hay que quitarles la asignación de Supervisor, no solo sumarles la de Tesorería. Se hace desde Usuarios y Accesos, en la ficha de cada uno.

  3. Si se quiere un usuario de pruebas para Tesorería, tesoreria@cislatam.test, se crea corriendo StagingTestUsersSeeder con run-artisan-command.yml: lo decide Carlos, porque crea una cuenta en el Firebase real. Es idempotente; el resto de los usuarios los encuentra y no los toca. Hasta entonces ese usuario no existe en Staging. A diferencia de las otras tres cuentas, la contraseña de Tesorería no está escrita en el repo ni en esta documentación, porque esa cuenta mueve plata. El seeder además se niega a correr contra production. Hay dos maneras de darle la contraseña, y la diferencia es dónde queda escrita:

    • La elegís vos y no pasa por ningún log (la recomendada): antes de correr el seeder, creá la cuenta a mano en la consola de Firebase del proyecto soterex-staging (Authentication → Add user, con tesoreria@cislatam.test y la contraseña que quieras). El seeder encuentra el usuario, lo enlaza con la base y no imprime nada.
    • Que la genere el seeder: si la cuenta no existe, nace con una contraseña al azar que el seeder imprime una sola vez. Pero run-artisan-command.yml manda esa salida a CloudWatch (/ecs/soterex-staging/web) y la vuelca sin enmascarar en el log de la corrida de Actions, así que la contraseña queda legible ahí para quien tenga lectura sobre el repo, mientras dure la retención. Si vas por este camino, anotala y después reemplazala: la consola de Firebase solo ofrece restablecer la contraseña de un usuario existente por mail, y ese mail es @cislatam.test (no recibe), así que se borra la cuenta y se vuelve a crear con Add user y la contraseña propia (el seeder la vuelve a enlazar).

    La variable STAGING_TESORERIA_PASSWORD que lee el seeder no se puede usar desde ese workflow, que solo pisa el command de la tarea y no define variables de entorno: sirve para correrlo a mano en otro lado, no acá.

  4. Mirar qué celdas se van a pisar. La migración fija nueve celdas aunque un Admin las haya editado (es política del cliente, no un valor inicial). Esta consulta, de solo lectura, lista las que hoy valen distinto de lo que sembró el seeder viejo —o sea, las que alguien tocó— y que el deploy va a dejar en el valor nuevo. Si da filas, hablalo antes con quien las editó; el deploy deja el antes y el después en Auditoría (Permiso cambiado por un deploy).

    sql
    SELECT r.name AS rol, rp.module AS modulo,
           rp.can_read AS l_actual, rp.can_write AS e_actual, rp.can_delete AS b_actual,
           v.l AS l_sembrada, v.e AS e_sembrada, v.b AS b_sembrada
    FROM role_permissions rp
    JOIN roles r ON r.id = rp.role_id
    JOIN (VALUES
        ('Backoffice',  'pago',           true,  false, false),
        ('Backoffice',  'auditoria',      true,  false, false),
        ('Supervisor',  'pago',           false, false, false),
        ('Supervisor',  'fondeo_caja',    true,  true,  false),
        ('Supervisor',  'prefondeo',      true,  true,  false),
        ('Supervisor',  'prefondeo_pais', true,  true,  false),
        ('Supervisor',  'tipo_cambio',    true,  true,  false),
        ('Supervisor',  'auditoria',      true,  false, false),
        ('Admin',       'pago',           true,  false, false)
    ) AS v(rol, modulo, l, e, b) ON v.rol = r.name AND v.modulo = rp.module
    WHERE (rp.can_read, rp.can_write, rp.can_delete) IS DISTINCT FROM (v.l, v.e, v.b);

    Correrla antes del deploy: después, Backoffice ya se llama Cajero y las nueve celdas ya valen lo nuevo.

    Esta consulta cubre solo las nueve celdas que fija la migración. Para ver todas (las 76) contra RoleSeeder::MATRIX, desde G8 está el comando de solo lectura permisos:diferencias, que se puede correr a partir del deploy de G8 (no existe en la imagen que corre hoy): ver el de G8.

  5. Rotar las contraseñas de las otras tres cuentas de prueba (admin@, supervisor@, backoffice@). Siguen siendo las del seeder y las de dev.md, que se publica con el sitio de documentación: cualquiera que lo lea puede entrar a Staging con ellas (la mejora de B6 cubre solo la cuenta nueva). Se cambian desde la consola de Firebase del proyecto soterex-staging, o dándolas de baja si ya no se usan. Es un pendiente de antes de B6, anotado en el plan v3 («higiene que se arrastra»).

Después del deploy:

  1. Entrar como Admin a Auditoría y filtrar por Rol renombrado por un deploy: tiene que haber un evento (Backoffice → Cajero), uno de Rol creado por un deploy (Tesorería) y los de las celdas cambiadas. Si faltan, la migración no corrió.
  2. Entrar con un usuario de cada perfil (el Cajero, backoffice@, el Supervisor y el Admin ya existen) y mirar a qué pantalla cae y qué ve en el menú: ver Perfiles y menú.
  3. Asignar Tesorería a quien hace tesorería (punto 2 de arriba).
  4. No correr db:seed para "arreglar" nada: RoleSeeder revertiría a la matriz del seeder lo que un Admin haya editado desde la app. Cualquier ajuste de permisos se hace desde la ficha del usuario o con una migración de datos nueva.

Una salvedad: la migración no toca las celdas que no están en su lista. Staging recibió la matriz del Cajero con lectura de Transacciones (A5.1) cuando se corrió db:seed a mano el 2026-10-01; si alguna base real no la tuviera, «Reporte individual» no aparecería en el menú del Cajero y se corrige desde la ficha del usuario.

Antes y después del deploy de G8: el tipo de cambio sale del Cajero y del Supervisor ​

G8 (plan de ajustes v3, decisión D3-11; ADR-014 §9) le saca la lectura del tipo de cambio al Cajero y al Supervisor, que se la había dejado B6. La hoja de menús del cliente lo reserva a Administrador y Tesorería, y nada operativo lo necesita: pay() lee el tipo de cambio vigente por el servicio, sin pasar por el permiso (el cobro en un país que convierte a moneda local sigue andando, y Guatemala paga en dólares). Igual que B6, cambia permisos de usuarios reales en el momento en que corre la migración 2026_10_07_000236_v3_tipo_de_cambio_solo_tesoreria_y_admin.php, y el cliente está probando con cuentas de Cajero y de Supervisor: conviene avisarle antes (pregunta QC-17 del plan).

Qué hace la migración (la corre el deploy, sin seeders): fija dos celdas de role_permissions a «—» (0/0/0) dentro de una transacción.

PerfilMóduloAntesDespués
Cajerotipo_cambioL—
Supervisortipo_cambioL—
  • Pisa lo que un Admin haya editado en esas dos celdas, como B6 (es una decisión del cliente, no un valor inicial). No toca ninguna otra celda, tampoco las del mismo perfil. Tesorería y Admin conservan el tipo de cambio.
  • Deja un evento de Auditoría sin usuario por cada celda que cambió (Permiso cambiado por un deploy, con el antes L-- y el después ---), y ningún dato personal. Es idempotente, escribe sin los eventos del modelo y no tiene down(): volver a darles la lectura sería abrir un acceso por un migrate:rollback. Si el cliente cambia de idea, es una celda en Roles y Permisos (o una migración nueva).

Qué se nota desde el deploy, para esas dos cuentas (backoffice@ y supervisor@ en las de prueba, y cualquier persona real con esos perfiles): GET /tipo-cambio/{pais} y GET /tipo-cambio/paises responden 403, el ítem «Tipo de cambio» desaparece de su menú y no entran por la URL. El manual en PDF de esos dos perfiles pierde la sección de Tipo de cambio (el del Cajero pasa de 7 a 6 secciones y el del Supervisor de 10 a 9). Pagar no cambia.

Antes del deploy:

  1. Avisarle a Magaly (CIS-EC) que el tipo de cambio queda solo para Tesorería y Administrador, como dice su hoja de menús, y que el Cajero y el Supervisor dejan de verlo.

  2. Saber a cuántas personas toca, con una consulta de solo lectura (las mismas salvedades que la de G4a: este repo no documenta un canal para correr SQL contra la base de Staging, y no se corre con run-artisan-command.yml, que no sirve para SQL). Cuenta personas por perfil, no imprime correos:

    sql
    SELECT r.name AS perfil, count(DISTINCT ra.user_id) AS personas_con_el_perfil
    FROM role_assignments ra
    JOIN roles r ON r.id = ra.role_id
    JOIN role_permissions rp ON rp.role_id = r.id AND rp.module = 'tipo_cambio' AND rp.can_read
    WHERE r.name IN ('Cajero', 'Supervisor')
    GROUP BY r.name;

    Una persona con otra asignación que también lee el tipo de cambio (Tesorería o Admin) lo sigue viendo: los permisos son la suma de sus asignaciones.

  3. Mirar si alguien editó esas dos celdas (si las tocó un Admin desde la app, el deploy las pisa igual). De solo lectura; si da filas, hablalo antes con quien las editó:

    sql
    SELECT r.name AS perfil, rp.can_read AS l, rp.can_write AS e, rp.can_delete AS b
    FROM role_permissions rp
    JOIN roles r ON r.id = rp.role_id
    WHERE rp.module = 'tipo_cambio' AND r.name IN ('Cajero', 'Supervisor')
      AND (rp.can_read, rp.can_write, rp.can_delete) IS DISTINCT FROM (true, false, false);
  4. (Opcional) Mirar la matriz entera, no solo estas dos celdas. El comando que lo hace solo, permisos:diferencias, llega con este mismo deploy: Staging todavía no lo tiene (el deploy aplica las migraciones con la imagen nueva y recién después reemplaza el servicio, y run-artisan-command.yml corre sobre la revisión activa), así que antes del deploy no se puede correr: se corre después (ver abajo). Si se quiere mirar antes, la consulta de solo lectura que baja la matriz de Staging (76 filas, sin datos personales) y se compara a ojo con matriz-de-perfiles.json es:

    sql
    SELECT r.name AS perfil, rp.module AS modulo, rp.can_read AS l, rp.can_write AS e, rp.can_delete AS b
    FROM role_permissions rp
    JOIN roles r ON r.id = rp.role_id
    ORDER BY r.name, rp.module;

    Tienen que diferir las dos celdas de este deploy (Cajero · tipo_cambio y Supervisor · tipo_cambio, que hoy dan L-- y en la matriz son ---) y nada más. Cualquier otra diferencia es una celda que ninguna migración fija y que el deploy no va a corregir (el caso que dio origen a esto: el Cajero de una captura de Staging sin «Transacciones», RV3-41). No se arregla sola ni con db:seed: cada una se decide con Carlos, celda por celda (puede ser política del cliente editada desde Roles y Permisos, y entonces se deja como está), y recién después se lleva a la matriz con una migración de datos nueva y se le avisa al cliente.

Después del deploy:

  1. Entrar como Admin a Auditoría y filtrar por Permiso cambiado por un deploy: tiene que haber un evento nuevo por cada celda que tenía lectura —los que contó la consulta previa del punto 3—, de L-- a ---: si esa consulta dio las dos filas, son dos (Cajero · tipo_cambio y Supervisor · tipo_cambio). La migración es idempotente: una celda que un Admin ya había dejado en --- no cambia y no se audita, así que menos eventos no quiere decir que no corrió. La comprobación que manda es el punto 4 de abajo: permisos:diferencias con «Sin diferencias».
  2. Entrar como backoffice@ y como supervisor@: no tienen que ver «Tipo de cambio» (ni en el menú ni, en pantallas chicas, en la barra de abajo del Cajero), y la URL /tipo-cambio no tiene que abrirse. Con tesoreria@ y admin@ sí.
  3. Probar un pago como Cajero en un PDV de Guatemala: tiene que seguir andando.
  4. Correr permisos:diferencias (solo lectura): imprime en qué celdas difiere role_permissions de RoleSeeder::MATRIX, las 76. Se dispara a mano con run-artisan-command.yml (ambiente staging, comando permisos:diferencias) y se lee en el log de la corrida; la salida lleva perfiles, módulos y marcas (L = leer, E = escribir, B = borrar) y, de un perfil que sobra, cuántas asignaciones tiene, nunca un correo ni un nombre. Con la matriz sana dice «Sin diferencias». Si lista algo, son celdas que ninguna migración fija (se resuelven como en el punto 4 de arriba, con Carlos y celda por celda); las dos de este deploy no tienen que figurar.
  5. No correr db:seed para "arreglar" nada (ver B6, arriba).

Qué ve cada perfil después del deploy:

PerfilMenúQué cambia respecto de B6
Cajero (backoffice@)Caja: Pago, Reporte individual, Saldos · DocumentaciónPierde el grupo Tesorería (Tipo de cambio). En el celular la barra baja a tres destinos
Supervisor (supervisor@)General: Dashboard · Caja: Pago, Reporte individual, Saldos · Tesorería: solo Fondeo PDVs (pestaña PDV) · Reportes · DocumentaciónPierde Tipo de cambio. En el celular entran sus seis destinos, sin «Más»
Tesorería (tesoreria@)Dashboard, Saldos, Prefondeo Soterex, Fondeo PDVs, Tipo de cambio, Reportes · DocumentaciónSin cambios
Admin (admin@)TodoSin cambios

El que tiene más de un perfil ve la suma de los menús de cada uno (por ejemplo, una cuenta con Cajero y Tesorería conserva Tipo de cambio por la asignación de Tesorería): no hay selector de perfil. Además del menú, el deploy no cambia nada más: pagar, cancelar, la caja y los extractos quedan como estaban. Lo único nuevo que ven Cajero + Tesorería es que el Estado de Situación deja de mostrarles el nombre del beneficiario (H3-01; y a un Supervisor de un PDV que además es Tesorería, solo se lo muestra en los pagos de su PDV) y que el selector de país de Reportes ofrece solo donde la persona tiene ese permiso (H3-02): son arreglos de la misma entrega, sin migración.

Antes y después del deploy de la alineación de la API C2P (2026-10-05): promover, probar y pasar a real ​

El plan 2026-10-05-alineacion-contrato-c2p-soterex (PR #80, ADR-017 y ADR-018) cambia el contrato que Soterex ve y agrega dos cosas que corren solas: la entrega de notificaciones y el vencimiento del MTCN. Lo único que le toca a un humano en Staging está en estos pasos, en este orden (cada uno depende del anterior). Nada de esto se hace desde una sesión autónoma: es de Carlos.

Decisión de Carlos, 2026-10-05: los pasos 4, 5 y 6 están EN PAUSA hasta que Soterex mande la URL de Notifications y el secret. Carlos todavía no los tiene y la integración sigue en modo mock, así que por ahora no se hace el c2p:expire --dry-run, no se prende el scheduler (ni se hace el terraform apply del flag) y no se carga la URL ni el secret ni se pasa a Real. Los pasos 1 a 3 y el 7 siguen en pie. Qué implica tener el scheduler apagado, en «Con el scheduler apagado».

Qué corre el deploy (migraciones, sin seeders): el tarifario de comisiones por país y el tramo provisional de Guatemala (50 USD fijos por transacción, en todos los ambientes; solo si Guatemala no tiene ningún tramo); previous_transaction_id en transactions; el payload del outbox pasa de jsonb a json (el body que se firma tiene que conservar el orden de las claves); las notificaciones pendientes de la demo pasan a SKIPPED; la tabla de secrets del webhook y la marca de firma inválida del sandbox; y la vigencia del MTCN de Guatemala a 60 días.

Pasos de Carlos:

  1. Pedirle a Teresa el tarifario real de comisiones (lo define Tesorería, no Soterex). Staging y producción arrancan con el provisional de Guatemala: 50 USD fijos por transacción, para cualquier monto (decisión de Carlos, 2026-10-05; la pantalla de Comisiones lo marca PROVISIONAL). Tesorería (Teresa) carga la tabla real cuando la defina: no es un requisito para abrir (ver las advertencias más abajo). Se carga desde la pantalla Parámetros → Comisiones (Admin): alta, edición y desactivación de tramos por país, con avisos de tarifario provisional y de montos sin comisión; ver el manual de Países y Comisiones y ADR-018 §6.
  2. Revisar y mergear el PR #80 a main.
  3. Promover main a staging con el flujo habitual (PR main → staging, ver la estrategia de branching). El deploy corre las migraciones solo; si fallan, se corta y el servicio viejo sigue sirviendo.
  4. (En pausa hasta que Soterex mande la URL y el secret.) Correr php artisan c2p:expire --dry-run en Staging, antes de prender el scheduler. GitHub → Actions → "Ejecutar comando artisan (manual)" → environment: staging y command: c2p:expire --dry-run. No cambia nada (ni estado, ni outbox, ni auditoría); lista qué vencería:
    • La primera línea dice el día que está usando: Hoy (Guatemala): AAAA-MM-DD — dry-run, no se cambia nada.
    • Después hay una línea por transacción, Vencería: <id> <RS-…> (último día de cobro: AAAA-MM-DD), y un resumen (N transacciones vencerían. No se cambió nada. o Nada para vencer.). Nunca imprime el MTCN ni datos del beneficiario.
    • Qué mirar: que lo que figure sea lo que esperás cancelar. El comando solo toca ACCEPTED que entraron por la API de Soterex (api_client_id no nulo): los datos de demo no figuran nunca, aunque su fecha esté en el pasado. Las transacciones de la API creadas antes de este deploy conservan su vencimiento original (30 días): si Staging solo tiene las de las últimas semanas, lo esperable es Nada para vencer., y si lista alguna, es una que ya pasó su último día.
  5. (En pausa hasta que Soterex mande la URL y el secret.) Prender el scheduler de Staging (el flag de Terraform): enabled = true en module "scheduler" de infra/terraform/environments/staging/main.tf, con terraform plan y apply de Carlos. El único cambio del plan tiene que ser el state de aws_scheduler_schedule.soterex_send_request (DISABLED → ENABLED); si muestra algo más, no aplicar. El costo y la frecuencia están más arriba, en «Costo: el NAT Gateway…». Sin scheduler no sale ninguna notificación y no vence ninguna transacción.
  6. (En pausa: es lo que se hace cuando Sean mande la URL y el secret del HMAC.) Cargar la URL y el secret y pasar a Real, en Configuración (Admin) y en este orden: (a) «Firma del webhook» → Cargar secret, con el key_id que indique Soterex (si no indica uno, k1); (b) la Notifications URL; (c) recién entonces el modo Real y Guardar. Si se guarda el modo real sin un secret activo, la pantalla avisa que las notificaciones reintentan durante unos 81 minutos (las esperas de 1, 5, 15 y 60 minutos) y que después quedan FALLIDAS, y hay que reenviarlas con notifications:retry (abajo). Cargar el secret primero evita ese trabajo. La Notifications URL tiene que ser https:// (en Staging y Producción; http:// solo en local), sin usuario ni contraseña, sin ? y sin #: la pantalla rechaza lo demás. En Producción el modo mock no manda nada y no da nada por entregado (la entrega falla, se reintenta y termina FAILED; al guardar mock la pantalla avisa, y mientras siga en mock muestra un aviso en rojo), así que ahí hay que pasar a Real. El secret se usa tal cual, como texto UTF-8: si Soterex lo manda codificado (hex, base64), se carga como lo mandó, no decodificado.
  7. Completar [CONTACTO CIS] y mandar el mail con el sign-off, el OpenAPI y la collection (borrador en 2026-10-06-mail-sean-sandbox-alineado y 2026-10-06-c2p-sign-off; el checklist completo, en 2026-10-06-antes-de-mandar-el-sign-off), una vez que el paso 3 esté hecho: el mail describe el contrato nuevo y Sean no tiene que ver dos contratos. Con el scheduler apagado el mail ya no promete notificaciones reales: dice que no se entrega nada hasta tener su URL y su secret. El client_secret del cliente OAuth no se pega en el mail ([CLIENT_SECRET] solo si hubo rotación, y se manda por el canal seguro).

El outbox de notificaciones: estados y notifications:retry ​

Cada pago o cancelación de una transacción de la API deja una fila en el outbox (outbound_notifications) que notifications:deliver entrega con reintentos. Cada corrida toma las filas de a una, justo antes de enviarlas, de la más vieja a la más nueva (por created_at), da un solo intento por fila y se corta al llegar a 50 filas o a 480 segundos (por debajo del mutex de 10 minutos del scheduler): lo que no alcanza queda PENDING para la corrida siguiente, y el comando lo dice («…y quedan pendientes: la próxima corrida sigue desde ahí»). Con el tick de 5 minutos del scheduler de AWS son hasta 600 por hora. Para vaciar una cola grande a mano (workflow de artisan), hay que correr el comando varias veces o subir los topes: notifications:deliver --limit=N (1 a 1000) y --max-seconds=S (1 a 3600). Los cuatro estados:

EstadoQué esSale de ahí
PENDINGEspera su próximo intento (recién encolada, o reintentándose)Se entrega (DELIVERED), o agota los reintentos o se rechaza (FAILED)
DELIVEREDSoterex la acusóEs final
FAILEDAgotó los reintentos (cinco intentos) o Soterex la rechazó con un 3xx/4xx. Ya no se reintenta solanotifications:retry la vuelve a PENDING
SKIPPEDNunca se va a mandar: era de una transacción que no entró por la API (dato de demo)Es final, no se reenvía

Qué hizo la migración con la demo. Las notificaciones PENDING de transacciones sin cliente de API (la demo de Staging, que el scheduler apagado nunca vació) pasaron a SKIPPED, con el motivo anotado; no se borró nada. Además, el comando de entrega vuelve a salteárselas si alguna reaparece. Las PENDING de transacciones de la API que habían quedado con el payload plano del contrato anterior se reconstruyen con el contrato nuevo al entregarse (el PAID toma la fecha y la hora del asiento de auditoría del pago); las que no se pueden reconstruir quedan FAILED con su auditoría.

Reenviar una notificación FAILED: php artisan notifications:retry {id}, por el mismo workflow de artisan (environment: staging, command: notifications:retry <id>). Todas las FAILED de una vez:notifications:retry --all-failed (con --limit=N, 100 por defecto y 1000 como tope: si quedan más, lo dice y se vuelve a correr). Es el caso de «se prendió el modo real sin secret (o con la URL mal) y se agotaron los intentos de muchas filas»: hace con cada una lo mismo que el modo por id (vuelve a PENDING y deja su asiento de auditoría), de la más vieja a la más nueva, y nunca toca las SKIPPED. Un id y --all-failed juntos son un error.

  • De dónde sale el id: de la tarjeta «Notificación a Soterex» del detalle de la transacción, que muestra el comando ya armado (con un botón para copiarlo) en las que están FALLIDAS. Tarjeta, comando y reenvío son para quien tiene acceso al servidor: la pantalla no reenvía.
  • Qué hace: la deja en PENDING con los intentos en cero, y la próxima corrida de notifications:deliver la entrega, firmándola de nuevo al enviarse (la firma y su timestamp nunca se guardan, así que el reenvío no arrastra los viejos). Queda en la Auditoría como Notificación a Soterex reenviada.
  • Qué no acepta: solo FAILED. Una PENDING ya se está reintentando, una DELIVERED ya llegó (reenviarla produciría un duplicado en Soterex) y una SKIPPED nunca se manda. Un id que no existe o que no es un UUID da error sin tocar nada.
  • Si vuelve a quedar FAILED: el último error de la tarjeta dice por qué (el código HTTP y, si Soterex lo mandó, su messageCode; nunca el cuerpo ni la URL). Un 401 suele ser un secret que no coincide; un 400, un body que Soterex no entiende; los 5xx y los timeouts se reintentan solos antes de llegar a FAILED.

Con el scheduler apagado (decisión del 2026-10-05) ​

Carlos todavía no tiene la URL ni el secret de Soterex y la integración sigue en modo mock, así que el scheduler de Staging no se prende por ahora (el flag enabled = true de module "scheduler" queda como está y no se hace el terraform apply). Es una pausa, no un olvido: se retoma cuando Soterex mande los dos datos. Mientras tanto:

  • Las notificaciones quedan PENDING en el outbox. El pago o la cancelación de una transacción de la API encola su aviso, pero nadie ejecuta notifications:deliver: ni siquiera el modo mock «entrega» nada (el mock lo da por entregado cuando el comando corre). Una PENDING no se pierde ni cambia sola.
  • El sandbox topa a los 50 disparos (2208): POST /api/c2p/v1/sandbox/notify rechaza el disparo 51 mientras haya 50 pendientes del mismo cliente, y como nada las vacía, Sean toparía y no podría seguir probando disparos hasta que se entreguen.
  • Las transacciones vencidas no se cancelan solas. c2p:expire tampoco corre. Una transacción de la API cuyo último día de cobro ya pasó sigue ACCEPTED y no genera su CANCELLED con CXL_EXPIRED. Lo que sí rige: pay() ya no deja pagarla (422 MTCN_EXPIRED), así que no hay riesgo de cobrar algo vencido.
  • Al prenderlo se entrega todo lo acumulado, incluidas las pruebas viejas: la primera corrida arranca por las más antiguas, de a 50 por corrida. Si el modo todavía es mock, el mock las da por entregadas sin mandar nada; si ya es real, salen a la URL de Soterex. Antes de pasar a Real hay que revisar la cola (la tarjeta «Notificación a Soterex» del detalle de cada transacción, o una consulta de solo lectura sobre outbound_notifications filtrando status = 'PENDING') y decidir qué hacer con lo que no debería llegar a la URL real de Soterex, por ejemplo avisos de prueba disparados con sandbox/notify sobre transacciones que ya no importan. Hoy no hay un comando para descartar a mano una fila (el estado SKIPPED lo pone una migración o la guarda de las transacciones que no entraron por la API): si hace falta, es una tarea nueva.
  • Lo que no depende del scheduler funciona igual: SendRequest, Cancel, el replay, la comisión, y que pay() rechace una vencida. Y los dos comandos se pueden correr a mano con el workflow de artisan (notifications:deliver, c2p:expire) para una prueba puntual.

Advertencias de despliegue ​

  • Las ACCEPTED existentes conservan su vencimiento. El deploy no recalcula expires_at: lo que ya se creó con 30 días vence a los 30, y lo nuevo de Guatemala nace con 60. Las de demo llevan un vencimiento ilustrativo que no se aplica (el vencimiento rige solo para lo que entró por la API).
  • La migración de Guatemala a 60 días pisa mtcn_expiration_days solo si está en NULL o en 30 (el default provisional del código); un valor distinto, cargado a propósito, no se toca. Un 30 puesto a propósito se pisa. En una base nueva lo escribe CountrySeeder.
  • Qué es "producción" para el sistema: una sola definición, con lista blanca. Son ambientes de prueba únicamente local, testing y staging (el APP_ENV, sin espacios en los bordes y en minúscula); todo lo demás es producción: production, prod, Production, un valor desconocido (development, prd, live) o vacío. Es lo que decide si existen el endpoint de disparos del sandbox y el modo mock (en producción no entrega nada). Ya no decide el tarifario provisional: se siembra en todos los ambientes (ver la advertencia siguiente). Un error de tipeo en APP_ENV apaga lo de prueba, no lo prende. La URL de Notifications puede ser http:// solo en local y testing. Esa misma definición es la guarda de «no en producción» de los comandos y seeders (no una igualdad exacta con production): api-client:create (el prefijo del client_id: cis_prod_ fuera de los ambientes de prueba, cis_stg_ en Staging, cis_local_ en local y testing), demo:reseed y demo:seed-accepted (solo corren en local/staging; en cualquier otro ambiente, producción incluida, hace falta --force) y StagingTestUsersSeeder (se niega en cualquier ambiente que no sea de pruebas). Con Production, prod o un APP_ENV que nadie previó, la guarda se aplica igual: antes se salteaba y un cliente de producción habría salido como cis_local_….
  • El tarifario provisional de Guatemala son 50 USD fijos por transacción y se siembra en todos los ambientes, producción incluida (decisión de Carlos, 2026-10-05; antes era el 1 % y solo fuera de producción), y solo si Guatemala no tiene ningún tramo: uno real que ya se cargó, o uno provisional que un Admin editó o desactivó, no se pisa ni se resucita. Producción arranca con ese provisional (la pantalla de Comisiones lo marca PROVISIONAL) y Tesorería (Teresa) carga la tabla real cuando la defina: ya no hace falta cargarla para abrir. Un SendRequest se rechaza con 2026 («No fee schedule covers this amount for the destination country») solo si un Admin desactiva todos los tramos o un monto queda sin cubrir. Dos consecuencias: con montos menores a 50 USD la comisión es mayor que el principal (se da de alta y se paga igual), y Soterex ve 50.00 en el fee de cada respuesta: el sign-off se lo dice.
  • El vencimiento cancela transacciones reales. Solo las ACCEPTED de la API, de a una, con lock, sin tocar saldos (una ACCEPTED no consumió nada), e idempotente. Por eso el --dry-run del paso 4 va antes de prender el scheduler.
  • Con el scheduler apagado (el estado actual, por decisión de Carlos) no sale ninguna notificación (ni el primer intento) y el endpoint de disparos a demanda del sandbox topa a los 50 disparos pendientes por cliente (2208), porque las pendientes no se vacían. Ver «Con el scheduler apagado».
  • sandbox/notify existe en Staging y no en producción (el ambiente sale de APP_ENV: staging en la task de ECS; en producción responde 404 con el mismo envelope que cualquier URL inexistente). En Staging, las notificaciones de prueba que pide Sean aparecen en la tarjeta del detalle como las reales: una transacción ACCEPTED puede mostrar «Pago · Entregada» sin estar pagada.
  • Riesgo conocido, sin decisión todavía: el cupo del pedido de token comparte la IP del balanceador. El límite de la API C2P (SendRequest, Cancel y el sandbox: 60 por minuto, por cliente de la API, un solo cupo compartido) se cuenta después de autenticar, así que un request sin token válido responde 401 y no consume nada. El límite de /api/oauth/token es otro y sigue siendo por client_id más IP (30 por minuto) y por IP (60 por minuto): mientras no se configure trustProxies en la app (una decisión de infra pendiente de Carlos), la IP que ve la app es la del ALB y ese límite comparte el cupo de la IP del ALB. Un tercero que conozca el client_id (es un dato público) puede agotarlo y hacer que el pedido de token de Soterex dé 429 durante un rato. No le permite autenticarse y los tokens ya emitidos duran una hora, pero es una molestia real. El control por IP real lo da la regla rate-based del WAF, no esta capa. Se deja anotado, sin compromiso de resolverlo en este plan.
  • Quedó infraestructura sin consumidor: los secrets soterex_username y soterex_password de Secrets Manager y su inyección en la task de ECS. El webhook ya no usa usuario y contraseña, y ningún código los lee. Sacarlos es un cambio de Terraform aparte.

Antes y después del deploy de L3: la bóveda del PDV y el permiso «Traspaso de caja» (ronda 3) ​

L3 (ADR-029) agrega una bóveda a cada PDV con módulo Caja y un permiso nuevo, traspaso_caja. Igual que B6 y G8, cambia permisos de usuarios reales en el momento en que corre la migración, y además cambia lo que ven en pantalla: no hay manera de desplegarlo "sin que se note". No promover hasta que Carlos lo decida (el PR de L3 no se mergea solo, y esto no es un deploy que se pueda tomar de paso con otro). Nada de esto se probó en Staging: lo verificado fue en dev.

Qué hacen las tres migraciones (las corre el deploy, sin seeders):

MigraciónQué hace
2026_10_19_100000_l3_boveda_en_cash_movements.phpPrepara el libro de movimientos: la sesión de un movimiento pasa a ser opcional (solo la bóveda no tiene), y agrega transfer_id y counterpart_cash_box_id para los traspasos. No toca ninguna fila existente.
2026_10_19_100100_l3_crear_las_bovedas.phpCrea una bóveda vacía (número 0) por PDV de un país con módulo Caja, también para los PDVs inactivos. Idempotente.
2026_10_19_100200_l3_permiso_traspaso_caja.phpCrea las filas del módulo traspaso_caja: Cajero 0/0/0 · Supervisor 1/1/0 · Tesorería 1/1/0 · Admin 1/1/1. No pisa lo que exista y deja un evento de Auditoría ROLE_PERMISSION_GRANTED_BY_MIGRATION por cada permiso que otorga.

Las dos últimas no tienen down() (una bóveda vacía es inofensiva y quitar una fila de permiso podría pisar una edición hecha a propósito). La primera sí, y se niega a deshacerse si ya hay movimientos de una bóveda: el libro de movimientos es inmutable.

Qué cambia para quien ya usa Staging:

  • El Supervisor y Tesorería ganan «Pasar plata entre cajas» (y el capítulo del manual correspondiente). Los Supervisores pueden mover plata de la bóveda a las cajas de sus PDVs, que es lo único nuevo que pueden hacer con ella. No pueden fondear ni ajustar.
  • Los saldos de los PDV no cambian y la suma tampoco: las bóvedas nacen en cero. Lo que cambia es el desglose de las tarjetas de Saldos (Bóveda … · Cajas …) y que aparece una tarjeta nueva, Bóveda del PDV (Caja 0), para quien ve todas las cajas del PDV. El Cajero no la ve.
  • «Fondear caja» pasa a ser «Fondear PDV» en Fondeo PDVs › PDV: la plata llega a la bóveda del PDV, sin que haga falta una caja abierta. Saldos sigue permitiendo fondear una caja abierta directamente. Quien estaba acostumbrado a elegir una caja en ese formulario ya no la elige.
  • Fondeo PDVs › País: Distribuido en cajas ahora incluye las bóvedas. Hoy no cambia ningún número (están en cero) pero cambia el sentido del texto: es lo repartido a los PDVs, no solo a las cajas.
  • El extracto del PDV y el del país no muestran los traspasos (suman cero). El reporte de Cajas gana la columna Traspasos y una fila por bóveda; Cierres por día gana también la columna Traspasos (la bóveda no cierra, así que no tiene fila ahí).

Antes del deploy:

  1. Avisarle a Magaly y a Teresa qué cambia: el Supervisor reparte la plata de la bóveda a sus cajas; Tesorería fondea el PDV, no la caja; el Cajero no ve la bóveda. Y las cuatro preguntas del cliente con la respuesta por defecto que se tomó (ADR-029, QC-42 a QC-45), por si alguna no es la que quieren.
  2. Mirar la cola: si hay cajas abiertas de un día anterior, el traspaso hacia o desde ellas se rechaza (ADR-013); conviene cerrarlas antes, como siempre.
  3. Decidir si se corre a mano permisos:diferencias después del deploy (ver abajo): lo corre Carlos con run-artisan-command.yml.

Después del deploy:

  1. php artisan permisos:diferencias debe decir «Sin diferencias». Si dice algo, no se arregla a mano en la base: se mira qué celda difiere.
  2. En Auditoría, filtrar por Permiso otorgado por un deploy: tiene que haber tres eventos del módulo traspaso_caja (Supervisor, Tesorería y Admin). El Cajero queda en 0/0/0 y no genera evento.
  3. Entrar como un Supervisor y como una Tesorería de prueba y recorrer las secciones 1 a 4 del plan de pruebas de L3. Para probar con plata hay que fondear un PDV: avisar antes para no mezclar la plata de prueba con la del cliente.
  4. Cada PDV con módulo Caja tiene que tener su bóveda: en Parámetros › Estaciones › Administrar figura como Bóveda del PDV (Caja 0), sin interruptor de activar.

Cómo se vuelve atrás. No hay un down(). Si el permiso del Supervisor no es el que se quiere, un Admin lo cambia desde Roles y Permisos (módulo Traspasos entre cajas (Pasar plata)), sin código. Las bóvedas vacías se pueden dejar donde están.

Antes y después del deploy de G1: los soportes de pago pasan a S3 ​

G1 (ADR-019, plan de ajustes v3, RV3-06 y RV3-07) saca los soportes de pago del disco del contenedor y los guarda en un bucket S3 privado. Hasta este despliegue ningún soporte subido a Staging sobrevivió a un deploy: la fila quedaba en Aurora y el archivo se iba con el contenedor (Staging se promovió 11 veces entre el 29/09 y el 04/10). Nada de esto se hace desde una sesión autónoma: es de Carlos.

Cuándo usar este runbook: el primer despliegue de G1 a Staging. Producción sigue el mismo orden cuando se provisione (production.md). Tiempo: dos deploys de entre 8 y 22 minutos cada uno, el apply (unos minutos) y la verificación (una media hora con la matriz completa de archivos). Riesgo: medio. Un orden equivocado deja a Pago con 500 en todo acceso a un soporte; un apply mal leído puede repetir el incidente del CORS (más abajo). Quién puede correrlo: Carlos. Hace falta el merge a main, el push a staging, terraform apply y credenciales de administración de AWS.

Qué pasa con lo que ya estaba subido. Nada se migra, porque no hay nada que migrar: los archivos anteriores ya se habían perdido. Después del paso 3 esas filas dan el 404 DOCUMENT_FILE_MISSING y la pantalla dice «El archivo no está disponible. Un Supervisor o Admin puede volver a subirlo». Se vuelven a subir a mano; documentos:verificar dice cuáles son.

Antes de empezar ​

  • [ ] El PR de G1 está mergeado a main, con la revisión de security hecha (el plan la exige para G1).
  • [ ] Tenés credenciales de administración de AWS en la cuenta de Staging: aws sts get-caller-identity tiene que mostrar esa cuenta. Y terraform version muestra 1.9 o más.
  • [ ] Tenés claro cuál es el destino de la vuelta atrás: la revisión que deja corriendo el deploy del paso 1 (imagen nueva, con la librería, y sin DOCUMENTS_DISK_DRIVER). Se anota al terminar ese paso y antes del apply, porque después del apply ya no es la última revisión de la familia. No es la que corre hoy: esa es la imagen anterior a G1.
  • [ ] (Recomendado, G1.1) Confirmá el diagnóstico antes de construir. Con DevTools abierto (pestaña Network), abrí un soporte subido antes del último deploy: tiene que responder 404 con code: DOCUMENT_FILE_MISSING. Si responde 500, 401 o 403, la causa es otra: parar y reabrir el análisis. Y comprobá en el Web ACL de Staging (consola de WAF) que existe la regla aws-managed-common-rules-uploads (la excepción de SizeRestrictions_BODY para POST …/documentos, aplicada el 2026-10-02).

Paso 1 — Promover la imagen con la librería (el disco sigue siendo local) ​

PR de main a staging con el flujo habitual (branching). Es la imagen con league/flysystem-aws-s3-v3 instalada y los mensajes nuevos de la pantalla. Como DOCUMENTS_DISK_DRIVER todavía no está definida en el entorno de ECS, la app sigue en local: no cambia nada visible.

  • Qué esperar: deploy verde y la app igual que antes.
  • Anotá la revisión que quedó corriendo, antes del apply. Es el destino de la vuelta atrás (más abajo):
    bash
    aws ecs describe-services --region us-east-1 --cluster soterex-staging-cluster --services soterex-staging-web \
      --query 'services[0].deployments[?status==`PRIMARY`].taskDefinition' --output text
    Devuelve algo como arn:aws:ecs:us-east-1:…:task-definition/soterex-staging-web:NN. Guardá ese NN (en este runbook, REVISION_BUENA).
  • Por qué primero: una tarea que arranca con DOCUMENTS_DISK_DRIVER=s3 sobre una imagen sin la librería da 500 en todo acceso a un soporte. Si el apply fuera antes, el siguiente deploy de cualquier cosa (un hotfix incluido) podría arrancar con la variable puesta y sin la librería.
  • No corras documentos:verificar en este paso. Con el disco local, una tarea puntual de run-artisan-command.yml tiene su propio disco, vacío: todas las filas figurarían sin archivo y el número no significaría nada.

Paso 2 — terraform apply de Staging, a mano y desde tu máquina ​

bash
cd infra/terraform/environments/staging
terraform init
terraform plan -out=tfplan

Con las mismas variables de siempre (terraform.tfvars o TF_VAR_…); cors_allowed_origins tiene que ser el origen del frontend, https://soterex.stag.cislatam.net, no la URL de la API. Leé el plan antes de aplicar. Tiene que mostrar esto, y nada más:

QuéCambio
module.documents.aws_s3_bucket.documents (soterex-staging-documents-<id de cuenta>) y sus seis recursos: ownership controls, public access block, cifrado, versionado, ciclo de vida y política del bucketse crean
module.ecs.aws_iam_role_policy.task_documents (soterex-staging-documents-storage, en el task role)se crea
module.ecs.aws_ecs_task_definition.web y .queuese reemplazan, con tres variables nuevas en el entorno: DOCUMENTS_DISK_DRIVER, DOCUMENTS_BUCKET y AWS_DEFAULT_REGION
module.scheduler.aws_scheduler_schedule.soterex_send_request y module.scheduler.aws_iam_role_policy.scheduler_run_taskse modifican en el lugar, por arrastre: apuntan por ARN a la task definition web (task_definition_arn = module.ecs.web_task_definition_arn), que cambia de revisión. El schedule sigue DISABLED
Output documents_bucket_namenuevo

Si ves algo más, no apliques. Salvo una cosa, que es esperable: si no hubo ningún apply desde el 2026-10-02, el estado de Terraform guarda todavía el CORS_ALLOWED_ORIGINS equivocado del incidente (la URL de la API, https://api.…; el arreglo en vivo fue manual y quedó pendiente "hasta que el Terraform se vuelva a aplicar", más abajo). En ese caso el plan va a mostrar ese valor pasando de https://api.… a https://soterex.stag.cislatam.net dentro del JSON de las task definitions: es el cambio correcto. Lo que no es esperable es cualquier otro origen, y lo que hay que exigir es que la revisión nueva tenga CORS_ALLOWED_ORIGINS igual a https://soterex.stag.cislatam.net, el origen del frontend. Y prevent_destroy está puesto en el bucket: un plan que quiera borrarlo o reemplazarlo se corta solo.

bash
terraform apply tfplan

Qué esperar: Apply complete! sin errores y documents_bucket_name = "soterex-staging-documents-…" en los outputs. El permiso del task role rige desde que termina el apply, también para las tareas que ya corren; lo que todavía no cambió es la variable de entorno.

No uses el workflow terraform-apply.yml para este paso. Planea y aplica en el mismo job, sin una pausa en el medio para leer el plan (según su propio comentario, solo el Environment de Producción exige reviewers). Con el antecedente del CORS, el plan se lee antes.

Entre este paso y el siguiente, no lances run-artisan-command.yml ni nada que registre una revisión nueva desde la última de la familia. El apply deja esa última revisión con image = …:initial, una imagen que no existe: el servicio sigue corriendo la revisión que ya tenía, pero un comando artisan puntual (que usa la familia, o sea la última revisión) no arrancaría.

Paso 3 — Un deploy más, que tome las variables ​

deploy-staging.yml arma la task definition nueva a partir de la última revisión de la familia, no de la que corre el servicio. Recién este deploy hereda DOCUMENTS_DISK_DRIVER=s3 y es el momento en que la app pasa a S3.

  • Cómo disparar: lo más simple es re-correr el job «Backend → AWS (Staging)» del deploy del paso 1 (GitHub → Actions → Re-run jobs). Desde el 2026-10-04 el push de la imagen tolera que el tag ya exista en ECR (el tag es el SHA y es inmutable, pero la imagen del intento anterior es la buena para ese commit), y la task definition se vuelve a renderizar desde la última revisión de la familia, que ya trae las variables de S3 (ver «Cómo recuperarse»). Esa vía se usó el 2026-10-07 y funcionó («Resultado de la primera vez»): si el job corta en el docker push, la alternativa es un commit nuevo en staging: sirve cualquier cambio que ya estuviera esperando en main; si no hay ninguno, un commit vacío (git commit --allow-empty -m "chore: redeploy para tomar las variables de S3") y el PR a staging.
  • Qué esperar: deploy verde y el servicio web estable. Comprobá que la revisión nueva trae la imagen del deploy (no :initial) y el disco en s3:
    bash
    aws ecs describe-task-definition --region us-east-1 --task-definition soterex-staging-web \
      --query 'taskDefinition.{revision:revision,imagen:containerDefinitions[0].image,disco:containerDefinitions[0].environment[?name==`DOCUMENTS_DISK_DRIVER`].value|[0]}'
    imagen termina en el SHA del commit y disco es "s3".

Paso 4 — Verificación ​

En este orden, porque cada prueba descarta una causa distinta:

  1. Preflight de CORS (tras todo apply que toque ecs):
    bash
    curl -si -X OPTIONS https://api.soterex.stag.cislatam.net/me \
      -H 'Origin: https://soterex.stag.cislatam.net' -H 'Access-Control-Request-Method: GET' | grep -i access-control-allow-origin
    Tiene que devolver access-control-allow-origin: https://soterex.stag.cislatam.net.
  2. Subir un soporte real desde la app, en una transacción ACCEPTED de prueba (si no hay, demo:seed-accepted 5 con el workflow de artisan, recién ahora que el paso 3 ya dejó la familia en una imagen que existe). Un JPG de 100 KB alcanza: el documento aparece con el tilde. Esta es la primera escritura real contra el bucket y la que confirma o descarta la ACL private (ADR-019). Si da 503 con DOCUMENT_STORAGE_UNAVAILABLE (o 500), el detalle no está en la respuesta (a propósito: con APP_DEBUG=true el mensaje del SDK trae el bucket, con el id de la cuenta, y la clave del objeto) sino en el log (/ecs/soterex-staging/web en CloudWatch), en la línea «TransactionDocumentController: no se pudo guardar el soporte», con la clase de la excepción y su mensaje:
    • AccessControlListNotSupported: es la ACL. Plan B, solo de configuración: en backend/config/filesystems.php, en la rama s3 del disco documents, agregar 'options' => ['ACL' => 'bucket-owner-full-control'] y promover (un commit, sin apply). Está verificado que reemplaza el private del PutObject (DocumentsDiskS3ConfigTest) y es la ACL que AWS documenta como aceptada con las ACL deshabilitadas. No sirve sacar 'private' de TransactionDocumentService::store(): el adaptador manda la ACL igual. Si ni eso, el plan C es escribir con el cliente del SDK, sin ACL (comentario de store()).
    • AccessDenied sobre PutObject o HeadObject: falta un permiso del task role (probar con el simulador de IAM, abajo). Si el simulador da allowed para PutObject, GetObject, AbortMultipartUpload y ListBucket y el PutObject real sigue dando AccessDenied, sospechá de s3:PutObjectAcl: el adaptador manda x-amz-acl en cada PutObject y no se pudo confirmar contra AWS si S3 exige ese permiso para ese encabezado con las ACL deshabilitadas. La política no lo trae (el plan G1.2 fija las acciones y la ausencia de DeleteObject es el control). Agregarlo en task_access del módulo documents, acotado a bucket/*, es inocuo: con BucketOwnerEnforced S3 rechaza cualquier ACL que no sea la del dueño.
    • Class "…" not found con un nombre de Aws\S3 o de League\Flysystem\AwsS3V3: la imagen no tiene la librería: se saltó el paso 1.
  3. Abrirlo. Click en el nombre del documento: el preview carga. En DevTools el pedido da 200.
  4. El objeto está en el bucket, es privado y está cifrado, con la CLI de AWS (los demás comandos de verificación, incluido el simulador de IAM, están en infra/terraform/README.md, sección «Bucket de soportes de pago»):
    bash
    BUCKET=$(terraform -chdir=infra/terraform/environments/staging output -raw documents_bucket_name)
    aws s3 ls "s3://$BUCKET/transacciones/" --recursive | tail -3        # la clave es transacciones/<id>/<tipo>-<uuid>.<ext>
    aws s3api head-object --bucket "$BUCKET" --key "<clave>" --query '{cifrado:ServerSideEncryption,tamanio:ContentLength}'
    aws s3api get-public-access-block --bucket "$BUCKET"
    curl -s -o /dev/null -w '%{http_code}\n' "https://$BUCKET.s3.amazonaws.com/<clave>"
    Esperable: cifrado vale "AES256"; el bloqueo de acceso público trae los cuatro valores en true; y el curl sin credenciales da 403. Ningún comando imprime el contenido de un soporte.
  5. Sobrevive a un redeploy (la prueba que habría detectado el problema). Reemplazá las tareas sin construir nada y volvé a abrir el documento del punto 3:
    bash
    aws ecs update-service --region us-east-1 --cluster soterex-staging-cluster --service soterex-staging-web --force-new-deployment
    aws ecs wait services-stable --region us-east-1 --cluster soterex-staging-cluster --services soterex-staging-web
    Con tareas nuevas (disco nuevo, vacío) el documento se abre igual. Antes de G1 esta prueba daba 404.
  6. Las filas viejas, medidas. documentos:verificar (abajo) con --detalle. Abrir una de las listadas da el mensaje específico, no el genérico.
  7. El smoke de subida de la sección siguiente, con la matriz completa.

Cuando todo lo anterior está verde, recién ahí se le avisa a Magaly que puede volver a probar documentos (el apartado 2 de la respuesta del plan les pidió no repetirlo hasta entonces) y se hace la pregunta QC-4: si el error «No se pudo guardar el documento» se repite, que pasen usuario, hora, tipo y tamaño del archivo y el MTCN de la transacción para correlacionar con los logs del ALB y del WAF. El mensaje al cliente es un borrador que manda Carlos.

Resultado de la primera vez de G1 en Staging (2026-10-07) ​

Lo que se hizo y lo que dio, con los valores reales (cuenta 810076098132, región us-east-1):

PasoQué se hizoResultado
1Promoción #96 (a47ace2), con el disco todavía localDeploy verde; el servicio quedó en soterex-staging-web:92
2terraform apply a mano (10 recursos creados, 2 modificados, 2 destruidos)Apply complete!; un plan posterior da «No changes» (dos veces)
3Re-run del job «Backend → AWS (Staging)» del deploy del paso 1 (intento 2 del run), sin commit nuevoVerde. Registró las revisiones 94 y 95; el servicio quedó en la 95, con la imagen sha-a47ace283a13…, DOCUMENTS_DISK_DRIVER=s3 y DOCUMENTS_BUCKET=soterex-staging-documents-810076098132; 1 de 1 tareas, un solo deployment en COMPLETED
4.1Preflight de CORS (hecho tras el apply)access-control-allow-origin correcto
4.2 y 4.3Subir un soporte real (una carta en PDF de 880 KiB) y abrirloOK. Quedó en el bucket como transacciones/<id>/carta-<uuid>.pdf. S3 aceptó la ACL private: no hizo falta el plan B ni s3:PutObjectAcl
4.4El bucket y el objetoget-public-access-block con los cuatro en true; get-bucket-encryption en AES256 (SSE-S3, con SSE-C bloqueado); head-object con AES256, application/pdf y 901.106 bytes
4.5--force-new-deploymentLa tarea cambió (6ad835b1… → 2afd0859…) y el soporte se abrió igual: el archivo vive en S3 y no en el disco del contenedor

Lo que quedó sin medir (sigue abierto, no es un fallo):

  • El curl sin credenciales contra el bucket (tiene que dar 403) y los demás comandos del punto 4 de la verificación.
  • documentos:verificar --detalle y el smoke de subida con la matriz completa (puntos 6 y 7).
  • La revisión de security de G1: el plan la exige y nunca se hizo. Es un bucket con identificaciones.
  • Avisarle a Magaly que ya puede volver a probar documentos, y la pregunta QC-4.

Qué se aprendió, para la próxima vez (producción incluida):

  • Cada deploy registra dos revisiones de la familia web, no una: la primera la usa el RunTask de las migraciones y la segunda es la del servicio (por eso la revisión pasó de la 93 a la 95). No es un deploy duplicado.
  • No hace falta el commit vacío. Re-correr el job alcanzó, porque el push de la imagen tolera el tag existente (desde el 2026-10-04) y la task definition se renderiza desde la última revisión de la familia, que ya traía las variables.
  • --force-new-deployment una sola vez. Si se repite mientras el primero está en curso, aparecen dos deployments IN_PROGRESS a la vez y la espera se alarga. Para esperar, usar el aws ecs wait services-stable del punto 5, no repetir el comando.
  • Con una sola tarea, ECS tarda unos minutos en retirar la vieja después de que la nueva pasa el health check, y mientras conviven las dos el balanceador puede llevarte a cualquiera. Abrir el soporte en ese momento no prueba nada (la vieja es la que lo escribió): hay que esperar a que list-tasks muestre una sola tarea, distinta de la anterior.
  • Si aws s3 ls no imprime nada, no es un error: el bucket está vacío. Un fallo imprime AccessDenied o similar.

Si algo falla: volver atrás ​

El destino es la revisión que anotaste en el paso 1 (REVISION_BUENA), que no tiene DOCUMENTS_DISK_DRIVER y por eso vuelve al disco local (con su defecto original: los soportes se pierden en cada deploy).

No alcanza con apuntar el servicio a esa revisión. deploy-staging.yml renderiza la task definition siguiente desde la última revisión de la familia, y la última es la del paso 3, con DOCUMENTS_DISK_DRIVER=s3: cualquier deploy posterior (un hotfix incluido) volvería a poner S3 sin avisar, y un terraform apply también. Es la misma trampa del CORS. Por eso la vuelta atrás registra una revisión nueva copiada de la buena, para que pase a ser la última de la familia, y apunta el servicio a ella (hay que repetirlo con la familia soterex-staging-queue si querés que el worker quede igual):

bash
aws ecs describe-task-definition --region us-east-1 --task-definition soterex-staging-web:REVISION_BUENA --query taskDefinition \
  | jq 'del(.taskDefinitionArn,.revision,.status,.requiresAttributes,.compatibilities,.registeredAt,.registeredBy)' > /tmp/td-web.json
aws ecs register-task-definition --region us-east-1 --cli-input-json file:///tmp/td-web.json --query taskDefinition.revision
aws ecs update-service --region us-east-1 --cluster soterex-staging-cluster --service soterex-staging-web \
  --task-definition soterex-staging-web:REVISION_NUEVA --force-new-deployment

Mientras el Terraform conserve las tres variables (DOCUMENTS_DISK_DRIVER, DOCUMENTS_BUCKET y AWS_DEFAULT_REGION en el módulo ecs), el próximo apply las vuelve a registrar. Para quedarse en disco local hay que sacarlas del módulo, en un commit, antes de volver a aplicar.

Lo subido a S3 mientras tanto no se pierde, pero la app deja de verlo hasta volver a s3. El bucket se queda: tiene prevent_destroy. Si el problema fue un apply que dejó algo mal (CORS, por ejemplo), la receta es la de «CORS roto tras un terraform apply».

Lo que el bucket guarda, y quién puede leerlo ​

Datos que hay que tener presentes mientras Staging reciba soportes con datos personales:

  • Los errores del almacenamiento no se ven en el navegador. Subir o abrir un soporte con S3 caído da un 503 con DOCUMENT_STORAGE_UNAVAILABLE y la pantalla dice «Error del servidor, avisá a soporte»; el detalle va al log de CloudWatch. Antes de esto, un 500 con APP_DEBUG=true (todo ambiente que no sea producción) devolvía a cualquiera el mensaje del SDK con el bucket (id de la cuenta) y la clave. Aun así, no compartas capturas de la pestaña Network ni del log sin mirarlas.
  • demo:reseed --wipe-only deja datos personales en el bucket, para siempre. Su backup previo escribe bajo backups/ del mismo bucket (el PutObject está permitido): el JSON de transactions (beneficiario, teléfono, fecha de nacimiento y el MTCN, que es la credencial de cobro), la auditoría y una copia de cada soporte, con la clave …/files/<id>.<ext> (desde G1 sin el nombre original, que suele ser el de la persona). El task role no puede borrar y ninguna regla de ciclo de vida toca backups/: se limpia a mano, con credenciales de administración y versiones incluidas. Tampoco borra los soportes de las filas que elimina: quedan huérfanos en el bucket por la misma razón.
  • run-artisan-command.yml equivale a poder leer todos los soportes. Corre un comando artisan de texto libre con el task role, que puede leer el bucket entero, y no deja rastro en la Auditoría de la app. En Staging solo lo frena lo que tenga configurado el Environment staging de GitHub.
  • Nadie registra los accesos al bucket por fuera de la app. TRANSACTION_DOCUMENT_VIEWED solo existe si la lectura pasa por la app; el módulo no prende logs de acceso de S3 ni eventos de datos de CloudTrail (decisión pendiente para Producción, en su checklist).

Cómo usar documentos:verificar ​

Cuenta las filas de transaction_documents cuyo archivo no está en el disco. Es de solo lectura: no borra filas (un soporte no se borra), no escribe ni borra archivos y no audita. Se corre con GitHub → Actions → "Ejecutar comando artisan (manual)", environment: staging y command (ese workflow corre cualquier comando artisan con el task role, que puede leer todos los soportes; el Environment staging decide si pide reviewers, y desde el repositorio no se ve):

documentos:verificar --detalle

Salida de ejemplo (con datos inventados; los ids son UUID):

Falta el archivo: soporte 0198f3a2-7c41-7d0e-9b1a-3f5e8c2d4a10 (transacción 0198f2c4-51aa-7b3c-8e02-6d1f9a7b3c55 RS-1002, IDENTIFICACION_ANVERSO, disco documents, subido 2026-10-02 14:31)
Falta el archivo, ya reemplazado por uno más nuevo: soporte 0198f3a2-9d12-71f0-a4c6-2b8e7d5f1c33 (transacción 0198f2c4-51aa-7b3c-8e02-6d1f9a7b3c55 RS-1002, CARTA, disco documents, subido 2026-10-02 14:33)
Soportes revisados: 14
Con archivo: 3
Sin archivo: 10
Sin archivo pero ya reemplazados por uno más nuevo: 1 (no hace falta repararlos)
  • Sin --detalle solo imprime los totales y una línea que dice que no se cambió nada. Con --detalle suma una línea por soporte faltante: id, transacción, RS-, tipo, disco y fecha. Nunca el nombre original del archivo (suele ser el de la persona), la ruta ni el MTCN: la salida de este workflow queda en CloudWatch y en el log de Actions sin enmascarar. (El log de errores de la app, cuando un disco no se puede consultar, sí lleva el mensaje de la excepción, y el de S3 puede traer la clave del objeto, transacciones/<id>/<tipo>-<uuid>.<ext>: ids y un tipo, nada personal.)
  • «Sin archivo» cuenta solo el soporte vigente de cada (transacción, tipo): el que la pantalla muestra y hay que reparar. Reemplazar un soporte no pisa la fila anterior, inserta una nueva (la tabla es inmutable), así que la fila vieja sin archivo sigue existiendo; por eso se cuenta aparte, como «ya reemplazados por uno más nuevo», y no hace falta repararla.
  • Código de salida. 0 si pudo verificar todo, aunque haya soportes sin archivo (es el resultado esperado, no un error de la corrida). 1 si alguna fila no se pudo consultar y la salida suma No se pudieron verificar: N: un permiso de S3 que falta (sin s3:ListBucket, un objeto que no existe da 403 y cuenta como "no se pudo"), un corte de red o un disco no configurado. En ese caso el resultado no es confiable: se mira el log de CloudWatch y se corrige antes de creerle al número. El workflow muestra ❌ El comando terminó con exit code 1 y no hace falta tomarlo como un fallo del comando.
  • Cuándo correrlo. Solo con el disco ya en S3 (después del paso 3) y fuera de la ventana entre el paso 2 y el 3. Cada fila es un HeadObject, pensado para los cientos o pocos miles de soportes que hay: no es una operación para correr en cada request.
  • Qué hacer con el resultado. Los soportes listados como Falta el archivo: se vuelven a subir, con Reemplazar (un Supervisor con alcance sobre el PDV o un Admin; con la transacción todavía ACCEPTED, cualquier Cajero con escritura. Quien pagó no puede reemplazar un soporte ya cargado, aunque su archivo falte: solo sube los tipos que nunca cargó, como la papeleta firmada). No hay reparación automática a propósito. Después de re-subir, «Sin archivo» baja en uno por cada soporte reparado y «reemplazados» sube en uno: si «Sin archivo» no baja, lo que se subió no quedó en el bucket, y ahí sí hay que mirar si algo escribe en otro lado.
  • Antes de que el cliente pague. El chequeo que bloquea el pago (Carta e identificación, ADR-008) mira filas, no archivos. Una transacción ACCEPTED con la Carta y la identificación subidas antes de G1 tiene las filas y no los archivos: la pantalla la deja pagar igual, sin ningún soporte guardado. Por eso, una vez en S3, repetí documentos:verificar --detalle y volvé a subir la Carta y la identificación de las transacciones que todavía están ACCEPTED (se ubican por el RS- de la salida) antes de avisarle al cliente que puede probar. Hacer que ese chequeo mire también el archivo costaría un HeadObject por soporte en cada pago: es una decisión aparte, no se tomó acá.

Prueba de humo de subida (después de cada apply que toque waf o ecs) ​

Es la regla P3-6 del plan de ajustes v3: tras cada terraform apply que toque el módulo waf o el ecs, y tras el deploy que levanta sus cambios, se sube un archivo real por el camino real (navegador → API en el ALB, detrás del WAF → nginx → PHP) y se abre. Existe porque dos incidentes de este ambiente se vieron recién cuando un usuario lo probó: el CORS roto del 2026-10-02 y la regla SizeRestrictions_BODY del WAF, que bloqueaba toda subida de más de ~8 KB (2026-10-01). Ninguna prueba automática sube un archivo por el ALB.

Tiempo: 10 minutos el mínimo, media hora la matriz completa. Quién: quien corre el apply (Carlos).

Qué se necesita: una transacción ACCEPTED de prueba y archivos reales de tamaño conocido. Para armar los archivos, el repo trae tres de 100 a 700 bytes en backend/tests/fixtures/ (soporte.jpg, soporte.pdf y soporte.png); esta función les agrega ceros después del contenido hasta el tamaño pedido en MB enteros (con 0 no sirve). El tipo se decide por los primeros bytes (el backend usa el contenido real, no la extensión), así que siguen siendo un JPG, un PDF y un PNG válidos para la subida:

bash
rellenar() { cp "$1" "$2"; head -c "$(( $3 * 1024 * 1024 - $(wc -c < "$1") ))" /dev/zero >> "$2"; }
rellenar backend/tests/fixtures/soporte.jpg /tmp/humo-1mb.jpg 1
rellenar backend/tests/fixtures/soporte.pdf /tmp/humo-15mb.pdf 15
# Para la matriz completa, los demás tamaños y tipos:
rellenar backend/tests/fixtures/soporte.png /tmp/humo-2mb.png 2
rellenar backend/tests/fixtures/soporte.png /tmp/humo-19mb.png 19
rellenar backend/tests/fixtures/soporte.pdf /tmp/humo-21mb.pdf 21     # el que la pantalla no tiene que dejar salir

Los de 100 KB de la matriz no salen de rellenar: usá un archivo real chico (una foto o un PDF de ese tamaño) o los propios fixtures, que ya pesan menos de 1 KB. Un archivo de relleno no es una buena prueba de que se ve bien: sirve para probar el viaje (WAF, nginx, PHP, S3) y que los bytes lleguen enteros. Para probar que un documento real se ve, usá una foto o un escaneo de verdad, pero de prueba: no subas el documento de una persona real a Staging. La app no puede borrar objetos y el objeto vigente no expira: un archivo subido ahí queda hasta que Carlos lo borre a mano, con credenciales de administración y con sus versiones (el bucket está versionado: un borrado deja una marca, no libera la versión).

Pasos (cada uno, desde la pantalla de Pago, con DevTools → Network abierto):

  1. Preflight de CORS: el curl del paso 4.1 del runbook de arriba.
  2. Subir el de 1 MB (humo-1mb.jpg) como cualquier tipo de documento. Esperable: POST …/documentos responde 201; el documento aparece con el tilde.
  3. Subir el de 15 MB (humo-15mb.pdf). Esperable: 201. Un 403 sin cabecera Access-Control-Allow-Origin es la firma de un bloqueo del WAF (lo habitual es una regla del Core Rule Set sobre el cuerpo): se mira Sampled requests del Web ACL. Un 413 es nginx (client_max_body_size 30m); un 422 con errors.archivo es la app.
  4. Abrir los dos. El preview carga. Con S3, comprobar que el tamaño del objeto es el del archivo: aws s3api head-object --bucket "$BUCKET" --key "<clave>" --query ContentLength tiene que dar 1048576 y 15728640.

Matriz completa (el primer despliegue de G1; el resto de las veces alcanzan el 1 MB y el 15 MB):

ArchivoResultado esperado
PDF, JPG y PNG de 100 KB, 2 MB y 19 MB201 y se abren
Archivo de 21 MBLa pantalla avisa «El archivo pesa … MB y el máximo es 20 MB. Probá con uno más chico.» y no sale ningún POST (en Network no aparece)
Un .zip o una foto HEIC«El archivo tiene que ser PDF, JPG o PNG.» y tampoco sale ningún POST
Un archivo de 20 a 25 MB mandado por API directo, sin la pantalla422 de Laravel (errors.archivo)

Las capas de límite, de la de adentro hacia la de afuera: la pantalla corta en 20 MB; Laravel valida 20 MB (max:20480 KB); PHP descarta por encima de 25 MB (upload_max_filesize); y nginx devuelve 413 por encima de 30 MB (client_max_body_size). Las dos últimas están en backend/docker/php-uploads.ini y backend/docker/nginx.conf y existen para que la validación de la app sea la que manda.

Si falla, no se sigue con la prueba del cliente: se anota qué respondió Network (status y cabeceras), la hora, y se corrige antes de avisarle a nadie.

Corregir las cajas afectadas por pagos de prueba con transferencia (G3) ​

  • Cuándo usarlo: una sola vez, después de desplegar G3 a Staging (el medio de pago pasa a ser solo efectivo, ver ADR-011), si la consulta del paso 1 devuelve filas. Si no devuelve ninguna, no hay nada que corregir y esta sección termina ahí.
  • Dónde: solo Staging. Producción nunca se aplicó y no tiene pagos que corregir.
  • Riesgo: medio. Escribe en el ledger de caja de Staging (plata de prueba) y lo que se carga no se puede borrar.
  • Quién: Carlos, con alguien que abra y cierre cajas (Cajero, Supervisor o Admin) y alguien que ajuste (Tesorería o Admin). Nada de esto lo corre una sesión autónoma: son cargas en el ledger de un ambiente que el cliente está probando.
  • Cuánto lleva: unos minutos por caja afectada (abrir, ajustar, cerrar, mirar), más lo que cueste destrabar una caja vencida.

Por qué hace falta. Hasta G3, applyCashBoxDiscount no leía el medio de pago: un pago por transferencia descontaba la caja del PDV como si fuera efectivo (RV3-13), y por eso la caja reporta menos efectivo del que tiene. G3 evita que vuelva a pasar (la API responde 422 si le mandan TRANSFERENCIA), pero no toca lo que ya pasó. Los datos de pago de una PAID son inmutables (ADR-011) y el ledger de caja también (ADR-005): el PAGO no se borra ni se edita. Lo que se hace es agregar un movimiento de signo contrario, un AJUSTE con su motivo, y la historia queda completa: el pago original más la corrección que dice por qué existe. Prefondeo País y Holding no se tocan: ya reflejaban el pago bien, porque una transferencia sale de Tesorería.

Antes de empezar:

  • [ ] G3 está desplegado. Prueba: en Pago, «Confirmar pago» ofrece Efectivo como única opción. Si no, entran más pagos por transferencia mientras se corrige.
  • [ ] Se sabe quién va a abrir y cerrar y quién va a ajustar. Tesorería no abre ni cierra cajas y el Supervisor no ajusta: la apertura y el cierre son del Cajero, el Supervisor o el Admin, y el ajuste de Tesorería o el Admin (ver Fondeo de caja).
  • [ ] Se le avisó a Magaly (CIS-EC) qué va a ver en los reportes (ver «Qué cambia para el cliente» más abajo).
  • [ ] Se decidió entre el camino de los ajustes y el de demo:reseed (ver «La alternativa»). El plan recomienda los ajustes cuando son pocas cajas y demo:reseed cuando son varias; qué es «varias» lo decide Carlos mirando el resultado del paso 1, el plan no fija un número.

Paso 1. Listar las cajas afectadas (solo lectura) ​

La consulta suma, por caja y moneda, lo que salió por pagos con transferencia, cuánto de eso ya se corrigió con el motivo de este procedimiento y cuánto falta. Por eso se puede volver a correr: después de cargar un ajuste, falta_corregir tiene que dar 0. Los nombres de tablas y columnas son los de las migraciones (cash_movements, cash_boxes, stations, transactions.delivery_type).

sql
WITH pagos AS (
    SELECT m.cash_box_id, m.currency, COUNT(*) AS pagos, SUM(m.amount_local) AS suma
    FROM transactions t
    JOIN cash_movements m ON m.transaction_id = t.id AND m.type = 'PAGO'
    WHERE t.status = 'PAID' AND t.delivery_type = 'TRANSFERENCIA'
    GROUP BY m.cash_box_id, m.currency
), correcciones AS (
    SELECT m.cash_box_id, m.currency, SUM(m.amount_local) AS suma
    FROM cash_movements m
    WHERE m.type = 'AJUSTE'
      AND m.motivo = 'Otro'
      AND m.motivo_detalle = 'Corrección de pago por transferencia de prueba'
    GROUP BY m.cash_box_id, m.currency
)
SELECT st.internal_code               AS pdv,
       cb.number                      AS caja,
       p.currency                     AS moneda,
       p.pagos                        AS pagos,
       -p.suma                        AS a_corregir,
       COALESCE(c.suma, 0)            AS ya_corregido,
       -p.suma - COALESCE(c.suma, 0)  AS falta_corregir
FROM pagos p
JOIN cash_boxes cb ON cb.id = p.cash_box_id
JOIN stations st   ON st.id = cb.station_id
LEFT JOIN correcciones c ON c.cash_box_id = p.cash_box_id AND c.currency = p.currency
ORDER BY st.internal_code, cb.number, p.currency;

Cómo se lee: cada fila es una caja (PDV y número) con pagos por transferencia. Los PAGO se guardan negativos, por eso a_corregir es la suma con el signo cambiado: lo que hay que devolverle a la caja. falta_corregir es el monto del ajuste a cargar en el paso 2.

  • Sin filas: no hay nada que corregir. Terminó.
  • moneda distinta de la moneda de pago vigente del país: pará y avisá. El formulario de ajuste carga en la moneda de pago que el país tiene hoy (pago_en_moneda_local en Países), así que un ajuste no corregiría un pago que se hizo en la otra. Guatemala paga en USD, y no debería pasar a menos que alguien haya cambiado esa opción.
  • Dos filas de la misma caja (una por moneda): es un ajuste por fila.

Para ver pago por pago, con el MTCN, y para el cotejo del paso 3 (no trae nombres, mails ni datos del beneficiario):

sql
SELECT st.internal_code AS pdv, cb.number AS caja, t.mtcn,
       m.amount_local AS monto, m.currency AS moneda,
       m.created_at AS pagado_el, cs.status AS sesion, cs.opened_at AS sesion_abierta_el
FROM transactions t
JOIN cash_movements m ON m.transaction_id = t.id AND m.type = 'PAGO'
JOIN cash_boxes cb    ON cb.id = m.cash_box_id
JOIN stations st      ON st.id = cb.station_id
JOIN cash_sessions cs ON cs.id = m.cash_session_id
WHERE t.status = 'PAID' AND t.delivery_type = 'TRANSFERENCIA'
ORDER BY st.internal_code, cb.number, m.created_at;

Y para saber cuántas PAID por transferencia no tocaron ninguna caja (un país sin módulo Caja, o pagos anteriores a él): esas no tienen nada que corregir.

sql
SELECT COUNT(*) FILTER (WHERE m.id IS NOT NULL) AS con_pago_de_caja,
       COUNT(*) FILTER (WHERE m.id IS NULL)     AS sin_pago_de_caja
FROM transactions t
LEFT JOIN cash_movements m ON m.transaction_id = t.id AND m.type = 'PAGO'
WHERE t.status = 'PAID' AND t.delivery_type = 'TRANSFERENCIA';

Cómo correrlas. Son SELECT: no escriben nada. run-artisan-command.yml no sirve para esto: arma el comando con split(' ') (no hay forma de pasarle SQL) y deja la salida sin enmascarar en CloudWatch y en el log de la corrida de Actions. Las consultas listan MTCN y montos, nunca nombres ni mails, pero igual no tienen por qué quedar en esos logs: corrélas por el canal de solo lectura que tengas a la base de Staging. diagnostico:v3 (G0.6 del plan v3, cuando esté en Staging) da la consulta 6 como conteos e ids, sin montos: sirve para saber cuántas cajas son, no para saber cuánto ajustar. Sin acceso a la base, se reconstruye desde la app caja por caja: Saldos, historial de la caja filtrado por tipo Pago (cada pago muestra su MTCN y su monto), y la ficha de cada transacción dice con qué medio se pagó. Es lento y sirve para pocas cajas. No uses el Excel de Cumplimiento para esto: trae los datos personales de todas las personas del país.

Paso 2. Corregir cada caja con un ajuste (de a una) ​

Una caja por vez, en este orden. Quien abre una caja no puede tener otra abierta: cerrá la anterior antes de abrir la siguiente (el sistema responde USER_ALREADY_HAS_OPEN_CASH_BOX).

  1. Mirar el estado de la caja en Saldos (con Admin o Tesorería aparecen primero los totales por PDV; elegí el PDV y después la caja) y anotar su saldo antes: lo vas a necesitar en el paso 3.

    • Cerrada. Un Cajero, un Supervisor o el Admin con acceso a ese PDV la abre. El saldo inicial no se tipea: es el que dejó el último cierre.
    • Abierta hoy (por quien sea). No hace falta abrir nada: andá al punto 2.
    • Vencida (abierta desde un día anterior). Con una caja vencida el ajuste está bloqueado. Alguien con permiso de apertura y cierre la cierra y la vuelve a abrir (ver Apertura y cierre de caja; hoy la puede cerrar cualquiera con ese permiso sobre el PDV, y la entrega G6 del plan v3 lo acota a quien la abrió, el Supervisor y el Admin del PDV: con el Admin no hay duda en ninguno de los dos casos). Si el cierre se frena con «hay pagos de esta sesión con documentación pendiente» (PENDING_PAYMENT_DOCUMENTS), es porque algún pago de esa sesión tiene documentos sin subir: las PAID viejas por transferencia siguen pidiendo sus cuatro documentos, a propósito (son historia). El aviso lista qué MTCN y qué falta; se sube desde la ficha de cada transacción (subir sigue permitido con la caja vencida) y se vuelve a cerrar. Con datos de prueba alcanza con archivos de prueba válidos.
  2. Cargar el ajuste. Tesorería o el Admin, en Saldos, con la caja abierta hoy, bloque de fondeo y ajuste:

    • pestaña Ajuste (no Fondeo);
    • Monto del ajuste: el falta_corregir de la consulta, positivo, en la moneda que muestra la pantalla;
    • Motivo: Otro;
    • Descripción: exactamente Corrección de pago por transferencia de prueba. Tiene que ser textual: es lo que reconoce la consulta del paso 1 para decir que esa caja ya se corrigió;
    • Ajustar.

    Un solo ajuste por caja y moneda, con el total, no uno por pago.

  3. Cerrar la caja (la cierra quien la abrió para esto). Si el ajuste se cargó sobre una caja que ya estaba abierta de hoy y alguien la está usando, no se cierra: se la deja como estaba.

  4. Pasar a la caja siguiente.

Si cargaste un monto equivocado, no hay nada que borrar: se corrige con otro ajuste del signo contrario (un ajuste negativo es válido mientras no deje la caja en negativo) y se explica en la descripción. Los dos quedan en la historia.

Paso 3. Comprobar el resultado ​

Por cada caja corregida:

  1. El saldo. El saldo de la caja después tiene que ser el saldo de antes menos la suma de los PAGO por transferencia de esa caja. Como los PAGO son negativos, esa resta suma: saldo después = saldo antes + a_corregir. En datos de prueba no hay arqueo físico con qué compararlo, así que el control es esta cuenta.
  2. La consulta del paso 1 vuelta a correr: falta_corregir en 0 en todas las filas.
  3. El extracto del PDV: menú Tesorería › Fondeo PDVs, pestaña PDV. Tiene que mostrar cada PAGO (la referencia es el MTCN) y el AJUSTE con el motivo Otro — Corrección de pago por transferencia de prueba, y el saldo corrido del último renglón coincide con el saldo actual del PDV.
  4. La cuenta del país no se movió por esto. Prefondeo País y Holding quedan como estaban: lo único que cambia es la caja y, por derivación, el disponible para distribuir del país.

Qué cambia para el cliente (hay que contárselo) ​

Nada se borra, así que los pagos por transferencia siguen apareciendo como pagos y el ajuste aparece como un ajuste:

  • El ajuste cae en la sesión del día en que se hace el arreglo, no en la de los pagos que corrige. En Reportes › Cierres por día se ve en la columna Ajustes de ese día, un día en que no hubo ningún arqueo.
  • Los días anteriores no se reescriben: su Saldo final sigue siendo el que figuraba, con la plata de más descontada. Desde el día del arreglo vuelve a ser el real.
  • En Reportes › Cajas el resumen y el detalle cuentan los pagos por transferencia en Pagos (cant.) y Pagos (total) del período, y el ajuste en Ajuste. El Saldo actual de la caja es el corregido.
  • Cumplimiento no cambia: las PAID por transferencia siguen saliendo con su medio de pago y su cuenta (columnas 16 y 17).
  • Auditoría guarda un evento CASH_ADJUSTED por cada ajuste, con el monto y el motivo, y uno de apertura y de cierre por cada vez que se abrió y cerró una caja para esto.

La alternativa: demo:reseed (cuándo conviene y cuánto cuesta) ​

demo:reseed, corrido con run-artisan-command.yml contra staging (solo corre en local y staging), borra todo el estado de prueba de Guatemala y lo vuelve a sembrar con fechas de hoy, ahora sin transferencias (G3.2). Conviene cuando son varias las cajas afectadas: ahí el trabajo de los ajustes (una apertura, un ajuste y un cierre por caja, más destrabar las vencidas) pesa más que volver a cargar los datos de prueba. Antes de elegirlo, lo que se pierde:

  • Todas las transacciones de Guatemala y sus documentos, incluidas las que cargó el cliente probando y las que Soterex creó contra el sandbox de Staging. Soterex está probando ahí: hay que avisarle. Desde G1 las filas de los documentos se van, pero los archivos no: en Staging el disco documents es el bucket S3 y el task role no puede borrar, así que quedan huérfanos en el bucket (ver «Lo que el bucket guarda»).
  • Los asientos de prefondeo de Guatemala (Holding y País), los movimientos de caja y los tipos de cambio.
  • Todas las cajas de Guatemala: el seeder vuelve a crear la Caja 1 de cada PDV, así que una caja extra dada de alta desde Estaciones no vuelve.
  • La Auditoría de demo (la marcada como sembrada por los seeders de demo).

No toca usuarios, roles, permisos, países ni PDVs. No es lo mismo que --wipe-only, que no vuelve a sembrar y deja Guatemala en cero con un respaldo previo a S3: para este caso no hace falta. Los ajustes, en cambio, conservan el trabajo de prueba del cliente y dejan rastro de qué pasó.

No hacer: editar o borrar a mano filas de cash_movements (el ledger es inmutable), cambiar el delivery_type de las PAID para «arreglarlas» (son datos del pago, ADR-011) ni correr db:seed para esto.

Cómo recuperarse (y cómo NO) ​

Re-lanzar el workflow de deploy sirve desde el 2026-10-04 (PR #76). Antes no: el repositorio de ECR tiene los tags inmutables y el tag es el SHA del commit, así que un rerun reconstruía el mismo commit, intentaba pushear un tag que ya existía y ECR lo rechazaba; el deploy se cortaba antes de tocar ECS (se probó el 2026-08-10 y falló justamente así). Hoy el push tolera ese error y sigue —la imagen del intento anterior es la buena para ese commit— y cualquier otro error de push sigue cortando el deploy. Los tags inmutables siguen siendo deseables: el rerun reusa la imagen, no la pisa.

Dos cosas que el rerun no hace: vuelve a renderizar la task definition desde la última revisión de la familia (no desde la que corre el servicio), así que sirve para terminar un deploy que se cortó pero no para volver atrás; y todavía no se usó en un caso real después del arreglo, así que si corta en el docker push la alternativa es el commit nuevo de abajo.

Para volver atrás, la imagen buena ya está en ECR y las revisiones viejas de la task definition siguen ACTIVE, así que alcanza con volver a apuntar los servicios ahí, sin construir nada (si la revisión buena no es la última de la familia, ver «Si algo falla: volver atrás»: apuntar el servicio no cambia lo que hereda el próximo deploy).

bash
aws ecs update-service --region us-east-1 --cluster soterex-staging-cluster --service soterex-staging-queue --task-definition soterex-staging-queue:14 --force-new-deployment

(Averiguar la revisión buena con describe-services: es la del deployment en ACTIVE, no la del PRIMARY que está fallando.)

La otra vía es pushear un commit nuevo a staging, que genera un SHA distinto y por lo tanto un tag nuevo. Sirve, pero es más lento y mezcla la recuperación con un cambio de código.

Para correr un comando de artisan puntual (un seeder, un tinker de diagnóstico) sin deployar, está run-artisan-command.yml, que se dispara a mano.

El branch staging no se toca sin OK explícito de Carlos — igual que production. Ver la estrategia de branching.

Terraform desde CI: no funciona todavía ​

Conviene saberlo antes de confiar en el semáforo verde de un PR de infra.

Staging se aplicó a mano, desde una laptop. terraform-apply.yml nunca corrió — cero ejecuciones desde que existe. terraform-plan.yml corrió sólo tres veces, todas fallidas. Los dos apuntan a soterex-terraform-apply-role, cuya trust policy exigía que el token viniera de ref:refs/heads/*, un claim que ninguno de los dos workflows presenta (declaran environment:, y cuando un job lo declara GitHub emite ese claim en lugar del de la branch). Encima el formato del sub cambió el 15/07/2026 y esa policy quedó con el viejo.

La trust policy ya está corregida en el código (infra/terraform/bootstrap/main.tf), pero bootstrap/ se aplica a mano: hasta que alguien corra ese apply, la de AWS sigue siendo la vieja.

El plan en PRs necesita además un rol aparte. No es un detalle a resolver de paso: el rol de apply crea VPCs, Aurora e IAM, y un PR puede editar el workflow que corre con esas credenciales. Que no sea asumible desde un pull request está bien puesto. Lo que falta es un rol de solo lectura (ReadOnlyAccess + bucket de estado + tabla de locks) para el plan. Hasta entonces ese job es advisory (continue-on-error) y no bloquea merges.

Nada de esto afecta al deploy de la app: deploy-staging.yml usa otro rol, con la trust policy bien puesta, y viene andando desde julio.

CORS roto tras un terraform apply desde CI (2026-10-02, resuelto el 2026-10-04) ​

Qué pasó. Desde el 2026-10-02 ~21:12 UTC el login de Staging no andaba: el navegador bloqueaba toda llamada del frontend a la API (Access-Control-Allow-Origin valía https://api.soterex.stag.cislatam.net, distinto del origen https://soterex.stag.cislatam.net). Se vio recién el 2026-10-04.

Causa. Los workflows terraform-apply.yml y terraform-plan.yml pasaban TF_VAR_cors_allowed_origins: secrets.STAGING_API_BASE_URL, o sea la URL de la API en vez de la del frontend. El terraform apply del 2026-10-02 01:06 UTC (el de la excepción de WAF para subir documentos) re-registró las task definitions con ese valor; el servicio no cambió (el Terraform ignora task_definition), pero el siguiente deploy (deploy-staging.yml renderiza la task definition desde la última revisión de la familia, no desde la que corre el servicio) heredó el valor equivocado y lo puso en producción de Staging. Con un único origen configurado, el backend responde siempre ese valor, así que cualquier origen distinto del configurado falla en el navegador y no en el plan.

Arreglo. (1) Los dos workflows pasan ahora el origen del frontend (Staging, el dominio público; Producción, el secret PROD_APP_URL, que hay que crear antes del primer apply de Producción). (2) La variable cors_allowed_origins de Terraform tiene una validation que rechaza vacío, http://, barra final y cualquier https://api.…. (3) En vivo, hasta que el Terraform se vuelva a aplicar: registrar una revisión de la task definition que corre el servicio (no la última de la familia: si ya incluye una imagen todavía no migrada, se estaría desplegando código nuevo sobre un esquema viejo) con CORS_ALLOWED_ORIGINS correcto y apuntar el servicio a ella.

Para no repetirlo. Después de cualquier terraform apply que toque el módulo ecs, comprobar el preflight: curl -si -X OPTIONS https://api.soterex.stag.cislatam.net/me -H 'Origin: https://soterex.stag.cislatam.net' -H 'Access-Control-Request-Method: GET' tiene que devolver access-control-allow-origin: https://soterex.stag.cislatam.net.

Costo: el NAT Gateway se comía $220/mes ​

Vale conocerlo antes de dimensionar producción, porque el mismo diseño escala el problema.

Una alerta de Cost Anomaly Detection (2026-08-09) mostró 163 GB/día pasando por el NAT Gateway, planos, ~$7.35/día. En un ambiente donde nadie opera. Ese patrón —idéntico todos los días, sin picos ni valles— no es gente usando el sistema: es algo automático.

Es el scheduler. Dispara una task de Fargate cada 5 minutos (288 por día) y cada arranque se baja la imagen entera de ECR, porque Fargate no comparte caché de imagen entre tasks. 163 GB ÷ 288 da ~580 MB por arranque, que es el tamaño de la imagen. Como no había ningún VPC endpoint, cada byte salía por el NAT y se pagaba a $0.045/GB.

Lo que más molesta es que el diseño era una optimización: el comentario del módulo dice que evita "pagar un contenedor prendido todo el día solo para el cron". Un contenedor chico 24/7 sale ~$15/mes.

Corregido y aplicado el 2026-08-10: un VPC Gateway Endpoint para S3 en modules/network. Es gratis —ni cargo por hora ni por GB— y es el que más rinde, porque las capas de las imágenes de ECR viven en S3.

El scheduler quedó apagado (2026-08-10). No hacía falta bajarle la frecuencia: en Staging la integración con Soterex sigue en modo mock, así que los 288 arranques diarios levantaban una task de Fargate para que Laravel decidiera no hacer nada. Se apaga con enabled = false en el módulo; el recurso sigue existiendo en DISABLED, así que volver a prenderlo es cambiar el flag y aplicar. Hay que volver a prenderlo cuando lleguen las credenciales de sandbox de Soterex — sin eso, M5 no ingesta nada aunque el resto esté listo.

Hay que volver a prenderlo para la integración C2P (2026-10-05, K6 de doc/plans/2026-10-05-alineacion-contrato-c2p-soterex.md). Ya no es una ingesta que nunca existió: Laravel tiene dos comandos con trabajo real en routes/console.php, ambos everyMinute():

ComandoQué haceSi el scheduler está apagado
notifications:deliverVacía el outbox de Notifications hacia Soterex (con reintentos)No sale ninguna notificación, ni el primer intento
c2p:expireCancela las transacciones de la API cuyo MTCN venció y notifica CANCELLEDNinguna vence

Frecuencia real y costo. El everyMinute() es el piso que declara Laravel; el techo lo pone EventBridge, que dispara schedule:run con rate(5 minutes) (modules/scheduler). En la práctica cada comando corre como mucho cada 5 minutos — un reintento "de 1 minuto" del outbox espera hasta el siguiente tick — y el costo vuelve a ser el de arriba: 288 arranques de Fargate por día (~580 MB de imagen cada uno; lo que se comía $220/mes era el NAT Gateway, que ya no existe en Staging, así que queda el cargo de las propias tasks). Sale alrededor de lo que costaría un contenedor chico 24/7; si molesta, la palanca es la frecuencia del tick (punto 1 de abajo), no volver a apagarlo.

El orden en routes/console.php importa: c2p:expire está registrado antes que notifications:deliver. schedule:run corre los comandos en serie y la entrega puede tardar hasta 8 minutos (su tope de --max-seconds), mientras que el vencimiento es corto: con la entrega primero, una corrida larga demoraría el vencimiento de los MTCN todo ese tiempo. No se arregla con runInBackground() (en ECS la tarea termina cuando termina schedule:run y mataría lo que quede en segundo plano), y SchedulerTest falla si se invierte el orden.

Cómo se prende. Es enabled = true en module "scheduler" de infra/terraform/environments/staging/main.tf, y entra en vigor solo con un terraform plan y apply que corre Carlos — el deploy automático al branch staging no toca Terraform. El recurso sigue existiendo en DISABLED, así que el único cambio del plan tiene que ser el state de aws_scheduler_schedule.soterex_send_request (DISABLED → ENABLED); si el plan muestra algo más, no aplicar. Estado al 2026-10-05: el cambio del flag no está hecho en este branch (el Terraform quedó fuera de lo que esta sesión pudo editar) y Carlos decidió no prenderlo por ahora: todavía no hay URL ni secret de Soterex (ver «Con el scheduler apagado»). El scheduler de Staging sigue apagado hasta que Soterex mande esos datos y se edite ese flag y se aplique.

Antes de prenderlo (en pausa junto con el resto) correr php artisan c2p:expire --dry-run en Staging (workflow de comando artisan) para ver qué vencería: el comando solo toca transacciones que entraron por la API (api_client_id no nulo), no los datos de demo, pero conviene verlo antes de que corra solo.

Queda por decidir:

  1. La frecuencia del tick, para cuando se vuelva a prender. Si el job real corre cada 30 minutos, un tick cada 30 son 6x menos arranques. Cambia comportamiento (la latencia máxima de cualquier tarea programada pasa a ser 30 min), así que no se toca sin confirmarlo. Ojo que con la C2P ya hay más de un job y el outbox espera latencias de minutos, no de media hora.
  2. Endpoints de tipo Interface (ecr.api, ecr.dkr, logs, secretsmanager). Cuestan ~$7.30/mes cada uno por AZ. Actualizado (ítem 1.3 del plan de reducción de costos AWS, 2026-09-21): ya no hay NAT Gateway en absoluto en Staging, no solo menos tráfico por él — las tareas de ECS/scheduler pasaron a subnet pública con IP propia en vez de depender del NAT. Mientras sigan ahí, estos endpoints son un ahorro más (evitarían salir a internet para hablar con AWS), no una dependencia. Si alguna vez se las vuelve a poner en subnet privada sin agregar NAT, dejan de ser opcionales: sin NAT y sin estos endpoints, esas tareas no tienen forma de autenticar contra ECR, escribir logs ni leer secrets — se rompería el deploy entero (ver el fix hecho en deploy-staging.yml/run-artisan-command.yml para el mismo problema en el RunTask de migraciones).

Para volver a medir:

bash
aws ce get-cost-and-usage --time-period Start=2026-07-28,End=2026-08-10 --granularity DAILY --metrics UnblendedCost UsageQuantity --filter '{"Dimensions":{"Key":"USAGE_TYPE","Values":["NatGateway-Bytes"]}}' --query 'ResultsByTime[].{dia:TimePeriod.Start,GB:Total.UsageQuantity.Amount,USD:Total.UnblendedCost.Amount}' --output table

El queue worker quedó en crash-loop al sacar el NAT Gateway (resuelto el 2026-09-21) ​

Pasó el mismo día que se aplicó el ítem 1.3 (sin NAT Gateway). El terraform apply salió limpio ("No changes" en el plan posterior), pero el servicio queue quedó reintentando arrancar una task sin parar, y ninguna llegaba a RUNNING.

La causa no fue el código ni el apply en sí — fue aws_ecs_service lifecycle.ignore_changes = [task_definition, desired_count] (a propósito, para no pelearse con el pipeline de deploy — ver modules/ecs/main.tf). Ese ignore_changes no incluye network_configuration, así que el apply sí actualizó la config de red del servicio a subnet pública — confirmado con un terraform plan inmediatamente después, que dio "No changes". El problema apareció más tarde:

  1. Como task_definition está en ignore_changes, el servicio siguió corriendo la revisión vieja (con QUEUE_CONNECTION=redis apuntando a un ElastiCache que este mismo PR acababa de destruir). Esa task, al arrancar, fallaba.
  2. Cada fallo disparaba el circuit breaker de ECS (deployment_circuit_breaker { rollback = true }), que hace rollback al último deployment que sí llegó a estado estable — en este caso, uno de semanas atrás, de antes de este PR, con su propia network_configuration guardada en subnet privada.
  3. El rollback restaura esa config de red vieja junto con la task definition vieja — así que el servicio volvía a subnet privada solo, sin que nadie lo pidiera en el .tf. Sin NAT Gateway (ya destruido) y sin VPC Interface Endpoint para secretsmanager, cualquier task en subnet privada quedaba aislada de AWS por completo.
  4. El error real, visible en los eventos del servicio (aws ecs describe-services), era: ResourceInitializationError: unable to pull secrets or registry auth: unable to retrieve secret from asm: There is a connection issue between the task and AWS Secrets Manager. — no "Redis no responde" como hacía pensar el cambio de driver, sino la task ni siquiera pudiendo leer APP_KEY de Secrets Manager para terminar de arrancar.

Se repitió un par de veces: cada intento de redeploy (manual o por CI) volvía a fallar de la misma forma, porque el servicio arrancaba de nuevo desde la config de red mala que el circuit breaker había restaurado la vez anterior.

Resuelto con un solo update-service que fija desired-count=0 y network-configuration (subnets públicas, IP habilitada) en el mismo llamado:

bash
aws ecs update-service --cluster soterex-staging-cluster --service soterex-staging-queue \
  --desired-count 0 \
  --network-configuration "awsvpcConfiguration={subnets=[<públicas>],securityGroups=[<sg>],assignPublicIp=ENABLED}" \
  --region us-east-1

Con desired-count=0 no hay ninguna task que ECS intente levantar, así que no hay nada que pueda volver a fallar y disparar otro rollback — coincide además con el diseño real de queue desde el ítem 1.2 (sin worker persistente, QUEUE_CONNECTION=sync).

Lección para la próxima vez que se toque network_configuration de un servicio con ignore_changes en task_definition/desired_count: el apply de Terraform no alcanza para confiar en que el servicio quedó bien — si el servicio tiene un historial largo de deployments estables en la config vieja, un solo fallo de arranque puede hacer que el circuit breaker restaure esa config vieja completa (red incluida), no solo la task definition. Verificar el estado real del servicio (aws ecs describe-services, no solo terraform plan) después de cualquier cambio de este tipo.

Redis nunca funcionó en Staging (resuelto el 2026-08-10) ​

Confirmado resuelto. El worker venía muriendo cada ~2 minutos y siguió haciéndolo hasta las 16:34; el deploy entró 16:36 y a partir de ahí no hubo un solo reinicio en 90+ minutos, cuando al ritmo anterior tendrían que haber pasado unas 50 vueltas del loop. El corte cae exactamente sobre el deploy.

Encontrado el 2026-08-10. La cola venía crasheando y reiniciándose cada 90 segundos, y por lo visto desde hace mucho: queue:work consulta la caché en cada vuelta de su loop, la conexión a Redis falla, el proceso muere, ECS lo repone. En el log, la misma excepción repetida sin fin:

RedisException: read error on connection to
tcp://master.soterex-staging-redis...:6379   ← al hacer Redis->select(1)

La causa es el tcp:// de ese mensaje. ElastiCache tiene transit_encryption_enabled = true, así que exige TLS; el cliente abre TCP plano, el servidor no responde en claro, y el primer comando muere en un "read error" que no dice "falta TLS" por ningún lado.

Lo llamativo es que el código está bien: config/database.php tiene 'scheme' => env('REDIS_SCHEME', 'tcp') en las dos conexiones, y modules/ecs setea REDIS_SCHEME=tls desde el 2026-07-28 (commit 5e3a842, presente en staging).

El problema es cómo se combinan las dos mitades del deploy:

  • Las variables de entorno vienen de Terraform. Sin apply, no llegan.
  • La imagen viene del pipeline, que toma la última revisión de la familia y sólo le reemplaza la imagen — no vuelve a leer el Terraform.

Como terraform apply no se corría desde antes de ese commit, las revisiones que estuvieron corriendo todo este tiempo (queue:14, web:30) nunca tuvieron REDIS_SCHEME. Y el apply del 2026-08-10, que sí lo trajo, generó revisiones (queue:15, web:31) con la imagen rota — el arreglo y la rotura llegaron juntos, así que en la práctica nunca convivieron una imagen buena y la variable correcta.

Cómo se sale: un deploy normal lo resuelve solo, porque renderiza la imagen buena sobre la última revisión de la familia, que ya tiene REDIS_SCHEME=tls. Necesita un commit nuevo en staging (el tag de ECR es el SHA y es inmutable, así que re-lanzar un deploy viejo no sirve).

Vale la pena revisar qué más rompía: CACHE_STORE=redis y QUEUE_CONNECTION=redis, así que todo lo que dependa de caché o de jobs en segundo plano estuvo degradado en Staging desde el principio. El web seguía respondiendo porque su health check no toca Redis.

Cómo llegar de cero a un ambiente andando ​

Solo hace falta si alguna vez hay que reconstruirlo: el runbook completo está en 2026-07-25-staging-go-live-runbook (Firebase, ACM, Terraform, DNS, GitHub Secrets, primer deploy, verificación).

En una base nueva, migrate solo no alcanza: la migración de datos de referencia salta lo que no puede ubicar, y los roles y los países los crean RoleSeeder y CountrySeeder. La primera vez hay que correr db:seed (con run-artisan-command.yml) — solo sobre una base sin roles: sobre una que ya los tiene, RoleSeeder pisa los permisos editados. A partir de ahí los datos de referencia nuevos llegan con cada deploy y no hace falta volver a sembrar. Esto vale también para el primer deploy de producción, que nunca se aplicó.

El bloqueante que ese runbook no cubría —la config de Firebase hardcodeada a literales "REEMPLAZAR" en doc/site/public/— está resuelto desde el 2026-07-28: hoy tiene la config real del proyecto soterex-staging. Sigue siendo un valor hardcodeado en el HTML y no una variable de ambiente, lo cual es aceptable acá (una config de cliente de Firebase es pública por diseño), pero significa que para producción hay que resolver el templating por ambiente de verdad — no alcanza con cambiar el literal.

Usuarios y datos ​

Los usuarios de prueba los crean StagingAdminSeeder y StagingTestUsersSeeder, uno por perfil:

EmailPerfilAlcance
admin@cislatam.testAdminGuatemala, todos los PDVs
supervisor@cislatam.testSupervisorGT-CAP-001 + GT-QUE-002
backoffice@cislatam.testCajeroGT-CAP-001
tesoreria@cislatam.testTesoreríaGuatemala, todos los PDVs

Las contraseñas de admin@, supervisor@ y backoffice@ están en el propio seeder (backend/database/seeders/StagingTestUsersSeeder.php), son de prueba y no se repiten acá (ver el punto 5 de «Antes y después del deploy de B6» sobre rotarlas). La de tesoreria@ no está en ningún archivo: la elegís al crear la cuenta en Firebase o la genera el seeder (con el costo que explica el punto 3 de esa misma sección). El Cajero conserva el mail backoffice@: es el Backoffice de antes, el rol se renombró en la migración de B6 y la cuenta ya existe en Firebase. tesoreria@ es la única cuenta nueva, y no existe en Staging hasta que alguien corra el seeder, cosa que decide Carlos. Los datos son de prueba: la integración con Soterex sigue en modo mock (falta la URL de Notifications y el secret que Soterex tiene que mandar), así que las transacciones son las del seeder o las que cree Soterex contra el sandbox, no tráfico real.

Los usuarios de prueba y los datos de demostración siguen saliendo de un seeder corrido a mano. Los datos de referencia (catálogos de los combos del pago, permisos de los módulos nuevos) no: llegan por migración, ver "Los datos de referencia llegan con el deploy" más arriba.

Esto tiene una consecuencia práctica: Staging se puede reconstruir sin perder nada de valor. No hay dato real que preservar.

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