Ajustes v3 — pasos para Carlos
Date: 2026-10-07
Plan: Ajustes v3 del cliente GT (su «Estado de la ejecución (2026-10-07)» dice qué PR es cada entrega).
Estado (2026-10-07, noche). El PR de integración #95 está mergeado (
fde0013) y la promoción #96 también: G1 a G12 están enmainy en Staging, con el deploy verde. Hechos en Staging:permisos:diferencias(«Sin diferencias»), elterraform applyde G1, el deploy que tomó las variables de S3 y la prueba de que un soporte subido sobrevive al reemplazo del contenedor. Quedan: lo marcado más abajo como pendiente (el resto de la verificación de G1, el aviso a Magaly, las verificaciones a ojo de los demás ajustes) y lo no hecho (G13, RV3-67,diagnostico:v3). Lo de abajo se escribió antes de mergear, y cuando una frase diga «ninguno mergeado» o «nada se probó contra Staging», vale este párrafo.Qué es esto. Lo que solo vos podés hacer para cerrar la tanda de ajustes v3, en orden y con casillas para marcar. Hoy hay doce PRs de entregas (#83 a #94) y el de integración (#95), ninguno mergeado. Nada se probó contra Staging: Claude no tiene login, así que todo lo verificado salió de dev, de tests y de la revisión de cada PR. Este archivo no autoriza nada: mergear a
mainy cualquier push, merge o deploy astagingoproductionsigue necesitando tu OK en el chat (CLAUDE.md). Los mails (a Soterex y al cliente) y la muestra para el cliente son borradores que mandás vos; no se envió nada.
Camino recomendado: instalar todo con el PR de integración (#95)
Los PRs individuales se pisan entre sí (ver 0.2): la cadena apilada, y G1 y G4b en código. Por eso, después de escribir todo lo de abajo, se armó una rama de integración que los junta, con los conflictos resueltos y probada como conjunto: el PR #95 (integration/ajustes-v3 → main), con G1 a G12, el cierre administrativo y el npm audit fix del frontend. Backend: 2889 pasan y 1 falla (C2PRateLimitTest, previo y ajeno: el contenedor local trae CACHE_STORE=redis); frontend: 2001 tests, build y npm audit en 0; docs:build OK.
- [x] 1. Mergear el #95 a
main(necesita tu OK en el chat):gh pr merge 95 --merge. Con eso entran las 12 entregas juntas. Hecho el 2026-10-07 (fde0013). - [x] 2. Los PRs individuales (#83 a #94) quedan como referencia. No se mergean: sus commits ya están en
mainpor el #95. Cerralos (si GitHub no los marca solos como «Merged»). Hecho el 2026-10-07: #86 y #88 a #94 se cerraron sin mergear, con un comentario y sin borrar las ramas (el último commit de cada una es ancestro demain); #83, #84, #85 y #87 ya figuraban como mergeados. - [x] 3. Promover a Staging con un PR
main → staging(también necesita tu OK; el deploy corre solo al mergear). Antes, lo de G8 (avisarle al cliente;php artisan permisos:diferencias) y, por el orden de G1, esta secuencia: (i) deploy de la imagen con el disco todavía local; (ii)terraform applya mano; (iii) un deploy más que tome las variables; (iv) verificar. Los detalles de cada paso están en la sección 2 de este archivo («Lote 6») y endoc/environments/staging.md(G1). Hecho el 2026-10-07 con el #96 (a47ace2): (i) deploy verde;permisos:diferencias→ «Sin diferencias»; (ii)terraform applyhecho (elplanposterior da «No changes»); (iii) el deploy que tomó las variables fue re-correr el job «Backend → AWS (Staging)» (intento 2, sin commit nuevo; el PR #97 de commit vacío que se había abierto para eso no hizo falta); (iv) verificado en parte: ver «Resultado de la primera vez» en el runbook de G1, con lo que falta medir (documentos:verificar --detalle, elcurlsin credenciales y el smoke de subida). El aviso al cliente por G8 sigue siendo tuyo (borrador). - [ ] 4. Las secciones 3 en adelante (verificaciones en Staging, cliente y Soterex, decisiones, lo no hecho) siguen valiendo igual.
Las secciones 1 y 2 de más abajo (merge por PR y despliegue por lotes) quedan como alternativa si preferís revisar y desplegar de a pocos: la lógica de qué corre solo en el deploy y qué hay que avisar sigue siendo la misma.
0. Antes de empezar: tres hallazgos
0.1 El CI está en rojo por algo que no es de las entregas
- [ ]
Frontend — lint, typecheck, buildfalla en #83, #84, #85 y #87 en el pasonpm audit: tres avisos altos nuevos (vuehasta 3.5.41 con@vue/server-renderer, ysource-map-jshasta 1.2.1). Ninguno de los cuatro tocafrontend/package.jsonni el lock; el último CI verde demaines del 2026-10-06 00:14 UTC y el primer rojo, de las 15:11 UTC: los avisos salieron en el medio. Los apilados (#86 y #88 a #93; #87 tiene basemainy sí muestra sus checks) no muestran checks porque su base no esmain(el CI corre solo para PRs haciamain,stagingyproduction), pero van a mostrar el mismo rojo apenas se re-apunten. Hace falta un PR chico aparte que actualice esas dos dependencias (como el de@grpc/grpc-js, #59). No lo hice: es código y dependencias, fuera de este encargo. Decidí vos: arreglarlo primero, o mergear con el check en rojo si GitHub te deja. - [ ]
Backendfalla en #87 por dos tests deWebhookSigningTest(ErrorException): fijan una fecha y vencen con el paso del tiempo (según el cuerpo de #87, fallan igual enmainlimpio). #83, #84 y #85 pasaron más temprano ese mismo día; si se re-corren hoy, lo esperable es que fallen igual. Lo arregla #90 (G7), que está al final de la cadena: si querésmainen verde antes, se saca ese arreglo (el commitbedb055y ela9ec4d5de #90) a un PR propio contramain. - Esperable y no bloquea:
Plan — stagingfalla en #84 (Not authorized to perform sts:AssumeRoleWithWebIdentity). Es el rol de Terraform que no se puede asumir desde un PR; está documentado en «Terraform desde CI: no funciona todavía» y el job es solo informativo.
0.2 Los tres PRs «independientes» no lo son: chocan con la cadena
Los cuerpos de #83, #84 y #87 los presentan como independientes (y lo son en lo conceptual), pero tocan los mismos archivos que la cadena. Lo simulé el 2026-10-07 con git merge-tree (sin tocar ramas ni el árbol de trabajo) contra main más la cadena hasta #93. Es orientativo: cambia con el PR de G12 y con cada resolución.
| PR | Conflicto con la cadena (#85 a #93) | Archivos |
|---|---|---|
| #84 G1 | De código | TransactionDocumentController.php, useTransactionDocuments.ts, DocumentacionPago.vue, DocumentacionPrePago.vue y los tres specs que los prueban (DocumentacionPago.spec.ts, DocumentacionPrePago.spec.ts y useTransactionDocuments.spec.ts); en docs, staging.md, architecture/index.md, manual/10-pago.md y el funcional 02-datos-y-documentos.md |
| #87 G4b | De código | TransactionController.php; en docs, los funcionales 02-roles-permisos.md y 05-secuencias-pantalla.md |
| #83 G3 | Solo docs | ADR-011, los funcionales 01-modelo-de-saldos.md, 02-datos-y-documentos.md y 05-secuencias-pantalla.md, y el QA 2026-09-11-e5-pago-documentos-plan-de-pruebas.md |
| Entre ellos | #83 con #84: staging.md · #83 con #87: 05-secuencias-pantalla.md · #84 con #87: nada |
El cuerpo de #88 habla de «un conflicto chico de textos» con G1: es más que eso (es el código de subida y de la pantalla de documentos).
Qué hacer con esto: mergear la cadena primero y resolver los tres después, cada uno en su branch (un git merge origin/main en el branch del PR, resolver, correr npm test, los tests del backend y docs:build, y pushear). Los de la cadena entran limpios porque cada uno ya contiene al de abajo, y los tres de afuera no tienen nada apilado encima, así que lo que se resuelve no se arrastra. El orden inverso (G1 primero) hace caer los conflictos en #85, #86 y #88, y cada resolución se arrastra hacia arriba de la pila. Si igual querés G1 antes, por ser lo más urgente del plan, es posible; contá con resolver tres PRs encadenados en vez de tres sueltos. Resolver es cambiar código de las entregas y pushear: lo hace quien vos digas (Claude con tu OK, o vos). Con G1 al final, los lotes 1 a 5 se promueven con los soportes todavía en el disco del contenedor (cada promoción los borra, como hoy): conviene que el cliente no pruebe documentos hasta el lote 6, que es lo que le pide la respuesta del plan (§6.0, apartado 2).
0.3 Los runbooks que se citan viven en el branch de cada PR
Cada PR agrega su sección a doc/environments/staging.md; en main todavía no están. Verifiqué que existen en el branch de cada PR y calculé sus anclas con el renderer de VitePress (son las que se enlazan abajo). Hasta que el PR mergee, el enlace abre staging.md pero no salta a la sección. Lo mismo pasa con los ADR y los planes de QA nuevos (ADR-019 a ADR-023 y doc/qa/2026-10-06-g*/2026-10-07-g*): se nombran sin enlace porque todavía no existen en main.
1. Orden de merge, con el comando de cada PR
Dos reglas para todos:
- Siempre
--merge(merge commit) y--delete-branch. Nada de--squashni--rebase: con squash los commits del PR de abajo reaparecen en el diff del de arriba y el rebase de GitHub reescribe los SHA; las dos formas rompen la pila. Borrar el branch es lo que hace que GitHub re-apunte solo el PR siguiente amain. - Después de cada merge de la cadena, comprobá que el siguiente quedó sobre
mainy sin conflictos:bashSi GitHub exige checks y un PR re-apuntado no los muestra (un cambio de base no suele disparar el CI), cerrarlo y reabrirlo, o un push al branch, los dispara. Desde la UI es lo mismo: Create a merge commit y tildar Delete branch.gh pr view SIGUIENTE --repo raxardev/soterex --json baseRefName,mergeable --jq '.baseRefName + " " + .mergeable' # tiene que decir: main MERGEABLE gh pr edit SIGUIENTE --repo raxardev/soterex --base main # solo si la base no cambió sola
Fase 1 — la cadena, en este orden
- [ ] 1. #85 G2 —
gh pr merge 85 --repo raxardev/soterex --merge --delete-branch - [ ] 2. #86 G4a (se re-apunta a
mainal borrarse el branch de #85) —gh pr merge 86 --repo raxardev/soterex --merge --delete-branch - [ ] 3. #88 G5 —
gh pr merge 88 --repo raxardev/soterex --merge --delete-branch - [ ] 4. #89 G6 —
gh pr merge 89 --repo raxardev/soterex --merge --delete-branch - [ ] 5. #90 G7 (incluye G6.C) —
gh pr merge 90 --repo raxardev/soterex --merge --delete-branch - [ ] 6. #91 G8 (cambia permisos de usuarios reales al desplegarse: mirá el lote 3 de la sección 2 antes de promover) —
gh pr merge 91 --repo raxardev/soterex --merge --delete-branch - [ ] 7. #92 G9 —
gh pr merge 92 --repo raxardev/soterex --merge --delete-branch - [ ] 8. #93 G10 + G11 —
gh pr merge 93 --repo raxardev/soterex --merge --delete-branch - [ ] 9. G12, cuando exista su PR (apilado sobre #93, número todavía sin asignar) —
gh pr merge NUMERO --repo raxardev/soterex --merge --delete-branch
El merge de la cadena no es el despliegue: main no despliega nada. Promover a Staging es un paso aparte (sección 2) y se puede hacer por tramos de la cadena.
Fase 2 — los tres de afuera, uno por uno
Para cada uno: traer main al branch del PR y resolver (sección 0.2), revisar el CI (ver 0.1) y recién ahí mergear.
- [ ] 10. #87 G4b (conflicto de código en
TransactionController.php) —gh pr merge 87 --repo raxardev/soterex --merge --delete-branch - [ ] 11. #83 G3 (solo docs) —
gh pr merge 83 --repo raxardev/soterex --merge --delete-branch - [ ] 12. #84 G1 (el más pesado de resolver; su deploy lleva el
terraform apply, lote 6) —gh pr merge 84 --repo raxardev/soterex --merge --delete-branch
Si gh no borra el branch remoto, git push origin --delete NOMBRE-DEL-BRANCH, o el botón en la UI.
2. Despliegue a Staging, por lotes
Promover es un PR de main a staging; al mergearlo corre deploy-staging.yml (8 a 22 minutos). Lleva todo lo que haya en main, así que los lotes se arman mergeando solo hasta donde querés llegar y promoviendo ahí. El plan (§2, «Cómo se ejecuta») pide un lote por promoción, con tu OK, y avisarle a Magaly antes de cada una que cambie algo visible.
gh pr create --repo raxardev/soterex --base staging --head main \
--title "Promover a Staging: LOTE" \
--body "Migraciones que corren con este deploy: LAS DEL LOTE (tabla de abajo)"El deploy aplica migrate --force (espera a que Aurora despierte, PR #75) y no corre seeders. Si una migración de datos falla, el deploy se corta y el servicio viejo sigue sirviendo; no hay camino de vuelta para las de datos: se arregla hacia adelante con otra migración. Antes de cada promoción corré cd doc && npm run docs:build: el CI de PR no lo corre (G0.8 sin hacer), y un link roto recién aparece en el deploy.
| Lote | PRs | Migraciones que corren solas | ¿Cambia permisos de usuarios reales? | A mano | Runbook de staging.md |
|---|---|---|---|---|---|
| 1 | #85, #86, #88 (G2, G4a, G5) | 2026_10_06_100000_g4_completar_el_pdv_de_los_pagos_viejos (datos) | No toca la matriz. Pero G4a hace que quien tiene dos o más PDV y ninguno activo reciba 422 al pagar sin caja abierta, y G5 que el Cajero no reemplace un documento de una pagada | — | G4a |
| 2 | #89, #90 (G6, G7) | 2026_10_06_110000_g7_activar_y_desactivar_cajas (esquema: cash_boxes.active, default true) | No toca la matriz. G6 cambia quién puede cerrar una caja ajena | — | G6 |
| 3 | #91 (G8) | 2026_10_07_000236_v3_tipo_de_cambio_solo_tesoreria_y_admin (datos: 2 celdas) | Sí: Cajero y Supervisor pierden tipo_cambio | — | G8 |
| 4 | #92, #93 (G9, G10 + G11) | 2026_10_07_100000_g10_paises_de_cumplimiento, …110000_g11_columnas_de_formato_de_identificacion, …110100_g11_reglas_de_dpi_y_pasaporte (datos y esquema; las dos migraciones de datos, …100000 y …110100, tienen un down() vacío a propósito: se arreglan hacia adelante; la de esquema, …110000, sí revierte) | No | Cargar los tres PDV reales por pantalla (G9.7) | PDV reales, prefijo C-, G10 y G11 |
| 5 | G12 (PR sin crear) | Según el plan, ninguna | No toca la matriz; cambia el saldo que ve una Tesorería con alcance parcial | — | Sin runbook hasta que exista el PR |
| 6 | #87, #83, #84 (G4b, G3, G1) | 2026_10_06_100000_g4_indice_de_audit_logs_por_transaccion (esquema: un índice en audit_logs) | No | terraform apply de G1 | G1, humo de subida, G3 |
El único cambio de filas de permisos es el de G8. Los demás cambian lo que una persona puede hacer sin tocar role_permissions, y por eso no dejan un evento de Auditoría por celda. Si preferís un solo lote, la lista previa es la suma de todas las de abajo, y G1 necesita su orden propio (imagen, apply, otro deploy) en el medio de una promoción que ya trae a G8: no te lo recomiendo.
Lote 1 — G2, G4a y G5 (#85, #86, #88)
Trae: quien paga una transacción de otro PDV recupera sus soportes y su papeleta; el PDV de cada pago es el de la caja; documentos de una pagada («subir lo que falta» no es «reemplazar»), papeleta con dos botones.
- [ ] Las dos consultas de solo lectura del runbook de G4a. No con
run-artisan-command.yml: no sirve para SQL y vuelca los mails sin enmascarar en CloudWatch y en el log de Actions. El repo no documenta un canal de SQL a Aurora (está en una subred privada): se corren con el acceso que tengas. Sin canal no se frena el deploy, pero cambia cómo se verifica (el runbook lo explica). Anotáque_completa_la_migracion. - [ ] Avisar a las personas que dé la consulta (b) (dos o más PDV y ninguno activo;
supervisor@es una): sin caja abierta, subir el primer documento o pagar da 422ACTIVE_STATION_REQUIRED. Se destraba abriendo su caja o con un PDV activo fijado por un Admin. - [ ] Avisar a Magaly con una línea: el Cajero ya no corrige un documento mal subido en una pagada (lo reemplaza un Supervisor o un Admin; el Cajero sigue subiendo lo que falta), y la papeleta tiene dos botones, tirilla y A4.
- [ ] Mirar la decisión que tomé sin vos en #86: un país sin Caja con un usuario de dos PDV y sin PDV activo ahora da 422 (el test pasó de esperar 200 con PDV nulo a 422; el plan se contradecía).
- [ ] Mergear #85, #86, #88 (sección 1), correr
docs:build, promover. - [ ] Después (runbook de G4a): Auditoría → acción «Pagos completados con su PDV», con el mismo N que
que_completa_la_migracion(si era 0, no tiene que haber evento); volver a correr la consulta (a), que da 0; entrar con una persona de la consulta (b) sin caja abierta y subir el primer documento de unaACCEPTED: tiene que salir «Falta tu PDV activo». - [ ] Verificaciones de la sección 3 (G2, G4a y G5).
Lote 2 — G6 y G7 (#89, #90)
Trae: «Abierta por …» en cada caja y quién la cierra; línea de país en Saldos; desactivar y reactivar cajas.
- [ ] Consulta de solo lectura del runbook de G6: cajas abiertas, quién las abrió y cuántos otros pueden cerrarlas. Cada fila con
0es una persona a avisar que cierre su caja antes de irse: si no, solo podrá cerrarla un Admin (el runbook lo explica). - [ ] Las tres consultas de solo lectura del plan de QA de G7 (
doc/qa/2026-10-06-g7-administrar-cajas-plan-de-pruebas.md, «Antes de desplegar a Staging»): cajas abiertas en un PDV inactivo, abiertas en un país sin módulo Caja, y plata en cajas de un PDV inactivo o de un país sin módulo. Con filas, reactivar y cerrar antes de volver a desactivar. - [ ] Avisar a los operadores que hoy dependen de que un compañero les cierre la caja: desde el deploy la cierra quien la abrió, un Supervisor o un Admin del PDV. Revierte ADR-013 §5; si preferís que otro operador pueda cerrar las vencidas, es un cambio chico en
canCloseCashSession(lo describe el ADR-021 de #89). - [ ] «Retiro por baja de caja» (motivo de ajuste nuevo de G7) todavía no lo aprobó Tesorería: queda como pregunta abierta en el funcional de Caja, con su valor por defecto.
- [ ] Mergear #89, #90,
docs:build, promover. - [ ] Después: como Cajero sobre una caja abierta por otro, no ofrece «Cerrar caja» y dice quién la abrió; como Supervisor del PDV, sí. En Estaciones / PDV el panel «Administrar»; Saldos con la línea de país. Detalle en
doc/qa/2026-10-06-g6-quien-opera-y-quien-cierra-plan-de-pruebas.mdy en el de G7.
Lote 3 — G8 (#91): cambia permisos de usuarios reales
- [ ] Avisarle a Magaly antes (pregunta QC-17): el tipo de cambio queda solo para Tesorería y Administrador, como dice su hoja de menús; el Cajero y el Supervisor dejan de verlo. El cliente está probando con esas cuentas. No promuevas sin ese aviso.
- [ ] Que exista
tesoreria@en el Firebase de Staging: sin esa cuenta el cliente no ve el perfil Tesorería y la verificación de abajo no se puede hacer. Si no existe,StagingTestUsersSeederlo corrés vos, con las contraseñas que elijas en la consola (las generadas quedan legibles en los logs). - [ ] Consulta de personas por perfil que hoy leen
tipo_cambio(cuenta, no imprime mails) y consulta de las dos celdas, por si un Admin las editó: el deploy las pisa igual; si dan filas, hablalo antes con quien las tocó. - [ ] (Opcional) Bajar las 76 celdas de
role_permissionsy compararlas a ojo condoc/architecture/matriz-de-perfiles.json: tienen que diferir soloCajero · tipo_cambioySupervisor · tipo_cambio.permisos:diferenciashace esto solo, pero solo existe después del deploy. - [ ] Mergear #91,
docs:build, promover. - [ ] Después: Auditoría → «Permiso cambiado por un deploy»: un evento por cada celda que tenía lectura, de
L--a---(una celda que ya estaba en---no deja evento);backoffice@ysupervisor@sin «Tipo de cambio» en el menú ni por URL,tesoreria@yadmin@con él; un pago de prueba como Cajero en un PDV de Guatemala sigue andando. - [ ]
permisos:diferencias(GitHub → Actions → «Ejecutar comando artisan (manual)», environmentstaging): tiene que decir «Sin diferencias». Si lista algo, son celdas que ninguna migración fija: decidís celda por celda si es política del cliente editada desde Roles y Permisos (se deja) o una diferencia de despliegue (se lleva a la matriz con una migración nueva: eso es G8.9, que no se hizo). - [ ] No correr
db:seedpara «arreglar» nada: revierte la matriz a la del seeder.
Lote 4 — G9 y G10 + G11 (#92, #93)
Trae: Cumplimiento con Payer Name «CIS Guatemala», Additional Notes vacía y MTCN con «C-»; A4 de cuatro incisos; búsqueda con «C-» en Pago; la lista de países del cliente (255 filas: 251 cargadas y cuatro dudosas sin cargar); formato de DPI y Pasaporte.
- [ ] Soterex: antes de que un regulador lea el reporte, confirmar que «C-» se sigue usando (pregunta S-2 del mail a Sean). Mientras no contesten rige
C-; se apaga conCUMPLIMIENTO_MTCN_PREFIXvacía (procedimiento en el runbook; toca Terraform). - [ ] (Opcional) Consulta de solo conteos de pagos con DPI o Pasaporte fuera de formato (runbook de G10 y G11). Una
ACCEPTEDcon un DPI viejo fuera de formato no se puede pagar hasta que el operador lo corrija: si da más de cero, avisar al cliente. LasPAIDno cambian. - [ ] Avisar a Magaly del renombre retroactivo de 23 países (QC-26): reimprimir un recibo viejo muestra el nombre nuevo; los códigos guardados no cambian.
- [ ] Mergear #92, #93,
docs:build, promover. Si una de las tres migraciones de G10 y G11 falla, el deploy se corta. - [ ] Cargar los tres PDV reales por la pantalla (runbook «Cargar los tres puntos de venta reales», unos 30 minutos): editar
GT-CAP-001yGT-QUE-002sin cambiar el código interno y crear Chimaltenango (el códigoGT-CHI-005es una propuesta, elegís vos). Los datos están en el runbook, literales (las dos direcciones con errores de tipeo van tal cual: QC-22). Nunca correrStationSeederni undb:seedcompleto después: esupdateOrCreatey revierte los PDV editados.GT-MIX-003yGT-ESC-004quedan activos y sin tocar hasta que el cliente apruebe la muestra. - [ ] Después de G9: un pago de prueba por PDV con el A4 (agencia y ciudad) y el Excel de Cumplimiento, columnas U, V, X, AD y de AG a AJ (la tabla está en el runbook).
- [ ] Después de G10 y G11: 251 países activos, las siete etiquetas del spot-check, las reglas de DPI y Pasaporte en Catálogos, los dos eventos de Auditoría y un pago de prueba (Pasaporte con Kosovo; DPI con espacios, que se limpian solos).
Lote 5 — G12 (PR por abrir)
- [ ] Cuando exista el PR: completar acá el número y, si trae un runbook, su enlace. Del plan: alcance de una Tesorería de un solo país, tarjeta de la Holding limitada a sus países y rótulos; no incluye RV3-67. El plan pide revisión de
securitypara G12. - [ ] La muestra para el cliente (G0.9): Excel de Cumplimiento y PDF del A4 con datos de demo, y capturas del menú y de los extractos. Se genera recién cuando mergean #91, #92 y G12, porque cambian esas salidas. Va con un OK explícito por tanda (B4, B5, B6 y B7); hasta entonces el cliente no tiene que darlas por validadas.
Lote 6 — G4b, G3 y G1 (#87, #83, #84), con el terraform apply
Trae: «Procesada por» en Reporte individual; medio de pago solo efectivo; los soportes de pago en un bucket S3 privado.
Antes
- [ ] Decidir la revisión de
securityde G1 (el plan la pide, y el PR dice que no se hizo): es un bucket nuevo con identificaciones. Es antes del merge de #84. - [ ] Credenciales de administración de AWS en la cuenta de Staging:
aws sts get-caller-identitytiene que mostrar esa cuenta, yterraform version1.9 o más. - [ ] (Recomendado) Confirmar el diagnóstico de G1 con DevTools: abrir un soporte subido antes del último deploy tiene que dar 404 con
code: DOCUMENT_FILE_MISSING. Si da 500, 401 o 403, la causa es otra: parar. Y comprobar en el Web ACL la reglaaws-managed-common-rules-uploads. - [ ] Avisar a Magaly con una línea: el medio de pago queda solo en efectivo y hay una columna nueva. Una pestaña abierta con el frontend viejo y «Transferencia» elegida recibe 422: front y back salen juntos.
- [ ] Mergear #87, #83 y #84 (fase 2 de la sección 1),
docs:build.
Deploy 1 y terraform apply (todo esto está paso a paso en el runbook de G1 y en infra/terraform/README.md; el orden es lo que importa: el deploy renderiza la task definition desde la última revisión de la familia y Terraform ignora task_definition, que es lo que rompió el CORS el 2026-10-02)
- [ ] Paso 1 — Promover (
mainastaging) la imagen conleague/flysystem-aws-s3-v3. El disco sigue siendo local: no cambia nada visible. Corre la migración del índice deaudit_logs. - [ ] Anotar la revisión que quedó corriendo, antes del
apply(es el destino de la vuelta atrás):bashaws ecs describe-services --region us-east-1 --cluster soterex-staging-cluster --services soterex-staging-web \ --query 'services[0].deployments[?status==`PRIMARY`].taskDefinition' --output text - [ ] Paso 2 —
terraform applya mano, desde tu máquina (no el workflowterraform-apply.yml: planea y aplica en el mismo job, sin pausa para leer el plan):bashcd infra/terraform/environments/staging terraform init terraform plan -out=tfplan # mismas variables de siempre; cors_allowed_origins = https://soterex.stag.cislatam.net (el frontend, no la API) # leer el plan. Tiene que mostrar esto y nada más: # se crean: el bucket soterex-staging-documents-<id de cuenta> y sus seis recursos, y aws_iam_role_policy.task_documents # se reemplazan: las task definitions web y queue, con DOCUMENTS_DISK_DRIVER, DOCUMENTS_BUCKET y AWS_DEFAULT_REGION nuevas # se modifican por arrastre: el schedule de SendRequest y su rol (siguen DISABLED) # output nuevo: documents_bucket_name # Si ves algo más, NO apliques. Esperable: CORS_ALLOWED_ORIGINS pasando de la URL de la API (https://api.…) al origen del frontend. terraform apply tfplan - [ ] Entre el
applyy el deploy siguiente no lancesrun-artisan-command.yml: elapplydeja la última revisión conimage …:initial, que no existe. - [ ] Paso 3 — Un deploy más que tome las variables: re-correr el job «Backend → AWS (Staging)» del deploy del paso 1 (Actions → Re-run jobs). Si corta en el
docker push, un commit nuevo astaging. Comprobar que la revisión nueva trae la imagen del SHA (no:initial) yDOCUMENTS_DISK_DRIVERen"s3"(el comando está en el runbook).
Verificación (el runbook las numera 1 a 7; cada una descarta una causa distinta)
- [ ] Preflight de CORS devuelve
access-control-allow-origin: https://soterex.stag.cislatam.net. - [ ] Subir un soporte real a una
ACCEPTEDde prueba: es la primera escritura real contra el bucket. Si da 503DOCUMENT_STORAGE_UNAVAILABLE, el detalle está en CloudWatch (/ecs/soterex-staging/web):AccessControlListNotSupportedes la ACLprivate(plan B de solo configuración, en el runbook);AccessDeniedcon el simulador de IAM en «allowed» huele as3:PutObjectAcl. - [ ] Abrirlo (200 en DevTools); el objeto está en el bucket, cifrado
AES256, con el bloqueo público entruey uncurlsin credenciales que da 403. - [ ] Sobrevive a un redeploy:
aws ecs update-service … --force-new-deploymenty el documento se abre igual (antes de G1 daba 404). - [ ] Prueba de humo de subida con 1 MB y 15 MB por el ALB, después de cada
applyque toquewafoecs. - [ ]
documentos:verificar --detalle(Actions → «Ejecutar comando artisan (manual)»,staging): lista los soportes viejos sin archivo. Re-subir la Carta y la Identificación de lasACCEPTEDantes de dejarlas pagar: la compuerta de ADR-008 cuenta filas, no archivos. - [ ] Recién ahí avisarle a Magaly que puede volver a probar documentos, y preguntarle (QC-4) usuario, hora, tipo, tamaño y MTCN si «No se pudo guardar el documento» se repite.
G3 y G4b, después del deploy
- [ ] G3: en Pago, «Confirmar pago» ofrece solo Efectivo. Correr la consulta del paso 1 del runbook de G3 (de solo lectura, tampoco por
run-artisan-command.yml): sin filas, no hay nada que corregir. Con filas, un ajuste por caja y moneda (abre, ajusta y cierra, de a una) odemo:reseedsi son varias: lo decidís mirando el resultado.demo:reseedborra todas las transacciones de Guatemala, incluidas las que Soterex creó contra el sandbox: avisale antes. Ojo con el cierre: cerrar una caja vencida puede frenarse conPENDING_PAYMENT_DOCUMENTS, porque lasPAIDviejas por transferencia siguen pidiendo sus cuatro documentos (lo dice el cuerpo de #83 y el runbook); entonces «abre, ajusta y cierra» se traba en el cierre. Los caminos: subir los documentos de prueba que piden, odemo:reseed. - [ ] G4b: Reporte individual con la columna «Procesada por» al final y los rótulos «Sin asignar (bolsa del país)», «Cancelada por Soterex» y «Sin PDV asignado»; el Excel se llama
reporte-individual-AAAAMMDD-HHMM.xlsx.
3. Verificaciones en Staging que Claude no pudo hacer
Ninguna entrega se probó contra Staging (no hay login), y G1 tampoco contra un S3 real. Lo que sigue es lo que queda sin ver con datos reales, por entrega; el paso a paso está en el plan de pruebas de cada PR (doc/qa/2026-10-06-g* y 2026-10-07-g*, en el branch de cada uno).
| Entrega | Qué mirar en Staging | Por qué no se pudo |
|---|---|---|
| G1 (#84) | Que S3 acepte el PutObject con ACL private en un bucket con ACLs deshabilitadas (confianza media); la política IAM renderizada; subir, abrir y sobrevivir a un redeploy | Solo corrió terraform validate; los tests usan archivos reales pero no un S3 |
| G2 (#85) | El ciclo completo: A sube, B paga desde otro PDV, B imprime la papeleta, sube la firmada y cierra la caja | Cubierto por un test de API; con las cuentas de hoy solo se reproduce el caso del supervisor@ (sin PDV). Un segundo Cajero del mismo PDV pide las cuentas de G0.7, que no se crearon |
| G3 (#83) | «Confirmar pago» solo con Efectivo; qué cajas tiene afectadas Staging | Sin acceso a la base ni a la app |
| G4a (#86) | Un pago real con caja abierta: el PDV de la ficha es el de la caja; la migración de datos con las filas reales | Sin Staging; el N esperado sale de la consulta (a) |
| G4b (#87) | «Soterex (API)» para una cancelada por Cancel y «Sistema» para una vencida por c2p:expire con datos reales | Solo con datos de demo |
| G5 (#88) | Reemplazar como Supervisor y como Admin, «Solo consulta» para el Cajero tras pagar, campos grisados, dos botones de papeleta; la Auditoría de subidas anteriores a G5 (caso 6.4 del QA) | Sin Staging; ese caso solo existe con datos de Staging |
| G6 (#89) | Con dos Cajeros reales: «Abierta por …», sin «Cerrar caja» para el otro, con él para el Supervisor | No se pudo probar con dos Cajeros reales; los casos están en tests de API |
| G7 (#90) | El panel «Administrar»; Escuintla Norte (un PDV en un país con módulo Caja y sin cajas se arregla con «+ agregar caja»); la línea de país contra «Distribuido en cajas» de Prefondeo País | Sin Staging. La tabla de Estaciones sigue con scroll horizontal a 1280 px |
| G8 (#91) | Las cuatro cuentas (backoffice@, supervisor@, tesoreria@, admin@) en el menú y la barra mobile; permisos:diferencias con las 76 celdas reales | La migración solo se aplicó en la base de dev |
| G9 (#92) | El A4 de cuatro incisos y el Excel de Cumplimiento de 36 columnas con los PDV reales; la búsqueda de Pago con «C-» | Solo con datos de demo |
| G10 + G11 (#93) | 251 países; el collation del combo en Aurora (no determinado); el pago con DPI y Pasaporte | Sin Staging |
| G12 | A completar cuando exista el PR | — |
4. Lo que depende del cliente y de Soterex
Las respuestas no frenan nada de lo ya hecho: cada pregunta tiene su valor por defecto, que es lo que traen los PRs y se cambia después con poco costo. Los textos completos están en el plan, §6.1. La carta al cliente, puesta al día con lo ejecutado y con las seis preguntas que importan ahora, es el borrador de respuesta: no está enviada y la mandás vos. Las preguntas que sirven solo a G13 (QC-31, 33, 34 y 37) no van en esa carta: se mandan cuando se retome G13 (el borrador guarda su texto, listo para pegar); QC-35, 36, 38 y 39 tampoco se preguntan ahora.
| QC | Qué se le pregunta | Si no contestan (el valor por defecto, que es lo que hay en los PRs) | Entrega |
|---|---|---|---|
| 1 | ¿El Administrador también puede pagar? | Sí; Pago sigue para Cajero, Supervisor y Administrador (no se tocó) | — |
| 2, 3 | Documentos de una pagada: ¿«no modificar» es «no reemplazar»? ¿Los de un intento anterior? | Sí a las dos; se mantienen con «Subido por … el …» y un aviso | G5 |
| 7, 8 | ¿Medio de pago visible con Efectivo? ¿Hay otras formas de pago? | Visible, Efectivo preseleccionado; no hay otras ni catálogo | G3 |
| 9, 10, 11 | PDV del pago; ¿alcanza el mail para «procesada por»?; ¿Cumplimiento es el «reporte completo»? | PDV de la caja solo si queda vacío; mail (y «Soterex (API)»); sí | G4a, G4b |
| 12, 13, 14 | Quién cierra una caja ajena; ¿vieron abrir una abierta?; ¿alcanza el mail para «quién la tiene»? | Quien la abrió, el Supervisor y el Admin (si hay un PDV sin Supervisor, variante C); ya lo impedía un 409; sí | G6 |
| 15, 16 | La línea de país de Saldos; desactivar una caja con saldo | Total de plata en las cajas; se rechaza hasta dejarla en cero | G7 |
| 17, 18 | Tipo de cambio sin lectura para Cajero y Supervisor; ¿alguien editó permisos de prueba? | Sí, avisando antes; no se toca nada más hasta permisos:diferencias | G8 |
| 19, 20 | «Send» o «Sent»; idioma del Update | Queda «Sent» y en inglés (no se tocaron) | G9 |
| 21, 22, 23, 24 | MTCN con «C-»; direcciones con errores de tipeo; ciudad «Guatemala» o «Ciudad de Guatemala»; «Transacción fija» | C- aplicado y reversible; tal cual; «Ciudad de Guatemala» (G9.8, hecho el 2026-10-07); se sigue imprimiendo | G9 |
| 26, 27, 28, 29 | Renombre retroactivo; cuatro casos de países dudosos y la Antártida; qué es el «#»; municipios sin verificar | Sí, los códigos no cambian; ninguno cargado; contador; se usan las cargadas | G10 |
| 30 | DPI con separadores | El formulario los quita; el servidor exige 13 dígitos exactos | G11 |
| 31, 32, 33 | Escenario de prefondeo; qué ve de la Holding una Tesorería de un país; el «Saldo final CIS Holding» de 32.708 | Escenario 1 como supuesto (el Dashboard no se toca); su parte con aviso de «parcial»; no se muestra (RV3-67 sin hacer) | G12 |
| 34 a 39 | Alerta al 30 %, confirmaciones de recepción, columna de porcentaje | Nada implementado: G13 está diferida | G13 |
Soterex. Las cinco consultas (S-1 a S-5) van en un solo mail a Sean, solo de consulta: ninguna cambia C2PController, OAuth, SendRequest ni Cancel. El mail es un borrador: no está enviado y lo mandás vos. A G9 le importan S-2 (¿«C-» sigue vigente?) y S-4 (cómo modifican una transacción ya enviada: hoy un transaction_id repetido devuelve la transacción original con COD_009 y no aplica los datos nuevos, sin avisar con un rechazo, según el sign-off 1.4; el 2001 que dice el plan está retirado desde el PR #80); a los extractos, S-3 (si el RS- es el transaction_id); a G10, S-5 (¿la lista de países es su picklist?); S-1 es de G13. El sign-off de la integración C2P sigue su propio camino (sign-off) y este plan no lo toca.
5. Decisiones que se tomaron sin vos (conviene mirarlas antes de mergear)
Todas reversibles; el detalle está en el cuerpo de cada PR.
| PR | Qué se decidió |
|---|---|
| #83 G3 | El mensaje del 422 al elegir TRANSFERENCIA («El medio de pago solo puede ser efectivo.») lo redacté yo. Se borró la rama «bank_account obligatoria con transferencia», en el backend y en su espejo del frontend (ya no es alcanzable: pay() y datosPago() descartan la cuenta siempre). El select de «Medio de pago» queda habilitado con una sola opción. Y el runbook avisa de algo que el plan no tenía: cerrar una caja vencida puede frenarse con PENDING_PAYMENT_DOCUMENTS (ver el lote 6) |
| #86 G4a | Un país sin Caja con dos PDV y sin PDV activo pasa a dar 422 (antes pagaba con PDV nulo). El plan decía a la vez «sin Caja no hay desempate» y «ese test queda como está». El mensaje del 422 nombra la pantalla «Caja», que desde B6 es «Saldos» |
| #89 G6 | Revierte lo que decía ADR-013 §5 (un compañero destraba una caja vencida): ahora solo un Supervisor o un Admin del PDV. El mail del operador lo ve cualquiera que vea la lista de cajas |
| #90 G7 | «Retiro por baja de caja» es una constante en código, sin migración y sin aprobación de Tesorería. Desactivar un PDV no desactiva sus cajas. Se arreglaron de paso tres tests de WebhookSigningTest |
| #87 G4b | Las canceladas por el vencimiento del MTCN dicen «Sistema», no «Soterex (API)»; un índice nuevo en audit_logs por transaction_id |
| #88 G5 | «Supervisa los soportes» exige fondeo_caja:read más transacciones:write en la misma asignación. Una carrera aceptada y documentada: dos subidas simultáneas del mismo tipo faltante pasan las dos |
| #84 G1 | Retención de versiones no vigentes: 90 días en Staging y 365 en producción (si hay un plazo regulatorio, se ajusta ahí); SSE-S3 y no KMS; prevent_destroy también en Staging; ADR-019 en vez del 017 del plan |
| #85 G2 | Una limitación sin resolver: antes de pagar, una ACCEPTED que otro PDV ya reclamó sigue dando 404 en los soportes a quien no es de ese PDV (cambiaría una regla de alcance de datos personales) |
| #91 G8 | permisos:diferencias termina siempre con código 0 (es un informe; con otro código la corrida de Actions saldría en rojo) |
| #92 G9 | El prefijo C- de la búsqueda exige un guion o espacios entre la C y los dígitos |
| #93 G10 + G11 | QC-30 por defecto: estricto sin separadores en el servidor; no se valida el dígito verificador del DPI |
6. Lo que NO se hizo, y por qué
- G13 — alerta de reposición al 30 %, confirmaciones de recepción y columna de porcentaje en los extractos. La dejaste para después (2026-10-07): es la entrega más grande del plan (L, tres bloques: A alerta, B confirmaciones, C porcentaje) y no querías esperar lo que lleva. Además tiene preguntas al cliente sin respuesta: QC-34 a QC-39 (sobre qué ingreso se calcula el porcentaje, si alcanza verla en la herramienta, un porcentaje o uno por nivel, si la confirmación bloquea, si se acepta la autoconfirmación, si quieren la columna); sus decisiones de diseño (D3-20 marca o estado, D3-21 dónde vive el porcentaje, D3-26 el escenario) no se usaron, y el plan trae una recomendación para cada una. Y el cliente dejó oculto el Escenario 2 de prefondeo en su Excel, así que el escenario no está definido. El diseño y los valores por defecto están en el plan, §4 «G13»; saldría de un branch
feature/v3-tesoreria-reposicion-y-confirmacionapilado sobre G12 ya mergeada. Mientras tanto no hay alerta ni confirmación de recepción en tesorería, y el pedido RV3-60, 62, 64 y 68 del cliente sigue abierto. - G8.9 — llevar a la matriz las celdas de Staging que difieran. Depende de correr
permisos:diferenciasen Staging, que solo existe después del deploy de G8, y de decidir celda por celda con vos. G9.8 — renombrar el municipio «Guatemala» a «Ciudad de Guatemala».Hecho el 2026-10-07 por pedido tuyo (no es producción y los datos son simulados): migración de datosg98_ciudad_de_guatemala, que solo renombra si la etiqueta sigue siendo la sembrada. Cambia la ciudad del beneficiario en Cumplimiento y en el A4 de todos los pagos de ese municipio (retroactivo en reimpresiones). QC-23 queda como aviso al cliente, ya no como pregunta.- RV3-67 de G12 — el «Saldo final CIS Holding» de 32.708. Espera QC-33: supera en 208 (la comisión) a lo que queda, y puede ser un doble conteo. No se muestra.
- El comando
diagnostico:v3(G0.6), y con él el PR 0b. No se hizo: es un comando artisan, o sea código, y G0 salió como solo documentación. Por eso las consultas de solo lectura sobre Staging las corrés vos con el acceso a la base que tengas, y cada runbook trae las suyas; ninguna se corrió. Tampoco G0.7 (cuentas de prueba para los escenarios mixtos: segundo Cajero, Supervisor de un solo PDV, cuentas combinadas) ni la mitad de G0.8 que falta:docs:builden el CI de PR (elnpm testya lo trajo otro commit,740b10e). - Revisión de
security. El plan la pide para G1, G2, G5, G6, G8, G9, G11, G12 y G13.B. El PR de G1 dice expresamente que no se hizo; los cuerpos de los demás describen revisores con una lente de permisos o de datos pero no nombran asecurity: decidís vos si querés pasarla antes del merge. - La advertencia de combinaciones sensibles de perfiles en la ficha de usuario (D3-24 b): se resolvió solo documentando (D3-24 a), como recomendaba el plan.
- Nada contra Producción. Ninguna de estas entregas la toca; el Terraform de producción de G1 está escrito y validado, y no se aplicó.

