Skip to content

Plan — Ajustes v3: respuesta del cliente a la entrega B1–B5 (Soterex GT) ​

Date: 2026-10-04

Estado de partida (2026-10-04). Los ajustes v2 están hechos: B1 a B7 están mergeadas a main y desplegadas a Staging (B1–B5 el 2026-10-02 con el PR #69; B6, cuatro perfiles y menú, y B7, extractos de tesorería, después; los arreglos de deploy #74, #75 y #76 están en main). El cliente probó hasta B5. Sus capturas son del Staging del 30/09 y el 01/10: anteriores a B1–B5 (que llegaron el 02/10), al arreglo de los límites de subida de archivos (01/10) y al de la regla del WAF (apply del 02/10), y por supuesto a B6 y B7, que no vieron. Por eso parte de lo que piden ya está hecho, y una parte chica contradice lo que hicimos después. Cada ítem de este plan dice cuál de los casos es, con evidencia de código.

Fuentes:

  • Mail de Magaly Benavides (CIS-EC), 2026-10-02, respuesta a nuestro pedido de "lo que necesitamos de ustedes para poder cerrar bien esa etapa" (sin el hilo citado).
  • Excel "Soterex GT - ajustes v2.xlsx" (12 hojas, 33 capturas reales de Staging con anotaciones del cliente: las anotaciones son pedidos, también las que son formas dibujadas sobre una captura, como el cuadro de texto de RV3-28, que el volcado a texto no muestra). Guardado en doc/reference/2026-10-02-respuesta-ajustes-v2/, sin commitear: ver G0 por los datos personales de las capturas.
  • Decisiones de Carlos del 2026-10-04 (§3, firmes).

Qué es esto: la reconciliación de esas fuentes contra el código de main, las decisiones que salen de ahí y el plan de ejecución de la próxima tanda (G1 a G13, más G0 de cierre administrativo). No hay código en este PR: es el plan.

Cómo leerlo. Las referencias archivo:línea salen de leer el branch feature/ajustes-v3-cliente-gt (= main más este plan) el 2026-10-04; verificalas antes de apoyarte en ellas. Donde una causa no se pudo determinar leyendo, dice "no determinado — hay que reproducir" y se pide la reproducción antes de construir. Las inferencias del product owner están marcadas como propuesta; lo que pide el cliente está citado de su hoja. Los MTCN que el cliente cita se mencionan; ningún dato personal de las capturas (beneficiarios, documentos, teléfonos, mails, direcciones) se copia acá.

⚠️ Lo más urgente de este plan no lo pidió el cliente. Al analizar el ítem 5 de la hoja Pago ("la documentación cargada no se puede visualizar") apareció que los soportes de un pago no se guardan en ningún lugar persistente: el disco documents es local dentro del contenedor Fargate y se pierde en cada deploy (G1). Es bloqueante para producción (son identificaciones y el respaldo contable del pago) y condiciona todo re-test del cliente sobre documentos.


Actualización del 2026-10-07 (noche). El recuadro que sigue se escribió con los PRs todavía abiertos; hoy G1 a G12 están en main por el PR de integración #95 (fde0013) y en Staging por el #96 (a47ace2, deploy verde). Además: G9.8 está hecha (en main), permisos:diferencias en Staging dio «Sin diferencias» (G8.9 cerrada) y G1 está verificada de punta a punta contra un S3 real (el terraform apply, el deploy que tomó las variables, un soporte subido y abierto, y abierto de nuevo después de reemplazar el contenedor; el detalle y lo que quedó sin medir, en el runbook de G1). Siguen abiertas: G13 (diferida), RV3-67 (QC-33), el comando diagnostico:v3 (G0.6), la revisión de security de G1, y avisarle a Magaly (QC-4). Los PRs individuales ya están resueltos: #83, #84, #85 y #87 se mergearon, y #86 y #88 a #94 se cerraron sin mergear el 2026-10-07 (su contenido está en main por el #95). Donde la tabla de abajo diga «ninguna mergeada» o «sin probar contra Staging», vale esta nota.

Estado de la ejecución (2026-10-07). Las entregas G1 a G12 están implementadas y ninguna está mergeada: G1 a G11 salieron en once PRs abiertos (#83 a #93) y el de G12 todavía no existe (se está terminando; viene apilado sobre #93). G13 quedó afuera por pedido de Carlos y no se tocó. Nada se probó contra Staging (no hay login): cada PR dice qué se verificó en dev y con tests, y qué decisiones se tomaron sin Carlos. Lo que le toca a Carlos, paso a paso (merge, despliegue por lotes, terraform apply de G1, avisos al cliente, verificaciones y preguntas pendientes), está en 2026-10-07-ajustes-v3-pasos-para-carlos.md. Lo que sigue de esta página es el plan tal como se escribió el 2026-10-04, sin reescribir: donde difiera de esta tabla, vale la tabla.

EntregaPR · baseQué cambió respecto de lo escrito acá, o qué quedó sin hacer
G0este PR (feature/v3-cierre-administrativo)Solo la parte documental. G0.6 no se hizo: el comando diagnostico:v3 no existe (y con él, el PR 0b), así que las consultas de solo lectura sobre Staging las corre Carlos con el acceso a la base que tenga; los runbooks de staging.md traen las suyas. G0.7 (usuarios de prueba mixtos) y la mitad de G0.8 (docs:build en el CI de PR; el npm test ya lo trajo otro commit) tampoco se hicieron. Los mails y la muestra al cliente son borradores: no se mandó nada
G1#84 · mainHecha, con ADR-019 (el plan decía 017, ocupado por C2P). Sin la revisión de security (sigue sin hacerse). (Probada contra un S3 real en Staging el 2026-10-07: ver la actualización de arriba.) Necesitó un terraform apply a mano (D3-1 a: bucket privado)
G2#85 · mainHecha (D3-2 a). G2.2 (el 422 al multi-PDV sin PDV activo) salió en G4a, como decía el plan. Queda documentada una limitación: una ACCEPTED que otro PDV ya reclamó sigue dando 404 en los soportes a quien no es de ese PDV
G3#83 · mainHecha (D3-4 b, D3-5 a, D3-6 a): el backend rechaza TRANSFERENCIA con 422 y las filas históricas no se tocan. Las cajas de Staging ya descontadas se corrigen con el runbook G3.5
G4Se partió. G4a #86 · #85 y G4b #87 · mainG4a: G4.1, G4.2, G2.2, G4.6 y G4.7 (D3-7 b, D3-8 sí; ADR-020). G4b: G4.3 a G4.5 (columna «Procesada por», rótulos de PDV, nombre del Excel)
G5#88 · #86Hecha (P3-1 a P3-4, D3-9 a, D3-10 1). Quedó apilada sobre G4a y no solo sobre G2: la cadena es lineal
G6#89 · #88G6.A y G6.B juntas (D3-12 B, D3-13 i; ADR-021, que supersede en parte ADR-013 §5), más H3-03. G6.C salió con G7
G7#90 · #89G7 y G6.C juntas (D3-14 a; ADR-022). Apilada sobre G6 completo, no solo sobre G6.A. El motivo «Retiro por baja de caja» es una constante en código, sin migración y sin que Tesorería lo haya aprobado. Arregla de paso tres tests de WebhookSigningTest
G8#91 · #90Junta F1 y F2 (D3-11 a ya decidida). No incluye G8.9 (llevar a MATRIX las celdas de Staging que difieran: depende de correr permisos:diferencias en Staging). Sin advertencia de combinaciones (D3-24 a: solo documentar). Cambia permisos de usuarios reales en el deploy
G9#92 · #91G9.8 se hizo después (2026-10-07, a pedido de Carlos, en el PR de integración #95): renombrar «Guatemala» a «Ciudad de Guatemala» (antes esperaba QC-23). «Send/Sent» y el idioma del Update no se tocan (QC-19, QC-20). Los tres PDV reales son un procedimiento por pantalla (D3-17), no código
G10 y G11#93 · #92Juntas, en un solo PR en vez de dos apilados. Los casos dudosos de países no se cargaron (QC-27); QC-30 por defecto: estricto, sin separadores en el servidor
G12PR sin crear · #93Alcance de una Tesorería de un solo país, tarjeta de la Holding limitada a sus países y rótulos (D3-19 b). No incluye RV3-67 (el «Saldo final CIS Holding» de 32.708: espera QC-33)
G13—Diferida por pedido de Carlos (2026-10-07): alerta de reposición al 30 %, confirmaciones de recepción y columna de porcentaje. No se tocó; su diseño y valores por defecto siguen en §4

Orden de merge (obligatorio para las apiladas): #85 → #86 → #88 → #89 → #90 → #91 → #92 → #93 → G12. #83, #84 y #87 no dependen de nadie en lo conceptual, pero chocan con la cadena (con código, en #84 y #87): el archivo de pasos dice dónde y recomienda mergearlos después de ella. Correspondencia con «Orden y branches» (§2): A = #84, B1 = #85, B2 = #86, B3 = #87, C = #83, D = #88, E1 y E2 = #89, E3 y E4 = #90, F1 y F2 = #91, G = #92, H y su apilado = #93, I = el PR de G12; el PR 0b no se hizo.

Un punto del plan que quedó viejo: el «2001». §6.2 S-4, D3-22 y RV3-91 dicen que un transaction_id repetido «da 2001». Ya no es cierto desde el PR #80 (mergeado el 2026-10-05): un SendRequest repetido devuelve la transacción original con COD_009 y no aplica los datos nuevos; el 2001 está retirado (sign-off, 1.4 y Apéndice C). El riesgo sigue, con otra forma: el reenvío parece un éxito y el cambio no entra. El borrador del mail a Sean ya lo dice así (borrador); las tres frases de abajo no se reescribieron.

Resumen para Carlos ​

Para leer en tres minutos. Todo el detalle está más abajo; los números salen de contar las filas de §1.1 y §6.1.

Qué pidió el cliente, en números. El mail y las 12 hojas del Excel dan 99 ítems: ✅ 41 ya cubiertos · 🐞 4 bugs · 🆕 23 cambios · ⚠️ 6 que contradicen algo nuestro · ❓ 12 preguntas · ℹ️ 13 informativos. Casi la mitad ya estaba hecha: sus capturas son anteriores a B6 y B7, que no vieron. De los 99, 38 se cierran solo con una respuesta o con documentación (G0), 4 necesitan respuesta y una entrega, 56 son solo de una entrega de G1 a G13 y 1 no pide nada. Además, 12 hallazgos propios (§1.2), 6 de ellos bugs.

Lo más urgente, y no lo pidió el cliente: G1. Los soportes de pago (identificaciones y respaldo contable) no se guardan en ningún lugar permanente: el disco documents es local al contenedor y se pierde en cada deploy; no hay bucket ni librería de S3. Staging se promovió 11 veces entre el 29/9 y el 4/10. Eso explica el "No se pudo abrir el documento" del cliente y es bloqueante para producción. Necesita D3-1 y que corras vos el apply. Hasta que esté, no hay que pedirle que repita pruebas con documentos.

Se puede arrancar hoy (con tu OK a la recomendación indicada): G0 (este PR: respuesta y documentos al día; las consultas de solo lectura a Staging no son de hoy, dependen del PR 0b y de su promoción: ver el párrafo siguiente), G3 (medio de pago solo efectivo), G12 (alcance de Tesorería), G6.A (quién opera cada caja), G6.C (la línea de país que dibujó el cliente), la parte de G8 que es documentación y dos fugas de Reportes, lo seguro de G9 (cuatro columnas, A4 de cuatro incisos) y los 23 renombres de G10. G2, G4 y G5 arrancan después de reproducir en Staging (G0.6) y con tus D3-2/3, D3-7/8 y D3-9/10; G5 sale además después de G2, y el Reporte individual de G4 (G4.3 a G4.5) no espera a nadie.

Camino crítico de las consultas (G0.6). Las de base de datos se hacen con un comando artisan nuevo, diagnostico:v3, que va en el PR 0b y solo existe en Staging cuando ese PR mergea a main y se promueve a staging (run-artisan-command.yml corre sobre la imagen ya desplegada). O sea: PR 0b → main → promoción a Staging en un lote propio, con tu OK → recién ahí corrés las consultas → recién ahí se construyen las entregas que las esperan (G2, G3, G4, G7, G8, G9, G10, G11 y G12, cada una con las suyas, ver G0.6). No esperan ese lote la consulta 7 (que es DevTools y CloudWatch) ni la parte de la 10 que se lee en los logs del ALB.

No se puede arrancar, y por qué: G1 (D3-1 y el apply) · G6.B (revierte ADR-013 §5: D3-12/13 y QC-12) · G7 (D3-14, QC-16) · la migración de G8 (D3-11: cambia permisos de usuarios reales) · G11 (D3-15, QC-30) · G13 (QC-34 a 39, D3-20/21: es la más cara y el cliente dice que el escenario no está definido) · RV3-67 de G12 (QC-33).

Decisiones que necesito de vos (§3.3: 26 en total, las 16 filas cubren todas; 🏛 pide ADR):

D3Una líneaRecomendaciónDestraba
D3-1 🏛Dónde se guardan los soportesBucket S3 privadoG1
D3-2, 3Pagador de otro PDV; multi-PDV sin PDV activoExcepción del pagador; rechazar con 422G2 (D3-3: G2.2, con G4.1)
D3-4, 5 🏛, 6Transferencia: dónde se saca; formas de pago; cajas ya descontadas422 en el backend; sin catálogo; un AJUSTE por cajaG3
D3-7 🏛, 8PDV del pago; PDV de los PAID viejosEl de la caja solo si queda vacío; backfill auditadoG4
D3-9, 10El Cajero sube lo que falta; documentos de un intento anteriorSí; se mantienen con "subido por"G5
D3-11Tipo de cambio sin lectura para Cajero y SupervisorSí, avisando antesG8 (migración)
D3-12, 13 🏛Quién cierra una caja ajenaDueño, Supervisor y Admin; derivado, sin tocar la matrizG6.B
D3-14 🏛Desactivar una caja con saldoRechazarG7
D3-15 🏛Dónde viven las reglas de DPI y PasaporteCuatro columnas en el catálogoG11
D3-16Lista de países y casos dudososMigración; cargar Kosovo y AntillasG10
D3-17, 18PDV reales; prefijo "C-"Por UI; aplicarlo ya, reversibleG9
D3-19Qué ve de la Holding una Tesorería de un paísSu parte, con aviso de parcialG12
D3-20 🏛, 21 🏛, 26Confirmación; alerta; escenarioMarca; fila única en Configuración y solo en la app; Escenario 1 "asumido"G13
D3-22, 23Mail único a Sean; muestra al clienteSí; con OK explícitoG0
D3-24Combinaciones sensibles de perfilesDocumentar ahoraG8
D3-25Montos en la metadata de AuditoríaAclarar la regla—

Preguntas al cliente: 35 vigentes (§6.1: QC-1 a QC-39, con 4 retiradas o diferidas), 11 frenan algo (QC-12, 16, 27, 30, 33 y 34 a 39); el resto tiene un valor por defecto que se implementa si no contestan. Más 5 consultas para Soterex en un solo mail (§6.2), solo consulta.

Qué contestarle por las dos decisiones firmes (texto completo en §6.0):

  • Tesorería es un solo perfil y es regional por asignación. No hay "Tesorería Local": una persona asignada a un solo país ve el estado de cuenta de su país y de sus PDV, y no carga nada en otro; "CIS Guatemala solo su estado de cuenta" queda cubierto sin rol aparte. Al dar de alta un país hay que sumárselo a la Tesorería regional; para ver un solo PDV el perfil es Supervisor. G12 ajusta lo que ve de la Holding.
  • Con más de un perfil se suman las opciones, a propósito. El cliente confirmó el 24/07 roles distintos por país y un Supervisor de varios PDV; que dentro de un mismo país se sumen las opciones es el diseño de ADR-014 §6 y no se les había consultado. Un selector solo escondería opciones (el permiso y el backend siguen); Cajero más Admin ya da el menú del Admin. Se documenta (manual, ficha, ADR-014 §6, sin ADR nuevo), se cierran tres fugas que causa la suma (H3-01 a 03) y se recomienda no mezclar Cajero y Tesorería en un país.

1. Reconciliación: qué respondió el cliente ​

Una fila por ítem del cliente, en el orden de las hojas del Excel (Pago, TXs, Prefondeo, Caja, Reportes-Informes, Auditoría, Ubicaciones, Menús y perfiles, Módulo tesorería, Dashboard, Catálogo Países, Catálogo Tipos ID) y después el mail. Ni siquiera los ítems "OK" o "sin cambios" quedan sin fila. La columna Fuente conserva la trazabilidad hoja/celda/imagen; img N es xl/media/imageN.png. Clasificación: ✅ ya cubierto · 🐞 bug · 🆕 cambio · ⚠️ contradice (una decisión o un documento nuestro) · ❓ pregunta · ℹ️ informativo. "G0" = solo respuesta o documentación, sin código.

1.1 Los ítems del cliente ​

#FuenteQué pide el clienteQué hay hoy (evidencia)Clasif.Entrega
RV3-01Pago!B2Pago "habilitada solo para el cajero y el supervisor de PDVs".Pago L·E lo tienen Cajero, Supervisor y Admin (RoleSeeder.php:60-63, 81-83, 126-130); pagar exige pago:write (routes/api.php:95-96). Decisión de Carlos del 2026-10-02 ("el Admin cancela y paga", ADR-014 §1 y §4). La propia hoja Menús y perfiles (C4/G4) lista a Administrador.⚠️G0 · QC-1
RV3-02Pago!A4/B4, img 2Si Soterex no cancela por API, "cancelar tx" solo para Administrador, no para Cajero (recuadro rojo en el botón "Cancelar transacción" de un Cajero).Hecho en B6.3: cancelar exige transacciones:delete, solo Admin, en la ruta (api.php:97-98) y en el controller (TransactionController.php:642-651); el botón sigue al permiso (PagoView.vue:73, MatchResultCard.vue:138-145, TransaccionDetalleView.vue:41,45). Tests en PerfilesAccesoApiTest.php. Soterex sí cancela por POST /api/c2p/v1/Cancel, que no pasa por estos permisos. La captura es previa al deploy de B6.✅G0
RV3-03Pago!A29/B29, img 15En una tx pagada se pueden modificar los documentos; "al igual que los datos, no deben permitirse modificar" (círculo azul sobre el "Reemplazar" de la Carta).Datos: bloqueados con 409 PAYMENT_DATA_LOCKED (TransactionController.php:720-730, 777-783), pero el formulario deshabilitado no se ve distinto (DatosPagoForm.vue:298). Documentos: no hay bloqueo; quien pagó, el Supervisor y el Admin suben y "reemplazan" sin límite (PermissionService.php:244-270; TransactionDocumentController.php:54-116; botón DocumentacionPago.vue:362-367).🆕G5 · QC-2
RV3-04Pago!A60/B60, img 3Tx pagada: los soportes se pueden visualizar, pero solo en modo consulta.Ver y abrir ya se puede y queda auditado (api.php:112-113; useTransactionDocuments.ts:131-146). "Modo consulta" lo tiene hoy quien no pagó y no es Supervisor/Admin; no quien pagó (puede_subir).🆕G5
RV3-05Pago!B61"La impresión de la papeleta puede estar habilitada siempre".Ya lo está para una tx pagada: el botón no depende de canUpload, la ruta acepta transacciones read o write (api.php:83-86) y papeleta() responde 422 TRANSACTION_NOT_PAID si no se pagó (TransactionController.php:974-1027).✅G5 (test)
RV3-06Pago!A81/B81, img 4, 5, 8, 9"No permite adjuntar documentos en PDF o JPG": elige el archivo y responde "No se pudo guardar el documento" (recuadros rojos).El código acepta PDF, JPG y PNG hasta 20 MB (TransactionDocumentController.php:72-80). Las capturas (30/9 y 1/10) calzan con dos fallas de infraestructura corregidas después: límites de PHP-FPM/nginx (1/10, commit 4a715de) y la regla SizeRestrictions_BODY del WAF (apply del 2/10, commit 36855c3). Ningún test sube archivos reales. Causa: media, no reproducida.✅ (re-test)G1 · QC-4 (diferida)
RV3-07Pago!A180/B180, img 6"La documentación cargada de un pago no permite visualizar": "No se pudo abrir el documento".Causa probable (confianza alta en el almacenamiento, media-alta en que sea lo que vieron): el disco documents es local dentro del contenedor (config/filesystems.php:30-45); no hay bucket, ni DOCUMENTS_DISK_DRIVER=s3 en la infra, ni league/flysystem-aws-s3-v3 en vendor/ (solo flysystem-local). Cada deploy borra los archivos y deja las filas → 404 DOCUMENT_FILE_MISSING (TransactionDocumentController.php:133-139). Staging se promovió 11 veces entre el 29/9 y el 4/10. La documentación dice lo contrario (S3 privado).🐞G1 · D3-1
RV3-08Pago!A199/B199, img 7Si el cajero se equivoca al cargar, que Supervisor o Administrador puedan reemplazar el documento. (La captura trae recortado un texto de una versión anterior: datos adicionales de una tx pagada solo visualizables.)Ya pueden: canManageTransactionDocuments deja pasar al nivel supervisor con alcance del PDV (PermissionService.php:244-270, isSupervisorTier :173-181). Reemplazar es subir otro del mismo tipo y el anterior queda (regla R8). No hay tests de reemplazo ni una acción de auditoría que lo distinga.✅G5 (tests, auditoría)
RV3-09Pago!A215/B215, img 10Ubicación de la papeleta A4: un botón "Imprimir papeleta A4" en la fila del encabezado, al lado del que existe (dibujó "tirilla" e "Imprimir papeleta A4").Formato por país ya hecho (B5): botón principal + chevron "Descargar en otro formato" (DocumentacionPago.vue:223-289); en Guatemala el botón visible es el A4. La captura es previa a B5. Falta la presentación que dibujó: dos botones siempre visibles. P9(b) de Carlos decidió "menú secundario" sin ver este dibujo.🆕G5
RV3-10Pago!A246/B246, img 11Después de guardar la tx, reemplazar documentos solo Administrador y Supervisor; el Cajero puede reemplazar mientras no haya dado "guardar" (óvalo sobre toda la columna de botones).El backend no distingue "subir uno que falta" de "reemplazar": store() siempre inserta (TransactionDocumentService.php:48-77). Con ACCEPTED sube/reemplaza cualquiera con transacciones:write en el país; con PAID/CANCELLED, quien resolvió, un Supervisor o un Admin (PermissionService.php:258-269). Es la misma regla que RV3-03.🆕G5 · QC-2
RV3-11Pago!A264/B264, B265 (MTCN 6189214933), img 12"Si se busca una tx y no se la paga, la herramienta no debería traerme cargados los documentos".Por diseño (ADR-008 §1 y §3) los documentos previos al pago quedan guardados contra la tx desde la primera subida y la tarjeta los trae al montarse (useTransactionDocuments.ts:52-75; PagoView.vue:504-513); el gate de pay() cuenta cualquier documento del tipo (Transaction.php:151-156). Ambiguo: (a) no ver los de un intento anterior o (b) no mostrar la sección al solo consultar. La captura usa el mismo archivo en todas las txs.❓G5 · QC-3 · D3-10
RV3-12Pago!A301/B301, img 13Del catálogo de medios de pago, quitar "transferencia bancaria".No es un catálogo: Transaction::DELIVERY_TYPES (Transaction.php:16-20), validado en TransactionController.php:918 y con <option> fijos (ConfirmActionModal.vue:184-187). Coincide con C13 (Carlos, 2026-09-30: el medio de pago es siempre efectivo).🆕G3 · QC-7
RV3-13Pago!A329/B329, img 14Si no se elimina, corregir el saldo: la transferencia sale de Tesorería, no del PDV (subrayado el movimiento "Pago MTCN 6189214933" en la caja).Confirmado: applyCashBoxDiscount descuenta la caja siempre que el país tenga Caja y nunca lee delivery_type (TransactionController.php:448-457, 548-640). Prefondeo País y Holding no miran el medio de pago. Se evita para los pagos nuevos con RV3-12; quedan los ya hechos en Staging.🐞G3 · D3-6
RV3-14Pago!A357/B357, img 16, 17"Se pagó esta tx, pero me dio error para la generación de la papeleta". La captura muestra "No se pudo cargar la documentación de esta transacción" (no el aviso de papeleta).Soportes y papeleta fallan con 404 por el mismo motivo: alcance por PDV (TransactionDocumentController.php:182-186; TransactionController.php:984-987 → PermissionService.php:198-211). Dos caminos dejan afuera a quien pagó: (1) el PDV de una ACCEPTED lo fija el primer documento (ADR-008 §1) y station_id ??= en pay() (TransactionController.php:480); (2) usuario con 2+ PDV sin PDV activo → PDV null (PermissionService.php:327-336). Cuál fue el caso: no determinado — hay que reproducir (MTCN 3751272495). Confianza: media.🐞G2 · D3-2
RV3-15TXs!B14, img 18La opción podría llamarse "Reporte individual".Hecho en B6 (AppLayout.vue:81; TransaccionesView.vue:175); path y name de ruta intactos (ADR-014 §9). Captura previa a B6. Queda con el nombre viejo el archivo transacciones-AAAAMMDD-HHMM.xlsx (TransactionController.php:309).✅G4 (archivo)
RV3-16TXs!A16/B16, img 19El reporte debe traer una columna adicional con el usuario que procesó la transacción (la captura es el Excel exportado; el texto no distingue pantalla de Excel).resolved_by_user_id existe y se graba al pagar y al cancelar un humano (TransactionController.php:481; TransactionCancellationService.php:53), pero no sale en la pantalla (lista blanca, ADR-016) ni en el Excel (8 columnas fijas, TransactionController.php:289). users solo tiene email.🆕G4 · QC-10
RV3-17TXs!A37/B37, img 20"No todas las txs muestran el PDV" (2 de 3 PAID con "—").Seis causas: (1) ACCEPTED sin PDV, por diseño; (2) CANCELLED por la API de Soterex (no hay persona); (3) PAID/CANCELLED por una persona con alcance ambiguo → resolveStationForResolution devuelve null (PermissionService.php:327-336; TransactionController.php:442, 480; el test TransactionApiTest.php:595-611 lo fija); (4) primer documento sobre una ACCEPTED, igual; (5) datos viejos o de demo; (6) el PDV queda fijado por un camino (primer documento, PDV activo) y la plata sale de la caja que abrió quien paga, que puede ser de otro PDV (applyCashBoxDiscount y el PDV se resuelven por separado a propósito, E4-multi §2.3). Quién pagó, con las capturas del propio Excel: la img 14 (Caja 1 de Central, 1/10) lista los pagos de 6189214933 y 3321190529 hechos por el mismo operador, con 13 minutos de diferencia, y esa persona es la de la img 31 (Cajero y Admin a la vez); en la img 20 el primero tiene PDV "—" y el segundo "Mixco Plaza". O sea que 3321190529 se pagó con plata de la caja de Central y quedó atribuida a Mixco Plaza: es la causa 6, el PDV no es null, y ni D3-7 (b) ni el backfill D3-8 la corrigen. Por qué el primero quedó en "—" no se explica con lo visible (no determinado). De 2916186807 (actualizada 14:32, fuera del rango de la img 14), quién la pagó sigue no determinado. Sin PDV, el pagador acotado no ve su propio pago, el Dashboard no lo suma y Cumplimiento sale con las columnas 33-36 vacías.🐞G4 · QC-9 · D3-7
RV3-18TXs!A58/B58 ("2" por segunda vez)"Este reporte podría ser la base para el reporte completo (cumplimiento)". La frase es ambigua: o el Excel de Reporte individual es la base de uno más ancho, o el reporte completo que ya existe es el que quieren.El reporte completo ya existe desde B4 como export aparte (36 columnas, permiso reporte_cumplimiento, solo Admin; ADR-016). El Excel de Reporte individual quedó delgado a propósito (8 columnas, más la novena de G4) porque los datos personales en bloque salen solo por Cumplimiento. Se da por contestado si QC-11 es sí (el valor por defecto).❓G0 · QC-11
RV3-19Prefondeo!B14, img 21Opción habilitada solo para los perfiles de la definición de tesorería.Hecho en B6: prefondeo/prefondeo_pais L·E solo para Tesorería y Admin; el Supervisor entra a Fondeo PDVs solo por fondeo_caja:read (RoleSeeder.php:104-150; ADR-015 §10). La captura es la pantalla vieja.✅G0
RV3-20Prefondeo!B15, B16Pestaña 1: ingresar/controlar el prefondeo de Soterex. Pestaña 2: controlar los fondeos a los PDV.Hecho en B7: Prefondeo Soterex (alta de asiento + dos extractos) y Fondeo PDVs (envío al país + extractos País y PDV): PrefondeoView.vue, PrefondeoPaisView.vue. Dos ítems de menú con dos pestañas cada uno.✅G0
RV3-21Prefondeo!B17Una pestaña individual por opción donde se vea el saldo final después de cada movimiento.Hecho en B7: cuatro extractos con saldo corrido, saldo anterior y rango (TreasuryStatementService.php; ExtractoTesoreria.vue:380-396).✅G0
RV3-22Prefondeo!B18-B21Cada movimiento con fecha, referencia (# de MTCN, débito, crédito) y saldo final, tipo estado de cuenta.Hecho en B7: Fecha · Concepto · Referencia · Débito · Crédito · Saldo. La referencia es el MTCN en pagos y comisiones y el texto libre en los asientos; los fondeos y ajustes de caja no tienen referencia (solo motivo). La "fecha" es la de carga, no una fecha valor: supuesto nuestro (el cliente pidió la "fecha del movimiento" y la leemos como la fecha de carga); no se pregunta aparte, se contrasta con la muestra de los extractos (G0.9).✅G0
RV3-23Caja!B22, img 22El menú podría llamarse "Saldos".Hecho en B6 (AppLayout.vue:86; CajaView.vue:525). La clave de módulo, la ruta y el tour siguen llamándose caja (ADR-014 §9).✅G0
RV3-24Caja!A23/B23Supervisor y Tesorería ven el saldo de todos los cajeros y PDV.Ya: ve el saldo real quien tiene fondeo_caja:read en el alcance de su asignación (PermissionService.php:140-143; CashBoxController.php:257-266); el Cajero solo el de la caja que abrió. "Todos los PDV" = los de la asignación. Hallazgo: canSeeBalance decide por país y no por PDV (H3-03).✅G6 (H3-03)
RV3-25Caja!A25/B25El mismo operador que abre una caja debe ser el único autorizado a cerrarla; hoy un segundo usuario puede cerrar la abierta por otro.Confirmado y es una decisión escrita que esto revierte: cierre() autoriza por apertura_cierre_caja:write sobre el PDV sin mirar opened_by_user_id (CashBoxController.php:385-443); ADR-013 §5 lo dice a propósito (la caja vencida de un cajero ausente la destraba un compañero o un Supervisor) y un test lo fija (CashBoxApiTest.php:1496-1502). A quien le cierran la caja, pay() le responde NO_CASH_BOX_OPEN_FOR_USER.⚠️G6 · QC-12 · D3-12
RV3-26Caja!A26/B26, img 23Si una caja está abierta, no puede abrirla otro usuario (para que no se crucen los saldos).Impedido: 409 CASH_ALREADY_OPEN sin filtrar por usuario (CashBoxController.php:281-299) más el índice único parcial cash_sessions_one_open_per_box. El único test es del mismo usuario. El cruce que sí es posible: B cierra la caja de A (RV3-25) y la abre.✅G6 (test) · QC-13
RV3-27Caja!A38/B38, img 24Incluir el usuario en la caja, para saber quién opera en cada una (círculo a la derecha de "Caja 1").No se muestra: /caja/disponibles trae opened_by_user_id pero no el mail (CashBoxController.php:53-124); la tarjeta muestra PDV, número, saldo y estado (CajaView.vue:618-640). El dato sí está en "Cierres por día".🆕G6 · QC-14
RV3-28Caja!A56/B56, img 25 (dos veces) y un cuadro de texto dibujado sobre la captura"Incluir una línea principal del saldo para GT, para Tesorería". El cliente dibujó cómo la quiere: sobre la captura de Saldos, entre el aviso de documentación pendiente y las tarjetas por PDV, un cuadro de texto "GUATEMALA / USD 24878.53" (xl/drawings/drawing5.xml, "CuadroTexto 7", con idioma es-EC, es decir que lo escribió el cliente; un rectángulo blanco tapa la parte original de la captura). 24.878,53 = 20.680,07 + 0,00 + 4.198,46, las tres tarjetas de la captura, y es el mismo número que "Distribuido en cajas" de Prefondeo País (img 33): el total de plata en las cajas de Guatemala. El volcado a texto no muestra los shapes: se encontró leyendo los XML de dibujo.Saldos muestra una tarjeta por PDV (CashBoxController.php:140-175); no hay línea de país. CountryPrefundingService::distributedInCashBoxes (:50-71) ya calcula ese total, en la moneda de pago vigente del país.🆕G6.C · QC-15
RV3-29Caja!A75/B75, img 26Habilitar una opción para administrar cajas: agregar…"+ agregar caja" existe desde E4-multi (EstacionesView.vue:375-385; StationController.php:122-135, auditado). Escuintla Norte aparece con 0 cajas en la captura: causa no determinada (H3-06).✅G7
RV3-30Caja!A75/B75…activar, desactivar.No existe: cash_boxes no tiene estado ni baja ("no hay borrado en este alcance", CashBoxService.php:153-157).🆕G7 · QC-16 · D3-14
RV3-31Reportes-Informes!B1, img 27Reportes habilitado para todos los perfiles excepto el cajero.Hecho en B6 (RoleSeeder.php:69, 91, 113, 137; AppLayout.vue:109-115; AppLayout.spec.ts, PerfilesAccesoApiTest.php:383-415). La pestaña Cumplimiento tiene permiso propio, solo Admin.✅G0
RV3-32Reportes-Informes!A22/B22Añadir el reporte completo solicitado para cumplimiento.Hecho en B4: pestaña Cumplimiento, 36 columnas (ReporteCumplimientoService.php; api.php:276-278). Las cuatro columnas que el cliente validó en el mail: RV3-89 a RV3-93.✅G9
RV3-33Auditoría!B19, img 28Opción habilitada solo para el Administrador.Hecho en B6: auditoria L solo para Admin (RoleSeeder.php:72, 94, 116, 146); la migración de B6 se la sacó al Cajero y al Supervisor.✅G0
RV3-34Auditoría!B20Pasar a menú Administración.Hecho en B6 (AppLayout.vue:132); la URL sigue siendo /admin/auditoria.✅G0
RV3-35Ubicaciones!A27, img 29El tipo de cambio pasa al menú de Tesorería (lo controla finanzas a diario).La ubicación está hecha en B6 (AppLayout.vue:106; ruta /tipo-cambio). Pero B6 lo dejó en solo lectura para Cajero y Supervisor (RoleSeeder.php:68, 90; ADR-014 §9, decisión nuestra) y la hoja de menús lo reserva a Administrador y Tesorería. Ninguna función lo necesita: pay() usa ExchangeRateService en el servidor y Guatemala paga en dólares.🆕G8 · D3-11 · QC-17
RV3-36Ubicaciones!A28El resto de las opciones (países, estaciones) se quedan en este menú.Hecho (Parámetros: Países y Estaciones/PDV; router/index.ts:213-263).✅G0
RV3-37Ubicaciones!A29, img 29 y 30Los tipos de ID, provincias, ciudades, etc. (combos) se manejan desde esta misma opción.Hecho desde A4/B1: pestaña Catálogos dentro de Parámetros, solo Admin (router/index.ts:270-279). La img 29 es de un usuario sin abm_catalogos, por eso no la veía.✅G0
RV3-38Ubicaciones!A30El menú podría llamarse "Parámetros".Hecho en B6 (AppLayout.vue:128).✅G0
RV3-39Ubicaciones!A32/B32 ("1"), img 30Añadir el catálogo de formas de pago.Las formas de pago no son un catálogo: son una lista fija con comportamiento atado en código (cuenta bancaria, 4 documentos extra, columna 16 de Cumplimiento, descuento de caja). No dicen qué formas faltan. Choca con C13 y se superpone con RV3-12.❓G3 (default: no) · QC-8 · D3-5
RV3-40Menús!C4:G4Pago: Cajero, Supervisor, Administrador.Coincide celda por celda (RoleSeeder.php:61, 82, 105, 129). Ver la contradicción RV3-01.✅G0
RV3-41Menús!C5:G5Transacciones (Reporte individual): Cajero, Supervisor, Administrador.Coincide (RoleSeeder.php:62, 83, 106, 130). Riesgo de datos: la img 32 de un Cajero en Staging no tiene "Transacciones" aunque el seeder se la da desde A5.1; el deploy corre solo migrate y la migración de B6 no fija esa celda. No determinado: consultar role_permissions de Staging.✅G8 (verificación) · H3-04 · QC-18
RV3-42Menús!C6:H6Caja (Saldos): Cajero, Supervisor, Administrador, Tesorería.Coincide (RoleSeeder.php:63, 84, 107, 131).✅G0
RV3-43Menús!B8:H9Tesorería: "traer opciones actuales"; Prefondeo – Soterex: Administrador y Tesorería.Coincide (RoleSeeder.php:110, 134).✅G0
RV3-44Menús!C10:H11"Opciones nuevas": Fondeo – PDVs: Supervisor, Administrador, Tesorería.No es una pantalla nueva: es el antiguo Prefondeo País más la pestaña PDV de B7; el Supervisor ve solo la pestaña PDV de sus PDV (AppLayout.vue:102; ADR-015 §10).✅G0
RV3-45Menús!B13:H14Reportes: Supervisor, Administrador, Tesorería.Coincide.✅G0
RV3-46Menús!A17:G20Administración: mantener las opciones actuales; Auditoría se mueve acá, solo Administrador.Coincide (AppLayout.vue:116-134).✅G0
RV3-47Menús!C21:H22"Mover a otro menú": Ubicaciones (tipo de cambio) para Administrador y Tesorería.Igual que RV3-35.🆕G8
RV3-48Menús!H6, H9, H11, H14, H22En las cinco filas donde participa Tesorería: "Tesorería Local o Regional según corresponda".D3-T1: Tesorería es un solo perfil y es regional; no existe "Tesorería Local". Las cinco celdas se leen "Tesorería" y ya las cubre ese rol (RoleSeeder.php:104-125). "Local o Regional" lo da la asignación de países de cada persona.ℹ️ (decidido)G12 (alcance, docs) · G0 (respuesta)
RV3-49Menús!A25/B25 ("1")Con más de un perfil la herramienta mezcla las opciones de menú; "debería haber una opción de consulta de con qué perfil se quiere ingresar".D3-T2: la mezcla es intencional y se mantiene; no hay selector de perfil. Hoy el menú es la unión global de las asignaciones (PermissionService.php:363-379; stores/me.ts:60-62) y los datos y las acciones se deciden por país. Hay que contestarle por qué y documentarlo.⚠️ (decidido)G0 (respuesta) · G8 (docs)
RV3-50Menús!B26, img 31"Menú cuando tiene los 2 perfiles": Backoffice·GT más Admin·GT, con todo el menú subrayado.Con B6, Cajero más Admin da el menú del Admin (el Admin contiene todo lo del Cajero): la mezcla desaparece en la práctica.ℹ️G0
RV3-51Menús!B48, img 32"Menú cuando tiene un solo perfil": Backoffice·GT solo.Previa a B6. Con B6 un Cajero ve Caja (Pago, Reporte individual, Saldos), Tesorería (hoy solo Tipo de cambio, ver RV3-35) y Documentación.ℹ️G8
RV3-52Módulo tesorería!A1/B1, img 33"Este par de menús ajustar al detalle de las celdas de abajo, que es la forma correcta de controlar los saldos de c/entidad" (óvalo sobre "Prefondeo Holding" y "Prefondeo País").La captura es previa a B6/B7. Hoy son "Prefondeo Soterex" y "Fondeo PDVs" con dos pestañas de estado de cuenta cada uno (ADR-015 §10). Del "detalle de las celdas" faltan las confirmaciones, la alerta al 30% y la regla fina de visibilidad.✅G0 (paraguas)
RV3-53Módulo tesorería!A24, A26Títulos "Flujo para API Soterex" y "Módulo Tesorería".Informativo.ℹ️—
RV3-54Módulo tesorería!A28/B28Escenario 1: Soterex prefondea a CIS Holding y esta a CIS Guatemala y CIS EC.Es el modelo implementado (ADR-007, tres ledgers, saldos derivados). El plan v2 lo listó como confirmado (C7), pero el Excel del 22/09 ya traía "Tere confirma el escenario a usar" y el cliente repite en la hoja Dashboard que no está claro: C7 es una lectura nuestra.✅G0 · D3-26 · QC-31
RV3-55Módulo tesorería!B29 (y B62)CIS Holding ve todo el movimiento, igual que CIS EC (administrador); CIS Guatemala solo su estado de cuenta.Admin y Tesorería con todos los países ven todo. Una Tesorería de un solo país ve País y PDV de su país (eso cubre "solo su estado de cuenta"), pero también la porción de su país de los dos extractos de la Holding y el saldo global de la Holding en la tarjeta (PrefundingController.php:63-66); y partial cuenta países inactivos (TreasuryStatementController.php:297).🆕G12 · D3-19 · QC-32
RV3-56Módulo tesorería!B31, F31Paso 1: Soterex notifica a CIS el monto de prefondeo. Nota: consultar a Soterex si lo comunicarán por la API.No existe canal entrante de prefondeo: el contrato C2P tiene token, SendRequest, Cancel y Notifications. Hoy se carga a mano (PrefundingController::store). La consulta a Soterex nunca se hizo.❓G0 · D3-22
RV3-57Módulo tesorería!B32Paso 2: si lo notifica por API, CIS confirma la recepción; si no, CIS ingresa el monto.La rama manual está cubierta: cargar el asiento es confirmar que llegó. La rama API no existe porque no existe el aviso (RV3-56).✅G0
RV3-58Módulo tesorería!F32, F34, F65El costo bancario por acreditación lo asume quien recibe y no es parte del control del prefondeo.Coincide con C8 y ADR-015 §7: el crédito es el monto del asiento; no se modela costo bancario. Falta una línea en el manual. (F65 dice "CIS Holding" dentro del Escenario 2, que no tiene Holding.)✅G12 (manual)
RV3-59Módulo tesorería!B33Paso 3: la Holding envía prefondeo a Guatemala / EC.Hecho (CountryPrefundingController::store; POST /prefondeo-pais).✅G0
RV3-60Módulo tesorería!B34Paso 4: CIS Guatemala / EC confirma la recepción.No existe ninguna confirmación: el asiento cuenta en el saldo apenas se carga.🆕G13.B · QC-37, QC-38
RV3-61Módulo tesorería!B35Paso 5: CIS Guatemala envía prefondeo a sus PDV; Ecuador no necesita desarrollo de acá en adelante.Hecho: fondeo de caja con aviso OVER_COUNTRY_PREFUNDING; Ecuador no tiene módulo Caja.✅G0
RV3-62Módulo tesorería!B36Paso 6: cada PDV confirma la recepción.No existe.🆕G13.B · QC-38
RV3-63Módulo tesorería!B37Paso 7: del prefondeo se debitan las txs pagadas, incluido el valor de comisión.Hecho por capa (ADR-007 §1): la Holding resta principal más comisión; el país y la caja, solo el principal.✅G0
RV3-64Módulo tesorería!B38, F38 y las marcas S47, X50, K83, N98, S101, N57Paso 8: cuando el saldo prefondeado llega al 30%, el nivel de abajo pide un nuevo prefondeo (PDV al país, país a la Holding, Holding a Soterex); el % es un parámetro. Marcas "enviar alerta de pedido de prefondeo adicional" en PDV1 (30,0%), PDV2 (22,2%) y en el Escenario 2.No existe nada: ni umbral, ni cálculo, ni aviso de saldo bajo. No hay mail y el scheduler de Staging está apagado. Estaba fuera de alcance en el plan v2 §6 ("queda anotada"). Reglas que fija la planilla: comparación ≤ inclusiva; base = lo recibido; la Holding mide su saldo neto de comisión.🆕G13.A · QC-34, QC-35, QC-36
RV3-65Módulo tesorería!B40:W53Ejemplo del Escenario 1 con los saldos de cada entidad (C, H, L, Q, V).Reproducido: TreasuryStatementApiTest::test_reproduce_la_planilla_del_cliente_paso_a_paso da 32.292 / 20.208 / 7.000 / 1.500 / 4.000. Los números son idénticos a los del Excel del 22/09.✅G0
RV3-66Módulo tesorería!filas 55-59Totales por columna (comisiones 208, pagos de PDV 3.500 y 14.000), saldos finales y filas de control en 0.El control es automático (cierre = monto actual = servicio). La suma de comisiones no aparece separada y el test no afirma los totales de los PDV.✅G12 (opcional)
RV3-67Módulo tesorería!F57:H58"Saldo final CIS Holding" = 32.708 (Holding sin repartir 20.208 más el saldo final de CIS Guatemala 12.500).La app no muestra ese número; muestra 32.292 (saldo global de la Holding), 20.208 (pestaña CIS Holding) y 12.500 (país). 32.708 supera en 208, la comisión, a la plata física que queda (32.500): puede ser doble conteo o un activo contable. No se puede decidir leyendo.❓G12 (no empezar) · QC-33
RV3-68Módulo tesorería!columnas D, I, M, R, WUna columna de porcentaje en cada estado de cuenta (está en el ejemplo visible, bajo "qué debería ver c/entidad"; la hoja no tiene columnas ocultas).Los extractos no la tienen y el plan v2 §6 la dejó afuera, pero el cliente la pide en cada estado de cuenta, así que no se descarta: se entrega una columna derivada y de solo lectura (G13.C) salvo que digan que no. Los cinco % del ejemplo no miden lo mismo (consumo vs. distribución: I cae a 40% apenas la Holding envía a un país) y "lo recibido" no está definido con más de un ingreso: de ahí QC-34 (la base) y QC-39 (si la quieren).❓G13.C · QC-34, QC-39
RV3-69Módulo tesorería!G48:G50, G80La comisión del ejemplo es 1,2% del principal.En la app la comisión la manda Soterex en cada SendRequest (C2PController.php:70) y CIS no la calcula; el ejemplo mezcla 1,0, 1,2, 1,5 y 1,15%.ℹ️G0
RV3-70Módulo tesorería!A61:B62, A64:B69Escenario 2: Soterex prefondea en forma independiente a CIS Guatemala y CIS EC (sin Holding).Las filas 61 a 111, todo el Escenario 2, están ocultas en el archivo (hidden="1" fila por fila, sin agrupar: alguien las ocultó a mano). La fila 112 "Perfiles", visible, lista solo entidades del Escenario 1, y el mail habla de "un ejemplo completo" en singular; pero la nota de Dashboard sigue diciendo que el escenario no está definido (RV3-74): la señal es mixta. Se registra y no se toma como requisito. El modelo es el 1; el 2 se podría cargar con las mismas capas, pero no existe el concepto de "entidad" ni de qué países cuelgan de cuál. Los pasos del bloque están numerados 1, 2, 5, 6, 3, 4.ℹ️G0 (fuera de alcance) · QC-31
RV3-71Módulo tesorería!filas 73-89 (ocultas)Escenario 2, bloque CIS EC: Soterex↔CIS EC debe dar 4.271 y "CIS EC" 4.742.Contenido oculto: se anota por si lo vuelven a mostrar, no es requisito. 4.271 sale del extracto Soterex↔Holding filtrado por país. 4.742 = saldo del país 4.400 más todas las comisiones (342, también las de Guatemala): requeriría una pertenencia país→entidad que no existe. Error de la hoja: C76 (=C79+B76) apunta hacia adelante y arrastra a C77, y muestran 9.334 en vez de 15.000.ℹ️G0 (fuera de alcance)
RV3-72Módulo tesorería!filas 92-110Escenario 2, bloque Guatemala: 7.287 con Soterex, 7.500 CIS Guatemala, 1.500 PDV1, 6.000 PDV2.Se reproduce con las mismas capas (envío completo de 25.000 al país). Falta un test con estos números (bloque oculto: es opcional y no sale de un requisito). La hoja rotula como PDV1 al PDV2 (P107).✅G12 (test)
RV3-73Módulo tesorería!fila 112Perfiles: Soterex↔Holding y CIS Holding = "Tesorería Regional"; CIS Guatemala, PDV1 y PDV2 = "Tesorería Local".D3-T1: un solo perfil. "Regional" = Tesorería con asignación sin acotar a todos los países; "Local" = asignada a un país. Para ver solo un PDV el perfil es Supervisor (una asignación acotada por PDV no lee los extractos de país entero, ADR-015 §5).⚠️ (decidido)G12 · G0 (respuesta)
RV3-74Dashboard!B23, img 1"No se solicitan cambios hasta tener claro por qué escenario de prefondeo se decide que vayamos".El plan v2 trató el escenario como definido (C7 y §6: "ya está definido"); el cliente dice que no lo está. El KPI "Saldo de prefondeo (país)" es el saldo de la Holding atribuible al país (DashboardController.php:117-121), no el global ni el disponible.⚠️G0 (corregir C7) · QC-31
RV3-75Catálogo Países (255 filas)La lista de países que tiene que ofrecer el desplegable "País de la identificación" y que sale en Cumplimiento.249 ítems ISO sembrados (B1.2). Contra la hoja: 225 etiquetas idénticas, 23 con otro nombre (p. ej. Holanda, Suazilandia, Macedonia, Qatar, República Checa) y los casos de RV3-76 (2 con código que no tenemos, 3 sin código ISO, #216 y Timor Oriental repetido: 255 en total; Antártida no está en su lista, ver G10). Los nombres se resuelven al imprimir, así que el cambio es retroactivo en reimpresiones. El encabezado de la hoja (Global Country Values, #, Translation - Spanish) sugiere un picklist exportado, quizá el de Soterex o su Salesforce: no determinado, se pregunta (S-5).🆕G10 · D3-16 · QC-26 · S-5
RV3-76Catálogo Países #27, #59, #121, #160, #168, #207, #216, #228/#229; falta Antártida(Inferido del diff) valores sin código ISO 3166-1 (Chipre del Norte, Irlanda del Norte, Somalilandia), uno retirado (Antillas Holandesas), Kosovo, un "Santo Tomas" (#216) que no es Santo Tomé y Príncipe (ese ya viene aparte, #196), Timor Oriental repetido, y no incluyen Antártida.El país se guarda con un código de 2 letras (char(2), TransactionController.php:905-914): lo que no tiene código no entra sin inventar uno. El mapeo nombre→código lo hice a mano (el cliente no manda códigos).❓G10 · QC-27
RV3-77Catálogo Países, columna "#" (1 a 255)Una numeración junto a cada país; no dicen para qué.No existe columna de orden; el combo ordena por etiqueta (CatalogItemController.php:28, 59). El "#" sigue el orden alfabético en inglés (Baréin #17 entre Bahamas y Bangladés): parece un contador de planilla (o el orden de un picklist exportado, S-5).❓G10 · QC-28 · S-5
RV3-78Catálogo Tipos ID!A3 (nombre)"DPI (Documento Personal de Identificación)" y "Pasaporte" son los tipos válidos.Ya sembrados para Guatemala como DPI y PASAPORTE (B1.2). Solo difiere la redacción del DPI ("Documento Personal de Identificación (DPI)"), que sale en Cumplimiento col. 10 y en el A4.✅G10
RV3-79Catálogo Tipos ID!A3/B3DPI: 13 caracteres numéricos.Sin regla: identification_number es nullable|string|max:60 (TransactionController.php:915). El seeder de demo genera DPI con espacios (DemoTransactionSeeder.php:373-375).🆕G11 · D3-15 · QC-30
RV3-80Catálogo Tipos ID!A3DPI: país emisor GT siempre.Hoy el "País de la identificación" es un select libre con toda la lista (DatosPagoForm.vue:437-441) y el backend solo exige que exista; se puede guardar DPI con Ecuador.🆕G11
RV3-81Catálogo Tipos ID!A4/B4Pasaporte: mínimo 7, máximo 13 caracteres alfanuméricos.Sin regla (mismo punto que RV3-79).🆕G11 · QC-30
RV3-82Catálogo Tipos ID!A4Pasaporte: país emisor "todos".Ya es así: el select carga toda la lista y el backend no cruza tipo con país. Hay que cuidar que el Pasaporte quede sin país emisor fijo.✅G11
RV3-83Mail, 1.ª viñetaConfirman que la pestaña "módulo tesorería" del Excel v2 es la versión actualizada de la definición de tesorería y que mandaron todo en un solo archivo.Cierra el pendiente #1 del plan v2 §7 (el adjunto que faltaba).ℹ️G0
RV3-84Mail, 2.ª viñetaEn cada pestaña dejaron solo los puntos a corregir; "los que estaban ok los eliminamos".Lo que falta en el Excel se toma como aceptado, con una excepción: B4, B5, B6 y B7 no tuvieron validación visual (ninguna captura muestra Cumplimiento ni el A4 de B5; los menús de las capturas son previos a B6/B7).ℹ️G0 · D3-23
RV3-85Mail, 3.ª y 4.ª viñetas"Menús y perfiles" trae las asociaciones correctas de cada menú con su perfil; "Módulo tesorería", un ejemplo completo de qué debería ver cada entidad y con qué perfil.Las dos hojas pasan a ser la fuente vigente. Comparación celda por celda: filas RV3-40 a RV3-47; única diferencia real, el tipo de cambio (RV3-35).ℹ️G8 · G12
RV3-86Mail, 5.ª viñeta"En las pestañas catálogos países e IDs, los datos correspondientes".Llegaron 2 de las 4 listas que esperaba B1.5: países y tipos de ID (con formato y país emisor). No llegaron departamentos ni municipios: B1.5 queda cerrada solo en países e ID.ℹ️G10 · G11 · QC-29
RV3-87Mail, pedido de PDVLa ciudad y la provincia de cada PDV, "o confirmar si prefieren que las carguemos nosotros": pasan nombre, dirección, ciudad y departamento de CIS EXPRESS CIUDAD DE GUATEMALA, CHIMALTENANGO y QUETZALTENANGO.Se lee "cárguenlos ustedes" (confirmar en la respuesta). stations tiene state y city desde B4.1 (códigos del catálogo). Staging tiene los PDV de fixture (StationSeeder.php:28-52), no los reales: Chimaltenango no existe en ningún ambiente. Dos direcciones traen errores de tipeo evidentes ("NTERAMERICANA", "MVEL 2"). El A4 imprime nombre y ciudad del PDV; la provincia solo sale en Cumplimiento (col. 35).🆕G9 · D3-17 · QC-22
RV3-88Mail, tabla de PDV (columna Ciudad)La ciudad del primer PDV es "CIUDAD DE GUATEMALA" y el departamento "GUATEMALA".El catálogo tiene el departamento 01 "Guatemala" y su municipio 01-01 también "Guatemala" (database/data/catalogo_guatemala.php:39-45). Cargado el PDV, el A4 y Cumplimiento dicen "Guatemala", no "Ciudad de Guatemala". Diferencia de etiqueta, no un bug.❓G9 · QC-23
RV3-89Mail, Cumplimiento: Transaction Status"Se queda siempre con Send desde el momento que se le envía a Soterex el MTCN de la tx".Es la constante Sent en la columna 23 (ReporteCumplimientoService.php:227), igual para todo estado. El mail escribe "Send": una letra de diferencia en un archivo regulatorio; no se puede resolver leyendo (la planilla original tiene datos personales y no está en el repo).❓G9 · QC-19
RV3-90Mail, Cumplimiento: Payer Name"Siempre va a ser CIS Guatemala".Hoy config('cumplimiento.payer_name') con default CISLatam (config/cumplimiento.php:15; col. 24, ReporteCumplimientoService.php:228). Con un valor global, el día que se active otro país su reporte diría "CIS Guatemala".🆕G9
RV3-91Mail, Cumplimiento: Transaction Status – UpdateCambia a pendiente, pagada o cancelada según corresponda. "Validar si Soterex pone un estatus distinto a alguna tx modificada (por ejemplo si le cambió el nombre del beneficiario)".Hecho: Pending / Paid / Cancelled según el estado vigente (ReporteCumplimientoService.php:89-93). Lo escribe en español; no se sabe si lo quieren en español. El contrato C2P no tiene operación de "modificación" (solo SendRequest y Cancel): si Soterex reenvía con el mismo transaction_id hoy recibe 2001 y la modificación no entra. Pregunta para Soterex, no código.✅G9 · QC-20 · D3-22
RV3-92Mail, Cumplimiento: Additional NotesDejar la columna en blanco.Hoy trae el código del PDV si está pagada y el motivo si está cancelada (ReporteCumplimientoService.php:279-286, que lee audit_logs).🆕G9
RV3-93Mail, Cumplimiento: MTCN"MTCN lleva el prefijo C-, mantenerlo como ahora porque es numeración interna de Soterex, salvo que ellos ya no la necesiten / usen en su API".El sistema nunca guarda ni exporta el prefijo: el MTCN son 10 dígitos (MtcnGenerator.php); el "C-" lo agrega Soterex al imprimir su carta (funcional de pago 01-flujo L84-90) y la API lo excluye (Cancel exige 10 dígitos, C2PController.php:239-240). "Como ahora" se lee "como en su planilla". La condición depende de qué diga Soterex.🆕G9 · QC-21 · D3-18
RV3-94Mail, recibo A4(Sobre el quinto inciso de la declaración) "Reemplazar el texto de la declaración A4 por el de tirilla para que los 2 queden igual".DECLARACION_A4 tiene cinco incisos (PapeletaService.php:77-83), el quinto agregado por B5.3 a pedido de ellos; la tirilla tiene cuatro. Esto revierte B5.3 y la parte "quinto inciso" de P9(d).⚠️G9
RV3-95Mail, recibo A4(Sin respuesta) qué significa "Transacción fija: Sí / No".Se imprime tal cual en cada copia del A4 (papeleta-a4-copia.blade.php:105-109); la tirilla no lo tiene. Quedó asignada a Alexis (plan v2 §7 #6).❓G9 (no cambia) · QC-24
RV3-96Mail, estado de cuenta de la Holding: REF BAN / REF INT¿Dos campos o uno? Respuesta: "tomar en cuenta lo detallado en la pestaña módulo tesorería y desechar cualquier otra info".La pestaña no tiene columnas de referencia bancaria ni interna; la hoja Prefondeo pide una "Referencia" en singular. Hoy hay una referencia opcional por asiento (prefunding_entries.motivo). Se da por contestada por defecto (la respuesta del cliente es una inferencia, no un sí): un solo campo.✅G0
RV3-97Mail, "desechar cualquier otra Info"Para el estado de cuenta de cada entidad rige la pestaña "módulo tesorería"; todo lo demás se descarta.B7 se armó también sobre el Excel del 22/09 y el Financial Report de Ecuador. La pestaña contesta dos preguntas de ADR-015: el débito de un pago es principal más comisión (B46, el ejemplo de Guatemala; la versión de Ecuador, B78, está en el bloque oculto) y la comisión suma al saldo de la Holding (H43).ℹ️G0 · G12
RV3-98Mail, RS-xxxxx"¿Necesitan ver el RS-xxxxx de cada pago? Es parte de la info que envía Soterex; si la mantiene, mantengamos igualmente en el reporte, caso contrario eliminarlo". El cliente ya fijó la regla y depende de Soterex.El RS no está en ningún lugar del repo ni del contrato. Lo único propio de Soterex que recibimos es transaction_id (soterex_transaction_id, C2PController.php:62). Hipótesis, confianza baja: el RS-xxxxx es ese transaction_id. Si S-3 lo confirma, la regla del cliente manda mostrarlo como referencia secundaria en los extractos; si no viaja, se omite. La hoja nueva pide solo "# de MTCN" como referencia.❓G0 · D3-22 · S-3
RV3-99Mail, primera línea"Por ahora te respondo lo urgente".Puede venir un segundo mail.ℹ️G0

1.2 Hallazgos propios que salen del relevamiento (no los pidió el cliente) ​

Mantengo estos separados de la tabla anterior para no inventar pedidos. Todos son propuesta del PO; cada uno dice en qué entrega entra y con qué confianza.

#HallazgoEvidenciaConfianzaEntrega
H3-01🐞 Quien tiene Cajero y Tesorería en el mismo país recibe el nombre del beneficiario de todos los pagos del país en el Estado de Situación y en su Excel y PDF, cuando en Reporte individual ve solo lo que pagó él. La unión de asignaciones decide el nombre.ReportesController.php:352 usa allows(..., 'transacciones', 'read', pais), la unión; el listado usa isScopedToOwnTransactions (misma asignación). El test PerfilesAccesoApiTest.php:472-493 no llama a Reportes.Alta (lectura)G8
H3-02🐞 Con roles distintos por país (Cajero en GT, Tesorería en EC), el selector de país de Reportes ofrece GT y la primera carga da 403.SituacionView.vue:11, VolumenView.vue:10, CajasView.vue:15 usan countriesWithAccess() sin módulo; el backend devuelve 403 PERMISSION_DENIED (ReportesController.php:322-324). Es el mismo bug que ya se arregló en el Dashboard.Media (orden de asignaciones sin definir)G8
H3-03🐞 canSeeBalance decide por país y no por PDV: Supervisor del PDV A más Cajero del PDV B ve el saldo y los movimientos reales de las cajas de B.CashBoxController.php:257-266 → PermissionService.php:140-143; scopedCashBoxes (:221-241) sí filtra por PDV.Media (leído, no reproducido)G6
H3-04La matriz de Staging puede no ser RoleSeeder::MATRIX: el deploy corre solo migrate y la migración de B6 fija nueve celdas. Evidencia: la img 32 (Cajero sin "Transacciones").doc/environments/staging.md ("Antes del deploy", punto 4) cubre nueve celdas, no las 76.MediaG8 (consulta) · G0
H3-05🐞 Si la carta de Soterex dice "C-5436014032", la búsqueda de Pago responde 422 INVALID_MTCN (exige solo dígitos) y el filtro de Reporte individual tampoco la encuentra.PagoController.php:94-98; frontend/src/utils/mtcn.ts:15-18; TransactionController.php:198-206.Alta en el comportamiento; media en que le pase a un cajero (depende de RV3-93)G9
H3-06🐞 Desactivar un PDV no desactiva sus cajas; agregarCaja no valida módulo Caja ni PDV activo; mover un PDV a un país con módulo Caja no le crea la Caja 1.StationController.php:76-135; CashBoxController.php:221-241; 02-flujos-caja.md hallazgo 4.AltaG7
H3-07🐞 El ABM acepta un código de país de hasta 20 caracteres, pero el pago exige exactamente 2: un ítem "XKX" aparece en el combo y al elegirlo el guardado falla.CatalogItemController.php:171, 199; TransactionController.php:905-906; char(2).AltaG10
H3-08defaultStationFor toma el primer default_station_id no nulo de todas las asignaciones del país sin ordenar: con varias, el PDV que se graba puede cambiar de una corrida a otra.PermissionService.php:310-316, :56-58.Media (no reproducido)G4
H3-09La auditoría de subida de documentos guarda el nombre original del archivo en la metadata y el export de Auditoría la vuelca entera; los operadores nombran los archivos con el nombre del beneficiario. Contra la regla del proyecto.TransactionDocumentController.php:105; AuditLogController.php:59.Media-altaG5
H3-10partial de los extractos de la Holding se calcula contra todos los países de la tabla, activos o no (SV y HN se siembran inactivos): una Tesorería asignada solo a Guatemala recibe partial = true aunque no haya nada que ocultarle.TreasuryStatementController.php:297; CountrySeeder.php:40-42. Determinado: El Salvador existe en Staging (img 30: aparece en el selector de países de Catálogos, que lista todas las filas de countries, CatalogItemController.php:41-46), así que pasa hoy.AltaG12
H3-11La tarjeta "Saldo global de la Holding" muestra el saldo de todos los países a quien lee solo uno, y no coincide con las pestañas de la misma pantalla.PrefundingController.php:65; PrefondeoView.vue:97-112. ADR-015 lo aceptó en Consequences.AltaG12
H3-12CashBox::openSession() se consulta una vez por caja (N+1) y opened_by_supervisor_id sigue viajando aunque desde E4b.1 es siempre null.CashBoxController.php:62, 154, 263; CajaReportesController.php:438; frontend/src/services/caja.ts:10.AltaG6

2. Mapa de entregas ​

Agrupadas por dependencia y por riesgo, no por hoja. Primero lo que traba la operación de Pago (soportes que se pierden, el pagador que no ve su propia papeleta, el saldo del PDV afectado por una transferencia), después lo que corrige datos de reportes y lo que cambia reglas de caja, y al final lo que espera respuestas del cliente.

EntregaQué esÍtemsEsfuerzo¿Se puede empezar?
G0Cierre administrativo: respuesta al cliente, mail a Soterex, consultas de solo lectura a Staging, estado de los documentos; más la preparación técnica (usuarios de prueba, comando de consultas, CI)respuestas de 42 ítems de §1.1 (38 se cierran solo acá)M✅ ahora (este PR y el PR 0b); las consultas de G0.6 corren recién cuando el PR 0b esté mergeado y promovido a Staging (lote propio, con OK de Carlos)
G1Soportes que sobreviven a un deploy (almacenamiento persistente, mensajes de error, prueba de humo)RV3-06, 07L⏸ no hasta D3-1; el apply de Terraform lo corre Carlos
G2El pagador y su papeleta: quien paga ve sus soportes y su papeletaRV3-14M◐ después de reproducir en Staging (solo lectura); G2.1 con D3-2; G2.2 (la regla del multi-PDV) sale con G4.1 y espera D3-3
G3Medio de pago: solo efectivo (y el saldo del PDV deja de moverse por una transferencia)RV3-12, 13, 39M✅ con las recomendaciones de D3-4 a D3-6
G4El PDV de cada pago y el Reporte individual (quién procesó, rótulos)RV3-15, 16, 17M◐ el Reporte individual (G4.3 a G4.5) ✅ sin depender de nadie; el PDV del pago (G4.1, G4.2, G4.6, G4.7) con D3-7 y D3-8, apilado sobre G2
G5Documentos del pago: consulta, reemplazo, papeleta con dos botonesRV3-03, 04, 05, 08, 09, 10, 11L◐ con D3-9 y D3-10, después de G2 (se pisan en el mismo código); el re-test del cliente espera a G1
G6Caja: quién opera cada caja, quién la cierra, la línea de paísRV3-24, 25, 26, 27, 28L◐ G6.A ✅; G6.B ⏸ hasta D3-12 y D3-13; G6.C ✅ (el cliente dibujó la línea; QC-15 solo la confirma)
G7Caja: administrar cajas (activar y desactivar)RV3-29, 30M⏸ hasta D3-14; apilado sobre G6.A (no hereda los bloqueos de G6.B ni G6.C)
G8Perfiles: tipo de cambio solo Tesorería y Admin, perfiles mezclados documentados, dos fugas por la uniónRV3-35, 41, 47, 49, 51, 85L◐ la documentación y las fugas ✅ (PR F1); la migración de permisos ⏸ hasta D3-11 (PR F2)
G9Cumplimiento, recibo A4 y PDV reales: cuatro columnas, prefijo "C-", declaración del A4, datos de los tres PDVRV3-32, 87 a 95M◐ lo seguro ✅; "Sent/Send" y el idioma esperan QC-19 y QC-20 (no se tocan); el prefijo "C-" depende de D3-18 (QC-21 lo confirma)
G10Catálogo de países de CumplimientoRV3-75 a 78, 86M◐ los 23 renombres ✅; los casos dudosos ⏸ hasta QC-27
G11Formato del documento de identidad (DPI, Pasaporte)RV3-79 a 82, 86L⏸ hasta D3-15 (ADR); apilado sobre G10
G12Tesorería: alcance de la Tesorería de un país, saldo de la Holding, rótulosRV3-48, 55, 58, 66, 67, 72, 73, 85, 97M✅ con D3-19; RV3-67 ⏸ hasta QC-33
G13Tesorería: alerta de reposición al 30%, confirmaciones de recepción y columna de porcentajeRV3-60, 62, 64, 68L⏸ no hasta QC-34 a QC-39 y D3-20, D3-21

Esfuerzo: S hasta medio día, M hasta 2 días, L más. El tamaño incluye código, tests, la documentación de §5 y el plan de QA; la revisión de security se cuenta aparte (medio día a un día por PR que pasa por ella). Hay 8 M (G0, G2, G3, G4, G7, G9, G10 y G12) y 6 L (G1, G5, G6, G8, G11 y G13): entre 25 y 45 días-persona, sin contar los apply de Terraform ni las esperas de respuestas. G5, G6 y G8 son L porque cada una arrastra unas 12 a 15 piezas de documentación, un ADR o una Actualización, y varios specs: por eso se cortan en tajadas (más abajo) y la tajada es la unidad de PR. Convención de esta tabla: ✅ se puede arrancar, ◐ se puede arrancar una parte, ⏸ no se puede empezar (el bloqueo está en la columna).

Orden y branches ​

Sale de main; los PRs de feature van a main y de ahí main → staging → production (nada de este plan toca producción). Cada PR es una tajada desbloqueable: lo que espera una decisión va en un PR aparte y no frena a lo que ya se puede hacer.

PR 0   feature/ajustes-v3-cliente-gt          este plan + G0 (documentación, respuesta, mail)
PR 0b  feature/v3-preparacion-tecnica         G0.6 (comando de consultas), G0.7 (usuarios de prueba), G0.8 (CI)

PR A   feature/v3-soportes-persistentes       G1                              (⏸ D3-1)
PR B1  feature/v3-pagador-y-papeleta          G2.1, G2.3, G2.4                (después de reproducir; D3-2)
PR B2  feature/v3-pdv-del-pago                G2.2 + G4.1, G4.2, G4.6, G4.7   (apilado sobre B1; D3-3, D3-7, D3-8)
PR B3  feature/v3-reporte-individual          G4.3, G4.4, G4.5                (✅ independiente)
PR C   feature/v3-medio-de-pago-efectivo      G3
PR D   feature/v3-documentos-del-pago         G5                              (después de B1: se pisan en el mismo código)
PR E1  feature/v3-caja-quien-opera            G6.A                            (✅)
PR E2  feature/v3-caja-quien-cierra           G6.B                            (⏸ D3-12, D3-13, QC-12; apilado sobre E1: comparte el helper)
PR E3  feature/v3-caja-linea-de-pais          G6.C                            (✅ sin decisiones pendientes; comparte `totalesPorPdv` con G6.A2: el segundo en mergear rebasea)
PR E4  feature/v3-administrar-cajas           G7                              (⏸ D3-14; apilado sobre E1)
PR F1  feature/v3-perfiles-y-mezcla           G8 sin la migración             (✅)
PR F2  feature/v3-tipo-de-cambio-tesoreria    G8.1, G8.2, G8.9                (⏸ D3-11)
PR G   feature/v3-cumplimiento-recibo-pdv     G9
PR H   feature/v3-lista-de-paises             G10 ──▶ G11         feature/v3-formato-de-identificacion (apilado)
PR I   feature/v3-tesoreria-alcance           G12 ──▶ G13         feature/v3-tesoreria-reposicion-y-confirmacion (apilado)
  • Orden recomendado: primero el PR 0b (G0.8 el CI, G0.6 el comando diagnostico:v3, G0.7), mergeado a main y promovido a Staging en un lote propio, con OK de Carlos (sin esa promoción el comando no existe en Staging: es el primer paso del camino crítico y lo esperan las consultas de G0.6, que corre Carlos, y con ellas G2, G3, G4, G7, G8, G9, G10, G11 y G12). Después, G1 (cuando se pueda; su consulta, la 7, no espera la promoción), G2, G3, G4, G5; después G6.A, G6.C, G8 (documentación), G9; después G6.B, G7, G10, G12; al final G11 y G13. G1, G2 y G3 son independientes entre sí y se pueden llevar en paralelo.
  • Se apila solo donde el código se pisa de verdad: G2 → G4.1, G4.2, G4.6 y G4.7 (los dos tocan resolveStationForResolution y pay(); el Reporte individual, G4.3 a G4.5, no depende de nadie); G6.A → G6.B y G7 (la tarjeta de quién tiene abierta cada caja y el helper de abajo; G7 no hereda los bloqueos de G6.B ni de G6.C); G10 → G11 (mismo ABM de catálogos y mismo estilo de migración); G12 → G13 (misma pantalla y mismo ADR). G5 no se apila sobre G1 aunque comparten useTransactionDocuments.ts: G1 puede tardar (infraestructura) y el conflicto es chico. G5 sí sale después de G2: los dos cambian PermissionService::inTransactionScope y canManageTransactionDocuments, TransactionDocumentController y DocumentacionPago.vue; el segundo en mergear rebasea sobre el primero.
  • Un solo helper de "dentro de una misma asignación" (P3-2) para G5 (reemplazo de soportes), G6.A (saldos) y G6.B (cierre de caja): lo crea el primer PR que lo necesite (G5.1 o G6.A2, el que mergee antes), con su test, y el segundo lo reutiliza sin redefinirlo.
  • Nueve entregas pasan por security antes del merge: G1 (un bucket nuevo con identificaciones), G2 y G5 (tocan quién ve y quién reemplaza datos personales de un pago), G6 y G8 (cambian quién puede qué), G9 (G9.5 relaja la búsqueda de Pago, que es la regla anti-enumeración), G11 (un Admin edita reglas que deciden qué puede pagar un Cajero), G12 (cambia qué porción de la Holding y qué saldo ve quien lee un solo país) y G13.B (endpoints de escritura con permisos y alcance por PDV y país). G4 también, solo si se activa el backfill, y G3 si se quiere revisar el cambio de contrato de pay(). G8 cambia permisos de usuarios reales de Staging, y G6.B cambia quién puede cerrar una caja ajena sin tocar la matriz (D3-13 i): ver §7, R-1.
  • Todo cambio de permisos viaja por migración de datos con RolePermission::withoutEvents, y RoleSeeder::MATRIX y doc/architecture/matriz-de-perfiles.json se cambian en el mismo commit (un test los compara). No se corre el seeder en Staging.
  • La documentación va en el mismo PR que el cambio (§5). Una entrega no está terminada sin ella.

Cómo se ejecuta ​

  1. Autonomía. La autorización de CLAUDE.md (crear el branch, implementar, pasar code-reviewer, commit, push del branch y gh pr create sin preguntar) es del plan E1–E7 y dice que no se extiende a otro trabajo salvo que se reafirme. Este plan no la reafirma ni la acota: la decide Carlos. Hasta entonces, cada PR se abre y espera su OK antes de la entrega siguiente. Siguen necesitando OK explícito, siempre, mergear a main y cualquier push, merge o deploy a staging o production.
  2. Antes de mergear: en dev. Cada entrega se prueba con ./start-dev.sh y los seeders Demo, con los perfiles que la tarea nombra; npm test y npm run docs:build se corren en local hasta que G0.8 los ponga en el CI. Las pruebas "Manual en Staging" de §4 son el humo posterior a la promoción, no la primera prueba (R-5).
  3. Promoción a Staging (main → staging). Un lote por promoción, con OK de Carlos. El primer lote es el PR 0b: sin él no existe diagnostico:v3 en Staging y las consultas de G0.6 no se pueden correr. El PR de promoción lista las migraciones de datos que lleva (G4.7, G8.1, G8.9, G10.2 y G11.2 corren en el deploy y lo cortan si fallan; las de G10 no tienen down()). Si una migración de datos sale mal, se arregla hacia adelante con otra migración: no hay camino de vuelta. Hasta que G1 mergee, cada promoción borra los soportes que el cliente suba (R-3).
  4. Aviso al cliente. Cada promoción que cambia algo visible (menús, permisos, pantallas, reportes) se avisa antes a Magaly con una línea; no solo la de G8.

3. Decisiones ​

Hay cuatro tablas. Las D3-T (Carlos, 2026-10-04) son firmes: sin opciones ni recomendación, y se aplican. Las C3 vienen del cliente y están cerradas (con las salvedades que dice cada fila). Las P3 son propuestas del product owner para lo que nadie definió: quedan aprobadas cuando Carlos lanza la ejecución, y cada una dice qué cambiaría si se revierte. Las D3 son para Carlos: cada una con opciones y recomendación, y apuntando qué entrega destraba. 🏛️ marca las que cambian arquitectura y piden un ADR nuevo (la numeración de ADR es provisoria; se asigna al abrir cada PR).

3.0 Decisiones de Carlos del 2026-10-04 ​

Firmes. No se reabren ni se tratan como pregunta.

D3-T1 — Tesorería es un solo perfil y es regional ​

Donde el cliente escribe "Tesorería Local o Regional según corresponda" (hoja Menús y perfiles, celdas H6, H9, H11, H14 y H22, y fila 112 de la hoja Módulo tesorería) se lee "Tesorería", el perfil que creó B6. No existe "Tesorería Local" y no se crea otro rol. Qué significa "regional" en el código, y sus consecuencias:

  1. "Regional" no es un atributo del rol ni una entidad: es la asignación. Una persona tiene asignaciones (usuario × país × rol × PDV opcionales) y el alcance de cada módulo son los países de las asignaciones que lo permiten (PermissionService.php:273-304). Regional = Tesorería con una asignación sin acotar por PDV en cada país activo; local = asignada a un país. No existe una asignación "todos los países" (RoleAssignmentController.php:38 exige country_id): una persona regional necesita una asignación por país, y al dar de alta un país nuevo hay que sumárselo.
  2. La Holding es global (ADR-007 §1) y solo se ve completa con cobertura de todos los países (TreasuryStatementController.php:263-300). Con uno solo, el extracto es parcial y lo avisa.
  3. Las escrituras son siempre por país (PrefundingController.php:85, CountryPrefundingController.php:82, CashBoxController.php:512, 580, ExchangeRateController.php:110): una Tesorería de Guatemala no carga nada en otro país.
  4. Cómo ve País y PDV una persona asignada a un solo país: el extracto País y el de PDV completos de ese país. "CIS GUATEMALA solo su estado de cuenta" queda cubierto por el alcance de la asignación, sin rol aparte, para País y PDV. Lo que no queda cubierto, y se resuelve en G12: esa persona también ve la porción de su país de los dos extractos de la Holding y la tarjeta "Saldo global de la Holding" con el saldo de todos los países (RV3-55, H3-10, H3-11).
  5. Una asignación acotada por PDV no lee los extractos de país entero (ADR-015 §5, pregunta 5; es la pregunta #20 de 06-preguntas-abiertas-caja.md). Con un solo perfil, las asignaciones de Tesorería se dan siempre por país entero; quien tiene que ver un PDV solo es un Supervisor.
  6. No se puede dar a una persona de Tesorería solo lectura de un país: los permisos son del rol y la matriz es compartida (UsuariosView.vue:675-678 avisa que editarla cambia el rol de todos). El alcance es lo único que la acota.
  7. Un solo perfil no separa "quien manda" de "quien recibe": la misma persona puede cargar el envío de la Holding a Guatemala y recibirlo. Hoy el control es detectivo (libro inmutable y Auditoría). Lo que lo distinguiría sin rol nuevo son las confirmaciones de recepción (G13.B).
  8. Dashboard: una Tesorería de un solo país ve el KPI "Saldo de prefondeo" y la comisión (prefondeo:read); queda pendiente de la definición del escenario (RV3-74) y no se toca.

Qué se hace: nada en la matriz (las cinco celdas ya las cubre el rol); G12 (alcance y rótulos); documentación (§5); y la respuesta al cliente de §6.0.

D3-T2 — Usuarios con más de un perfil: se mezclan las opciones ​

Está bien que se mezclen (la unión de permisos de las asignaciones, como hoy). No se construye un selector de perfil ni una "asignación activa". El pedido de la hoja Menús y perfiles (ítem 1, RV3-49) queda cerrado como decisión de producto: hay que contestarle al cliente que el comportamiento es intencional y por qué, y documentarlo (manual de usuario, ficha de usuario, ADR-014 §6). No hace falta un ADR nuevo: la decisión se registra como subapartado de ADR-014 §6. Consecuencias:

  1. Qué es "la mezcla" hoy: el menú, las rutas y el manual son la unión global de las asignaciones (PermissionService::effectiveModules, :363-379); los datos y las acciones se deciden por país; el alcance por PDV se une por acción; "supervisa transacciones" se evalúa dentro de una misma asignación (ADR-014 §6); el timeout de sesión toma el menor; la pantalla de inicio es la primera ruta legible (solo un Cajero puro cae en Pago); el encabezado muestra "Rol · PAÍS" por asignación, desde 1024 px.

  2. Por qué no un selector (es lo que se le dice al cliente): (a) el cliente confirmó el 2026-07-24 roles distintos por país y un Supervisor a cargo de varios PDV (02-roles-permisos.md §2.3); que dentro de un mismo país se sumen las opciones es como está diseñado desde ADR-014 §6 y no se les había consultado, y la img 31 (Cajero y Admin en el mismo país) es justo el caso que esa confirmación no cubre: el argumento es técnico, no de autoridad; (b) una Tesorería regional necesita todas sus asignaciones en el mismo pedido para ver la Holding global; (c) un selector solo escondería opciones: la persona seguiría teniendo ambos permisos y el backend también, así que no agrega control. El control está en qué asignaciones se le dan a cada persona; (d) con B6 el Admin ya contiene todo lo del Cajero, de modo que "Cajero más Admin" ve exactamente el menú del Admin (es la captura de la img 31).

  3. Lo que sí corresponde hacer, y no es un selector: documentarlo (G8), y cerrar tres fugas causadas por la unión (H3-01 Reportes, H3-02 selector de país de Reportes, H3-03 saldo de Saldos por PDV) y evaluar "supervisor" dentro de una misma asignación en todo lo nuevo que lo necesite (P3-2: reemplazo de soportes, cierre de caja ajena).

  4. Combinaciones sensibles (análisis de riesgo, para el manual y ADR-014 §6):

    Combinación (mismo país)Qué pasaCobertura hoy
    Cajero + TesoreríaFondea y ajusta la caja con la que paga (fondeo_caja:write no compara con quien abrió la sesión): arma toda la cadena del dinero. Control: libro inmutable y Auditoría (CASH_FUNDED, CASH_ADJUSTED), que es lo que ADR-007 §4 eligióSolo documentable; H3-01 (nombres en Reportes) es un bug aparte
    Cajero + Tesorería, soportes y listadoNo se eleva a "supervisor" por sumar permisosCubierto con test (ADR-014 §6; PerfilesAccesoApiTest.php:472-493)
    Cajero PDV1 + Supervisor PDV2Ve todas las transacciones de PDV1 y PDV2, no solo las que resolvió en PDV1, y puede reemplazar soportes en ambosSin test ni doc → G8 (test de caracterización) y P3-2
    Supervisor + TesoreríaEl estado de tesorería anterior a B6Documentado en el manual 01
    Admin + cualquier perfilSin riesgo: la unión es Admin; solo suma alcance de PDV y PDV activoTest de caracterización en G8
    Perfil bajo en un país + Admin en otroPagar y cancelar son por país; pero los ABM, Auditoría y Configuración no tienen paísADR-014 solo lo dice para abm_asignacion_roles
    Dos asignaciones del mismo país con PDV activo distintoEl PDV que se graba al pagar no es determinístico (H3-08)G4
  5. Advertencia no bloqueante en la ficha de usuario (opcional, no se impone): ver D3-24. La recomendación es documentar ahora y dejar el aviso para cuando haya usuarios reales con perfiles mezclados.

3.1 Pedidos del cliente ya cerrados, con salvedades ​

Lo que el cliente definió. Una fila sin salvedad no necesita más trámite; las que la llevan dicen qué pregunta o decisión la matiza. Entre paréntesis, dónde se ve en §1.

#DecisiónFuente
C3-1Cancelar una transacción es solo del Administrador (reafirma B6)Pago ítem 1 (RV3-02)
C3-2En una tx pagada los datos y los documentos no se modifican; reemplazar un documento es solo de Supervisor y Administrador; el Cajero solo hasta dar el "guardar". Salvedad: que "guardar" sea "Confirmar pago" y no "Guardar datos" es lectura nuestra (P3-1, QC-2)Pago ítems 2, 6, 8 (RV3-03, 08, 10)
C3-3Transferencia bancaria sale de los medios de pago; si se mantuviera, el saldo del PDV no se afectaPago ítems 10 y 11 (RV3-12, 13)
C3-4El Reporte individual lleva el usuario que procesó; todas las transacciones deben mostrar el PDVTXs ítems 1 y 2 (RV3-16, 17)
C3-5Caja: solo quien abre cierra; una caja abierta no la abre otro; se ve el usuario en cada caja; se administran cajas (agregar, activar, desactivar). Salvedad: el plan propone una salida para el Supervisor y el Admin, que revierte ADR-013 §5 (D3-12, QC-12)Caja ítems 2 a 5 (RV3-25 a 30)
C3-6Menús y perfiles: la hoja es la asociación correcta (leída con D3-T1); "Reporte individual", "Saldos", "Parámetros"; Auditoría solo Admin y en Administración; Reportes para todos menos el Cajero; tipo de cambio en Tesorería para Administrador y TesoreríaHojas Menús, Auditoría, Reportes, Ubicaciones (RV3-31 a 47)
C3-7Para el estado de cuenta de cada entidad rige la pestaña "módulo tesorería"; se descarta cualquier otra información. Un solo campo de referencia (REF BAN / REF INT); el débito de un pago es principal más comisión y la comisión suma a la HoldingMail (RV3-96, 97)
C3-8Flujo de tesorería de ocho pasos: confirmación de recepción en cada nivel y alerta de reposición al 30%, con el % parametrizable; el costo bancario queda fueraMódulo tesorería (RV3-58, 60 a 64)
C3-9Cumplimiento: Payer Name "CIS Guatemala"; Additional Notes en blanco; Update pendiente/pagada/cancelada; el MTCN lleva "C-" salvo que Soterex ya no lo use. Salvedad: la grafía de "Send/Sent" y el idioma del Update no se tocan hasta QC-19 y QC-20; el "C-" depende de Soterex (D3-18, QC-21)Mail (RV3-90 a 93)
C3-10La declaración del recibo A4 es la de la tirilla (revierte B5.3)Mail (RV3-94)
C3-11Catálogos: países de la hoja; DPI: 13 numéricos y emisor GT siempre; Pasaporte: 7 a 13 alfanuméricos y cualquier emisor. Salvedad: los casos dudosos de la lista de países (QC-27) y los separadores del DPI (QC-30)Hojas Catálogo Países y Tipos ID (RV3-75 a 82)
C3-12Datos de los tres PDV reales: nombre, ciudad y departamento (dirección incluida), y que los carguemos nosotros. Salvedad: es nuestra lectura de "o confirmar si prefieren que las carguemos nosotros"; se confirma en la respuesta (6.0)Mail (RV3-87)
C3-13El Dashboard no cambia hasta definir el escenario de prefondeoDashboard (RV3-74)

3.2 Propuestas del product owner ​

#DecisiónSi se revierte
P3-1Una sola regla para los documentos de una tx pagada: "subir uno que falta" ≠ "reemplazar uno ya cargado". Subir lo que falta sigue permitido a quien pagó, al Supervisor y al Admin (la papeleta firmada solo existe después de pagar y sin ella no cierra la caja); reemplazar es solo del Supervisor con alcance del PDV y del Admin. Con ACCEPTED no cambia nada. La parte "subir lo que falta" es la opción (a) de D3-9, que se decide una sola vez allí. "Guardar la tx" se lee como "Confirmar pago" (el botón que paga) y no como "Guardar datos" (el borrador del formulario): propuesta nuestra, se confirma en QC-2Si el Cajero no subiera nada después de pagar, se rompe el cierre de caja (PENDING_PAYMENT_DOCUMENTS)
P3-2"Es Supervisor" se evalúa dentro de UNA misma asignación (rol con fondeo_caja:read y permiso de escribir, y PDV que cubra el de la tx o la caja) en todo lo nuevo: reemplazo de soportes, cierre de caja ajena, saldos de Saldos. Un solo helper en PermissionService (assignmentHolds($user, $countryId, [[módulo, acción], …], ?$stationId), nombre provisorio: ¿hay una asignación del país que reúne todas esas capacidades y cubre el PDV?), no tres chequeos sueltos. Cada uso declara sus capacidades (reemplazo de soportes: las de isSupervisorTier, fondeo_caja:read más acceso a transacciones; cierre de caja ajena: apertura_cierre_caja:write más fondeo_caja:read; saldos: fondeo_caja:read): no hay una definición única de "supervisor". Lo crea el primer PR que lo necesite (G5.1 o G6.A2) y el segundo lo reutiliza. No reabre D3-T2: la unión de permisos se mantieneUna persona Supervisor del PDV B y Cajero del PDV A pasa a ser supervisora también en A solo por sumar asignaciones
P3-3El reemplazo de un soporte se audita con acción propia TRANSACTION_DOCUMENT_REPLACED (tipo, id del documento reemplazado, estado de la tx), y el nombre original del archivo sale de la metadata de la subida (H3-09)Una marca reemplaza_documento_id en TRANSACTION_DOCUMENT_UPLOADED: no toca el catálogo de acciones, pero no se filtra
P3-4La papeleta tiene dos botones siempre visibles, "Imprimir papeleta tirilla" e "Imprimir papeleta A4" (rótulos del cliente), cada uno con su formato explícito; el del país se marca "predeterminado". Reemplaza el menú "Descargar en otro formato" de P9(b)Dejar botón más chevron y explicarle al cliente dónde está el otro formato
P3-5Los mensajes de error de documentos y papeleta distinguen la causa (404 de alcance, archivo faltante, red o 413, 5xx) en vez del genérico "No se pudo…"—
P3-6Tras cada apply de Terraform que toque waf o ecs se corre una prueba de humo: subir un archivo real (1 MB y 15 MB) por el ALB y abrirlo, y el chequeo de preflight CORS. Va a doc/environments/staging.mdEl incidente del CORS (2026-10-02) y el del WAF se repiten sin que nadie los vea
P3-7Confirmaciones y alertas de tesorería son una marca y un cálculo al leer, nunca un estado ni un saldo guardado, y no condicionan pagar ni cerrar la caja. Se guardan solo: el parámetro, la marca de confirmación y, si algún día hay mail, el hecho de que se avisóUn estado "pendiente" que no suma al saldo bloquearía los pagos de Ecuador (sin Caja) mientras la transferencia está en tránsito
P3-8Cumplimiento: Payer Name por mapa de ISO (vacío si el país no tiene entrada); Additional Notes siempre vacía; prefijo "C-" por configuración reversible. "Sent/Send" y el idioma del Update no se tocan hasta ver una fila de su planillaEl valor global no distingue países; un prefijo fijo en código no se apaga si Soterex dice que no lo usa
P3-9La búsqueda de Pago tolera el prefijo "C-" seguido solo de dígitos; "C", "C-" o "Carlos" siguen siendo INVALID_MTCN (se conserva la regla anti-enumeración)Un prefijo laxo reabre la búsqueda por nombre
P3-10Un renombre de catálogo se aplica solo si la etiqueta sigue siendo la sembrada: lo que un Admin editó no se pisa—
P3-11Todo cambio de permisos por migración de datos (idempotente, RolePermission::withoutEvents, evento de Auditoría por celda), con RoleSeeder::MATRIX y matriz-de-perfiles.json en el mismo commit—
P3-12No se tocan claves de módulo, name de rutas ni data-tour (ADR-014 §9)—
P3-13Las preguntas a Soterex van en un solo mail (D3-22). Es solo consulta: no se propone ningún cambio a C2PController, OAuth, SendRequest ni Cancel—
P3-14Jerarquía de fuentes de tesorería: la pestaña "módulo tesorería" manda para saldos, entidades y perfiles; la hoja "Prefondeo" (del mismo archivo) manda para qué columnas lleva cada movimiento. Fecha, referencia y saldo se conservanSacar fecha y referencia de los extractos sería un retroceso respecto de B7
P3-15Administrar cajas (agregar, activar, desactivar) queda en abm_estaciones, solo Admin; el operador se identifica por mail (el sistema no guarda nombre y apellido)Es una celda de la matriz si piden otro perfil
P3-16G1 se hace antes de pedirle al cliente que repita las pruebas de documentos: cada deploy invalida lo que subióSe re-testea ya y se aclara que los archivos pueden perderse
P3-17Los defaults de las preguntas al cliente (§6) son lo que se implementa si no contestan; cada uno es reversible—

3.3 Para Carlos ​

Cada decisión dice qué entrega destraba. 🏛️ = arquitectura, pide ADR.

D3-1 🏛️ — ¿Cómo se guardan los soportes de pago en Staging y producción? (destraba G1)

  • (a) Bucket S3 privado, con cifrado y versionado, acceso por el task role. Es lo que ya decían el diseño de E5a y los comentarios del código.
  • (b) EFS montado en las tareas Fargate.
  • (c) Dejar el disco local hasta producción (los documentos de Staging se pierden en cada deploy).
  • Recomendación: (a). Es lo diseñado, no suma estado a las tareas, escala a más de una tarea (web_max_count es 2 en Staging y 8 en producción) y se versiona. EFS agrega costo y un punto de falla para algo que S3 resuelve; (c) descarta toda la prueba de soportes del cliente en Staging.

D3-2 — Pagador de otro PDV: ¿cómo recupera el acceso a sus soportes y su papeleta? (destraba G2)

  • (a) Excepción del pagador: quien tiene resolved_by_user_id igual a su id y el permiso por país queda dentro del alcance. Nada más.
  • (b) Abrir la lectura de soportes y papeleta a todo el país con transacciones:write.
  • (c) No tocar el alcance y solo mejorar los mensajes.
  • Recomendación: (a). Es lo mínimo que arregla el ciclo pagar, imprimir, firmar, subir, cerrar. (b) expone identificaciones de otros PDV, que es justo lo que el diseño evita.

D3-3 — Usuario con más de un PDV, sin PDV activo y sin caja abierta: ¿se rechaza o se acepta? (destraba G2.2, que sale en el PR B2 junto con G4.1)

  • (a) Rechazar con 422 y pedirle que elija su PDV activo, al subir el primer documento y al pagar (como ya dice ADR-008 §1 y el código no hace). Solo cuando allowedStationIds devuelve dos o más PDV y no hay PDV activo ni caja abierta del usuario en el país que lo resuelva. Las asignaciones sin acotar (allowedStationIds === null: el Admin, o un Supervisor o Tesorería sin PDV) quedan exentas, como hoy: resolveStationForResolution devuelve null por las dos razones (PermissionService.php:327-336), así que el 422 no puede montarse sobre ese null; y en un país sin Caja no hay caja que desempate. La subida del primer documento (TransactionDocumentController.php:88-93) usa el mismo criterio que D3-7 (b): con caja abierta, el PDV es el de esa caja; sin ella, 422 para el multi-PDV sin PDV activo.
  • (b) Aceptar PDV nulo y confiar en la excepción del pagador.
  • Recomendación: (a) con ese predicado, después de listar en Staging qué usuarios caen en el caso (supervisor@, con dos PDV y sin PDV activo, es uno). Una tx sin PDV sale mal en los reportes por PDV, los extractos y Cajas. Con D3-7 (PDV de la caja) el caso casi desaparece en Guatemala.

D3-4 — Medio de pago: ¿hasta dónde se saca la transferencia? (destraba G3)

  • (a) Solo de la pantalla. (b) Pantalla y backend (422 si mandan TRANSFERENCIA). (c) Además, reescribir las filas históricas.
  • Recomendación: (b). Dejarlo abierto por API es dejar vivo el defecto de RV3-13. (c) no: reescribiría datos del pago de una PAID, que son inmutables (ADR-011, D4). Criterio único con D3-8: no se reescriben los datos del pago; sí se completa una atribución derivable del ledger.

D3-5 🏛️ — ¿Las formas de pago pasan a ser un catálogo de Parámetros? (destraba G3)

  • (a) No: constante en código, solo efectivo; se revisa cuando el cliente defina otras formas y su comportamiento.
  • (b) Catálogo cerrado (PAYMENT_METHOD, por país) con Efectivo y Transferencia, esta última desactivada.
  • (c) Catálogo abierto con atributos de comportamiento por ítem.
  • Recomendación: (a). El cliente pidió "añadir el catálogo" pero también "quitar transferencia" y nadie definió otra forma; reactivar Transferencia desde el ABM traería de vuelta RV3-13 y los 4 documentos extra, y (c) es comportamiento de plata sin definir. Si la respuesta a QC-8 es "necesitamos otras formas", pasa a (c) con su propio ADR y decide de paso el patrón de atributos por ítem de catálogo (cruza con D3-15).

D3-6 — Los pagos por transferencia que ya descontaron caja en Staging: ¿cómo se corrigen? (G3)

  • (a) Un AJUSTE por caja afectada (+monto, motivo "Otro" con detalle). Cuesta más de lo que parece: el ajuste exige una sesión abierta del día en esa caja (CashBoxController.php:578-600: CASH_SESSION_CLOSED o CASH_SESSION_FROM_PREVIOUS_DAY, ADR-013) y Tesorería no tiene apertura_cierre_caja (RoleSeeder.php:108): por cada caja afectada, un Cajero o el Admin la abre (o cierra y reabre la vencida), se ajusta y se cierra. El ajuste cae en la sesión del día del arreglo, no en la de los pagos que corrige, y se ve en "Cierres por día" y en Reportes → Cajas. (b) demo:reseed (borra todo el estado de prueba del cliente). (c) Dejarlo y avisar.
  • Recomendación: (a) si la consulta 6 de G0.6 muestra pocas cajas: no pierde el trabajo de prueba del cliente y deja traza (el ledger es inmutable: no se borra el PAGO). (b) si son varias, porque ahí el costo operativo de (a) supera al de volver a cargar los datos de prueba.

D3-7 🏛️ — ¿Qué PDV se graba al pagar en un país con módulo Caja? (destraba G4; ADR corto "el PDV de un pago es el de la caja")

  • (a) Siempre el de la caja desde la que se pagó. (b) El de la caja solo cuando hoy daría null (el PDV activo y el PDV único siguen ganando). (c) No tocar la lógica y exigir PDV activo en toda asignación ambigua que pague.
  • Evidencia de las capturas del cliente (img 14, 20 y 31; RV3-17, causa 6): un operador con Cajero y Admin pagó 6189214933 y 3321190529 desde la misma caja, la Caja 1 de Central; la primera quedó con PDV "—" y la segunda con "Mixco Plaza". Con (b), 6189214933 pasaría a Central, pero 3321190529 queda en Mixco Plaza aunque la plata salió de Central: ni (b) ni el backfill de D3-8 la tocan (su PDV no es null), y Cumplimiento (col. 33-36, "dónde se pagó") y los totales por PDV dirían Mixco para plata de Central. Solo (a) lo unifica. Esto revierte en parte E4-multi §2.3, que desacopló a propósito "a qué PDV se atribuye la transacción" de "qué caja paga" ("si aparece como problema real en el uso, es un ajuste chico después"); el docblock de applyCashBoxDiscount (TransactionController.php:544-546) queda falso con (a) y con (b).
  • Recomendación: (b) ahora, por ser el cambio con menos sorpresa (solo llena huecos y no pisa el PDV activo que el cliente pidió el 2026-07-25); pasar a (a) si el cliente confirma QC-9, porque además elimina la ambigüedad de las asignaciones múltiples, o si Carlos no quiere vivir con la discrepancia de las capturas: con esa evidencia, es lo primero que conviene mirar de esta decisión.

D3-8 — ¿Se completan los PAID históricos sin PDV desde su movimiento de caja? (G4)

  • Sí, con una migración de datos auditada · No, quedan como histórico · Solo en Staging, a mano.
  • Recomendación: sí. Es derivable del ledger, Producción nunca se aplicó y deja a Cumplimiento y a los totales por PDV consistentes desde el primer día. Necesita tu OK porque modifica filas de transactions (no sus datos de pago, que son inmutables). Criterio único con D3-4 (c): no se reescriben los datos del pago; sí se completa la atribución derivable del ledger. station_id no lo ingresó el operador ni es un dato del pago que proteja ADR-011, pero sí alimenta Cumplimiento (col. 33-36) y los totales por PDV: por eso el backfill deja un evento de Auditoría con el conteo.

D3-9 — Después de pagar, ¿el Cajero que pagó puede seguir subiendo por primera vez los documentos que faltan? (G5)

  • (a) Sí, todos los tipos que faltan, como hoy (solo se bloquea el reemplazo). (b) Solo los de post-pago (papeleta firmada, foto del cliente, los 4 de transferencia). (c) Ninguno.
  • Recomendación: (a). Es lo mínimo que pide el cliente (RV3-10) y no rompe el cierre de caja. (c) lo rompe. Es la regla P3-1: se decide acá y no allá.

D3-10 — Documentos que quedaron de un intento anterior sobre una ACCEPTED (G5)

  • (1) Se mantienen, con "subido por X el …" y un aviso (solo frontend). (2) La consulta no los trae: datos y documentos aparecen al tocar "Iniciar pago". (3) Los de un intento anterior no valen para pagar (vigencia por usuario o por caja): cambia ADR-008.
  • Recomendación: (1) hasta que el cliente conteste QC-3, porque sirve en las dos lecturas y es medio día. (2) si contesta que lo que molesta es verlos al consultar. (3) no: es lo más caro y rompe el cotejo posterior del Supervisor.

D3-11 — Tipo de cambio: ¿se le saca la lectura al Cajero y al Supervisor? (destraba la migración de G8; cambia permisos de usuarios reales)

  • (a) Sí: tipo_cambio en 0/0/0 para los dos. (b) No: queda en solo lectura (ADR-014 §9) y se le explica al cliente.
  • Recomendación: (a). La hoja lo dice literalmente, nada operativo lo necesita y se revierte con una celda. Preguntarle al cliente en la misma respuesta (QC-17) y avisarle antes del deploy.

D3-12 🏛️ — ¿Quién puede cerrar una caja abierta por otra persona? (destraba G6.B; supersede en parte ADR-013 §5)

  • (A) Estricto: solo quien la abrió, más el Admin como escape. (B) Quien la abrió, más Supervisor y Admin del PDV (siempre, auditado). (C) Como (B), y además cualquier operador del PDV cuando la sesión está vencida.
  • Recomendación: (B). Respeta lo que pide el cliente entre pares (un Cajero no toca la caja de otro) y deja una salida para la caja trabada. (C) solo si el cliente dice que hay PDV sin Supervisor (QC-12).

D3-13 🏛️ — ¿Cómo se expresa la capacidad de cerrar cajas ajenas? (G6.B)

  • (i) Derivada de permisos existentes dentro de una misma asignación (apertura_cierre_caja:write y fondeo_caja:read), sin tocar la matriz. (ii) Una celda explícita (apertura_cierre_caja:delete = cerrar cajas ajenas), editable desde Roles, con migración de datos para el Supervisor.
  • Recomendación: (i). No cambia permisos de usuarios reales de Staging y reusa el patrón de isSupervisorTier. (ii) queda como evolución si quieren configurarlo por perfil.

D3-14 🏛️ — Desactivar una caja con saldo distinto de cero (destraba G7)

  • (a) Se rechaza: primero hay que dejarla en cero con un motivo de ajuste nuevo del catálogo cerrado ("Retiro por baja de caja"), lo que obliga a abrirla, ajustar y cerrarla. (b) Se permite: queda inactiva con su saldo, que sigue sumando en los totales del PDV y los extractos, marcada. (c) Se permite y el saldo se ignora.
  • Recomendación: (a) si Tesorería aprueba el motivo nuevo (es decisión suya, pregunta #2 de 06-preguntas-abiertas-caja.md); (b) como alternativa. (c) no: rompe la conciliación con el extracto del PDV.

D3-15 🏛️ — ¿Dónde viven las reglas de formato del documento de identidad? (destraba G11)

  • (a) Cuatro columnas nullable en catalog_items, solo para ID_TYPE, editables por el Admin y auditadas. (b) Archivo de configuración en código, por code de tipo. (c) Una columna jsonb genérica.
  • Recomendación: (a). Un formato mal pensado (un pasaporte real de 6 caracteres) no debe obligar a un deploy para poder pagar, y un tipo nuevo o un código editado en (b) quedaría sin validar en silencio. (c) solo si D3-5 resulta en (c).

D3-16 — La lista de países del cliente: ¿cómo se carga y qué se hace con los dudosos? (G10)

  • Carga: migración de datos idempotente (renombra solo lo no editado, crea lo que falta) · alta manual por un Admin · seeder a mano.
  • Dudosos: cargar XK y AN con su código; los 3 sin ISO con código interno XA a XZ; no cargar nada hasta que el cliente confirme.
  • Recomendación: migración de datos; cargar XK y AN ahora, y esperar la respuesta del cliente para los 3 sin código ISO y para "Santo Tomas". El código tiene que tener exactamente 2 letras o el pago falla (H3-07).

D3-17 — Los tres PDV reales: ¿cómo se cargan, y qué se hace con Mixco Plaza y Escuintla Norte? (G9)

  • Carga: por UI de un Admin (edita 2 y crea 1; auditado, valida ciudad dentro de provincia y crea la caja) · migración idempotente que solo completa lo vacío · reconstruir el StationSeeder.
  • Los dos de fixture que no están en la lista: dejarlos activos · desactivarlos (no se borran: tienen transacciones y cajas) · renombrarlos.
  • Recomendación: por UI (la migración queda especificada en G9 por si preferís que el dato viaje con el deploy; reconstruir el seeder rompe StationSeederTest, UsuariosDePruebaSeedersTest y demo:reseed). Los dos de fixture, dejarlos hasta tener aprobada la muestra (D3-23) y desactivarlos después.

D3-18 — Prefijo "C-": ¿se aplica ahora o se espera a Soterex? (G9)

  • Aplicar ahora con configuración reversible · esperar a que Soterex conteste.
  • Recomendación: aplicar ahora. El cliente lo pidió explícitamente y la excepción es condicional; si Sean dice que ya no lo usan, se apaga con una variable de entorno.

D3-19 — ¿Qué ve de la Holding una Tesorería con asignación en un solo país? (destraba G12)

  • Encuadre: (b) revierte en parte dos decisiones escritas: ADR-007 §1 (Carlos, 2026-08-06: "el saldo que se muestra es la suma global de todos los países") y ADR-015 §5 (que aceptó la tarjeta global para quien lee un solo país, en Consequences).
  • (a) Lo de hoy, documentado (extractos parciales de su país y tarjeta global). (b) Lo de hoy, más la tarjeta limitada a sus países y partial calculado solo contra países activos o con movimientos. (c) La Holding (tarjeta y pestañas) solo con prefondeo:read en todos los países activos; el "local" entra a Fondeo PDVs y a nada más.
  • Recomendación: (b). Cierra la contradicción sin ocultar pantallas. (c) solo si el cliente confirma que CIS Guatemala no puede ver la Holding ni la comisión (QC-32); además revierte ADR-015 §5.

D3-20 🏛️ — Confirmación de recepción: ¿marca o estado? (destraba G13.B)

  • (a) Marca de control (append-only) que no toca ningún saldo. (b) Un estado "pendiente" que no suma al saldo hasta confirmar. Y: ¿se bloquea que confirme quien cargó el asiento? (no se bloquea, se muestra "autoconfirmado" · se bloquea).
  • Recomendación: (a), sin bloquear la autoconfirmación. (b) rompe ADR-007 (pagos de Ecuador bloqueados por plata en tránsito) y obliga a revisar Dashboard, Reportes, extractos y demo; un bloqueo deja sin salida a un equipo regional chico, y el Admin siempre puede confirmar.

D3-21 🏛️ — Alerta de reposición: ¿dónde vive el porcentaje y por qué canal sale? (destraba G13.A)

  • Parámetro: fila única en Configuración (editable por Admin) · columna por país · dentro de SoterexSetting. Canal: solo en la app, calculada al leer · app más mail · app más mail más scheduler.
  • Recomendación: fila única en Configuración y solo en la app. El mail necesita infraestructura que no existe (transporte, y el scheduler está apagado en Staging) y es una decisión de costo tuya; se agrega encima sin rehacer nada. Si Tesorería tiene que editar el porcentaje, no se le da abm_configuracion: esa misma celda abre el modo mock o real de la integración Soterex, su usuario y su contraseña, y el timeout de sesión (routes/api.php:233-246; Tesorería está en 0/0/0, RoleSeeder.php:121). El endpoint del umbral se gatea con prefondeo:write (Tesorería y Admin) y el campo se muestra también en Prefondeo Soterex; un módulo propio iría por migración de datos (EnsureRolePermissions::forModule) más PermissionModules, MATRIX y matriz-de-perfiles.json.

D3-22 — ¿Sumás las preguntas a Soterex al próximo mail a Sean? (G0, G9, G13)

  • Sí, en un solo mail · No, esperar a ver tráfico real.
  • Recomendación: sí. Cinco preguntas baratas: (1) ¿comunican cada prefondeo por la API, con qué mensaje y qué campos? (2) ¿su carta y su Salesforce siguen mostrando "C-" más el token, y lo necesitan en nuestros listados? (3) ¿el RS-xxxxx es el transaction_id que mandan en SendRequest? (4) ¿cómo se modifica en Soterex una transacción ya enviada: Cancel y SendRequest nuevo, con qué transaction_id y qué sub_status? (la del transaction_id repetido, que hoy da 2001, puede romper una operación real). (5) ¿la lista de países que mandó el cliente (Global Country Values, Translation - Spanish) es el picklist de su Salesforce, con qué código viaja cada valor y qué orden tiene el "#"?

D3-23 — ¿Se cierra la etapa con el silencio del cliente o con una muestra aprobada? (G0)

  • Silencio = aprobado · Muestra con OK explícito para B4, B5, B6 y B7.
  • Recomendación: muestra con OK explícito, generada después de G8, G9 y G12 (G0.9), no en el primer mail: esas entregas cambian justamente las salidas que se piden aprobar (columnas 21, 24 y 30 del Excel de Cumplimiento, el A4 de cuatro incisos, el menú del Cajero y del Supervisor y los rótulos de los extractos). Es barata (Excel y PDF generados con datos de demo; capturas de las pantallas de B6 y B7) y evita una vuelta más. Ninguna de esas entregas fue validada visualmente por el cliente. Si Carlos prefiere mandarla ya, el OK se acota a lo que no cambia y el mail dice qué puntos están en cambio.

D3-24 — Combinaciones sensibles de perfiles: ¿alcanza con documentar? (G8; no es el selector)

  • (a) Solo documentar (manual, ADR-014 §6, ayuda en la ficha). (b) Documentar y mostrar una advertencia no bloqueante al asignar la combinación, calculada en el frontend con la matriz que ya manda el backend. (c) Además, un control preventivo en backend (p. ej. nadie fondea ni ajusta la caja que abrió).
  • Recomendación: (a) ahora; (b) si el cliente va a asignar combinaciones reales. (c) no: cambia una regla de caja que Teresa y Diego pidieron detectiva (ADR-007 §4) y también tocaría al Admin.

D3-25 — ¿La regla "sin montos en la metadata de Auditoría" alcanza a los importes del ledger? (transversal, no bloquea)

  • Hoy CASH_SESSION_OPENED/CLOSED guardan saldos y CASH_FUNDED, CASH_ADJUSTED, PREFUNDING_ENTRY_CREATED y COUNTRY_PREFUNDING_ENTRY_CREATED guardan el monto (CashBoxController.php:346, 451, 551, 634; PrefundingController.php:105; CountryPrefundingController.php:95-105).
  • Opciones: la regla es solo de datos personales (se deja y se documenta) · alcanza a los importes (se sacan, con su test).
  • Recomendación: aclararlo. Todo lo nuevo de este plan va sin montos en cualquier caso.

D3-26 — Mientras el cliente no confirme el escenario, ¿seguimos con el 1 como supuesto? (G0, G12, G13)

  • Sí, supuesto explícito en los docs · Esperar confirmación escrita antes de seguir con cualquier cambio de tesorería.
  • Recomendación: sí, corrigiendo la redacción de C7 en el plan v2, ADR-015 y CLAUDE.md ("asumido hasta que el cliente confirme", no "confirmado"). El diseño de G13 es neutral al escenario: los niveles País y PDV son idénticos en los dos y el nivel "cuenta con Soterex" queda en una sola función.

4. Entregas ​

Las referencias archivo:línea salen de leer el branch el 2026-10-04. Verificalas antes de apoyarte en ellas. En cada entrega, las tareas van separadas por capa (Backend, Frontend, Datos, Infra, Docs) y la documentación se actualiza en la misma entrega que cambia el comportamiento.

G0 — Cierre administrativo y respuesta al cliente ​

Commits: G0. Branch feature/ajustes-v3-cliente-gt (este PR) y, para G0.6 a G0.8 (código chico), feature/v3-preparacion-tecnica (PR 0b). Esfuerzo M: la parte documental (G0.1 a G0.5 y G0.9) es S; la preparación técnica, el resto. Alcance: todos los ítems que son solo respuesta o documentación (✅ y ℹ️ de §1) y las preguntas al cliente.

#CapaQué
G0.1Docsdoc/reference/2026-10-02-respuesta-ajustes-v2/README.md: qué hay (12 hojas, 33 capturas), qué reemplaza a qué (la fila 112 y las celdas H* de la v2 reemplazan la captura de la v1 con "Backoffice Regional"; el mail dice "desechar cualquier otra info"), que "Local o Regional" sale de la hoja y no del mail, y por qué el .xlsx no se sube todavía; y que el volcado a texto no muestra los shapes dibujados sobre las capturas ni las filas ocultas (el cuadro de texto de RV3-28 está en xl/drawings/drawing5.xml; las filas 61 a 111 de Módulo tesorería tienen hidden="1"): para leer un .xlsx del cliente hay que mirar los XML de dibujo y los atributos de fila, no solo las celdas
G0.2Datos personalesRevisar las 33 capturas antes de commitear el .xlsx. La img 10 muestra un mail y una dirección tipeados a mano que parecen reales; para este plan solo se abrieron las que se citan. Alternativa, con el criterio del README de v1: guardar el .xlsx fuera del repo y commitear solo un volcado de texto sin imágenes. Hasta que Carlos decida, el archivo queda sin trackear. doc/ se publica en el sitio (salvo reference/) y no vi autenticación en el sitio: cualquier documento nuevo en plans/ o qa/ queda público
G0.3DocsPoner al día lo que quedó atrás: CLAUDE.md (B6 #71, B7 #72 y #55 figuran pendientes de merge y están mergeadas; "cuatro preguntas para Magaly y Teresa"; C7 pasa de "confirmada" a "asumida"), doc/README.md (tabla del 2026-08-05), plan v2 §6, §7 #1 (el adjunto llegó) y C7, README de doc/reference/2026-10-01-respuesta-ajustes-v1/ ("Lo que nos falta"). En 06-preguntas-abiertas-caja.md §6.3 (y en las equivalentes de ADR-015 "Preguntas abiertas"): la 18 y la 19 resueltas por la hoja del 2026-10-02 para Guatemala (B46 y H43 son visibles; la parte de Ecuador de la 18 se apoya en B78, que está en el bloque oculto, así que queda como confirmación); la 16 resuelta por defecto (un solo campo: el cliente contestó "desechar cualquier otra info", que es una inferencia y no un sí); y dejar abiertas la 17 (RS, ahora S-3), la 20 (asignaciones acotadas) y la 21 ("Cargado por": es una decisión de Carlos sobre trazabilidad y la hoja no dice nada, y el silencio no la cierra)
G0.4RespuestaCarlos le manda a Magaly la respuesta de §6.0, con capturas actuales de Staging para lo ya hecho (la muestra de B4 a B7 va después, G0.9). La carta puesta al día con lo ejecutado (2026-10-07) está en el borrador 2026-10-07-borrador-respuesta-al-cliente-ajustes-v3, no enviado. Precondiciones: que exista la cuenta tesoreria@cislatam.test en el Firebase de Staging (no existe hasta que Carlos corra StagingTestUsersSeeder a mano: sin ella el cliente no ve el perfil Tesorería) y que Staging esté sano (el login estuvo roto entre el 02/10 y el 04/10 por un CORS mal puesto por un apply)
G0.5SoterexMail a Sean con las cinco preguntas de D3-22. Solo consulta: no se propone ningún cambio a la integración C2P. Borrador (no enviado): 2026-10-07-borrador-preguntas-a-soterex-ajustes-v3
G0.6DiagnósticoConsultas de solo lectura sobre Staging, que corre Carlos; ninguna modifica nada. Canal: el único que hay es run-artisan-command.yml, que arma el comando con split(' ') y lo antepone con php artisan (no sirve para SQL ni para un tinker con espacios) y deja la salida sin enmascarar en CloudWatch y en el log de Actions (doc/environments/staging.md, "Antes del deploy"). Por eso las consultas se escriben antes como un comando artisan de solo lectura, diagnostico:v3 (PR 0b), que imprime conteos e ids, nunca mails, nombres ni montos; el resultado se anota en el PR de la entrega que lo usa, sin datos personales. Precondición: el comando solo existe en Staging cuando el PR 0b mergea a main y se promueve a staging (un lote propio, con OK de Carlos), porque run-artisan-command.yml corre sobre la imagen ya desplegada; las consultas 1 a 6, 8 y 9 y la parte de base de la 10 dependen de esa promoción, la 7 (DevTools y CloudWatch) y la parte de la 10 que se lee en los logs del ALB no. Cada entrega las espera antes de construir: (1) role_permissions completa, 4 roles por 19 módulos, contra RoleSeeder::MATRIX → G8; (2) select iso_code, active from countries → G10, G12; (3) select internal_code, name, address, state, city, active from stations order by internal_code y cajas por PDV (cash_boxes agrupado por station_id; Escuintla Norte con 0) → G7, G9; (4) PAID y CANCELLED con station_id is null: cuántas, resolved_by_user_id y asignaciones de esos usuarios, y los PAID cuyo station_id difiere del PDV de la caja del movimiento PAGO (RV3-17, causa 6; D3-7) → G2, G4; (5) usuarios con 2 o más PDV y sin PDV activo → G2; (6) PAID con delivery_type = 'TRANSFERENCIA' y su movimiento PAGO por caja → G3; (7) abrir con DevTools un documento viejo y uno recién subido (esperable 404 DOCUMENT_FILE_MISSING el primero) y mirar en CloudWatch que la métrica de la regla common-rules-uploads cuenta y no bloquea → G1; (8) PAID con DPI cuyo número no cumple ^[0-9]{13}$, Pasaporte que no cumple ^[A-Za-z0-9]{7,13}$ y DPI con país distinto de GT, solo conteos → G11; (9) transactions.soterex_transaction_id like 'RS-%' → RV3-98; (10) reproducción de RV3-14 con el MTCN 3751272495: station_id y resolved_by_user_id de la tx contra los PDV de quien la buscó, y status HTTP de /documentos y /papeleta en los logs del ALB → G2 (para RV3-17 las capturas ya dicen quién pagó dos de las tres filas: queda 2916186807)
G0.7Datos de prueba (PR 0b)Usuarios de prueba para los escenarios de §4: extender StagingTestUsersSeeder (y UsuariosDePruebaSeedersTest) con un segundo Cajero del mismo PDV (GT-CAP-001), un Cajero solo de GT-QUE-002, un Supervisor de un solo PDV y dos cuentas mixtas (Cajero y Tesorería en el mismo país; Cajero de un PDV y Supervisor de otro). Hoy hay cuatro cuentas (StagingTestUsersSeeder.php: el Admin con PDV activo GT-CAP-001, el Supervisor de GT-CAP-001 y GT-QUE-002 sin PDV activo, un Cajero y Tesorería) y ni dos Cajeros de un mismo PDV, ni un Supervisor de un solo PDV, ni cuentas mixtas: las pruebas "Manual en Staging" de G2, G5, G6 y G8 no se pueden ejecutar sin ellas. Crear cuentas es crear usuarios en el Firebase real: lo corre Carlos una sola vez, junto con la de Tesorería (G0.4), y con contraseñas que elija él en la consola (las generadas quedan legibles en los logs). Alternativa: esos escenarios se cubren con tests de backend y los seeders Demo en dev, y en Staging queda un humo con las cuentas que ya existen
G0.8CI (PR 0b)Sumar a .github/workflows/ci.yml npm test como paso del job frontend (hoy corre npm audit, type-check --if-present y build, con working-directory: frontend; frontend/package.json ya tiene el script test) y npm run docs:build en un job nuevo docs, con working-directory: doc, cache-dependency-path: doc/package-lock.json y su propio npm ci, como el job de documentación de deploy-staging.yml: ese script vive en doc/package.json, no en el del frontend, así que ponerlo en el job frontend fallaría. No necesita DOCS_API_URL (el nav cae a un valor por defecto en doc/.vitepress/config.mts:86: el build de PR no publica nada). Casi todos los "Terminado cuando" de front de §4 dependen de specs de vitest que el CI de PR no corre, y un link roto de la documentación recién se descubre en el deploy (A-3). Tiene que estar antes de que mergee G2. Mientras no esté, "npm test y docs:build corridos en local" es un ítem explícito del checklist de cada PR
G0.9RespuestaLa muestra para validar B4 a B7: Excel de Cumplimiento y PDF A4 generados con datos de demo, y capturas del menú y de los extractos (con la "fecha del movimiento" a la vista: RV3-22). Se genera después de que mergeen G8, G9 y G12, porque esas entregas cambian las columnas 21, 24 y 30 del Excel, el A4 de cuatro incisos, el menú del Cajero y del Supervisor y los rótulos de los extractos. Se manda con un OK explícito por tanda (D3-23). Si Carlos prefiere mandarla antes, el OK se acota a lo que no cambia y el mail dice qué puntos están en cambio

Terminado cuando:

  • El README de la carpeta de referencia existe y el .xlsx no está commiteado sin revisión.
  • Plan v2, CLAUDE.md y doc/README.md ya no dicen que B6/B7 esperan merge ni que el adjunto falta; C7 dice "asumida".
  • La respuesta a Magaly salió (la manda Carlos) y el mail a Sean, si D3-22 es sí.
  • Las diez consultas tienen su resultado anotado en el PR de la entrega que las usa.
  • Los usuarios de prueba de G0.7 existen en Staging y el CI de PR corre npm test y npm run docs:build (G0.8).
  • La muestra de G0.9 salió con las versiones finales de G8, G9 y G12, y hay un OK explícito por tanda (B4, B5, B6 y B7).

Docs a actualizar: los listados en G0.1 y G0.3; doc/environments/staging.md (consulta previa al deploy ampliada a las 76 celdas más countries).

Riesgos: commitear capturas con datos personales (G0.2). Mandar la respuesta sin la cuenta de Tesorería creada: el cliente seguiría sin ver el perfil y creería que no está. Pedir el OK de B4 a B7 sobre una muestra que G8, G9 y G12 van a cambiar (G0.9). Crear los usuarios de prueba con una contraseña generada: queda legible en los logs (G0.7).


G1 — Soportes que sobreviven a un deploy ​

Commits: G1. Branch feature/v3-soportes-persistentes. Esfuerzo L. Alcance: RV3-06, RV3-07. Depende de D3-1 y de que Carlos corra el apply; QC-4 (diferida hasta que G1 esté desplegado) solo condiciona el re-test del cliente. Pasa por security. ⏸ No se puede empezar hasta D3-1.

Por qué. El cliente reporta que no puede adjuntar PDF/JPG (RV3-06) y que no puede abrir lo adjuntado (RV3-07). Lo primero tiene dos causas de infraestructura ya corregidas el 01/10 y el 02/10; lo segundo tiene una causa que no estaba corregida ni diseñada: ningún archivo de soporte se guarda en un lugar persistente.

  • config/filesystems.php:30-45: el disco documents es local salvo que DOCUMENTS_DISK_DRIVER sea s3.
  • Ningún lugar de la infra define esa variable (infra/terraform/modules/ecs/main.tf:109-126, .github/workflows, Dockerfile; solo .env.example dice local); no existe un bucket de documentos en el Terraform (el único aws_s3_bucket es el del estado); la task definition no monta volúmenes; y league/flysystem-aws-s3-v3 no está en composer.json ni en vendor/ (solo flysystem-local): aunque se pusiera la variable, la app no podría usar S3.
  • El archivo se guarda en storage/app/documents dentro del contenedor Fargate, que se destruye en cada deploy; Staging se promovió 11 veces entre el 29/09 y el 04/10. Todo documento subido antes del último deploy dejó la fila y perdió el archivo.
  • La documentación afirma lo contrario (S3 privado en Staging y producción: plan E5a §2, funcional 02-datos-y-documentos.md 2.5 punto 4, comentario de filesystems.php) y dice que el bucket "va a Terraform en la entrega de infra": esa entrega nunca lo hizo. "Completa" sigue diciendo que está todo porque la completitud se calcula sobre filas, no sobre archivos (Transaction.php:117-139).
  • Con más de una tarea (web_max_count es 2 en Staging, infra/terraform/environments/staging/main.tf:84, y 8 en producción; el default del módulo es 4) un archivo caería en una y se pediría a otra.
#CapaQué
G1.1DiagnósticoConfirmar antes de construir (consulta 7 de G0.6): un documento viejo da 404 DOCUMENT_FILE_MISSING y uno recién subido abre hasta el próximo deploy. Si el status fuera 500, 401 o 403, la causa es otra y se reabre
G1.2InfraMódulo Terraform documents: bucket privado (acceso público bloqueado, cifrado en reposo, versionado, política que niega conexiones sin TLS, ciclo de vida para versiones no vigentes). IAM del task role: s3:PutObject y s3:GetObject sobre bucket/* y s3:ListBucket sobre el bucket (sin él un objeto inexistente da 403 y, con throw => true, exists() revienta en 500 en vez del 404 controlado), sin s3:DeleteObject (un soporte no se borra). Variables DOCUMENTS_DISK_DRIVER=s3, DOCUMENTS_BUCKET y AWS_DEFAULT_REGION en common_environment de ecs/main.tf. Staging y producción (producción no se aplica)
G1.3Backendcomposer require league/flysystem-aws-s3-v3 (más lock). Credenciales por el task role, sin key/secret. TransactionDocumentService::store pasa 'private' como visibilidad (:63): verificarlo contra un bucket real con ACLs deshabilitadas; si falla con AccessControlListNotSupported, sacarlo (el bucket ya es privado; confianza baja, es un detalle conocido de Flysystem con buckets modernos)
G1.4BackendComando de solo lectura documentos:verificar: cuenta las filas de transaction_documents sin archivo. No borra filas: un soporte no se borra; los de prueba anteriores se reparan reemplazándolos (G5)
G1.5FrontendabrirPreview (useTransactionDocuments.ts:131-146) mapea el 404 DOCUMENT_FILE_MISSING a "El archivo no está disponible. Un Supervisor o Admin puede volver a subirlo."; validación previa de tamaño (más de 20 MB) y de tipo antes de enviar; error de red o 413 → "No se pudo enviar el archivo: revisá la conexión o probá con uno más chico"; 5xx → "Error del servidor, avisá a soporte"; se muestra el code del 422 cuando viene (P3-5). DocumentacionPago.vue y DocumentacionPrePago.vue
G1.6DocsVer "Docs a actualizar". Incluye el smoke de subida de P3-6
G1.7DespliegueOrden (lección del CORS del 2026-10-02: deploy-staging.yml renderiza la task definition desde la última revisión de la familia y el Terraform ignora task_definition): (i) merge y deploy de la imagen con la dependencia, con el disco todavía local; (ii) terraform apply manual (Carlos); (iii) un deploy más que tome las variables; (iv) verificación: subir, forzar un redeploy, abrir; más el chequeo de preflight CORS que ya documenta staging.md

Terminado cuando:

  • Un documento subido sobrevive a un redeploy: se sube, se promueve cualquier cambio a Staging y se abre. (Es la prueba que habría detectado el problema.)
  • Con la CLI de AWS: el objeto está en el bucket, es privado, está cifrado y no se puede leer sin credenciales.
  • Suben PDF, JPG y PNG de 100 KB, 2 MB y 19 MB; 21 MB da el mensaje de tamaño y no llega al servidor.
  • documentos:verificar lista las filas viejas sin archivo; abrir una da el mensaje específico.
  • Si QC-4 (que se pregunta recién con G1 desplegado) reproduce la falla de subida, hay hora y MTCN para correlacionar con los logs del ALB y del WAF.

Pruebas:

  • Backend: descarga con el archivo borrado del disco → 404 DOCUMENT_FILE_MISSING (el camino existe, falta el test); subir un JPG y un PDF reales mínimos de fixture (backend/tests/fixtures/) que pasen por el finfo real → 201 con el MIME correcto, y uno que miente → 422 (hoy los tests usan UploadedFile::fake(), que no ejercita nada real); la configuración del disco con DOCUMENTS_DISK_DRIVER=s3 no se rompe; documentos:verificar.
  • Frontend: useTransactionDocuments.spec.ts (TypeError de red, 413, 500 y 404 DOCUMENT_FILE_MISSING muestran cada uno su texto; un archivo de más de 20 MB no sale).
  • Manual en Staging: lo de "Terminado cuando", más el smoke de P3-6.

Docs a actualizar:

  • doc/plans/2026-08-07-e5a-datos-y-documentos-del-pago-diseno-tecnico.md §2 (nota de lo que nunca se hizo).
  • doc/functional/2026-08-07-pago-con-documentos/02-datos-y-documentos.md 2.5 punto 4 y 2.6.
  • ADR nuevo "Almacenamiento de los soportes de pago" (provisorio ADR-017) y doc/architecture/index.md.
  • backend/.env.example (L72-75), doc/environments/staging.md (smoke de subida; cómo se verifica) y production.md, infra/terraform/README.md, comentario de filesystems.php.
  • doc/manual/10-pago.md (formatos y tamaño aceptados; qué pasa si un archivo no se encuentra).

Riesgos:

  • Alto si no se corrige: pérdida de identificaciones y de respaldos contables en producción. Del arreglo: ordenar mal el despliegue (una tarea con DOCUMENTS_DISK_DRIVER=s3 sobre una imagen sin la librería da 500 en todo acceso a soportes), un apply que re-registra task definitions con valores equivocados (precedente del 2026-10-02), ListBucket faltante, y un bucket nuevo con datos personales que tiene que nacer con cifrado y acceso mínimo.
  • Otra regla del WAF que dispare sobre contenido binario (poco probable: solo mira los primeros 8 KB) o que el apply de la excepción no esté vigente.
  • Costo para Pago: mientras esto no esté, cualquier prueba del cliente que abra un documento falla después de cada deploy. G5, G2 y G9 se re-testean recién después de G1.

G2 — El pagador y su papeleta ​

Commits: G2. Branch feature/v3-pagador-y-papeleta. Esfuerzo M. Alcance: RV3-14. Depende de D3-2 (G2.2 también de D3-3) y de reproducir antes (G0.6 consultas 4, 5 y 10). Pasa por security (toca el alcance de PII).

Por qué. Las dos llamadas de la captura fallan con 404 por el mismo motivo: el alcance por PDV de una transacción ya resuelta. La búsqueda de Pago acota por país, no por PDV (PagoController.php:87, 119-125), así que encuentra la tx y dibuja "Imprimir papeleta" aunque la lista de soportes esté caída; la generación del PDF no es el problema (tolera datos faltantes con "—", PapeletaService.php:322-385). Si quien miró la tx no la pagó y es de otro PDV, es el 404 correcto con un mensaje engañoso. Si quien miró sí la pagó, es un defecto grave: no puede imprimir la papeleta del pago que acaba de hacer, no puede subir la papeleta firmada, el aviso de pendientes lo lista igual (PagoController.php:232 usa resolved_by_user_id) y el cierre de caja se bloquea con PENDING_PAYMENT_DOCUMENTS (CashBoxController.php:411-418) sin que pueda destrabarlo. Al día siguiente la caja vencida bloquea pagar. No determinado cuál fue el caso: reproducir en Staging (solo lectura). Confianza: media.

#CapaQué
G2.1BackendExcepción del pagador (D3-2 a): en PermissionService::inTransactionScope (:198-211) y TransactionDocumentController::authorizeScope (:161-189), quien tiene resolved_by_user_id igual a su id y el permiso por país queda dentro del alcance aunque el PDV no coincida. Cubre soportes, papeleta y datos_pago de un solo golpe. Solo para el pagador: no se abre el PII de otro PDV al resto del país
G2.2BackendUsuario multi-PDV sin PDV activo (D3-3 a). Va en el PR B2, junto con G4.1, y no en el de G2: tiene que decidir mirando la caja abierta, y esa lógica nace en G4.1; si saliera antes, la ventana entre los dos merges rechazaría a quien hoy paga con una caja abierta. Predicado: 422 con código nuevo ("elegí tu PDV activo en…") cuando allowedStationIds devuelve dos o más PDV y no hay PDV activo ni caja abierta del usuario en el país que lo resuelva, al subir el primer documento y al pagar. Las asignaciones sin acotar (allowedStationIds === null: Admin, o un Supervisor o Tesorería sin PDV) quedan exentas, como hoy, y en un país sin Caja no hay caja que desempate. resolveStationForResolution devuelve null por las dos razones (multi-PDV y sin acotar: PermissionService.php:327-336), así que el 422 no puede montarse sobre ese null: hay que distinguir los dos casos. Corrige la incoherencia de ADR-008 §1, que dice que ese usuario "no puede ser el primero en subir" y el código guarda null sin rechazar (TransactionDocumentController.php:88-93). Antes de activarlo, listar en Staging qué usuarios caen en el caso (G0.6 consultas 4 y 5)
G2.3FrontenduseTransactionDocuments.ts (:66-75) distingue 404 de los demás errores: con 404 dice "Esta transacción se pagó en otro punto de venta: sus soportes y su papeleta los ven ese PDV, un Supervisor o un Administrador" y no ofrece "Imprimir papeleta"; el aviso de papeleta (DocumentacionPago.vue:98-128) distingue "no tenés acceso" (404) de "no se pudo generar, probá de nuevo" (red o 5xx)
G2.4DocsVer abajo

Terminado cuando:

  • A sube la Carta desde el PDV A; B (PDV B) paga: B recibe 200 en soportes y papeleta de esa tx y datos_pago no es null en la búsqueda; B sube la papeleta firmada y cierra la caja.
  • Un tercero del PDV B que no pagó recibe 404 (los tests existentes de alcance siguen verdes sin tocarlos).
  • (G2.2, PR B2) Usuario con dos PDV acotados, sin PDV activo y sin caja abierta: pagar o subir el primer documento responde 422 con el código nuevo (si se acepta D3-3 a); con caja abierta, el PDV es el de esa caja; un Admin o una asignación sin acotar siguen pagando y subiendo como hoy. supervisor@ de Staging, sin caja abierta, recibe el 422.
  • Con 404 de la lista, la pantalla muestra el mensaje nuevo y no ofrece la papeleta.

Pruebas:

  • Backend: los cuatro casos de arriba, más PermissionServiceTransactionScopeTest ("resolved_by gana sobre el PDV solo para quien resolvió"); sigue en verde TransactionApiTest.php:2395-2426, PapeletaFormatosTest.php:240, TransactionDocumentApiTest.php:149.
  • Frontend: con 404 de la lista se muestra el mensaje nuevo y no el link; el aviso de papeleta distingue 404 de 500.
  • Manual en Staging (con las cuentas de G0.7): dos usuarios de dos PDV sobre una misma ACCEPTED: A sube, B paga, B imprime, sube la firmada y cierra.

Docs a actualizar: ADR-008 §1 (actualización: excepción del pagador; corrección de la incoherencia); funcional 01-flujo-del-pago.md §1.6, 02-datos-y-documentos.md §2.7 y 03-papeleta.md (alcance); doc/manual/10-pago.md (qué pasa con una tx de otro PDV); doc/qa/2026-09-12-adr008-documentos-bloquean-pago-plan-de-pruebas.md (o QA nuevo de esta entrega).

Riesgos: la excepción toca el alcance de PII, pero es mínima (solo quien resolvió). Rechazar al multi-PDV puede frenar operaciones hoy posibles: revisar en Staging antes de activar, y por eso G2.2 sale con G4.1 y no antes. No tocar el alcance de lectura de Admin ni de Supervisor.


G3 — Medio de pago: solo efectivo ​

Commits: G3. Branch feature/v3-medio-de-pago-efectivo. Esfuerzo M. Alcance: RV3-12, RV3-13, RV3-39. Depende de D3-4, D3-5 y D3-6 (con sus recomendaciones se puede arrancar), de QC-7 y de la consulta 6 de G0.6 (cuántas PAID con transferencia hay y qué cajas afectan).

Por qué. El cliente pide sacar la transferencia (RV3-12) y, si no se saca, que el saldo del PDV no se afecte (RV3-13). Coincide con C13. Hoy una transferencia descuenta la caja del PDV como si fuera efectivo (applyCashBoxDiscount no lee delivery_type), y por eso la caja reporta menos efectivo del que tiene. Es un defecto latente que ya estaba anotado el 07/08 (04-preguntas-abiertas.md #3: "esta parte sí bloquea"). Prefondeo País y Holding no miran el medio de pago: lo de "sale de Tesorería" ya se cumple. Sacar la transferencia del backend resuelve RV3-13 para los pagos nuevos sin escribir una rama nueva.

#CapaQué
G3.1BackendConstante nueva con los medios aceptados para escribir ([EFECTIVO]), usada en paymentDataRules (TransactionController.php:918): pay() y datosPago() responden 422 si mandan TRANSFERENCIA. DELIVERY_TYPES y DELIVERY_TRANSFERENCIA se quedan para leer (completitud histórica, TransactionDocument::requeridosPara, Cumplimiento col. 16-17)
G3.2BackendDemoTransactionSeeder.php:362-383: solo efectivo. No se tocan los 4 tipos de documento de transferencia (catálogo cerrado, hay historia), delivery_type ni bank_account
G3.3BackendTest de regresión: un pago nuevo es siempre efectivo y siempre crea su movimiento PAGO
G3.4FrontendConfirmActionModal.vue (:44-53, :84-106, :170-203): fuera la opción TRANSFERENCIA y el bloque de cuenta bancaria; Efectivo preseleccionado y el control sigue visible (literal con lo que pidió el cliente; se revierte con una línea). DatosPagoForm.vue (:349-368): la opción TRANSFERENCIA solo se renderiza si el valor guardado lo es (historia de solo lectura de una PAID). Las ACCEPTED que ya traen un borrador TRANSFERENCIA (datosPago() lo guarda mientras no se paga, ADR-011 §3) no son historia: el formulario las resetea a Efectivo al cargar, y pay() guarda el valor que manda, así que la fila queda consistente al pagar; sin eso, quien abra una de esas ACCEPTED recibiría un 422 al confirmar
G3.5DatosStaging (D3-6 a): listar los PAID con TRANSFERENCIA que tengan movimiento PAGO y corregir cada caja con un AJUSTE (+monto, motivo "Otro" con detalle "Corrección de pago por transferencia de prueba"). Procedimiento y costo: el AJUSTE exige una sesión abierta del día en esa caja (CashBoxController.php:578-600) y Tesorería no puede abrirla (no tiene apertura_cierre_caja, RoleSeeder.php:108): por cada caja afectada, un Cajero o el Admin abre la caja (o cierra y reabre la vencida), Tesorería o el Admin ajustan con ese motivo y se cierra. El ajuste queda en la sesión del día del arreglo, no en la de los pagos que corrige, y se ve en "Cierres por día" y en el reporte de Cajas: hay que explicárselo al cliente. El ledger es inmutable: no se borra el PAGO. Producción: nada
G3.6Catálogo (RV3-39)No se construye (D3-5 a): queda como constante hasta que QC-8 diga qué otras formas necesitan y cómo se comportan
G3.7DocsVer abajo

Terminado cuando:

  • "Confirmar pago" muestra Efectivo como única opción y se puede confirmar sin tocar nada.
  • Una PAID vieja por transferencia se ve bien en su ficha (valor en solo lectura) y sigue pidiendo sus 4 documentos.
  • pay con TRANSFERENCIA por API da 422 y no crea ningún CashMovement; con EFECTIVO, un PAGO por -amount.
  • Una ACCEPTED con borrador TRANSFERENCIA se abre con Efectivo, se paga con Efectivo y no pide los 4 documentos de transferencia.
  • Tras los ajustes, el saldo de cada caja afectada es su saldo previo menos la suma de los PAGO por transferencia revertidos (en datos de prueba no hay arqueo físico con qué compararlo), y el extracto del PDV muestra el PAGO y el AJUSTE con su motivo.

Pruebas:

  • Backend: TransactionApiTest (6 referencias a transferencia) y PagoApiTest (3): pay con TRANSFERENCIA → 422, con EFECTIVO → 200; una ACCEPTED con borrador TRANSFERENCIA se paga con EFECTIVO → 200 y no pide los 4 documentos; test_con_transferencia_se_exigen_cuatro_documentos_mas se queda pero la fila se arma directo en la base; ReporteCumplimientoApiTest ("Bank transfer") se queda; el seeder de demo sin transferencias.
  • Frontend: ConfirmActionModal.spec.ts (5 referencias), DatosPagoForm.spec.ts (3).
  • Manual en Staging: abrir "Confirmar pago"; abrir una PAID vieja por transferencia; comparar saldos de caja antes y después de los ajustes.

Docs a actualizar: funcional de pago 04-preguntas-abiertas.md (cerrar la #3 y su sub-pregunta de la caja física), 00-resumen.md (L48, L96), 02-datos-y-documentos.md; doc/plans/2026-08-07-analisis-definiciones-cis-ec.md §3.4; ADR-011 §3 (actualización: el medio de pago es solo efectivo); 01-modelo-de-saldos.md de Caja (todo PAGO de caja es efectivo) y nota en ADR-005; manual 10-pago.md (L49-50, L101-107, L178, L191); QA de E5a (caso 3.7); plan v2 C13; CLAUDE.md.

Riesgos: cambia un contrato de API (422 donde antes 200): front y back salen juntos; una pestaña con el front viejo y TRANSFERENCIA elegida recibiría un 422 con mensaje genérico. Las PAID viejas con transferencia siguen pidiendo sus 4 documentos (a propósito: son historia). Los AJUSTE de corrección entran en cierres y reportes de Cajas de Staging y hay que explicárselo al cliente. Si más adelante vuelve el pago por transferencia, no hay nada diseñado: no es un cambio chico.


G4 — El PDV de cada pago y el Reporte individual ​

Commits: G4. G4.1, G4.2, G4.6 y G4.7 van en feature/v3-pdv-del-pago (PR B2), apilado sobre G2 (tocan resolveStationForResolution y pay()); G4.3, G4.4 y G4.5 (Reporte individual) van en feature/v3-reporte-individual (PR B3), que no depende de nadie. Esfuerzo M. Alcance: RV3-15, RV3-16, RV3-17 (más H3-08). Depende de D3-7 y D3-8, y de QC-9, QC-10. Pasa por security si se activa el backfill.

Por qué. Una PAID siempre ocurrió en un PDV y el sistema lo sabe: en los países con módulo Caja todo pago descuenta la caja que el propio operador abrió (applyCashBoxDiscount, TransactionController.php:548-560) y esa caja pertenece a una estación; pero esa estación no se usa para atribuir el PDV. Cuando el PDV queda en null (RV3-17 causas 3 y 4), la persona acotada no ve su propio pago en Reporte individual (listingQuery filtra station_id IN alcance, :164-170); su ficha da 404 si es de nivel supervisor (el Cajero, acotado a lo propio, entra por authorizeScope antes de mirar el PDV y su ficha le da 200, TransactionController.php:1061-1067); el Dashboard no lo suma para usuarios acotados (DashboardController.php:86-93) y en Cumplimiento las columnas 33-36 salen vacías. Desde B6 hay más gente con alcance amplio que paga (el Admin, los Supervisores con varios PDV), así que el problema crece. defaultStationFor además toma el primer default_station_id no nulo de todas las asignaciones sin ordenar (PermissionService.php:310-316): con varias, el PDV puede cambiar de una corrida a otra (H3-08). Hay además una causa que no es un hueco (RV3-17, causa 6): el PDV fijado por otro camino puede ser distinto del de la caja que paga; ver D3-7.

#CapaQué
G4.1BackendEn pay(), país con módulo Caja: applyCashBoxDiscount devuelve también cashBox->station_id y se usa como PDV del pago según D3-7 (b: solo llena los huecos; el PDV activo y el PDV único siguen ganando). Países sin Caja: sin cambio. ADR corto "El PDV de un pago es el de la caja que pagó" (o addendum a ADR-007/ADR-011). Causa 6 de RV3-17 (PDV fijado ≠ PDV de la caja): con (b) no se corrige (D3-7); se agrega un test gemelo que fija el comportamiento elegido para "PDV activo ≠ PDV de la caja"
G4.2BackendOrden determinístico de las asignaciones en defaultStationFor (H3-08)
G4.3BackendReporte individual: columna "Procesada por" (RV3-16). TransactionListResource::CAMPOS suma un campo calculado procesada_por (mail de resolvedBy; "Soterex (API)" si está CANCELLED y resolved_by_user_id es null, que es el único camino no humano a CANCELLED; vacío en ACCEPTED), con resolvedBy:id,email cargado en index(). En export(): leftJoin users y una novena columna "Procesada por" al final (para no correr las posiciones que el cliente ya usa). SORTABLE_COLUMNS suma procesada_por. El alcance no cambia: el Cajero sigue viendo lo suyo. El mail es dato del operador, no del beneficiario, y no va a la metadata del evento de auditoría del export (ADR-016)
G4.4BackendEl archivo del Excel se llama reporte-individual-… (TransactionController.php:309; transactions.ts:127). No se tocan path, name de ruta ni la etiqueta de Auditoría "Exportación de transacciones"
G4.5FrontendColumna "Procesada por" en COLUMNS (TransaccionesView.vue:157-166) y renglón en la ficha. Rótulos en vez del "—" pelado: ACCEPTED → "Sin asignar (bolsa del país)", CANCELLED sin persona → "Cancelada por Soterex", PAID sin PDV → "Sin PDV asignado", en pantalla y en el Excel
G4.6FrontendAviso no bloqueante en la ficha de usuario (UsuariosView.vue, junto a "PDV activo", ~:598/:646): cuando el rol tiene pago:write, el alcance no es exactamente un PDV y no hay PDV activo, "los pagos de esta persona quedarán sin PDV si no tiene una caja abierta". En Guatemala casi no se dispara; cubre los países sin Caja
G4.7DatosBackfill opcional (D3-8): migración de datos idempotente que completa los PAID con station_id null desde su movimiento PAGO (cash_movements.transaction_id → cash_box → station) y deja un evento de Auditoría con el conteo, sin datos personales. Derivable del ledger; en Staging hay solo datos de prueba. Necesita OK explícito porque modifica filas de transactions. Mismo criterio que D3-4 (c): no toca los datos del pago, solo completa la atribución
G4.8DocsVer abajo

Terminado cuando:

  • País con Caja: un Supervisor con 2 PDV y sin PDV activo paga con caja abierta en el PDV B y la tx queda con station_id = B; ve su pago en Reporte individual, su ficha da 200, el Dashboard lo suma y Cumplimiento trae las columnas 33-36 llenas.
  • País sin Caja: sigue null (el test TransactionApiTest.php:595-611 queda como está y se agrega uno gemelo con Caja).
  • El Reporte individual y su Excel muestran "Procesada por" para PAID, para CANCELLED por una persona y como "Soterex (API)" para la cancelada por la API, y nada para ACCEPTED; el Excel tiene 9 columnas con la nueva al final y el mismo valor que la pantalla.
  • La migración de backfill, si se acepta, es idempotente: dos corridas dan lo mismo, solo toca PAID con station_id null y movimiento PAGO, y su evento no trae datos personales.
  • El Excel se llama reporte-individual-AAAAMMDD-HHMM.xlsx (G4.4); el path y el name de la ruta no cambiaron.
  • Una ACCEPTED dice "Sin asignar (bolsa del país)", una CANCELLED por la API "Cancelada por Soterex" y una PAID sin PDV "Sin PDV asignado", en pantalla y en el Excel (G4.5).
  • La ficha de usuario muestra el aviso de G4.6 cuando el rol paga, el alcance no es exactamente un PDV y no hay PDV activo; no lo muestra con un PDV activo, y no bloquea el guardado.

Pruebas:

  • Backend: los de arriba, más ReporteCumplimientoApiTest (columnas 33-36 llenas), el test de lista blanca (el listado no filtra ningún otro campo nuevo), TransactionExportApiTest (9 columnas; ordenar por procesada_por no rompe el export), el test del backfill, el de la lista de PDV determinístico y el gemelo de «PDV activo distinto del PDV de la caja» (G4.1).
  • Frontend: TransaccionesView.spec.ts (columna y rótulos por estado), UsuariosView.spec.ts (el aviso).
  • Manual en Staging con supervisor@… (2 PDV, sin PDV activo): pagar antes y después, repetir con una caja abierta en el otro PDV; bajar el Excel.

Docs a actualizar: funcional general 06-preguntas-abiertas.md #14 (cerrarla), 02-roles-permisos.md §2.4 (:205, qué PDV se graba); funcional de Caja (PDV del pago = PDV de la caja) y 06-preguntas-abiertas-caja.md pregunta #6 ("la caja que paga puede ser de un PDV distinto", hoy "pendiente no bloqueante, parcialmente resuelto"): se actualiza según lo que decida D3-7 (resuelta con la opción (a), el PDV es siempre el de la caja; con la (b), que es la recomendada, sigue parcial y se escribe la condición: el cruce dentro de un mismo país persiste cuando el PDV ya venía fijado); ADR corto o addendum; manual 20-transacciones.md (columna y rótulos; nombre del archivo), 81-admin-asignacion.md (PDV activo, que hoy no aparece en ningún Markdown del manual), 61-reportes-cumplimiento.md (la agencia sale de la caja); ADR-016 (una línea: la lista blanca suma procesada_por); doc/plans/2026-07-25-fix-pdv-asignacion-transacciones.md (nota de cierre); doc/plans/2026-08-04-e4-multiples-cajas-diseno-tecnico.md §2.3 (nota: la cláusula "no se valida que coincidan" queda superada por D3-7) y el docblock de applyCashBoxDiscount (TransactionController.php:544-546), que se actualiza en el mismo PR.

Riesgos: medio, porque toca la atribución de pagos (plata y reportes por PDV). Si la caja pasa a mandar siempre, cambian las cifras por PDV de Volumen, Dashboard y Cumplimiento respecto de lo ya reportado para quien tiene PDV activo distinto de su caja. El backfill modifica filas de transactions pagadas (no sus datos de pago). Las canceladas por la API siguen sin PDV: no se toca C2P.


G5 — Documentos del pago: consulta, reemplazo y papeleta ​

Commits: G5. Branch feature/v3-documentos-del-pago. Esfuerzo L. Alcance: RV3-03, 04, 05, 08, 09, 10, 11 (más H3-09). Depende de D3-9 y D3-10, de QC-2 y QC-3 y de G2 (merge secuencial: comparten PermissionService::inTransactionScope y canManageTransactionDocuments, TransactionDocumentController y DocumentacionPago.vue; el PR D sale después del PR B1); el re-test del cliente espera a G1. Pasa por security (cambia quién toca PII).

Por qué. Los ítems 2, 3, 6 y 8 de la hoja son una sola regla, y hoy no existe: el backend no distingue "subir un tipo que falta" de "reemplazar uno ya cargado" (TransactionDocumentService::store :48-77 siempre inserta y la UI muestra el más reciente). Por eso el Cajero que pagó ve "Reemplazar" sin límite de tiempo. No se puede aplicar literal "no modificar documentos de una tx pagada": la papeleta firmada se escanea después de pagar y el cierre de caja la exige (CashBoxController.php:411-420, 489-510); si el Cajero no pudiera subirla, no podría cerrar. Por eso "modificar" se lee como "reemplazar uno ya cargado", que es lo que pide el ítem 8 (P3-1).

Estado de la txSubir un tipo que faltaReemplazar uno ya cargado
ACCEPTEDCualquiera con transacciones:write en el país (como hoy)Igual: el Cajero corrige hasta "Confirmar pago"
PAID / CANCELLEDQuien pagó, el Supervisor con alcance del PDV, el Admin (como hoy; salvo que G5.1 endurece "supervisor" a una misma asignación: un Supervisor del PDV B que es Cajero del PDV A deja de poder subir en A, a menos que haya pagado él)Solo el Supervisor con alcance del PDV y el Admin. El atajo "resolvió él" desaparece
#CapaQué
G5.1BackendPermissionService::canReplaceTransactionDocuments(user, tx): ACCEPTED como hoy; PAID/CANCELLED exige nivel supervisor dentro de UNA misma asignación que cubra el PDV de la tx (P3-2), sin el atajo de quien resolvió. Mismo criterio para endurecer canManageTransactionDocuments (:244-270), que hoy combina "es supervisor" por país con el alcance de PDV en unión. Es un cambio de comportamiento aparte de "reemplazar": con asignaciones mezcladas (Cajero de un PDV y Supervisor de otro) cambia también quién puede subir un tipo que falta. El helper de P3-2 (assignmentHolds) lo crea este PR si mergea antes que G6.A, o lo reutiliza
G5.2BackendTransactionDocumentController::store: si ya existe un documento de ese type y la tx no está ACCEPTED, exige canReplace o responde 403 CANNOT_REPLACE_DOCUMENTS. index() devuelve puede_reemplazar junto a puede_subir
G5.3BackendAuditoría con acción propia TRANSACTION_DOCUMENT_REPLACED (tipo, id del reemplazado, estado de la tx; P3-3); TRANSACTION_DOCUMENT_UPLOADED deja de guardar el nombre original del archivo (H3-09, TransactionDocumentController.php:105)
G5.4FrontenduseTransactionDocuments expone puedeReemplazar. DocumentacionPago.vue (:362-377): "Reemplazar" solo con canUpload && puedeReemplazar, "Subir" (hueco vacío) con canUpload && puedeSubir; en consulta, línea "Solo consulta: los documentos cargados no se modifican; si hay un error, pedíselo a un Supervisor o Admin"; en cada fila, "subido por X el dd/mm" para quien puede reemplazar. PagoView.vue:520-527 y TransaccionDetalleView.vue:443-449 siguen al composable
G5.5FrontendPapeleta con dos botones (RV3-09, P3-4): se reemplazan el botón, la etiqueta y el chevron con su menú (DocumentacionPago.vue:93-198, 223-289, ~70 líneas de foco y teclado) por "Imprimir papeleta tirilla" e "Imprimir papeleta A4", cada uno con ?formato=termico o ?formato=a4, el del país marcado "predeterminado", sin depender de canUpload; en 375 px envuelven a una segunda línea y "Faltan N" sigue a la derecha. Alinear el rótulo ("tirilla" frente a "Térmica 58 mm" en PaisesView.vue:229 y formatoRecibo.ts)
G5.6FrontendLos campos de datos de una tx pagada se ven deshabilitados: estilo disabled (fondo gris, cursor: not-allowed) en DatosPagoForm.vue:298; hoy el preflight de Tailwind pisa el gris del navegador y el cliente probablemente los ve editables (por eso escribió "al igual que los datos"). No determinado: mirarlo en Staging
G5.7FrontendDocumentos previos al pago (RV3-11), default D3-10 (1): DocumentacionPrePago.vue muestra "Subido por usuario el fecha" (uploaded_by y created_at ya viajan) y un aviso de una línea cuando son de un intento anterior ("Estos documentos ya estaban cargados desde … Verificá que correspondan a quien tenés enfrente"). Si QC-3 responde (b): la búsqueda muestra solo la tarjeta del match y datos y documentos aparecen al tocar "Iniciar pago". No se mueven pago-buscador ni pago-mis-transacciones
G5.8DocsVer abajo

Terminado cuando:

  • El Cajero que pagó intenta reemplazar un documento existente en una PAID y recibe 403 CANNOT_REPLACE_DOCUMENTS sin fila nueva; sube la papeleta firmada (un tipo que falta) y cierra la caja.
  • El Supervisor del PDV reemplaza y queda TRANSACTION_DOCUMENT_REPLACED con el id reemplazado y sin nombre de archivo; el Admin reemplaza; un Supervisor de otro PDV recibe 404.
  • Con la tx ACCEPTED, el Cajero reemplaza Carta e Identificación.
  • Un Supervisor del PDV B que es Cajero del PDV A no reemplaza documentos del PDV A.
  • La papeleta se baja en los dos formatos desde dos botones visibles, para un Cajero en consulta que no pagó la tx y no para Tesorería (sin acceso a transacciones).
  • (G5.6) Una PAID abre con los campos de datos grisados y cursor: not-allowed, a 1280 px y a 375 px.
  • (G5.7) La tarjeta de documentos previos al pago muestra "Subido por usuario el dd/mm" y, cuando son de un intento anterior, el aviso de una línea; si QC-3 responde (b), la búsqueda no los trae hasta tocar "Iniciar pago".

Pruebas:

  • Backend (TransactionDocumentApiTest, PermissionServiceTransactionScopeTest): los casos de arriba; puede_reemplazar correcto por perfil y estado; CANCELLED igual que PAID; Cajero + Tesorería en el mismo país no reemplaza; test_quien_resolvio_puede_subir_soportes_despues_de_pagar sigue verde (es primera subida); la auditoría no contiene el nombre del archivo; la papeleta de una PAID la descarga un Cajero que no la pagó (200).
  • Frontend: DocumentacionPago.spec.ts (Reemplazar oculto con puede_reemplazar=false aunque puede_subir=true; dos botones, formato explícito, siguen visibles sin canUpload; los del chevron se reescriben), useTransactionDocuments.spec.ts, TransaccionDetalleView.spec.ts, DocumentacionPrePago.spec.ts (procedencia), DatosPagoForm.spec.ts (estilo).
  • Manual en Staging (cuentas de G0.7 para «un Supervisor de otro PDV») con los tres perfiles sobre una misma PAID; mirar a 1280 px y a 375 px sin scroll horizontal.

Docs a actualizar: ADR-011 §4 (nueva "Actualización" con la regla de reemplazo; hay precedente de tres) y ADR-008 (procedencia); funcional 00-resumen.md (R8), 01-flujo-del-pago.md (§1.4, §1.6 y los diagramas), 02-datos-y-documentos.md (2.5 punto 2 y 2.7), 03-papeleta.md y 01-flujo-del-pago.md (de "Descargar en otro formato" a dos botones); manual 10-pago.md (L201-204, "Después del pago", "Imprimir la papeleta"; sección nueva "Corregir un documento mal cargado" para Supervisor y Admin), 20-transacciones.md, 90-auditoria.md (acción nueva) y 82-admin-paises.md; etiqueta de la acción en AuditoriaView.vue; plan v2 P9(b) y B5.7; QA nuevo (o 2026-09-11-e5-pago-documentos-plan-de-pruebas.md marcado histórico).

Riesgos: medio. Cambia la decisión D5 de v1: un Cajero que sube por error un archivo en el hueco equivocado (la papeleta firmada, por ejemplo) ya no puede corregirlo y depende de un Supervisor o Admin; en un PDV sin Supervisor, solo del Admin. Hay que probar el cierre de caja. No mezclar "subir lo que falta" con "reemplazar". La fecha de las capturas del cliente (30/09 y 01/10) es anterior a B5: re-testear sobre el Staging actual.


G6 — Caja: quién opera cada caja y quién la cierra ​

Commits: G6. Tres PRs, uno por bloque: feature/v3-caja-quien-opera (G6.A, PR E1), feature/v3-caja-quien-cierra (G6.B, PR E2, apilado sobre E1) y feature/v3-caja-linea-de-pais (G6.C, PR E3, sin decisiones pendientes; toca totalesPorPdv igual que G6.A2). Esfuerzo L (A: M, B: M, C: S). Alcance: RV3-24, 25, 26, 27, 28 (más H3-03 y H3-12). Pasa por security (G6.B cambia quién puede qué). Tres bloques con bloqueos distintos: G6.A ✅ se puede empezar; G6.B ⏸ espera D3-12, D3-13 y QC-12; G6.C ✅ se puede empezar con lo que dibujó el cliente (QC-15 solo lo confirma).

Por qué. (RV3-27) La pantalla no dice quién tiene abierta cada caja; el dato está en la sesión. (RV3-26) Una caja abierta ya no se puede abrir por otro (409 + índice único), pero hoy un segundo usuario puede cerrarla y abrirla él, que es el "cruce de saldos" que describe el cliente. (RV3-25) Pide que solo quien la abrió pueda cerrarla; esto revierte una decisión escrita (ADR-013 §5: el cierre de una caja vencida lo destraba un compañero o un Supervisor, y el test CashBoxApiTest.php:1496-1502 dice que "si algún día se agrega solo cierra quien abrió, la caja vencida de un cajero ausente queda sin salida"). Con la regla literal, una caja vencida de un cajero que no vino, se fue o fue dado de baja queda trabada (no paga, no fondea, no ajusta) y el índice cash_sessions_one_open_per_user le impide abrir otra. Hace falta un escape y decidir quién lo tiene (D3-12). (H3-03) canSeeBalance decide por país y no por PDV: con perfiles mezclados (D3-T2) muestra saldos de más.

#CapaQué
G6.AVisible, sin decisiones pendientes
G6.A1Backenddisponibles() suma a la sesión opened_by {id, email} (RV3-27) con openSession precargada en scopedCashBoxes (hoy se consulta una vez por caja, H3-12); deja de mandar opened_by_supervisor_id, que desde E4b.1 es siempre null. El mensaje del 409 CASH_ALREADY_OPEN dice quién la tiene ("La Caja 1 de Mixco Plaza la tiene abierta mail")
G6.A2BackendH3-03: canSeeAllCashBoxes(user, país, ?PDV) mira allowedStationIds(user, 'fondeo_caja', 'read', país); canSeeBalance usa el PDV de la caja; totalesPorPdv cruza el alcance de caja:read con el de fondeo_caja:read. Escribir primero el test que reproduce el caso para confirmar el hallazgo. Usa el helper de P3-2 (assignmentHolds), que crea el primero que mergee entre este paso y G5.1; G6.B lo reutiliza
G6.A3FrontendTarjeta del selector: "Abierta por mail" o "Abierta por vos" (el id viaja); vista operativa: "Abierta el fecha por mail"; una caja abierta por otro Cajero no ofrece "Abrir". Es la propuesta de 05-ux-multiples-cajas-y-fondeo.md §5.1.3, hasta hoy sin implementar. Tipado en services/caja.ts. Ver el mail es visible para todos los que ven la lista de cajas del PDV (el Cajero necesita saber a quién pedirle que libere una caja y el mail ya sale en el historial)
G6.BCierre de una caja ajena (D3-12 B, D3-13 i)
G6.B1BackendPermissionService::canCloseCashSession(user, session): puede cerrar (1) quien abrió la sesión, o (2) quien tenga, dentro de UNA misma asignación que cubra el PDV de la caja, apertura_cierre_caja:write y fondeo_caja:read (Supervisor y Admin). Nadie más: ni otro Cajero, ni Tesorería (que no tiene apertura_cierre_caja). Así un Cajero + Tesorería no se eleva a "supervisor" solo por sumar asignaciones
G6.B2BackendEn cierre() (:385-475), después de encontrar la sesión y antes del control de documentos pendientes, 403 CASH_CLOSE_NOT_OWNER ("Esta caja la abrió otra persona. Solo quien la abrió, un Supervisor o un Admin pueden cerrarla."); disponibles() suma can_close (calculado en backend, como from_previous_day: el front refleja, no decide, ADR-013 §6); la auditoría de CASH_SESSION_CLOSED suma el booleano cierre_ajeno, sin montos
G6.B3Frontend"Cerrar caja" solo si session.can_close (CajaView.vue:695-712 y el slot del aviso de vencida :544-551); en una caja ajena, "La abrió mail: solo ella, un Supervisor o un Admin pueden cerrarla"; AvisoCajaVencida.vue:77-79 cambia "pedile a quien tenga ese permiso" por "pedile a un Supervisor o un Admin"
G6.B4Backend (opcional)Avisar al desactivar un usuario con una caja abierta (UserController::update, :85-106 no mira sesiones): esa caja solo la cierra un Supervisor o un Admin
G6.C✅ La línea de país (RV3-28): el cliente la dibujó, QC-15 solo la confirma
G6.C1Backend y frontendLa línea que dibujó el cliente: "Guatemala · USD 24.878,53" encima de las tarjetas por PDV, con el total de plata en las cajas del país en su moneda de pago. Un bloque countries[] en GET /caja/totales-pdv (uno por país, nunca suma entre monedas) cuyo total reusa CountryPrefundingService::distributedInCashBoxes, para que coincida con "Distribuido en cajas" de Prefondeo País (img 33) y no haya dos definiciones. scope_complete en true solo si el alcance cubre todos los PDV con caja del país; si no, el rótulo es "Total de tus PDV" y no "Guatemala". Lo ve quien ya ve totales-pdv (fondeo_caja:read: Supervisor, Tesorería y Admin). Si QC-15 respondiera (b), el disponible para distribuir, o (c), las dos: se suma la segunda cifra solo para quien tiene prefondeo_pais:read (Tesorería y Admin), reusando CountryPrefundingService::availableToDistribute. Con D3-T1 escala sin rol nuevo: una persona con varios países ve una franja por país
G6.DDocsVer abajo

Terminado cuando:

  • (A) Otro usuario intenta abrir una caja ya abierta y recibe 409 CASH_ALREADY_OPEN con la sesión del primero intacta y una sola OPEN; la tarjeta dice quién la tiene; el Cajero la ve aunque el saldo esté oculto.
  • (A) Supervisor del PDV A + Cajero del PDV B: ve el saldo real de A, balance: null en B, el historial de B da 403 CASH_BOX_BALANCE_HIDDEN y totales-pdv trae solo A. Supervisor de A + Tesorería del país entero sigue viendo todo (regresión).
  • (B) Quien abrió la cierra; el Supervisor del PDV cierra la ajena y queda cierre_ajeno; el Supervisor de otro PDV recibe 403; un Cajero + Tesorería en el mismo país no cierra la ajena; el Admin cierra cualquiera; en una vencida, el Cajero compañero recibe 403 y el Supervisor 200; el cierre ajeno del Supervisor sigue frenado por PENDING_PAYMENT_DOCUMENTS (puede subir los soportes, ADR-011 §4).
  • (B) A quien le cierran la caja, pay() le responde NO_CASH_BOX_OPEN_FOR_USER, y un Supervisor la destraba.
  • (C) En Saldos, un Supervisor o Tesorería con todos los PDV de Guatemala ve "Guatemala · USD N" arriba de las tarjetas, con N igual a la suma de las tarjetas por PDV y a "Distribuido en cajas" de Prefondeo País; con un alcance parcial el rótulo es "Total de tus PDV"; un país con otra moneda de pago no se mezcla.

Pruebas:

  • Backend: CashBoxApiTest (el test de :1502 se reescribe: de "un compañero cierra la caja vencida de otro" a 403 con la sesión intacta y sin evento de auditoría; los nuevos de arriba; un conteo de consultas para no meter un N+1; disponibles devuelve can_close correcto por perfil); PerfilesAccesoApiTest (fila nueva POST /caja/{abierta}/cierre sobre una caja abierta por otro: Cajero 403, Supervisor 200, Tesorería 403, Admin 200, usando una caja aparte; y el caso mezclado de H3-03). Para G6.C, CashBoxApiTest: el bloque countries[] de totales-pdv coincide con distributedInCashBoxes, no suma monedas y rotula "Total de tus PDV" con alcance parcial.
  • Frontend: CajaView.spec.ts ("Cerrar caja" ausente sobre caja ajena para el Cajero, presente sobre la propia y para el Supervisor; la tarjeta muestra "Abierta por mail" y "Abierta por vos"; el aviso de vencida sin botón dice a quién pedírselo).
  • Manual en Staging (cuentas de G0.7) con dos Cajeros del mismo PDV y un Supervisor: A abre la Caja 1, B entra a Saldos (ve quién la tiene y no ve "Cerrar"), B hace POST al cierre y recibe 403, el Supervisor la cierra y queda auditado, A intenta pagar y recibe NO_CASH_BOX_OPEN_FOR_USER.

Docs a actualizar: ADR nuevo "Quién cierra una caja ajena" (provisorio ADR-018) que supersede en parte ADR-013 §5, y ADR-013 marcado; funcional de Caja 02-flujos-caja.md (:155, :611-614, :645-649), 03-diagramas-actividad-caja.md (:357, :375-377), 04-secuencias-pantalla-caja.md (§4.3.1, qué muestra la pantalla), 05-ux-multiples-cajas-y-fondeo.md (§5.1.3 y hallazgo 2: de propuesta a implementado), 06-preguntas-abiertas-caja.md (pregunta nueva #22); manual 30-caja.md (sección "Quién tiene abierta cada caja" y una tabla "Qué ve cada perfil en Saldos"), 31-caja-apertura-cierre.md (:42-45 y "Si quedó abierta de un día anterior"), 01-perfiles-y-menu.md; ADR-014 §6; QA nuevo. Son siete menciones de la regla vieja: si queda una sin corregir, el manual contradice al sistema.

Riesgos: alto en operación, bajo en código. (1) Caja trabada si el PDV no tiene Supervisor (mitigación: el Admin siempre puede; o la variante C). (2) Se revierte una decisión documentada en siete lugares y protegida por un test. (3) Hay que avisar a los operadores que hoy dependen de que un compañero les cierre la caja. (4) La regla rige desde el deploy: las cajas que estén abiertas ese día solo las cierran quien las abrió, un Supervisor o un Admin. No agrega ningún permiso nuevo con la opción recomendada.


G7 — Caja: administrar cajas (activar y desactivar) ​

Commits: G7. Branch feature/v3-administrar-cajas, apilado sobre G6.A (el panel muestra quién la tiene abierta; no necesita G6.B ni G6.C). Esfuerzo M. Alcance: RV3-29, RV3-30 (más H3-06). ⏸ Depende de D3-14 y de QC-16.

Por qué. "Agregar" ya existe (RV3-29: + agregar caja en Parámetros → Estaciones/PDV, auditado). Lo que falta es la baja y la reactivación: cash_boxes solo tiene id, station_id, number y timestamps, y una caja existe para siempre, aparece en Saldos y en Reportes → Cajas y se puede abrir. Siguiendo la regla "se desactiva, no se borra". La columna "Cajas" de la pantalla muestra un número y un botón, pero no hay un lugar donde se vean las cajas de un PDV y su estado: probablemente por eso el cliente señala el botón. Hallazgos que la baja deja a la vista (H3-06): desactivar un PDV no desactiva sus cajas, agregarCaja no valida que el país tenga módulo Caja ni que el PDV esté activo, y mover un PDV a un país con módulo Caja no le crea la Caja 1. Escuintla Norte aparece con 0 cajas: no determinado; hipótesis, confianza baja: StationSeeder crea los PDV con updateOrCreate sin pasar por StationController::store, así que si corrió después de activar el módulo Caja no se creó su Caja 1 (consulta 3 de G0.6).

#CapaQué
G7.1DatosMigración de esquema: cash_boxes.active boolean default true (las existentes quedan activas). Es configuración, no un saldo: no toca ADR-005/007
G7.2BackendPATCH /admin/estaciones/{station}/cajas/{cashBox} con {active} bajo perm:abm_estaciones,write, validando que la caja sea del PDV. Desactivar da 409 CASH_BOX_HAS_OPEN_SESSION si tiene sesión OPEN y 409 CASH_BOX_HAS_BALANCE si el saldo derivado no es cero en ninguna moneda (D3-14 a: CashBoxService::balance() filtra por la moneda de pago vigente del país y el efectivo que quedó en otra moneda solo sale por residualBalances(), CashBoxService.php:70-82, así que el control mira las dos), con lockForUpdate de la caja como apertura, para que desactivar y abrir se serialicen. Reactivar vuelve con su número y el saldo que tenía. Auditoría CASH_BOX_ACTIVATED / CASH_BOX_DEACTIVATED con {station_id, number}, sin montos
G7.3BackendDefinir "caja operable" (activa, de un PDV activo, en un país con módulo Caja) en un solo scope de CashBox, usado por scopedCashBoxes (disponibles, totales-pdv), apertura (422 CASH_BOX_INACTIVE) y agregarCaja. total_cash_boxes cuenta solo activas. El resumen de Reportes → Cajas muestra las inactivas con "Inactiva"; "Cierres por día", los extractos de B7 y distributedInCashBoxes siguen leyendo el ledger sin cambios
G7.4BackendH3-06: agregarCaja da 422 si el país no tiene el módulo o el PDV está inactivo; desactivar un PDV con una caja abierta da 409 STATION_HAS_OPEN_CASH_BOX; StationController::update llama a ensureCashBoxForStation cuando el PDV pasa a un país con módulo Caja
G7.5FrontendLa celda "Cajas" de Estaciones/PDV pasa a "N cajas · Administrar" y abre un panel con la lista (Caja 1 Activa, Caja 2 Inactiva, "abierta ahora por mail" si corresponde), botones Activar/Desactivar con confirmación y el "+ agregar caja" adentro (se conserva el botón actual). CajasView.vue con la etiqueta "Inactiva". No se crea un módulo de permiso (P3-15)
G7.6DocsVer abajo

Terminado cuando:

  • Se desactiva la Caja 3 de un PDV (cerrada y en cero) y desaparece de Saldos y de la apertura; se reactiva con su número y su saldo; agregar una caja después de desactivar la última no reutiliza el número.
  • Desactivar con sesión abierta o con saldo da 409; sin abm_estaciones:write da 403; una caja de otro PDV en la URL da 404 o 422.
  • agregarCaja en un país sin módulo Caja y en un PDV inactivo da 422; mover un PDV a un país con módulo Caja le crea la Caja 1.

Pruebas: StationApiTest (todo lo anterior, incluido desactivar una caja con residuo en otra moneda → 409), CashBoxApiTest (disponibles y totales-pdv sin inactivas, total_cash_boxes solo activas, apertura de una inactiva 422, un test de carrera desactivar contra abrir), CajaReportesApiTest (el resumen incluye la inactiva con su marca), EstacionesView.spec.ts. Manual en Staging: desactivar, comprobar que desaparece de Saldos y de la apertura, reactivar.

Docs a actualizar: ADR nuevo "Alta y baja de cajas" (o un solo ADR de Caja v3 con G6; provisorio ADR-018); manual 83-admin-estaciones.md ("Cajas por estación"), 30-caja.md, 31-caja-apertura-cierre.md; funcional de Caja 04-secuencias-pantalla-caja.md (:794-812, :905-907), 01-modelo-de-saldos.md, 02-flujos-caja.md (hallazgo 4, :650-652), 06-preguntas-abiertas-caja.md; QA nuevo.

Riesgos: medio. (1) La plata de una caja que se da de baja: hoy no hay forma limpia de sacarla (solo un AJUSTE negativo "Faltante de arqueo", que miente) y fondeo/ajuste exigen sesión abierta; si se permite desactivar con saldo, el total del PDV de Saldos tiene que seguir incluyéndolo para no discrepar del extracto del PDV de B7 (CashBoxService::balanceForStation). (2) Los motivos de ajuste son un catálogo cerrado que decide Tesorería: agregar uno es decisión del cliente. (3) La migración tiene default true: segura, y no cambia permisos de nadie.


G8 — Perfiles: tipo de cambio, perfiles mezclados y dos fugas ​

Commits: G8. Dos PRs: feature/v3-perfiles-y-mezcla (F1: documentación, las dos fugas y los tests de caracterización) y feature/v3-tipo-de-cambio-tesoreria (F2: G8.1, G8.2 y G8.9, las migraciones). Esfuerzo L. Alcance: RV3-35, 41, 47, 49, 51, 85 (más H3-01, H3-02, H3-04). Depende de D3-11 (para la migración), D3-24 y QC-17, QC-18. Pasa por security. ◐ La documentación y las dos fugas se pueden hacer ya; la migración de permisos (F2) espera D3-11.

Por qué. (RV3-35 y 47) La hoja reserva el tipo de cambio a Administrador y Tesorería; B6 lo dejó en solo lectura también para Cajero y Supervisor por decisión nuestra (ADR-014 §9, "si no lo quieren, es la celda tipo_cambio de esos dos perfiles"). Nada operativo lo necesita: pay() lee el tipo de cambio por el servicio, sin pasar por el permiso (TransactionController.php:601), el único consumidor del endpoint en el frontend es TipoCambioView y Guatemala paga en dólares. (RV3-49) D3-T2: se documenta. (H3-01, H3-02) La unión de perfiles produce dos fugas que el selector de perfil no resolvería: están en Reportes.

#CapaQué
G8.1DatosMigración de datos nueva (no se edita la de B6, que ya corrió) <fecha>_v3_tipo_de_cambio_solo_tesoreria_y_admin (el prefijo de fecha lo pone artisan make:migration): EnsureRolePermissions::setCells(['Cajero' => ['tipo_cambio' => [false, false, false]], 'Supervisor' => [...]]) dentro de DB::transaction y con RolePermission::withoutEvents; deja ROLE_PERMISSION_CHANGED_BY_MIGRATION con antes y después. Idempotente. Pisa lo que un Admin haya editado en esas dos celdas (política de ADR-014 §8)
G8.2DatosEn el mismo commit: RoleSeeder::MATRIX (:68, :90) y doc/architecture/matriz-de-perfiles.json (un test compara matriz, migración y JSON; frontend/src/testing/perfiles.ts lo lee). Efecto visible: el Cajero pierde el grupo Tesorería; el Supervisor se queda con Fondeo PDVs; la barra mobile del Cajero baja a tres destinos; en el manual en PDF, el Cajero pasa de 7 a 6 secciones y el Supervisor de 10 a 9. Ojo con PerfilesMigrationTest: compara RoleSeeder::MATRIX con lo que deja ejecutar solo la migración de B6 (MIGRACION, migrar(), :32 y :108-112; la comparación, :255-272) y afirma tipo_cambio del Supervisor (:238-239): con tipo_cambio en 0/0/0 en MATRIX falla por diseño. migrar() tiene que aplicar B6 y la migración v3 en ese orden (o se agrega un test aparte para la v3), y esos asserts y la fixture se ajustan
G8.3BackendH3-01: ReportesController.php:352 pasa a $canSeeBeneficiary = ! $this->permissions->isScopedToOwnTransactions($user, $countryId), la misma señal que usa el listado (Supervisor y Admin ven el nombre; Cajero + Tesorería recibe null)
G8.4Backend(Opcional) comando de solo lectura permisos:diferencias que imprime la diferencia entre role_permissions y RoleSeeder::MATRIX; hoy la consulta previa de staging.md cubre nueve celdas y debería cubrir las 76 (H3-04)
G8.5FrontendH3-02: countriesWithAccess('reportes') en SituacionView, VolumenView y CajasView (y alinear TransaccionesView, donde el efecto es un filtro vacío y no un 403)
G8.6FrontendTextos: bajo "Roles y Asignaciones" (UsuariosView.vue:551-556 y :675-678) y en ManualUsuarioView.vue:75-79: "Los permisos de la persona son la suma de todas sus asignaciones, país por país"; el PDF es por rol, no por persona. Solo si D3-24 b: utils/combinacionesSensibles.ts, una función pura que por país devuelve notas (no errores) cuando la capacidad surge de la combinación y ningún rol por sí solo la tiene (así el Admin no dispara nada): pago y fondeo de caja en asignaciones distintas; asignación acotada por PDV junto a otra del mismo país; Admin más otro perfil; timeouts distintos. Se dibuja como aviso informativo bajo la tabla, sin bloquear el guardado
G8.7TestsDe caracterización que fijan D3-T2: /me con Cajero + Tesorería devuelve la unión y cada asignación conserva los suyos (MeApiTest); Admin + cualquier perfil no cambia ninguna celda (PerfilesAccesoApiTest, falla si alguien le da al Cajero algo que el Admin no tiene); Cajero PDV1 + Supervisor PDV2 ven todo PDV1 y PDV2 (documenta); Cajero + Tesorería fondea la caja que abrió (documenta, hasta que D3-24 decida otra cosa); AppLayout.spec.ts: Cajero + Tesorería muestra la suma de los dos menús
G8.8DocsVer abajo (acá está la documentación de D3-T1 y D3-T2)
G8.9Datos (condicional)Solo si la consulta 1 de G0.6 muestra celdas de role_permissions distintas de RoleSeeder::MATRIX (H3-04, RV3-41: el Cajero de la img 32 sin "Transacciones"): otra migración de datos con setCells que lleva a MATRIX solo las celdas divergentes, con la lista previa aprobada por Carlos celda por celda (algunas pueden ser política del cliente: QC-18) y aviso al cliente. La fuente de comparación es MATRIX, no la hoja de Menús, que dice qué menú ve cada perfil y no distingue lectura, escritura y borrado. Va en el PR F2

Terminado cuando:

  • Sobre una base con la matriz de B6, la migración deja tipo_cambio en 0/0/0 para Cajero y Supervisor; correrla dos veces da lo mismo; PerfilesMigrationTest compara matriz, migración y JSON sin diferencias.
  • GET /tipo-cambio/{pais} da 403 al Cajero y al Supervisor y 200 a Tesorería y Admin; el Cajero y el Supervisor no ven el ítem ni entran por URL; pagar en Guatemala sigue andando.
  • Cajero + Tesorería recibe null en el nombre del beneficiario en el Estado de Situación (pantalla y Excel); Supervisor y Admin siguen viéndolo.
  • Con asignaciones Cajero en GT y Tesorería en EC, el selector de Reportes ofrece solo EC y la primera carga no da 403.
  • El manual explica la mezcla; ManualPdfTest y manual.spec.ts verdes con los contadores nuevos.

Pruebas: además de G8.7: PerfilesMigrationTest (migrar() encadena B6 y la migración v3; matriz esperada y asserts del Supervisor, :238-239), PerfilesAccesoApiTest (GET /tipo-cambio/{pais} pasa de 200 a 403 para Cajero y Supervisor; el caso de H3-01 junto al de :472; el de :518 sigue verde), ManualPdfTest::test_cantidad_de_secciones_de_cada_perfil (6 y 9), AppLayout.spec.ts (el Cajero deja de ver Tipo de cambio; barra mobile), firstAllowedRoute.spec.ts (:154 queda sin sentido: reescribir), guardPorPerfil.spec.ts, ManualUsuarioView.spec.ts (fixture), un spec por vista de Reportes. Manual en Staging con backoffice@, supervisor@, tesoreria@ y admin@, y las cuentas mixtas de G0.7.

Docs a actualizar:

  • D3-T2: doc/manual/01-perfiles-y-menu.md (reescribir "Si tiene más de una asignación": suma, por país, pantalla de inicio, timeout mínimo, encabezado de asignaciones, "el Admin ya incluye al Cajero", combinaciones a evitar), 00-primeros-pasos.md, 80-admin-usuarios.md (la ficha muestra una matriz por rol, no la suma), 81-admin-asignacion.md (PDV activo); ADR-014 §6 (subapartado "Un usuario con más de un perfil: la mezcla es intencional (2026-10-04, D3-T2)", con la alternativa descartada y su costo); funcional 02-roles-permisos.md (§2.3: qué confirmó el cliente y qué es diseño, y la nota ⑴) y 05-secuencias-pantalla.md. No hay ADR nuevo.
  • D3-T1: nota en ADR-014 §1 ("Tesorería es un único perfil, regional por asignación") y en el manual 01 (alcance por asignación).
  • Tipo de cambio: ADR-014 (§1, §2, §9 y Consequences; hay que ver si va addendum o ADR nuevo según cuánto cambie la tabla), manual 01-perfiles-y-menu.md (tabla del menú), 70-tipo-cambio.md (:7-8, :38-40: "el Cajero y el Supervisor pueden consultarlo"), funcional 02-roles-permisos.md (matriz 2.1), doc/architecture/matriz-de-perfiles.json, frontend/src/router/index.ts:372-374 (comentario), doc/environments/staging.md; regenerar los cuatro PDF con php artisan manual:generar-pdf y abrirlos.

Riesgos: la migración cambia permisos de usuarios reales de Staging en el momento del deploy: el cliente está probando; necesita tu OK y conviene avisarle antes (QC-17). Un seeder de usuarios de prueba mal corrido deja a los usuarios con la matriz vieja. Si el drift de Staging (H3-04) existe, hay que decidir celda por celda cuáles son política del cliente (G8.9). PerfilesMigrationTest falla si migrar() no encadena las dos migraciones (G8.2). El aviso opcional puede ser ruido si la mayoría de los usuarios tiene perfiles mezclados.


G9 — Cumplimiento, recibo A4 y PDV reales ​

Commits: G9. Branch feature/v3-cumplimiento-recibo-pdv. Esfuerzo M. Alcance: RV3-32, 87, 88, 89, 90, 91, 92, 93, 94, 95 (más H3-05). Depende de D3-17, D3-18, D3-22 y de QC-19 a QC-24. Pasa por security (G9.5 relaja la búsqueda de Pago, que es la regla anti-enumeración). ◐ Lo seguro se puede hacer ya.

Por qué. El cliente validó cuatro columnas de Cumplimiento y el prefijo del MTCN, contestó lo del quinto inciso del A4 y mandó los datos de los PDV. Todo cae en ReporteCumplimientoService, PapeletaService y los datos de las estaciones, y se resuelve con un solo commit de reporte más uno de recibo. El reporte lo lee un regulador: lo que no está confirmado no se adivina ("Sent" o "Send", idioma del Update).

#CapaQué
G9.1BackendCol. 24 (Payer Name): mapa por ISO en config/cumplimiento.php (payer_names => ['GT' => 'CIS Guatemala']), vacío si el país no tiene entrada (coherente con la regla del servicio de no inventar datos); el servicio lo resuelve con el país de la tx. Se retira CUMPLIMIENTO_PAYER_NAME. Agregar un país es una línea de config (P3-8)
G9.2BackendCol. 30 (Additional Notes): siempre null. Se borran notaAdicional(), motivosDeCancelacion(), la clave motivos del contexto y el import de AuditLog. Se mantiene el encabezado "Transaction Status-Additional Notes" (el test compara la lista de 36). Efecto: el reporte deja de leer audit_logs y de exportar texto libre que escribió un usuario; el motivo de una cancelación de Soterex deja de verse en el reporte (sigue en el detalle de la tx)
G9.3BackendCol. 21 (MTCN) con prefijo cumplimiento.mtcn_prefix (default C-, env CUMPLIMIENTO_MTCN_PREFIX; vacío lo apaga sin tocar código). Col. 22 (PIN) queda sin prefijo, como en la carta. No se toca el almacenamiento, la API, los recibos ni los extractos (D3-18)
G9.4BackendCol. 23 ("Sent" o "Send") y col. 29 (inglés o español): no se tocan hasta QC-19 y QC-20. Si la respuesta cambia el literal, es una constante y tres cadenas (ESTADOS, :89-93) con sus tests
G9.5Backend y frontendH3-05: la búsqueda de Pago acepta un prefijo opcional C (mayúscula o minúscula) seguido de guion o espacios y solo dígitos, y lo descarta antes de comparar (PagoController.php:94-98, mtcn.ts:15-18, PagoView.vue:166-172, y el filtro del listado en TransactionController.php:198-206). "C", "C-" y "Carlos" siguen siendo INVALID_MTCN (P3-9)
G9.6BackendRecibo A4 (RV3-94): se borra el quinto elemento de DECLARACION_A4 (PapeletaService.php:82); el A4 queda con los cuatro incisos de la tirilla. Opcional y no recomendado en este cambio: una constante única que consuman las dos plantillas (habría que probar que el texto renderizado de la tirilla no cambia)
G9.7DatosLos tres PDV (RV3-87, D3-17): por UI de un Admin (auditado como STATION_UPDATED / STATION_CREATED, valida que la ciudad cuelgue de la provincia y crea la caja): editar GT-CAP-001 y GT-QUE-002 con el nombre real, la dirección, el departamento y la ciudad sin cambiar el internal_code (lo usan StagingTestUsersSeeder, DemoTransactionSeeder y las asignaciones); crear Chimaltenango por UI y no por migración (un INSERT se saltea la caja y la auditoría) y asignarlo a los usuarios de prueba que lo necesiten. Direcciones literales, o corregidas solo con QC-22. Alternativa especificada, por si Carlos prefiere que el dato viaje con el deploy: migración idempotente que solo completa state, city y address vacíos de un PDV de Guatemala cuando exactamente uno contiene en el nombre (minúsculas, sin tildes) "ciudad de guatemala", "chimaltenango" o "quetzaltenango"; resuelve el catálogo por (país GT, tipo, code): STATE 01, 04, 09 y CITY 01-01, 04-01, 09-01; no crea PDV, no toca nombre ni active, tolera una base sin Guatemala. Su aporte en Staging es chico (dos PDV)
G9.8Datos✅ HECHO el 2026-10-07 por pedido de Carlos (no es producción y los datos son simulados), por migración de datos y no por la UI. Capital (RV3-88): renombrar la etiqueta del ítem CITY 01-01 a "Ciudad de Guatemala" por la UI de Catálogos solo con la respuesta de QC-23 (cambia también la ciudad del beneficiario en Cumplimiento y en el A4). Mientras tanto queda "Guatemala"
G9.9DocsVer abajo

Terminado cuando:

  • El Excel trae exactamente los 36 encabezados en el mismo orden (el test compara la lista entera); la col. 24 dice "CIS Guatemala" para Guatemala y sale vacía para un país sin entrada; la col. 30 sale vacía en los tres estados; la col. 21 trae "C-" y el número y la col. 22 solo el número; con el prefijo vacío sale el número crudo.
  • Buscar "C-5436014032", "c-5436014032" y "C 5436014032" encuentra la tx y se audita igual; "C", "C-" y "Carlos" dan 422.
  • El PDF A4 tiene cuatro incisos con el mismo texto que la tirilla, entra en una sola página con nombre y dirección largos y se abrió y se miró.
  • Los tres PDV reales tienen ciudad y departamento; el A4 y el Cumplimiento de un pago de prueba en cada uno muestran agencia y ciudad correctas.
  • (G9.8, ✅ hecho) La ciudad del primer PDV se llama "Ciudad de Guatemala" en el A4 y en el Cumplimiento de un pago de prueba de ese municipio; si no, queda "Guatemala".

Pruebas:

  • Backend: ReporteCumplimientoApiTest (default del payer en :774 pasa a "CIS Guatemala" y se agrega el caso sin entrada; las filas esperadas de los estados :760-764 que traen el código del PDV y el motivo; el caso de la columna 30 siempre vacía; col. 21 con y sin prefijo y col. 22 sin él; las lecturas con array_column(..., 20) de :807, :821, :838-843); el test de consultas sin N+1 (:1354-1393) sigue verde. PagoApiTest (los casos de arriba, junto a :84-108).
  • PapeletaFormatosTest: se borran QUINTO_INCISO (:53) y el test de :817-834; nuevo: cuatro incisos, <b>(iv)</b> dos veces, ningún (v), texto idéntico al de la tirilla. Ojo con los tests de densidad (:342-402): el caso de dirección larga que debe desbordar con la letra normal y la cota sobraMm < 30 dependen de la altura de la declaración; sin el quinto inciso cada copia gana unas líneas y puede que el fixture deje de desbordar. No determinado: hay que correrlos y recalibrar.
  • Frontend: mtcn.spec.ts (acepta "C-8834201992", rechaza "C-" y "Carlos").
  • Manual en Staging: bajar el A4 y el Cumplimiento con datos de demo; abrirlos en Excel.

Docs a actualizar: manual 61-reportes-cumplimiento.md (tabla de las cuatro columnas y del prefijo), 83-admin-estaciones.md, 10-pago.md (búsqueda con "C-"; A4 con cuatro incisos), 20-transacciones.md (:60), 82-admin-paises.md (:21); funcional de pago 03-papeleta.md (:98, :203, :233-241 "cinco incisos"), 04-preguntas-abiertas.md (#13 y :258-259, que afirma que el MTCN se tolera con "C-"; hoy no es cierto), 01-flujo-del-pago.md; funcional general 05-secuencias-pantalla.md (:315); plan v2 (B4 filas 21-30, B5.3, P9(d), §7 #3 y #6); doc/environments/staging.md (correr StationSeeder a mano en Staging revierte nombre, dirección y ubicación: es updateOrCreate); doc/integracion/2026-09-30-soterex-staging.md (las preguntas a Sean).

Riesgos: un archivo que lee un regulador: no adivinar la grafía de "Send/Sent" ni el prefijo (por eso va por configuración). Imprimir "C-" si Soterex no lo usa, o no imprimirlo si lo usa, son dos errores. Renombrar un PDV cambia cómo se reimprimen recibos viejos y los reportes históricos, porque leen el nombre vigente. El A4 sin el quinto inciso puede desbordar o dejar de desbordar los tests de densidad. Mixco Plaza y Escuintla Norte no están en la lista del cliente: no usarlos como los reales.


G10 — Catálogo de países de Cumplimiento ​

Commits: G10. Branch feature/v3-lista-de-paises. Esfuerzo M. Alcance: RV3-75, 76, 77, 78, 86 (más H3-07). Depende de D3-16 y QC-26 a QC-29. ◐ Los 23 renombres se pueden hacer ya; los casos dudosos esperan QC-27. Cierra B1.5 para países y tipos de ID (departamentos y municipios siguen sin validar, QC-29).

Por qué. El cliente mandó su lista de 255 países y esa lista alimenta una columna de un reporte regulatorio. El diff contra nuestros 249 ítems ISO (emparejados por código; el cliente no manda códigos y el mapeo nombre→código lo hice a mano; la única lectura realmente dudosa es #216) da: 225 etiquetas idénticas, 23 con otro nombre, 2 con código que no tenemos (Kosovo, Antillas Holandesas), 3 sin código ISO (Chipre del Norte, Irlanda del Norte, Somalilandia), una entrada que no se sabe qué es (#216 "Santo Tomas": Santo Tomé y Príncipe ya viene aparte, #196), Timor Oriental repetido (#228 y #229) y Antártida, que está en la norma y no en su lista. Las etiquetas se resuelven al imprimir (EtiquetasDeCatalogo), así que el renombre es retroactivo en reimpresiones del A4 y en reexports; los códigos guardados en las transacciones no cambian, por eso no hay migración de transacciones. El encabezado de la hoja (Global Country Values, #, Translation - Spanish) sugiere un picklist exportado, quizá el de Soterex o su Salesforce: no determinado, se pregunta (S-5).

Los 23 nombres que difieren (código: nuestro → cliente):

Cód.HoyClienteCód.HoyCliente
AXÅlandIslas AlandNFIsla NorfolkIsla de Norfolk
BNBrunéiBrunéi DarussalamNLPaíses BajosHolanda
BQBonaire, San Eustaquio y SabaBonairePNIslas PitcairnPitcairn
CGRepública del CongoCongoQACatarQatar
CZChequiaRepública ChecaREReuniónIsla Reunión
FKIslas MalvinasIslas Falkland (Malvinas)SHSanta Elena, Ascensión y Tristán de AcuñaSanta Elena
GSGeorgia del Sur y las Islas Sandwich del SurIslas Georgias del Sur y Sándwich del SurSXSint Maarten (parte neerlandesa)San Maarten
KGKirguistánRepública KirguisaSZEsuatiniSuazilandia
KPCorea del NorteCorea, República Popular Democratica deTFTerritorios Australes FrancesesTerritorios Meridionales Franceses
KRCorea del SurCorea, República deUMIslas Ultramarinas Menores de Estados UnidosIslas Ultramarinas Menores de los Estados Unidos
MFSan Martín (parte francesa)San MartínVIIslas Vírgenes de los Estados UnidosIslas Vírgenes (EE.UU.)
MKMacedonia del NorteMacedonia

Dos nombres del cliente no llevan tilde: #119 "Democratica" y #216 "Santo Tomas".

#CapaQué
G10.1DatosArchivo nuevo database/data/catalogo_paises_cumplimiento.php con la lista final código → etiqueta, la sección renombres (código → [desde, hasta]) y la sección internos documentada. No se toca catalogo_paises_iso.php: es la entrada de B1.2 ("no se reabre") y sus tests fijan 249
G10.2DatosHelper EnsureCatalogLabels::renombrar(?countryId, type, renombres): UPDATE solo donde label es la sembrada (P3-10). Migración de datos nueva con el mismo guard de B1.2 (sin países operativos no hace nada): EnsureCatalogItems::ensure crea lo que falta + los 23 renombres + la etiqueta del DPI alineada con la del cliente (RV3-78) si sigue siendo la sembrada. Sin down(), como B1.2. No desactiva nada (Antártida queda; la desactiva un Admin si el cliente confirma)
G10.3DatosDudosos (D3-16): se crean XK y AN con su código; Timor una sola vez; los 3 sin código ISO se cargan con un código interno de 2 letras del rango que ISO reserva para uso del usuario (XA a XZ), documentado como "interno, no ISO", solo con la respuesta de QC-27; #216 no se carga hasta saber qué es. El orden no se mantiene (QC-28): el combo sigue alfabético por etiqueta
G10.4BackendH3-07: el ABM limita el código de un ítem COUNTRY a 2 letras mayúsculas (CatalogItemController.php:171, 199); hoy acepta hasta 20 y el pago exige size:2
G10.5BackendCatalogCountrySeeder (dev) pasa a leer el archivo nuevo; ajustar DatosDeReferenciaMigrationTest.php:320-345 ("los seeders parten del mismo dato que la migración")
G10.6FrontendCatalogosView.vue:28, 242: el tipo se llama "País de la identificación" (deja de decir "ISO 3166-1" porque ya hay valores no ISO)
G10.7DocsVer abajo

Terminado cuando:

  • Sobre una base con la precarga de B1.2, la migración deja los 23 renombres, crea XK y AN, no duplica Timor y no desactiva nada; un ítem cuya etiqueta el Admin ya editó, o que está desactivado, no se toca; correrla dos veces no cambia nada; los códigos no cambian.
  • Sin países operativos (base vacía) la migración no hace nada y no falla.
  • Un ítem COUNTRY con código de 3 letras da 422 en el ABM y "XK" se acepta.
  • Reimprimir el A4 de una tx con país "Islas Ultramarinas Menores de los Estados Unidos" (48 caracteres) entra en la celda del 32% (abrirlo); el Excel de Cumplimiento trae los nombres nuevos en las columnas 9 y 11.

Pruebas: PaisesDeCumplimientoMigrationTest nuevo (todo lo anterior), CatalogItemApiTest (código de 2 letras; el combo ordena por etiqueta), DatosDeReferenciaMigrationTest ajustado, ReporteCumplimientoApiTest y PapeletaFormatosTest siguen verdes (ninguno fija nombres que cambian). Manual en Staging: select count(*) de COUNTRY activos y spot-check de cinco etiquetas; elegir "Kosovo" en un pago de prueba y guardar.

Docs a actualizar: manual 85-admin-catalogos.md (la lista del cliente; el renombre de una etiqueta es retroactivo en reimpresiones y reexports), 61-reportes-cumplimiento.md; funcional de pago 03-papeleta.md; plan v2 B1.5 (cerrada para países); README de la carpeta de referencia.

Riesgos: retroactividad de las etiquetas (cambia el texto del país, no el país). Códigos internos XA-XZ que algún día chocarían con los que ISO o Soterex asignen (por eso se documentan). Cargar entidades dudosas (Somalilandia, Chipre del Norte) en un reporte regulatorio es una decisión de Cumplimiento, no nuestra. El orden de los desplegables depende del collation de la base: en dev es en_US.utf8 y el Terraform no lo fija (en Aurora, no determinado). Una migración de datos que corre en el deploy: si falla, corta el deploy (las migraciones esperan la base, PR #75); es idempotente y tolera una base incompleta.


G11 — Formato del documento de identidad ​

Commits: G11. Branch feature/v3-formato-de-identificacion, apilado sobre G10 (mismo ABM y mismo estilo de migración). Esfuerzo L. Alcance: RV3-79, 80, 81, 82, 86. ⏸ Depende de D3-15 (ADR) y de QC-30. Pasa por security (un Admin edita reglas que cambian qué puede pagar un Cajero).

Por qué. El cliente define para cada tipo de ID un formato y un país emisor que la herramienta debe respetar al cargar el pago. Hoy no existe ninguna regla (identification_number es nullable|string|max:60; identification_country solo size:2 y que exista). El Admin crea los tipos de ID desde el ABM, así que si la regla viviera en el código por code, un tipo nuevo o un código editado quedaría sin validar en silencio.

TipoFormatoPaís emisor
DPI13 caracteres, solo númerosGT siempre
Pasaportede 7 a 13 caracteres, letras y númeroscualquiera (sin país fijo)
#CapaQué
G11.1DatosMigración de esquema: cuatro columnas nullable en catalog_items, solo con sentido para ID_TYPE (un CHECK las limita): id_charset (numeric o alphanumeric o null = cualquiera), id_min_length, id_max_length, id_issuing_country (char(2), null = cualquier país). Nada de regex libre que escriba el Admin (riesgo de ReDoS y de reglas que rompen el pago): la regex la arma el backend a partir de esos campos
G11.2DatosMigración de datos: DPI = numérico 13/13, emisor GT; Pasaporte = alfanumérico 7/13, sin emisor. Solo si sus cuatro columnas están en null (no pisa lo editado). La siembra de dev suma una sección reglas_de_identificacion en catalogo_guatemala.php sin cambiar el formato de tipos_identificacion (la migración de B1.2 lo lee como código → etiqueta y se rompería)
G11.3BackendRegla App\Rules\FormatoDeIdentificacion aplicada en paymentDataRules (TransactionController.php:898-915) a identification_number y identification_country. Resuelve el tipo efectivo (el del request o, si no viene, el guardado: el mismo patrón que $estadoEfectivo, :853-860) contra el ítem activo del país de la tx. Sin tipo resoluble o sin reglas, no valida (D9: los datos viejos quedan como están). Mensajes en español armados en el propio $fail() y sin el valor tipeado (ADR-016). pay() ya reusa las reglas. PAID/CANCELLED responden 409 antes de validar (:727)
G11.4Backend/catalogos devuelve las cuatro columnas para que el frontend no duplique la regla. ABM (CatalogItemController.php:60, 171, 199): min <= max, país emisor existente y activo, rechazo si el ítem no es ID_TYPE, y CATALOG_ITEM_UPDATED suma los cuatro campos (no son datos personales)
G11.5FrontendDatosPagoForm.vue (:229-230, :398-415, :437-441): DPI → el país se completa con Guatemala y se bloquea con la nota "El DPI lo emite Guatemala"; al pasar a Pasaporte se desbloquea y conserva el valor; el número quita espacios y guiones al tipear o pegar (2999 99999 0101 queda 2999999990101), inputmode numérico, maxlength; aviso en línea bajo el campo y "Guardar datos" bloqueado mientras no cumpla (mismo patrón que fechaNacimientoInvalida, :257-262). Mensajes: "El número de DPI tiene que tener 13 dígitos, solo números." / "El número de pasaporte tiene que tener entre 7 y 13 caracteres, solo letras y números."
G11.6FrontendDatos viejos (CAT-12): una ACCEPTED con un número ya guardado que no cumple muestra el aviso apenas se abre el formulario y "Iniciar pago" queda deshabilitado con el motivo escrito (el formulario emite el estado al padre, como ya hace con sinGuardar, PagoView.vue:106-135). CatalogosView.vue: columna "Formato" y editor para ID_TYPE (caracteres permitidos, mínimo, máximo, país emisor). DemoTransactionSeeder.php:373-375 genera datos que el sistema aceptaría
G11.7DocsVer abajo

Terminado cuando:

  • DPI: 13 dígitos pasa y se conserva un cero a la izquierda (0123456789012); 12, 14, letras, espacios o guiones dan 422; DPI con país distinto de GT da 422. Pasaporte: 7 a 13 alfanuméricos pasa; 6 y 14 dan 422; Pasaporte con cualquier país pasa.
  • El mensaje de error no contiene el valor tipeado; la auditoría tampoco.
  • Una PAID vieja con un número fuera de formato sigue exportando en Cumplimiento sin error y datosPago() le responde 409. Una ACCEPTED con número viejo falla pay() con 422 y mensaje.
  • El Admin edita la regla de un tipo desde Catálogos y el cambio se ve en el siguiente pago; un tipo nuevo sin reglas no valida.

Pruebas: FormatoIdentificacionApiTest nuevo (tipo con reglas valida; sin reglas o inactivo o texto libre viejo no valida; guardado parcial usa el tipo guardado; pay() 422; PAID/CANCELLED 409 antes de validar); CatalogItemApiTest (alta y edición de ID_TYPE con reglas, min > max rechazado, país emisor inexistente rechazado, reglas sobre un ítem que no es ID_TYPE rechazadas); migración (setea DPI y Pasaporte, no pisa reglas editadas, idempotente, ignora un GT inexistente); DatosPagoForm.spec.ts, PagoView.spec.ts, CatalogosView.spec.ts, catalogos.spec.ts. Manual en Staging: pago de prueba con DPI de 12 dígitos (bloquea) y de 13 (paga).

Docs a actualizar: ADR nuevo "Las reglas de formato del documento de identidad viven en el catálogo" (provisorio ADR-019) y nota en ADR-011; funcional de pago 02-datos-y-documentos.md (L27-29); manual 85-admin-catalogos.md y 10-pago.md; QA nuevo; la consulta de solo lectura 8 de G0.6 (cuántos pagos viejos quedan fuera de formato).

Riesgos: es la pieza más grande de la porción de catálogos. Rechazar un pago por un formato demasiado estricto frena el mostrador (mitigado: reglas editables y auditadas). Si el front y el back derivaran la regla por separado se desalinearían (mitigado: el front lee las columnas del combo). Si un Admin desactiva GT en la lista de países, ningún DPI se puede guardar. Estricto sin separadores: si el cliente quería aceptar 2999 99999 0101 tal cual, la regla literal lo rechaza (la ayuda del front lo mitiga). No se valida el dígito verificador del DPI: no lo pidieron. Los pagos ya hechos con un número fuera de formato seguirán saliendo así en Cumplimiento (inmutables, ADR-011). Si la decisión D3-5 resulta en un catálogo con atributos por ítem, las columnas por tipo no escalan: evaluar jsonb una sola vez para los dos casos.


G12 — Tesorería: alcance, saldo de la Holding y rótulos ​

Commits: G12. Branch feature/v3-tesoreria-alcance. Esfuerzo M. Alcance: RV3-48, 55, 58, 66, 67, 72, 73, 85, 97 (más H3-10 y H3-11). Depende de D3-19 y QC-32; RV3-67 ⏸ espera QC-33. Es la entrega que aplica D3-T1. Pasa por security (cambia qué porción de la Holding y qué saldo ve quien lee un solo país).

Por qué. Con un solo perfil (D3-T1), "CIS Guatemala solo su estado de cuenta" se cumple por la asignación para País y PDV, pero una Tesorería de un solo país ve también la porción de su país de los extractos de la Holding y la tarjeta global. Esto ya pasa hoy en Staging: la base tiene El Salvador (sembrado inactivo; aparece en el selector de países de Catálogos, img 30) y partial se calcula contra todas las filas de countries, así que una Tesorería asignada solo a Guatemala recibe partial = true desde ahora (H3-10, confianza alta). Lo que todavía no pasa es que algún usuario real tenga alcance parcial: la Tesorería de Staging no existe hasta que Carlos corra StagingTestUsersSeeder.

#CapaQué
G12.1BackendTarjeta (H3-11, D3-19 b): PrefundingController::index (:63-66) devuelve, cuando el usuario no lee todos los países (la misma condición de partial de los extractos, extraída a PermissionService o PrefundingService para que haya una sola), PrefundingService::balanceForCountries($sus países) más un indicador de alcance parcial. Con todos los países no cambia nada
G12.2Backendpartial (H3-10): se calcula contra los países activos más los que tengan movimientos, no contra todas las filas de countries (TreasuryStatementController.php:297); así el extracto global sigue coincidiendo con globalBalance() y un país inactivo sembrado no vuelve "parcial" al regional
G12.3Backend(Opcional, RV3-66) en el encabezado de la pestaña CIS Holding, "de los cuales comisiones: N" (suma de las líneas PAYMENT_FEE); en el test de la planilla, afirmar total_debit de PDV1 y PDV2 (3.500 y 14.000) y la suma de comisiones (208)
G12.4FrontendPrefondeoView.vue:97-112: rótulo "Saldo de la Holding — de sus países" y se quita "De todos los países juntos" cuando el alcance es parcial; texto del paso 1 del recorrido (tours/prefondeo.ts) sin mover el data-tour. Rótulos que el cliente va a comparar con su hoja: la tarjeta pasa a "Saldo con Soterex" (su "SALDO FINAL CON SOTEREX"); el export del extracto País se titula "Extracto — Fondeo PDVs · País (disponible para distribuir)" (hoy dice "Prefondeo País", TreasuryStatementController.php:61); el encabezado del extracto País dice "CIS país"; se aclara qué incluye el "Monto actual" de CIS Holding. ExtractoTesoreria.vue (TEXTOS)
G12.5TestsNuevos en TreasuryStatementApiTest: Tesorería de GT con EC existente recibe balance == balance(GT) y el indicador; Tesorería de ambos recibe globalBalance; un país inactivo sin movimientos no vuelve parcial el extracto, uno con asientos sí; Tesorería de un solo país ve País y PDV completos y la Holding parcial; el Escenario 2 bloque B (7.287 / 25.000 → 0 / 7.500 / 1.500 / 6.000) cargado con las mismas capas (opcional: es contenido oculto del cliente, no sale de un requisito). En PrefundingApiTest: una Tesorería de un solo país no puede cargar un asiento de Holding en otro país (el chequeo existe en PrefundingController.php:85; falta el test)
G12.6DocsVer abajo. Incluye: "cargá el monto que envió o notificó el nivel de arriba, no el que acreditó el banco: el costo bancario queda fuera del sistema" (RV3-58)
—No se haceNo se agrega una etiqueta "Regional / Local" derivada en la ficha de usuario: inventa un concepto que no existe en el modelo (D3-T1). Si el cliente la pide, es solo lectura calculada de las asignaciones

Terminado cuando:

  • Una Tesorería asignada solo a Guatemala, en una base con Ecuador y movimientos en los dos países, ve País y PDV completos de Guatemala, las pestañas de la Holding con el aviso "parcial" y la tarjeta con el saldo de Guatemala y el rótulo nuevo; una asignada a GT y EC ve la tarjeta global sin aviso.
  • La Tesorería de GT recibe 403 al intentar cargar en Ecuador y al pedir el extracto de País de Ecuador.
  • Con la base de Staging (Guatemala activa; El Salvador y Honduras sembrados inactivos y sin movimientos), esa Tesorería ve la Holding sin aviso de parcial; con un país inactivo que tiene asientos, sí (G12.2).
  • (Opcional, G12.3) El encabezado de CIS Holding muestra "de los cuales comisiones: 208" con los números de la planilla, y el test de la planilla afirma 3.500, 14.000 y 208.
  • Los títulos y rótulos de la lista coinciden con su hoja.

Docs a actualizar:

  • D3-T1: doc/architecture/ADR-014-… §1 (nota), ADR-015 §5 (nota: con alcance parcial la tarjeta muestra el saldo de sus países; ya no es cierto que sea global para todos) y Consequences, ADR-007 §1 (Actualización fechada: revierte en parte "el saldo que se muestra es la suma global de todos los países", D3-19 b); funcional 02-roles-permisos.md (una tabla "quién ve qué extracto" con las cuatro filas de la hoja), 01-modelo-de-saldos.md 1.10 ("quién ve cada extracto"); manual 01-perfiles-y-menu.md, 40-prefondeo.md ("Si su usuario ve solo algunos países": una Tesorería de todos los países ve la Holding completa y al dar de alta un país hay que sumárselo; cargar el monto notificado), 41-prefondeo-pais.md.
  • 06-preguntas-abiertas-caja.md §6.3: 18 y 19 resueltas para Guatemala y 16 por defecto; 17, 20 y 21 abiertas. Los números del ejemplo (32.292 / 20.208 / 7.000 / 1.500 / 4.000 y 12.500) repetidos en 01-modelo-de-saldos.md §1.10 y ADR-015 §3 no tienen test que los compare con el texto: no cambian.
  • QA nuevo (no existe ninguno de los extractos).

Riesgos: medio-bajo. Cambia un número que hoy ven los usuarios con alcance parcial y revierte en parte una decisión consciente de ADR-015. La opción (c) de D3-19 revertiría ADR-015 §5 y rompería el caso legítimo de dos países de tres. Qué es el 32.708 (RV3-67) no se decide leyendo: 32.708 = F + Fe − Ap supera en 208 a la plata física que queda; si Teresa lo quiere en pantalla, es una línea derivada en el encabezado de CIS Holding con rótulo propio (nunca una fila del saldo corrido), y si es un doble conteo el número correcto sería 32.500.


G13 — Tesorería: reposición al 30% y confirmaciones de recepción ​

Commits: G13. Branch feature/v3-tesoreria-reposicion-y-confirmacion, apilado sobre G12. Esfuerzo L. Alcance: RV3-60, 62, 64, 68. ⏸ No se puede empezar: depende de QC-34 a QC-39, D3-20, D3-21 y D3-26. Pasa por security (G13.B: endpoints de escritura con permisos y alcance por PDV y país). Tres bloques que comparten ADR: A y B son independientes entre sí; C reusa la base de A.

Por qué. Los pasos 2, 4 y 6 del flujo (confirmar la recepción en cada nivel) y el paso 8 (alerta cuando el saldo prefondeado llega al 30%, con el % parametrizable) no tienen ninguna pieza en el código. La alerta ya estuvo planificada y se sacó de alcance en el plan v2 §6; ahora la hoja la repite con el parámetro explícito. El diseño tiene que respetar P3-7: marca y cálculo al leer, nunca estado ni saldo guardado, y no condiciona pagar ni cerrar la caja. Es la única lectura compatible con ADR-007 §2-3 y con que Ecuador (sin Caja) valide el pago contra el saldo del país. Y tiene que ser neutral al escenario (D3-26): los niveles País y PDV son idénticos en los dos, y el nivel "cuenta con Soterex" queda en una sola función.

G13.A — Alerta de reposición (L)

#CapaQué
G13.A1Datos y backendSingleton treasury_settings con replenishment_threshold_pct (default 30), mismo patrón que SessionSetting / SessionSettingController y la pantalla Configuración (abm_configuracion, solo Admin; si Tesorería tiene que editarlo, el endpoint se gatea con prefondeo:write y el campo se muestra también en Prefondeo Soterex, y no se le da abm_configuracion: D3-21), validación 0 < pct < 100, auditado con TREASURY_SETTINGS_UPDATED (metadata: el porcentaje). No va en SoterexSetting (es la fila de la integración) ni por país o PDV (el cliente pide un porcentaje y el nivel Holding no tiene país)
G13.A2BackendServicio de alertas calculadas al leer: por nivel, entidad, saldo, base, porcentaje y si está en alerta. Soterex↔Holding: saldo = globalBalance(), base = el último asiento de prefunding_entries; lo ve quien tiene prefondeo:read en todos los países. País: saldo contable = CountryPrefundingService::balance() (el "SALDO FINAL CIS GUATEMALA" de la planilla, no el disponible, que cae al repartir sin que nadie lo vea como falta de plata), base = el último asiento del país; prefondeo_pais:read sin acotar. PDV: saldo = Σ CashBoxService::balance de sus cajas, base = el último FONDEO; fondeo_caja:read con su alcance (Supervisor, Tesorería, Admin; no el Cajero). Condición saldo <= umbral × base en centavos enteros (RunningBalance), inclusiva, porque la planilla marca como alerta el 30,0% exacto. Sin ingresos no hay alerta; un ingreso nuevo la apaga solo
G13.A3BackendGET /tesoreria/alertas-reposicion, cada nivel filtrado por permisos y alcance: no expone nada que el usuario no vea ya en su extracto
G13.A4FrontendFranja ámbar (mismo estilo del banner de ExtractoTesoreria.vue:307-313 y de fondeoWarning) arriba de Prefondeo Soterex, de Fondeo PDVs → País (con la lista de PDV en alerta y link a su extracto) y en las tarjetas de totales por PDV de Saldos. "Solicitar" es la propia alerta: la hoja dice "enviar alerta de pedido", no un workflow de pedido y aprobación. Campo en Configuración (ConfiguracionView.vue)
—FueraMail o push, scheduler, umbral distinto por nivel o entidad, alerta en el Dashboard, estado de solicitud

G13.B — Confirmaciones de recepción (M)

#CapaQué
G13.B1Datos y backendTabla append-only treasury_receipts (receivable_type, receivable_id, confirmed_by, confirmed_at, nota opcional sin montos; UNIQUE por asiento): sin UPDATE sobre el asiento (el ledger es inmutable)
G13.B2BackendPaís: POST /prefondeo-pais/{entry}/confirmar con prefondeo_pais:write en ese país (sin asignación acotada por PDV). PDV: POST /caja/movimientos/{id}/confirmar con caja:write y alcance de estación (Cajero, su caja; Supervisor, las de su PDV; Admin). Tesorería, que es quien fondea, no puede confirmar: la separación sale de la matriz sin cambiarla. 409 si ya estaba confirmado
G13.B3BackendLos extractos suman a la fila del asiento receipt: pending / confirmed / self_confirmed y la fecha, sin el mail de quien confirma (igual que "Cargado por", ADR-015 §7). self_confirmed = confirmó quien cargó el asiento: se muestra, no se bloquea (D3-20). Auditoría PREFUNDING_RECEIPT_CONFIRMED con ids, sin montos. No cambia ningún saldo ni valida nada; el test de claves permitidas de B7.4 se actualiza a propósito para aceptar receipt y nada más
G13.B4FrontendChip "Pendiente de confirmar" (con antigüedad) en la pestaña País y su espejo en CIS Holding; botón "Confirmar recepción"; en Saldos, "Fondeos por confirmar" junto a las tarjetas de totales por PDV. Un clic; nunca condiciona pagar ni cerrar la caja (el cierre ya bloquea por documentos pendientes: no sumar otro bloqueo)

G13.C — Columna de porcentaje en los extractos (S, solo si QC-39 = sí)

#CapaQué
G13.C1Backend y frontendColumna "% del último ingreso" en cada estado de cuenta, derivada y de solo lectura: saldo corrido ÷ la base de G13.A2 (mismo cálculo, mismos centavos enteros), vacía si la entidad no tiene ingresos. Es lo que muestra el ejemplo del cliente (columnas D, I, M, R y W del Escenario 1, visibles), pero con una sola definición en vez de cinco: las del ejemplo miden consumo en unas columnas y distribución en otras. No cambia ningún saldo ni valida nada; el test de claves permitidas de B7.4 se actualiza para aceptar el campo. Depende de QC-34 (la base)

Terminado cuando: (A) con los números de la planilla el PDV1 entra en alerta tras el pago 2 (1.500 sobre 5.000 = 30% exacto), el PDV2 tras el pago 9 (22%) y no en el pago 7 (47%); el país (12.500 sobre 30.000) y la Holding (32.292 sobre 50.000) no alertan; cambiar el umbral a 50 cambia el resultado; un segundo ingreso apaga la alerta; la Tesorería de un solo país no ve el nivel Holding; el endpoint no escribe en ningún ledger (mismo conteo de filas antes y después). (B) Confirma con permiso y país correctos; 403 sin prefondeo_pais:write o con asignación acotada por PDV; el Cajero confirma el fondeo de su caja y no el de la de otro; Tesorería recibe 403 en el de PDV; confirmar no cambia balance(), availableToDistribute() ni los extractos cerrados (los tests de la planilla de B7 siguen verdes). (C) Con los números de la planilla, la columna de PDV1 muestra 100 %, 80 % y 30 % (tras el pago 2) y la de PDV2 baja hasta 22 %, con la misma base que la alerta; no cambia ningún saldo.

Pruebas: test nuevo de alertas (reproduce el Escenario 1; permisos y alcance; país en moneda local; entidad sin ingresos); SessionSettingApiTest como modelo del parámetro; PrefondeoView.spec.ts, PrefondeoPaisView.spec.ts, CajaView.spec.ts, spec de Configuración; ExtractoTesoreria.spec.ts (incluida la columna de G13.C, con los números de la planilla). Manual en Staging: demo:reseed deja saldos bajos y se baja el umbral para verla; cargar un envío a GT con un usuario y confirmarlo con otro.

Docs a actualizar: ADR nuevo "Reposición y confirmaciones de tesorería" (provisorio ADR-020), ADR-010 (aclarar que son otra familia que el aviso de sobrerreparto); funcional de Caja 01-modelo-de-saldos.md (nueva 1.11), 02-flujos-caja.md, 05-ux-multiples-cajas-y-fondeo.md, 06-preguntas-abiertas-caja.md (#23 en adelante), funcional general 03-user-flows.md (3.4); manual 40-prefondeo.md, 41-prefondeo-pais.md, 30-caja.md, 32-caja-fondeo.md, 84-admin-configuracion.md; plan v2 §6 (la alerta deja de estar fuera de alcance); texto del recorrido de Prefondeo; QA nuevo.

Riesgos: (1) La base: con "último ingreso" una recarga chica deja la alerta dormida (falso negativo, el error caro); la planilla tiene un solo ingreso por entidad y no lo resuelve (QC-34). (2) Alertar sobre el disponible del país prendería la alerta cada vez que se reparte: por eso el saldo contable. (3) Sin mail, la alerta solo se ve si alguien abre la pantalla: puede no alcanzar para el cliente. (4) Fricción en el mostrador: en agosto Diego descartó la firma del Supervisor al abrir caja porque agregaba un paso sin trazabilidad (ADR-007); con un solo perfil de Tesorería (D3-T1), quien envía y quien recibe pueden ser la misma persona del equipo regional y la confirmación aporta poco. (5) Si el cliente elige el Escenario 2 después de esto, el diseño neutral limita el retrabajo a una función. (6) Implementar la confirmación como columna con UPDATE rompería la inmutabilidad del ledger. (7) La rama "Soterex notifica por API" del paso 2 no existe mientras Soterex no conteste D3-22 (1): hasta entonces la "recepción" de la Holding es la propia carga del asiento y G13 no agrega un control ahí (RV3-57). (8) La alerta por PDV recorre cajas y movimientos de todos los PDV del alcance cada vez que se abre una pantalla: sin caché, hay que fijar el costo con un test de conteo de consultas como el que ya tiene B7, antes de que Guatemala tenga decenas de PDV. (9) No confundir con el aviso de sobrerreparto de ADR-010 (el "F2" del plan de estabilización del 2026-09-13), que sigue sin ejecutarse y es otra familia de avisos: G13 no lo toca.

Dependencias. QC-34 a QC-39, D3-20, D3-21 y D3-26 (todas con default, ver §6); G12 mergeado (misma pantalla y mismo ADR). El bloque A y el B se pueden entregar por separado; C va después de A. Esfuerzo: L en total (A: L, B: M, C: S).


5. Documentación y flujos a corregir ​

Una entrega no está terminada si su documentación no está al día: va en los mismos commits que el código, no en un pase al final (misma regla del plan v2). Esta sección junta lo que cada entrega ya lista en §4 por módulo, con la ruta real (todas se verificaron con ls el 2026-10-04; las referencias a línea son de ese día), y agrega lo transversal: diagramas, ADR, recorridos guiados, QA, referencia de API y los tests que atan la documentación al código. Si §4 y §5 difieren, manda §5: §4 lista lo principal de cada entrega y esta sección es la lista completa por documento.

Reglas de la casa que valen para todo lo que sigue

  • Los análisis funcionales no se reescriben: banner fechado en el encabezado y texto tachado (~~…~~) donde cambia una regla. Así están 01-flujo-del-pago.md, 02-datos-y-documentos.md y 03-user-flows.md.
  • Los ADR no se reescriben: una Actualización fechada dentro del ADR (precedente: ADR-011 tiene tres) o un ADR nuevo que marca al viejo como reemplazado en parte. Todo ADR nuevo entra al índice doc/architecture/index.md.
  • Los planes de QA anteriores se marcan históricos (§5.5), no se corrigen.
  • doc/ se publica entero en el sitio salvo site/**, README.md y **/reference/** (doc/.vitepress/config.mts:50) y no hay autenticación en el sitio: cualquier documento nuevo en plans/ o qa/ queda público. Ningún dato personal (§7, R-9).
  • Antes de abrir cada PR con documentación: npm run docs:build en doc/ (un link roto corta el deploy del sitio; el CI de los PR no lo corre hasta que G0.8 sume el job docs, §5.7) y abrir en npm run docs:dev toda página cuyo Mermaid cambió (el build no valida su sintaxis).
  • Los nombres de pantalla y de perfil están copiados a mano en muchos lugares: al tocar uno, el mismo PR actualiza AppLayout.vue (NAV y MOBILE_LABELS), PermissionModules::LABELS, el titulo del manual, los asserts por título de ManualPdfTest y el texto de los tours. Claves de módulo, name de ruta y data-tour no cambian (ADR-014 §9, P3-12).

5.1 Tabla por módulo ​

Primera columna: la pantalla o el tema. F-pago = doc/functional/2026-08-07-pago-con-documentos/; F-gral = doc/functional/2026-07-24-soterex-integracion/; F-caja = doc/functional/2026-08-05-modulo-caja/. Los números de línea (L…) son de los archivos de esa fecha.

MóduloDocumento (ruta real)Qué se corrigeEntrega
PagoF-pago/00-resumen.mdAlcance (L48): el medio de pago pasa de "efectivo o transferencia" a solo efectivo, con las PAID viejas como historia de solo lectura; regla R6 (L96) y R8 (L98): "reemplazarlo es subir otro" se parte en subir lo que falta y reemplazar uno cargado (P3-1)G3 · G5
PagoF-pago/01-flujo-del-pago.md§1.4 (qué bloquea el pago y qué no: medio de pago, reemplazo) y §1.6 (permisos y alcance: excepción del pagador, quién reemplaza); Mermaid 1.1 (L17) y 1.5 (L197)G2 · G3 · G5
PagoF-pago/02-datos-y-documentos.md2.1 (medio de pago; formato de DPI y Pasaporte, L27-29); 2.5 punto 2 (reemplazo) y punto 4 (almacenamiento: dice S3 privado y hoy es disco local; banner de lo que nunca se hizo); 2.6 (formatos y tamaño); 2.7 (cómo se ve una tx de otro PDV y "subido por")G1 · G2 · G3 · G5 · G11
PagoF-pago/03-papeleta.md3.1 y Mermaid L59 (de "Descargar en otro formato" a dos botones); declaración del A4 de cinco a cuatro incisos, con el texto de L98, L203 y L233-241 tachado (revierte B5.3); alcance del pagadorG2 · G5 · G9
PagoF-pago/04-preguntas-abiertas.md#3 (transferencia): cerrar; #9 (L258-259, "tolerando el prefijo C-"): aclarar que la verificación se sacó y que la búsqueda lo tolera desde G9.5; #13 (columnas del reporte): las cuatro validadas el 2026-10-02; #1 (Transacción fija) sigue abierta (QC-24)G3 · G9
PagoF-gral/03-user-flows.md3.2 (Mermaid L82: confirmar pago sin transferencia), 3.8 (L359: búsqueda con prefijo "C-"), 3.9.1 (L413: día del Cajero, sin el grupo Tesorería)G3 · G8 · G9
PagoF-gral/04-diagramas-actividad.md4.2 (secuencia pago Cajero → WebApp → Soterex, L94): sin transferenciaG3
PagoF-gral/05-secuencias-pantalla.md5.8 (L342, Mermaid L348: qué comprueba cada capa): 403 CANNOT_REPLACE_DOCUMENTS, 422 por TRANSFERENCIA, excepción del pagador; 5.7 (L242 y :315): CumplimientoG2 · G3 · G5 · G9
Pagodoc/manual/10-pago.mdFormatos y tamaño aceptados y qué pasa si un archivo no se encuentra (G1); qué pasa con una tx de otro PDV (G2); medio de pago solo efectivo (L49-50, L101-107, L178, L191) (G3); "Después del pago" e "Imprimir la papeleta" con dos botones (L201-257) y sección nueva "Corregir un documento mal cargado" para Supervisor y Admin (G5); búsqueda con "C-" y A4 de cuatro incisos (G9); DPI y Pasaporte (G11)G1 · G2 · G3 · G5 · G9 · G11
Pagodoc/plans/2026-08-07-e5a-datos-y-documentos-del-pago-diseno-tecnico.md§2: nota de lo que la entrega de infra nunca hizo (el bucket)G1
Pagodoc/plans/2026-08-07-analisis-definiciones-cis-ec.md§3.4 (medio de pago)G3
Reporte individualdoc/manual/20-transacciones.mdColumna "Procesada por" y rótulos de PDV y estado (G4); nombre del archivo reporte-individual-… (G4); :60 y la agencia que sale de la caja (G9)G4 · G9
Reporte individualF-gral/02-roles-permisos.md §2.4 (L189-205)Qué PDV se graba al pagar: el de la caja (D3-7)G4
Reporte individualF-gral/06-preguntas-abiertas.md #14Cerrar el "sigue abierto" del multi-PDV sin PDV activoG4
Reporte individualdoc/plans/2026-07-25-fix-pdv-asignacion-transacciones.mdNota de cierreG4
Saldos (Caja)doc/manual/30-caja.mdSección "Quién tiene abierta cada caja" y tabla "Qué ve cada perfil en Saldos" (G6); línea de país con el total de las cajas (G6.C); cajas inactivas (G7); "Fondeos por confirmar" y alertas (G13)G6 · G7 · G13
Apertura y cierredoc/manual/31-caja-apertura-cierre.mdL42-45 y "Si quedó abierta de un día anterior": quién puede cerrar (siete menciones de la regla vieja en total, ver G6)G6 · G7
Fondeo de cajadoc/manual/32-caja-fondeo.mdConfirmaciones de recepción y alerta por PDVG13
CajaF-caja/00-resumen-caja.md0.4 reglas de negocio: el cierre es de quien abrió, del Supervisor del PDV o del Admin; alta y baja de cajasG6 · G7
CajaF-caja/01-modelo-de-saldos.md1.10 (Mermaid L337 y L395; "quién ve cada extracto", L449); nueva 1.11 (alerta de reposición y confirmaciones); todo PAGO de caja es efectivo; la baja de una caja y su saldoG3 · G7 · G12 · G13
CajaF-caja/02-flujos-caja.md2.1 y 2.2 (Mermaid L49 y L113) y 2.10 (L560; :155, :611-614, :645-649): cierre de una caja ajena; 2.6 (L341): el PDV del pago es el de la caja y el pago es efectivo; 2.7 (L422) y hallazgo 4 (:650-652): alta y baja de cajasG3 · G4 · G6 · G7
CajaF-caja/03-diagramas-actividad-caja.md3.1 (L17, pago completo con Caja), 3.2 (L96, circuito), 3.3 (L152, apertura y cierre; :357, :375-377)G3 · G4 · G6 · G13
CajaF-caja/04-secuencias-pantalla-caja.md4.1 (mapa, L19), 4.2.2 y 4.2.3 (selector y vista operativa: quién la tiene), 4.2.5 y 4.2.7 (cerrar, vencida), 4.3.1 (qué muestra la pantalla), 4.4 y 4.4.3 (rótulos y chip de confirmación, Mermaid L653), 4.5 (Cajas con inactivas), 4.6 (Estaciones, L792-824 y :905-907), 4.8 (Tipo de cambio)G6 · G7 · G8 · G12 · G13
CajaF-caja/05-ux-multiples-cajas-y-fondeo.md5.1.3 y hallazgo 2: de propuesta a implementado; 5.7.4 (Mermaid L676): el circuito con confirmacionesG6 · G13
CajaF-caja/06-preguntas-abiertas-caja.md6.3: 18 y 19 resueltas por la hoja del 2026-10-02 (para Guatemala) y 16 por defecto; 17, 20 y 21 abiertas; pregunta nueva #22 (cierre ajeno) y #23 en adelante (G13). Pregunta #6 (la caja que paga puede ser de un PDV distinto al de la transacción): se actualiza según D3-7 (G4)G0 · G4 · G6 · G13
Estaciones / PDVdoc/manual/83-admin-estaciones.md"Cajas por estación" pasa a "Administrar cajas" (G7); provincia y ciudad de los tres PDV reales (G9)G7 · G9
Estaciones / PDVdoc/environments/staging.mdCorrer StationSeeder a mano revierte nombre, dirección y ubicación; consulta previa ampliada a las 76 celdas más countries (G0.6); smoke de subida de archivos (P3-6)G0 · G1 · G9
Países (Parámetros)doc/manual/82-admin-paises.mdRótulo del formato de recibo ("tirilla" frente a "Térmica 58 mm"); L21: A4 con cuatro incisosG5 · G9
Catálogosdoc/manual/85-admin-catalogos.mdLa lista de países del cliente; el renombre de una etiqueta es retroactivo en reimpresiones y reexports (G10); columna "Formato" y editor de reglas de identificación (G11)G10 · G11
Catálogosdoc/reference/2026-10-02-respuesta-ajustes-v2/README.md (nuevo) y doc/reference/2026-10-01-respuesta-ajustes-v1/README.mdQué hay, qué reemplaza a qué, por qué el .xlsx no se sube; la v1 deja de decir "Lo que nos falta"G0
Configuracióndoc/manual/84-admin-configuracion.mdPorcentaje de reposición de tesoreríaG13
Prefondeo Soterexdoc/manual/40-prefondeo.md"Si su usuario ve solo algunos países": una Tesorería regional necesita todos los países y al dar de alta un país hay que sumárselo; tarjeta con alcance parcial; cargar el monto que notificó el nivel de arriba y no el que acreditó el banco (RV3-58); alerta y confirmacionesG12 · G13
Fondeo PDVsdoc/manual/41-prefondeo-pais.mdÍdem; confirmar recepciónG12 · G13
Tesorería (extractos)F-gral/02-roles-permisos.mdTabla "quién ve qué extracto" con las cuatro filas de la hoja (D3-T1)G12
Tipo de cambiodoc/manual/70-tipo-cambio.mdL7-8 y L38-40: "el Cajero y el Supervisor pueden consultarlo" deja de ser cierto (si D3-11 es sí)G8
Tipo de cambioF-gral/02-roles-permisos.md y F-gral/01-sitemap.mdMatriz 2.1 (fila Tipo de cambio), Mermaid del menú por perfil (L121) y 1.2G8
Reportesdoc/manual/60-reportes.mdEstado de Situación: el nombre del beneficiario depende de lo que el perfil ve en Reporte individual, y el selector de país ofrece solo los países con Reportes (H3-01, H3-02); Cajas: cajas inactivasG7 · G8
ReportesF-gral/05-secuencias-pantalla.md 5.6 (L113, Mermaid L125)Quién ve el nombre del beneficiario en el Balance finalG8
Cumplimientodoc/manual/61-reportes-cumplimiento.mdTabla de las cuatro columnas y del prefijo (Payer Name por país, Additional Notes vacía, MTCN con "C-" y PIN sin él); la agencia sale de la caja (G4); nombres de países nuevos (G10)G4 · G9 · G10
Dashboard—Sin cambios por pedido del cliente (C3-13). Solo la redacción de C7 ("confirmado" pasa a "asumido") donde figureG0
Auditoríadoc/manual/90-auditoria.mdAcciones nuevas: TRANSACTION_DOCUMENT_REPLACED (G5), CASH_BOX_ACTIVATED y CASH_BOX_DEACTIVATED (G7), cierre_ajeno en el cierre de caja (G6), TREASURY_SETTINGS_UPDATED y PREFUNDING_RECEIPT_CONFIRMED (G13); la subida de un soporte ya no guarda el nombre del archivo (G5). Las etiquetas viven en frontend/src/views/admin/AuditoriaView.vue y no en un catálogo del backend: se actualizan por separadoG5 · G6 · G7 · G13
Perfiles y menúdoc/manual/01-perfiles-y-menu.mdReescribir "Si tiene más de una asignación" (D3-T2); alcance por asignación de Tesorería (D3-T1); tabla del menú sin Tipo de cambio para el CajeroG8 · G12
Perfiles y menúdoc/manual/00-primeros-pasos.md, 80-admin-usuarios.md (L25: "la suma de todas sus asignaciones"), 81-admin-asignacion.mdLa mezcla es por país; el PDV activo (hoy no aparece en ningún Markdown del manual); las asignaciones de Tesorería se dan por país enteroG4 · G8 · G12
Perfiles y menúF-gral/02-roles-permisos.md §2.3 y nota ⑴; F-gral/03-user-flows.md 3.9.3 (L466)La regla de unión (es diseño de ADR-014 §6; lo que confirmó el cliente el 24/07 es multipaís y multi-PDV); Tesorería con alertas y confirmacionesG8 · G13
Estado del proyectoCLAUDE.md, doc/README.md, doc/plans/2026-10-01-ajustes-v2-cliente-gt.md (§6, §7 #1, C7, C13, P9)Ver G0.3 y §5.8G0

5.2 Diagramas de flujo (Mermaid) que cambian ​

El build de VitePress no valida la sintaxis de Mermaid (vitepress-plugin-mermaid los renderiza en el navegador): cada diagrama tocado se mira abierto. Si un diagrama ya no aplica, se tacha con un banner en vez de borrarlo.

Archivo y posiciónQué cambiaEntrega
F-pago/01-flujo-del-pago.md flowchart 1.1 (L17)Pago de punta a punta sin transferencia; consulta de soportes de una pagada; papeleta con dos botonesG3 · G5
F-pago/01-flujo-del-pago.md secuencia 1.5 (L197)El pagador lee sus soportes y su papeleta aunque el PDV sea otro; 422 al multi-PDV sin PDV activoG2
F-pago/03-papeleta.md flowcharts L59, L107 y L180L59: dos botones; L180 (A4): declaración de cuatro incisosG5 · G9
F-gral/03-user-flows.md flowcharts 3.2 (L82), 3.8 (L359), 3.9.1 (L413) y 3.9.3 (L466)Sin transferencia; búsqueda con "C-"; el Cajero sin Tipo de cambio; Tesorería con alertas y confirmacionesG3 · G8 · G9 · G13
F-gral/04-diagramas-actividad.md secuencia 4.2 (L94)Sin transferenciaG3
F-gral/05-secuencias-pantalla.md secuencias 5.6 (L125), 5.7 (L257) y 5.8 (L348)Nombre del beneficiario por perfil; Cumplimiento ya no lee Auditoría; las comprobaciones de pagarG2 · G3 · G5 · G8 · G9
F-gral/01-sitemap.md flowchart del menú por perfil (L121)Tipo de cambio sale del Cajero y del SupervisorG8
F-gral/02-roles-permisos.md flowchart 2.1.2 (L126) y erDiagram (L179)Tipo de cambio; quién ve qué extractoG8 · G12
F-caja/01-modelo-de-saldos.md flowcharts L337 y L395El circuito de punta a punta con confirmaciones y alertas; rótulos de la tarjetaG12 · G13
F-caja/02-flujos-caja.md flowcharts 2.1 (L49), 2.2 (L113), 2.6 (L341), 2.7 (L422) y 2.10 (L560)Quién cierra; el PDV del pago; alta y baja de cajas; la caja vencidaG4 · G6 · G7
F-caja/03-diagramas-actividad-caja.md secuencias L17 (3.1), L96 (3.2) y L152 (3.3)Pago completo con Caja; circuito; apertura y cierreG3 · G4 · G6 · G13
F-caja/04-secuencias-pantalla-caja.md flowchart L19 y secuencia L653Panel de cajas en Estaciones; chip y botón de confirmaciónG7 · G13
F-caja/05-ux-multiples-cajas-y-fondeo.md flowchart 5.7.4 (L676)El circuito con confirmacionesG13

5.3 ADR: nuevos y enmendados ​

La numeración de los ADR nuevos es provisoria: se asigna al abrir cada PR, por orden de merge. El último existente es el 016.

ADRQué se haceQué registraEntrega
ADR-017 (prov.) Almacenamiento de los soportes de pagoNuevoS3 privado, IAM sin DeleteObject, orden de despliegue, por qué no EFS (D3-1)G1
ADR-018 (prov.) Cajas v3: quién cierra una caja ajena y alta y baja de cajasNuevo; reemplaza en parte ADR-013 §5canCloseCashSession dentro de una misma asignación (D3-12, D3-13); cash_boxes.active; "caja operable"; baja con saldo (D3-14)G6 · G7
ADR-019 (prov.) Las reglas de formato del documento de identidad viven en el catálogoNuevoCuatro columnas en catalog_items, sin regex libre (D3-15)G11
ADR-020 (prov.) Reposición y confirmaciones de tesoreríaNuevoMarca y cálculo al leer, nunca un estado ni un saldo guardado (P3-7, D3-20, D3-21); neutral al escenario (D3-26)G13
ADR-021 (prov.) El PDV de un pago es el de la caja que pagóNuevo, corto (o Actualización de ADR-011 si Carlos prefiere)D3-7G4
ADR-008 §1ActualizaciónExcepción del pagador; corrige la incoherencia del multi-PDV (dice "no puede ser el primero en subir" y el código guarda null); procedencia de los documentos previosG2 · G5
ADR-011 §3, §4ActualizacionesEl medio de pago es solo efectivo; regla de reemplazo (P3-1); nota del formato de identificaciónG3 · G5 · G11
ADR-013 §5Marcado "reemplazado en parte por ADR-018"La caja vencida ya no la destraba cualquier compañeroG6
ADR-014 §1, §6, §9 y ConsequencesActualizaciones fechadas§1: Tesorería es un único perfil, regional por asignación (D3-T1). §6: subapartado "Un usuario con más de un perfil: la mezcla es intencional (2026-10-04)" con la alternativa descartada y las combinaciones sensibles (D3-T2; no hay ADR nuevo). §9: el tipo de cambio sale del Cajero y del SupervisorG8 · G12
ADR-015 §5 y Preguntas abiertasNota y cierreCon alcance parcial la tarjeta muestra el saldo de sus países; 18 y 19 resueltas (Guatemala), 16 por defecto, 21 abierta; C7 "asumida"G0 · G12
ADR-005NotaTodo PAGO de caja es efectivo (G3)G3
ADR-007 §1Actualización fechada (revierte en parte)Carlos resolvió "global" el 2026-08-06; con alcance parcial la tarjeta muestra el saldo de los países del usuario (D3-19 b). Más una nota de que el PAGO de caja es efectivo (G3)G3 · G12
doc/plans/2026-08-04-e4-multiples-cajas-diseno-tecnico.md §2.3NotaEl PDV de un pago deja de estar desacoplado de la caja que paga (D3-7); la cláusula "no se valida que coincidan" queda superadaG4
ADR-010AclaraciónConfirmaciones y alertas de reposición son otra familia que el aviso de sobrerrepartoG13
ADR-016Una líneaLa lista blanca del listado suma procesada_por (G4); Cumplimiento deja de exportar texto libre de Auditoría (G9)G4 · G9
ADR-012Status "Accepted — en implementación" pasa a "Accepted" (el PR #55 está mergeado)Solo el encabezado; no se toca la integraciónG0
doc/architecture/index.mdÍndiceCada ADR nuevo, y el ADR-006 que hoy falta en el índicetodas
Si D3-5 resulta (c)ADR propio de formas de pagoSe decide ahí el patrón de atributos por ítem de catálogo (cruza con D3-15)G3

5.4 Recorridos guiados ​

Hay tres tours (Pago, Caja, Prefondeo) y siete anclas data-tour en el código: pago-buscador (TerminalSearchInput.vue:31), pago-mis-transacciones (PagoView.vue:540), caja-saldo (CajaView.vue:666), caja-historial (CajaView.vue:814), prefondeo-saldo (PrefondeoView.vue:107), prefondeo-asientos (PrefondeoView.vue:159) y help-menu (HelpMenu.vue:35). Este plan no crea tours ni anclas y no mueve ninguna (P3-12). Lo que sí cambia, y es solo texto:

TourQué cuidarEntrega
frontend/src/tours/prefondeo.ts paso 1La tarjeta pasa a "Saldo con Soterex" y puede mostrar solo el saldo de los países del usuario (G12.4). PrefondeoView.spec.ts fija las dos anclas (L156-157) y el valor USD 32,292.00 (L217); titulosPrefondeo.spec.ts fija los títulosG12
frontend/src/tours/prefondeo.ts paso 2 (prefondeo-asientos)G13 agrega un chip y un botón dentro del bloque que ya está anclado: el bloque no se mueveG13
frontend/src/tours/caja.tsG6.A3 cambia la tarjeta del selector y la vista operativa; si el texto del paso nombra quién abre, se ajusta. caja-saldo y caja-historial quedan donde estánG6
frontend/src/tours/pago.tsG9.5 (la búsqueda acepta "C-"): el texto del paso 1 puede decirlo. G5.7 no mueve pago-buscador ni pago-mis-transaccionesG5 · G9

Riesgo conocido (ADR-009 §3): un paso sin ancla se saltea a los 4 s sin que falle ningún test, y solo PrefondeoView.spec.ts pinea sus anclas. Propuesta barata para G5 y G6: copiar esa aserción a PagoView.spec.ts y CajaView.spec.ts. ADR-009 §1 cita pago-iniciar-pago y caja-abrir como ejemplos de nombre: no existen en el código.

5.5 Planes de QA ​

Los siete planes de doc/qa/ son anteriores a B1–B7 y usan nombres y reglas viejas: 2026-07-25-m1-transacciones-… (doce menciones a "Backoffice"; supone pagar = cancelar), 2026-07-25-m2-prefondeo-… (un solo saldo), 2026-07-27-m3-dashboard-reportes-… (§2.2-2.3 dicen que el Supervisor ve la comisión y el Admin no: hoy es al revés), 2026-07-27-m4-abms-administracion-… (§3-§5 describen la pantalla previa a E3), 2026-08-06-e4b-caja-y-prefondeo-… ("Prefondeo Holding / País"), 2026-09-11-e5-pago-documentos-… y 2026-09-12-adr008-documentos-bloquean-pago-… (roles de antes de B6). Se les agrega un banner de histórico (G0.3) y no se corrigen. Hoy no existe plan de QA de B1 a B7: cuatro perfiles y menú, extractos de tesorería, Fondeo PDVs, caja vencida y Cierres por día, Cumplimiento, A4, catálogos, datos del pago obligatorios. Cada plan nuevo cubre además el hueco heredado de su pantalla:

Plan nuevo (doc/qa/AAAA-MM-DD-…-plan-de-pruebas.md, con la fecha de la entrega)EntregasHueco heredado que cubre
…-g1-soportes-persistentes-…G1Subir y abrir un soporte real; sobrevivir a un redeploy; el smoke de P3-6
…-g2-g4-pagador-y-pdv-del-pago-…G2 · G4Datos del pago obligatorios (A3, B1) y fecha de nacimiento y nacionalidad (B4.0); dos usuarios de dos PDV sobre una misma tx
…-g3-medio-de-pago-efectivo-…G3Pagar en Guatemala (moneda de pago, sin tipo de cambio)
…-g5-documentos-del-pago-…G5Pagar sin cancelar por perfil (B6); los dos formatos de papeleta (B5)
…-g6-g7-caja-operador-cierre-y-cajas-…G6 · G7Caja vencida y Cierres por día (B3); varias cajas por sucursal
…-g8-perfiles-y-mezcla-…G8Los cuatro perfiles y el menú (B6) con backoffice@, supervisor@, tesoreria@ y admin@; Estado de Situación con Tesorería; perfiles mezclados
…-g9-cumplimiento-recibo-a4-y-pdv-…G9Reporte de Cumplimiento (B4) y recibo A4 (B5), abiertos y mirados
…-g10-g11-paises-e-identificacion-…G10 · G11Catálogos (A4, B1)
…-g12-g13-tesoreria-…G12 · G13Los cuatro extractos y Fondeo PDVs (B7); la pantalla de Tipo de cambio

5.6 Referencia de API ​

No existe referencia de la API interna (las ~100 rutas de backend/routes/api.php): la única referencia formal es la de C2P, que este plan no toca. El contrato de las pantallas vive en los tests de backend/tests/Feature/ y, para los extractos, en prosa en ADR-015 §8. Para v3 se mantiene ese criterio: el contrato de cada endpoint que cambia se describe en el ADR o en la Actualización de la entrega y lo fija un test; no se crea un OpenAPI (§8). Lo que cambia:

EndpointCambioEntregaDónde queda el contrato
POST /transacciones/{id}/documentos403 CANNOT_REPLACE_DOCUMENTS; 422 al multi-PDV sin PDV activo; el pagador entra al alcanceG2 · G5ADR-008 y ADR-011 (Actualización); TransactionDocumentApiTest
GET /transacciones/{id}/documentos y /papeletapuede_reemplazar; 200 para quien pagó aunque el PDV sea otroG2 · G5ídem
PATCH /transacciones/{id}/pay y /datos-pago422 con TRANSFERENCIA; formato de identificación; el PDV sale de la cajaG3 · G4 · G11ADR-011, ADR-019 y ADR-021
GET /transacciones y /exportCampo y novena columna procesada_porG4ADR-016 (una línea)
GET /pago/buscarTolera el prefijo "C-" seguido solo de dígitosG9PagoApiTest
GET /caja/disponiblesopened_by, can_close; deja de mandar opened_by_supervisor_idG6ADR-018
POST /caja/{id}/cierre403 CASH_CLOSE_NOT_OWNERG6ADR-018; CashBoxApiTest
GET /caja/totales-pdvAlcance de fondeo_caja:read; bloque countries[] (línea de país, G6.C)G6ADR-018
PATCH /admin/estaciones/{id}/cajas/{id} (nuevo) y POST …/cajasActivar y desactivar; 422 y 409 nuevosG7ADR-018; StationApiTest
GET /tipo-cambio/{pais}403 al Cajero y al SupervisorG8ADR-014; PerfilesAccesoApiTest
GET /reportes/situacion y /exportEl nombre del beneficiario sigue a isScopedToOwnTransactionsG8PerfilesAccesoApiTest
GET /reportes/cumplimiento/exportColumnas 21, 24 y 30G9Manual 61; ReporteCumplimientoApiTest
GET /catalogos y ABM de catálogosCuatro columnas de formato; código de país de 2 letrasG10 · G11ADR-019; CatalogItemApiTest
GET /prefondeoSaldo del alcance e indicador de alcance parcialG12ADR-015 §5 (nota)
GET /tesoreria/alertas-reposicion, parámetro de Configuración (nuevos)Alertas calculadas al leerG13ADR-020
POST /prefondeo-pais/{entry}/confirmar y POST /caja/movimientos/{id}/confirmar (nuevos); receipt en los extractosMarca de recepción, sin tocar saldosG13ADR-020; TreasuryStatementApiTest

5.7 Qué atan los tests y la CI (y qué no) ​

Antes de tocar un contador, un título o una celda de la matriz, mirá esta tabla: sumar o renombrar un archivo del manual, o cambiar una celda de la matriz, rompe a propósito esos tests y se actualizan en el mismo PR.

ArtefactoQuién lo vigila¿Corre en el CI de PR?Lo tocan
doc/architecture/matriz-de-perfiles.json contra RoleSeeder::MATRIX y contra la migraciónPerfilesMigrationTest (test_la_matriz_de_los_tests_del_frontend_es_la_del_seeder, L334; si falla: ACTUALIZAR_MATRIZ_DE_PERFILES=1 php artisan test --filter matriz_de_los_tests_del_frontend y se copia desde backend/storage/app/; ojo: migrar() aplica hoy solo la migración de B6 y G8 la encadena con la nueva)SíG8
Etiquetas de módulo contra la matrizPerfilesMigrationTest L295Sícualquier módulo nuevo
Cantidad de secciones del manual por perfil (hoy 7 / 10 / 9 / 20) y títulosManualPdfTest::test_cantidad_de_secciones_de_cada_perfil (L123-128) y asserts por título (L40-70)SíG8: Cajero 6 y Supervisor 9 si D3-11 es sí
20 archivos del manual, enlaces #slug, secciones por perfilfrontend/src/utils/__tests__/manual.spec.ts (L77-81) y ManualPdfTestmanual.spec.ts no (vitest no corre en CI); ManualPdfTest síG8. Este plan no agrega ni quita archivos del manual: el 20 no cambia
Frontmatter con : sin comillas en un tituloManualPdfTest (L229)Sítodo texto de manual
Menú, barra mobile y pantalla de inicio por perfilAppLayout.spec.ts, firstAllowedRoute.spec.ts (L154 queda sin sentido: reescribir), guardPorPerfil.spec.tsNoG8
Anclas de los toursPrefondeoView.spec.ts L153-160NoG12 · G13
La planilla de tesorería (32.292 / 20.208 / 7.000 / 1.500 / 4.000 y 12.500)TreasuryStatementApiTest::test_reproduce_la_planilla_del_cliente_paso_a_paso; el texto de 01-modelo-de-saldos.md §1.10 y ADR-015 §3 no se compara con ellaSíG12 · G13
Las 36 columnas de CumplimientoReporteCumplimientoApiTest (compara la lista entera de encabezados); el manual 61 no se comparaSíG9
Densidad del A4 (cota sobraMm < 30)PapeletaFormatosTest L342-402SíG9.6: recalibrar
Vínculos internos y páginas del sitionpm run docs:buildNo: lo corre el job deploy-docs de deploy-staging.yml, o sea que un link roto se descubre al desplegartodas
Sintaxis de MermaidNadie—G3, G5, G6, G7, G8, G13
Copias a mano sin red: tabla 2.1 de 02-roles-permisos.md, Mermaid de 01-sitemap.md, tablas de doc/manual/01-perfiles-y-menu.md, NAV de AppLayout.vue, motivos de fondeo (05-ux §5.3 y manual 32), etiquetas de AuditoríaNadie—G6, G8, G13

Desde G0.8 el CI de PR corre npm test (en el job frontend) y npm run docs:build (en un job nuevo docs, con working-directory: doc): los "No" de esta tabla pasan a "Sí".

5.8 Otros documentos desactualizados (los absorbe G0.3) ​

Los encontró el relevamiento de documentación y ninguno es un pedido del cliente. Son correcciones de una línea, sin riesgo, y conviene hacerlas en G0.3 para que quien lea el repo no se lleve una foto vieja:

DocumentoQué dice hoyQué corresponde
CLAUDE.md (bloque de estado)B6 (#71), B7 (#72) y M5 (#55) figuran "pendientes de merge"Están mergeadas (aab80f7, ebfe280, 7538936); y B6 y B7 desplegadas a Staging
doc/README.md (L66-69)Tabla de estado del 2026-08-05; B6 y B7 "pendientes de merge"; el árbol no lista manual/, integracion/, informes/, reference/ ni los ADR-008 a ADR-016Poner la tabla al día
doc/index.md (L34 y L42)"Los 3 ADRs" y "Las 4 APIs de Soterex (tokenC2P, SendRequest, Cancel, Notifications)"Desde ADR-012 son el token OAuth, SendRequest, Cancel y un webhook
doc/functional/index.md (L14 y L20)Los cambios de E4b "todavía no están en el código"; E5 "en revisión (PR #18)"Contradice el index.md de cada paquete, que ya está en presente
F-gral/index.md (L4)"Status: Draft … solo queda bloqueante la #2b"La #2b se disolvió con ADR-012
doc/environments/index.md (L6)Staging "Terraform listo, pendiente de aplicar"Está aplicado y en uso
doc/site/README.md (L21 y L82)"4 APIs … tokenC2P"; "basado en C2P_V14"Ídem
doc/architecture/index.mdNo lista el ADR-006; ADR-012 sigue "en implementación"Listarlo; ver §5.3
Los siete planes de doc/qa/Nombres y reglas anteriores a B6Banner de histórico (§5.5)

6. Preguntas y respuesta al cliente ​

Tres partes: 6.0 la respuesta que Carlos le manda a Magaly (incluye las dos decisiones firmes del 2026-10-04, D3-T1 y D3-T2); 6.1 las 39 preguntas numeradas para el cliente (35 vigentes), con la numeración que usa el resto del plan, el comportamiento por defecto que se implementa mientras no contesten (P3-17) y qué frena cada una; 6.2 las cinco consultas para Soterex (D3-22), que son solo consulta: ningún cambio a la integración C2P (P3-13).

6.0 La respuesta al cliente ​

La manda Carlos (G0.4), con capturas actuales de Staging para lo que ya está hecho (la muestra de D3-23, Excel de Cumplimiento y PDF del A4 con datos de demo, va después, G0.9). Está escrita para pegarse. Lo que va entre corchetes es decisión de Carlos o una precondición. No se manda antes de tener la cuenta de Tesorería en el Firebase de Staging y Staging sano (G0.4), ni el apartado 2 antes de la consulta 7 de G0.6.

Asunto: Soterex GT — respuesta a sus ajustes del 2 de octubre

Magaly, Alexis, Teresa: gracias por el Excel y el mail. Lo revisamos punto por punto. Tomamos lo que no está en el Excel como aceptado, salvo lo de abajo.

1. Gran parte de lo que señalan ya está hecho: sus capturas son del 30/9 y el 1/10. Después de esas fechas entraron dos tandas que no vieron. Cancelar una transacción es solo del Administrador. El menú ya se llama "Reporte individual", "Saldos" y "Parámetros"; Auditoría está en Administración y solo la ve el Administrador; Reportes está para todos menos el Cajero; el tipo de cambio está en Tesorería. El prefondeo está en dos pantallas, "Prefondeo Soterex" y "Fondeo PDVs", con estado de cuenta (fecha, concepto, referencia, débito, crédito y saldo). La papeleta se puede imprimir siempre que la transacción esté pagada. Les mandamos capturas actuales.

2. Una falla nuestra detrás de "No se pudo abrir el documento". Encontramos que los documentos que se suben en el ambiente de pruebas no se guardan en un lugar permanente: se pierden cada vez que lo actualizamos. Lo estamos corrigiendo. [Confirmar con la consulta 7 de G0.6 antes de mandar.] Les pedimos no repetir las pruebas con documentos hasta que les avisemos, y que los documentos de prueba anteriores se vuelvan a subir.

3. Dos decisiones que queremos dejarles claras.

Tesorería es un solo perfil y es regional. No vamos a crear una "Tesorería Local": lo local o lo regional lo define a qué países está asignada cada persona. Quien está asignado solo a Guatemala ve el estado de cuenta de su país y de sus PDV completos —eso cubre "CIS Guatemala solo su estado de cuenta"— y no puede cargar nada en otro país. Quien está asignado a todos los países ve la Holding completa. Dos consecuencias: al dar de alta un país nuevo hay que sumárselo a la Tesorería regional, y para que alguien vea un solo PDV el perfil es Supervisor. Aclaración: no se puede dar a una persona de Tesorería solo lectura en un país; los permisos son del perfil. Además proponemos ajustar lo que una Tesorería de un solo país ve de la Holding (la tarjeta de saldo y los dos extractos de la Holding) para que muestre lo de sus países y avise que es parcial (QC-32). [Si Carlos aprueba D3-19 b.]

Con más de un perfil se suman las opciones, y es a propósito. Ustedes confirmaron el 24 de julio roles distintos por país y un Supervisor a cargo de varios PDV; que dentro de un mismo país se sumen las opciones es como lo diseñamos y no se los habíamos consultado. No agregamos un selector de perfil por tres razones: quien tiene Tesorería regional necesita todas sus asignaciones juntas para ver la Holding; un selector solo escondería opciones —la persona seguiría teniendo ambos permisos y el sistema también—, así que el control real está en qué asignaciones le dan a cada persona; y con los cuatro perfiles nuevos, "Cajero más Administrador" ve exactamente el menú del Administrador (la captura de "los dos perfiles" ya no muestra mezcla). Lo documentamos en el manual y en la ficha del usuario, y corregimos dos casos en Reportes donde la suma mostraba de más. Una recomendación: no asignen a la misma persona, en el mismo país, Cajero y Tesorería (puede fondear la caja con la que paga; todo queda en Auditoría). [Si van a asignar combinaciones reales, avísennos y evaluamos un aviso en la ficha.]

4. Lo que vamos a cambiar: documentos de una transacción pagada (solo Supervisor y Administrador reemplazan; el Cajero sube lo que falta; modo consulta) y dos botones de papeleta, tirilla y A4; que quien paga vea sus documentos y su papeleta; medio de pago solo efectivo; PDV en todas las transacciones y la columna "Procesada por"; en Caja, quién tiene abierta cada caja, que solo cierre quien abrió (con salida para el Supervisor y el Administrador), la línea de Guatemala con el total de las cajas que dibujaron arriba de Saldos y administrar cajas; tipo de cambio solo para Tesorería y Administrador (QC-17); en Cumplimiento, Payer Name "CIS Guatemala", Additional Notes en blanco y MTCN con "C-"; recibo A4 con la declaración de la tirilla; los tres PDV reales; su lista de países y los formatos de DPI y Pasaporte; en Tesorería, el alcance de la Holding por país, la alerta al 30%, las confirmaciones de recepción y, si lo quieren (QC-39), la columna de porcentaje de sus estados de cuenta. El Dashboard no se toca hasta que definan el escenario de prefondeo; mientras tanto trabajamos con el escenario 1 como supuesto, no como definido.

5. Tres pedidos que contradicen algo que ya acordamos o hicimos; necesitamos su confirmación. (a) Pago "solo para Cajero y Supervisor": desde el 2/10 el Administrador también paga y cancela, por una decisión nuestra (QC-1). (b) Que solo cierre la caja quien la abrió: revierte lo que acordamos en agosto para cajas vencidas, que un compañero podía destrabar; proponemos que cierre quien la abrió, el Supervisor del PDV o el Administrador (QC-12). (c) El recibo A4 vuelve a cuatro incisos: revierte el quinto que ustedes pidieron en la tanda anterior; lo hacemos como piden.

6. Muestra para validar. Ninguna de las tandas B4 (Cumplimiento), B5 (recibo A4), B6 (perfiles y menú) y B7 (extractos) fue validada visualmente por ustedes, y varios de los cambios de arriba tocan justamente esas pantallas. Cuando estén hechos, les mandamos el Excel de Cumplimiento y el PDF del A4 con datos de prueba y capturas del menú y los extractos, y necesitamos un OK explícito de cada una. Hasta entonces, no las den por validadas.

7. Preguntas. Va la lista numerada (QC-1 a QC-39; las retiradas figuran tachadas). Las que frenan trabajo están marcadas; para el resto aplicamos el valor que indicamos si no contestan, y se cambia después con poco costo.

Un pedido: en las próximas capturas usen transacciones de prueba o tapen los datos de las personas.

6.1 Preguntas para el cliente ​

Ordenadas por número. Cada una es una decisión. "Si no contestan" es lo que se implementa (P3-17) y es reversible. "Frena" dice qué no se empieza hasta tener la respuesta o hasta que Carlos autorice usar el valor por defecto. Las filas tachadas están retiradas (ya contestadas, absorbidas por otra o diferidas): se conserva el número para no renumerar las referencias del plan. Quedan 35 vigentes.

QCPreguntaSi no contestanÍtems · entregaFrena
QC-1La hoja de Pago dice "solo cajero y supervisor"; la de Menús y perfiles incluye también al Administrador, y desde el 2/10 el Administrador cancela y paga (decisión nuestra, no un acuerdo con ustedes). ¿Confirman que el Administrador también puede pagar?Sí: Pago queda para Cajero, Supervisor y AdministradorRV3-01, 40 · G0—
QC-2En una transacción pagada leemos "no modificar los documentos" como "no reemplazar uno ya cargado": el Cajero puede seguir subiendo uno que falta (la papeleta firmada se escanea después de pagar y el cierre de caja la exige), pero solo el Supervisor o el Administrador reemplazan uno cargado. ¿Es lo que quieren? Y "luego de haber guardado la tx" lo leemos como "Confirmar pago" (el botón que paga), no como "Guardar datos" (el borrador del formulario): ¿es así?Sí a las dos (P3-1)RV3-03, 10 · G5—
QC-3Cuando buscan una transacción y no la pagan, ¿qué no debería aparecer: (a) los documentos que alguien cargó en un intento anterior, o (b) la sección de documentos mientras solo se consulta?Se mantienen, con "subido por … el …" y un aviso de que son de un intento anterior (D3-10 opción 1)RV3-11 · G5—
QC-4El error "No se pudo guardar el documento" al adjuntar PDF o JPG, ¿se repite después de las correcciones del 1 y 2 de octubre? Si se repite: usuario, hora, tipo y tamaño del archivoDiferida a G1: se pregunta cuando G1 esté desplegado y se les avise que pueden volver a probar (6.0, apartado 2, les pide no repetir las pruebas con documentos hasta entonces)RV3-06 · G1—
QC-5Los documentos de prueba subidos antes del 2/10 se perdieron con las actualizaciones del ambiente (apartado 2 de 6.0). ¿Alguno hay que recuperarlo, o eran solo de prueba y se vuelven a subir?Retirada: no es una decisión; el apartado 2 de 6.0 ya les dice que vuelvan a subir los documentos de pruebaRV3-07 · G1—
QC-6La transacción 3751272495, que se pagó y no dejó imprimir la papeleta: ¿quién la pagó, quién intentó imprimirla (¿la misma persona?) y en qué PDV estaba cada uno?Retirada: la consulta 10 de G0.6 y las capturas (img 14, 20 y 31) dan quién pagó y en qué PDV; G2 se hace con la excepción del pagador (D3-2 a)RV3-14 · G2—
QC-7Al sacar la transferencia, ¿el campo "Medio de pago" queda visible con Efectivo como única opción, o prefieren que desaparezca de la pantalla?Visible, con Efectivo preseleccionadoRV3-12 · G3—
QC-8Pidieron "añadir el catálogo de formas de pago" y también quitar la transferencia: ¿hay otras formas de pago que deban existir? Si las hay, ¿cuáles y qué cambia con cada una (documentos, cuenta bancaria, saldo de la caja)?No hay otras: solo efectivo y sin catálogo (D3-5 a)RV3-39 · G3—
QC-9En Guatemala, ¿el PDV de un pago es siempre el de la caja desde la que se pagó, aunque la persona tenga configurado otro PDV activo? (En sus capturas hay un pago con PDV Mixco Plaza cuya plata salió de la caja de Central.)Solo se usa el de la caja cuando la persona no tiene un PDV que se pueda resolver; el PDV activo configurado gana (D3-7 b)RV3-17 · G4—
QC-10Para "el usuario que procesó" ¿alcanza con el correo de la persona (el sistema no guarda nombre y apellido), en la pantalla y en el Excel?Correo, en pantalla y como novena columna del Excel; "Soterex (API)" si la canceló SoterexRV3-16 · G4—
QC-11¿El reporte de Cumplimiento (36 columnas, solo Administrador) es el "reporte completo" que piden, de modo que el Excel de Reporte individual siga con sus columnas actuales más la del usuario?SíRV3-18 · G0—
QC-12Proponemos que una caja abierta por otra persona la puedan cerrar solo quien la abrió, el Supervisor del PDV y el Administrador (hoy, cualquier compañero del PDV). ¿Hay PDV sin Supervisor donde esto dejaría una caja vencida sin salida?Esa regla (D3-12 B). Si hay PDV sin Supervisor, se agrega que otro operador pueda cerrar solo una caja vencida (D3-12 C)RV3-25 · G6.BG6.B
QC-13"Una caja abierta no la puede abrir otro": hoy el sistema ya lo impide con un error. ¿Vieron que dejara abrir una caja ya abierta por otra persona, o se referían a lo que pasa después de que alguien cierra la caja del otro?Lo segundo: se cubre con QC-12 y se suma un test de apertura duplicadaRV3-26 · G6—
QC-14Para mostrar quién opera cada caja, ¿alcanza con el correo, visible para todos los que ven la lista de cajas de ese PDV (incluido otro Cajero)?SíRV3-27 · G6—
QC-15Dibujaron arriba de las tarjetas por PDV una línea "GUATEMALA · USD 24878.53". Entendemos que es el total de plata en las cajas de Guatemala (la suma de las tarjetas, igual que "Distribuido en cajas" de Prefondeo País) y no el disponible para distribuir. ¿Es así, o quieren además el disponible?Sí, el total de las cajas; se implementa (G6.C)RV3-28 · G6.C—
QC-16Desactivar una caja que tiene saldo distinto de cero: ¿se rechaza hasta dejarla en cero con un motivo de ajuste nuevo ("Retiro por baja de caja", que aprobaría Tesorería), o se permite y queda inactiva con su saldo, que sigue sumando en el total del PDV?Se rechaza (D3-14 a)RV3-30 · G7G7
QC-17El tipo de cambio hoy lo consultan (solo lectura) el Cajero y el Supervisor; su hoja de menús lo reserva a Administrador y Tesorería. ¿Les sacamos esa consulta a Cajero y Supervisor? Se aplica en un deploy y avisamos antesSí (D3-11 a)RV3-35, 47 · G8—
QC-18¿Alguien de CIS cambió permisos desde la pantalla "Roles y Permisos" del ambiente de pruebas (por ejemplo el Cajero de la captura que no muestra "Transacciones")? Sirve para separar lo que es decisión de ustedes de lo que es diferencia de despliegueNo; no se toca nada salvo lo que Carlos apruebe después de la consulta 1 de G0.6 (G8.9); la fuente de comparación es RoleSeeder::MATRIX, no la hoja de MenúsRV3-41 · G8—
QC-19Transaction Status del reporte: el mail dice "Send" y el archivo dice "Sent". ¿Cuál es el literal de su planilla original? (Si pueden, una fila de ejemplo sin datos de personas; no es obligatorio.)Queda "Sent"RV3-89 · G9—
QC-20Transaction Status – Update sale hoy en inglés (Pending, Paid, Cancelled); ustedes lo escribieron "pendiente, pagada o cancelada". ¿Lo quieren en español?Queda en inglésRV3-91 · G9—
QC-21El MTCN del reporte con el prefijo "C-" (y el PIN sin él): ¿lo siguen necesitando en sus listados?Se aplica "C-" al MTCN del reporte, con una variable que lo apaga (D3-18)RV3-93 · G9—
QC-22Las direcciones de los tres PDV: dos traen errores de tipeo evidentes ("NTERAMERICANA", "MVEL 2"). ¿Las cargamos tal cual o las corregimos?Tal cualRV3-87 · G9—
QC-23 (✅ resuelta por Carlos el 2026-10-07: se renombró)La ciudad del primer PDV: el catálogo tiene el municipio "Guatemala" dentro del departamento "Guatemala". ¿Quieren que se llame "Ciudad de Guatemala"? (Cambia también el reporte y el A4 de todos los pagos de ese municipio)Queda "Guatemala"RV3-88 · G9—
QC-24En el recibo A4, ¿qué significa "Transacción fija: Sí / No", quién lo marca y quieren que se siga imprimiendo? (Quedó asignada a Alexis)Se sigue imprimiendo como hoyRV3-95 · G9—
QC-25¿Necesitan ver el RS-xxxxx de Soterex en los estados de cuenta? Si sí, ¿pueden mandar un ejemplo de dónde sale?Contestada por el cliente en el mail ("si Soterex lo mantiene, mantengamos igualmente en el reporte; caso contrario eliminarlo"): la pregunta pasa a Soterex (S-3). Si S-3 confirma que el RS es el transaction_id, se agrega como referencia secundaria en los extractos; si no viaja, se omiteRV3-98 · G0—
QC-26Al aplicar su lista, 23 nombres de país cambian (por ejemplo "Países Bajos" pasa a "Holanda", "Esuatini" a "Suazilandia", "Macedonia del Norte" a "Macedonia", "Catar" a "Qatar" y "Chequia" a "República Checa"). Los recibos y reportes que se reimpriman mostrarán el nombre nuevo también para transacciones ya hechas. ¿Está bien?Sí; los códigos guardados no cambianRV3-75 · G10—
QC-27¿Cuáles de estos casos hay que cargar? Respondan sí o no a cada uno: (a) Chipre del Norte, (b) Irlanda del Norte y (c) Somalilandia, que no tienen código ISO; (d) #216 "Santo Tomas": ya tienen Santo Tomé y Príncipe (#196), ¿qué es esta entrada? (¿Saint Thomas, de las Islas Vírgenes de EE.UU.?); (e) Antártida, que está en la norma y no en su lista. Kosovo y Antillas Holandesas se cargan con el código que usan hoy, y Timor Oriental queda una sola vezNinguno de los cinco; no se desactiva nadaRV3-76 · G10G10 (solo esos casos)
QC-28La columna "#" (1 a 255) de la lista de países, ¿es un contador de la planilla o un orden que quieren en los desplegables? (El encabezado de la hoja sugiere un picklist exportado.)Contador; los desplegables siguen alfabéticosRV3-77 · G10—
QC-29No llegaron las listas de departamentos y municipios de Guatemala. Los 22 departamentos de la herramienta son el estándar INE, pero los municipios (unos 338 de 340) se compilaron sin verificar contra la fuente. ¿Esas listas son las correctas para el reporte o tienen una propia?Se usan las cargadasRV3-86 · G10 · G11—
QC-30El DPI a veces se escribe con espacios ("2999 99999 0101"). ¿El formulario debe quitar espacios y guiones al escribir o pegar y validar los 13 dígitos juntos, o el número debe escribirse limpio y rechazarse si trae separadores?El formulario los quita al escribir o pegar; el servidor exige 13 dígitos exactosRV3-79, 81 · G11G11
QC-31¿Qué escenario de prefondeo aplica: el 1 (Soterex → CIS Holding → países) o el 2 (Soterex prefondea a cada país por separado)? ¿Es el mismo para Guatemala y Ecuador? Vimos que el Escenario 2 está oculto en su hoja: ¿queda descartado?Escenario 1 como supuesto explícito (D3-26); el Dashboard no cambiaRV3-54, 70, 74 · G0 · G12 · G13—
QC-32¿La Tesorería de CIS Guatemala puede ver la Holding (saldo y movimientos de su país) y la comisión, o solo su país y sus PDV?Ve la parte de su país de la Holding, con aviso de "parcial" (D3-19 b)RV3-55 · G12—
QC-33El "Saldo final CIS Holding" de la hoja (32.708) es la Holding sin repartir (20.208) más el saldo final de CIS Guatemala (12.500); supera en 208, la comisión, a los 32.500 que quedan. ¿Es un doble conteo o quieren ese número?No se muestra; siguen 32.292, 20.208 y 12.500RV3-67 · G12RV3-67
QC-34Alerta al 30%: ¿sobre qué ingreso se calcula el porcentaje: el último recibido, la suma de lo recibido desde el último prefondeo completo, u otro? (De esto depende también la columna de porcentaje, QC-39)El último ingreso; sin ingresos no hay alertaRV3-64, 68 · G13.AG13
QC-35La alerta de reposición, ¿alcanza con verla en la herramienta (una franja al abrir la pantalla) o necesitan un aviso por mail?Solo en la herramientaRV3-64 · G13.AG13
QC-36El 30% ¿es un único porcentaje para Soterex, países y PDV, o uno por nivel?Único, editable por el Administrador en ConfiguraciónRV3-64 · G13.AG13
QC-37Cuando un envío (de la Holding a un país o de un país a un PDV) no está confirmado, ¿alcanza con que quede marcado "pendiente de confirmar" o debe impedir algo (repartir o pagar con esa plata)?Solo la marca; no bloquea pagos ni cierres de cajaRV3-60 · G13.BG13
QC-38Si el equipo de Tesorería es chico, quien carga un envío puede ser quien lo confirma. ¿Lo aceptan (queda marcado "autoconfirmado") o debe confirmar siempre otra persona?Se acepta y se marcaRV3-60, 62 · G13.BG13
QC-39En su ejemplo, cada estado de cuenta tiene una columna de porcentaje. ¿La quieren en la herramienta? Los cinco porcentajes del ejemplo miden cosas distintas (consumo en unos, lo que queda sin repartir en otros); proponemos una sola columna: el saldo después de cada movimiento sobre lo último que recibió esa entidad (depende de QC-34)Sí: esa columna, derivada y de solo lectura (G13.C)RV3-68 · G13.CG13.C (el resto de G13 no)

Quedan en pie y sin pregunta. RV3-83 a RV3-85, RV3-99 y los ℹ️ de §1.1 son informativos; RV3-96 (un solo campo de referencia) se da por contestado por defecto (el mail dice "desechar cualquier otra info", que es una inferencia y no un sí); RV3-98 ya la contestó el cliente y queda en S-3.

6.2 Consultas para Soterex ​

Un solo mail a Sean (D3-22, G0.5). Solo consulta: ninguna se traduce en un cambio a C2PController, OAuth, SendRequest ni Cancel (P3-13). Si la respuesta pide un cambio de integración, es otro plan.

#PreguntaPara quéEntrega
S-1¿Comunican cada prefondeo por la API? Con qué mensaje y qué camposRV3-56: hoy se carga a mano; define si existe la rama "notifica por API" del paso 2G0 · G13
S-2¿Su carta y su Salesforce siguen mostrando "C-" más el token, y lo necesitan en nuestros listados?RV3-93 y H3-05G9
S-3¿El RS-xxxxx es el transaction_id que mandan en SendRequest?RV3-98: el cliente ya dijo que si Soterex lo envía se mantiene en el reporte y si no, se eliminaG0
S-4¿Cómo modifican en Soterex una transacción ya enviada: Cancel y SendRequest nuevo, con qué transaction_id y qué sub_status? (Hoy un transaction_id repetido da 2001, y puede romper una operación real)RV3-91 y el estado "Update" de CumplimientoG9
S-5La lista de países que mandó el cliente tiene el encabezado "Global Country Values" y "Translation - Spanish": ¿es el picklist de países de su Salesforce? Si lo es, ¿con qué código viaja cada valor y qué orden tiene el "#"?RV3-75 a 77 (el "#" y los valores sin código ISO)G10

7. Riesgos ​

Los riesgos propios de cada entrega están en su sección de §4; acá van los que cruzan entregas o dependen de cómo se ejecute el plan. Cada uno dice dónde pega.

  • R-1. Cambios de permisos y de menú sobre usuarios reales de Staging (G8, G6.B). La migración de G8 saca tipo_cambio a Cajero y Supervisor en el momento del deploy, mientras el cliente prueba; G6.B cambia quién puede cerrar una caja abierta; B6 ya cambió los permisos de todos en Staging y el cliente todavía no vio ese menú. La migración pisa lo que un Admin haya editado en esas celdas (política de ADR-014 §8). El RoleSeeder pisa lo editado desde la app cada vez que alguien lo corre: por eso todo viaja por migración de datos con RolePermission::withoutEvents, y nadie corre db:seed en Staging (G0.6, consulta 1). Mitigación: el OK de Carlos antes del deploy, avisarle a Magaly (QC-17), la consulta de las 76 celdas contra RoleSeeder::MATRIX antes de tocar nada (H3-04), y probar logueado con los cuatro perfiles (firstAllowedRoute ya dejó a un rol sin pantalla de inicio dos veces).
  • R-2. El escenario de prefondeo no está definido y el Dashboard queda congelado (G0, G12, G13). El cliente escribió en la hoja Dashboard "no se solicitan cambios hasta tener claro por qué escenario de prefondeo se decide que vayamos" (RV3-74), y en Módulo tesorería el Escenario 2 quedó oculto (filas 61 a 111; RV3-70 y RV3-71): una señal a favor del 1, pero que no reemplaza la nota de Dashboard. El plan v2 y CLAUDE.md trataron el Escenario 1 como "confirmado" (C7); no lo está. Mitigación: corregir la redacción a "asumido" (G0.3), diseñar G13 neutral al escenario (D3-26), no tocar el Dashboard (C3-13) y no empezar RV3-67. Si el cliente elige el Escenario 2, el modelo necesita el concepto de "entidad" y de qué países cuelgan de cuál: es otro plan.
  • R-3. Los soportes de pago se pierden en cada deploy (G1) y condicionan todo re-test del cliente. Hoy ningún archivo se guarda en un lugar persistente (el disco documents es local dentro del contenedor, y sin la librería de S3 instalada). Es bloqueante para producción: son identificaciones y el respaldo contable de cada pago. Mientras no esté, cualquier prueba del cliente que abra un documento falla después de cada deploy, así que G2, G5 y G9 se re-testean recién después de G1 (P3-16). Las filas quedan y los archivos no: "completa" sigue diciendo que está todo porque se calcula sobre filas. Mitigación: G1 antes que el re-test; documentos:verificar; y no prometer en la respuesta al cliente (6.0, apartado 2) algo que la consulta 7 de G0.6 no confirmó.
  • R-4. Un apply de Terraform puede romper lo que anda (G1). deploy-staging.yml renderiza la task definition desde la última revisión de la familia y el Terraform ignora task_definition: un apply que re-registra con valores equivocados repite el incidente del CORS del 02/10 (login roto hasta el 04/10), y el WAF ya bloqueó subidas una vez. Mitigación: el orden de G1.7 (imagen con la dependencia, apply manual de Carlos, un deploy que tome las variables, verificación), la prueba de humo de P3-6 después de cada apply que toque waf o ecs, y el chequeo de preflight CORS de staging.md.
  • R-5. Este plan toca Pago, la pantalla crítica del Cajero. G2 (alcance de soportes y papeleta), G3 (medio de pago y pay()), G4 (el PDV que se graba al pagar), G5 (reemplazo de documentos y botones), G9.5 (la búsqueda por MTCN) y G11 (validación de la identificación) cambian lo que ve y puede hacer quien está en el mostrador. Los errores acá se pagan en la ventanilla, no en un reporte. Mitigación: G3 cambia un contrato (422 donde antes 200): front y back salen juntos; G5 no mezcla "subir lo que falta" con "reemplazar" (el cierre de caja depende de la papeleta firmada); G11 tiene reglas editables y auditadas; ninguna entrega de Pago se promueve a Staging sin probarse antes en dev (./start-dev.sh y los seeders Demo) con los tres perfiles sobre una misma tx, a 1280 px y a 375 px; en Staging queda el humo posterior ("Cómo se ejecuta", punto 2).
  • R-6. Se revierten decisiones escritas. Cierre de caja solo por quien abrió revierte ADR-013 §5 (y un test que lo protege); el PDV de un pago como el de la caja revierte en parte E4-multi §2.3 (D3-7); la tarjeta de la Holding limitada a los países del usuario revierte en parte ADR-007 §1 y ADR-015 §5 (D3-19 b); el A4 de cuatro incisos revierte B5.3; los dos botones de papeleta reemplazan a P9(b); el tipo de cambio sin lectura para Cajero y Supervisor revierte una decisión de ADR-014 §9; Pago "solo cajero y supervisor" contradice a Carlos del 02/10 (RV3-01). Cada una se había acordado antes con el cliente o con Carlos. Mitigación: cada una tiene ADR o Actualización y una pregunta explícita al cliente (QC-1, QC-12, QC-17) o una decisión de Carlos (D3-7, D3-19); las siete menciones de la regla vieja del cierre se corrigen juntas (G6) o el manual contradice al sistema.
  • R-7. Migraciones de datos de catálogos (G10, G11, G9.8). Renombrar una etiqueta de país, de ciudad o de tipo de ID es retroactivo en reimpresiones y reexports (cambia el texto, no el país guardado). La lista de municipios de Guatemala se compiló sin verificar contra la fuente (unos 338 de 340; QC-29) y se carga en un reporte regulatorio. Los códigos internos XA a XZ para entidades sin ISO podrían chocar algún día con los que asigne ISO o Soterex. Una migración de datos que falla en el deploy corta el deploy (las migraciones esperan la base, PR #75). Mitigación: idempotentes, con el mismo guard que B1.2 (sin países operativos no hacen nada), un renombre se aplica solo si la etiqueta sigue siendo la sembrada (P3-10), nada se desactiva, y los casos dudosos no se cargan hasta tener la respuesta (QC-27). El orden de los desplegables depende del collation de la base (en_US.utf8 en dev; en Aurora, no determinado).
  • R-8. G4 mueve cifras que ya se reportaron. Si el PDV de un pago pasa a ser el de la caja, cambian los números por PDV de Volumen, Dashboard y Cumplimiento para quien tiene un PDV activo distinto de su caja; el backfill (D3-8) modifica filas de transactions pagadas (no sus datos de pago, que son inmutables). Sin PDV, el pagador acotado no ve su propio pago. Mitigación: D3-7 opción (b) (solo llena huecos; el caso de las capturas, PDV activo distinto del de la caja, queda como está salvo que Carlos elija (a)), backfill idempotente con evento de Auditoría que lleva solo un conteo, y el OK explícito de Carlos.
  • R-9. Datos personales en las capturas, en el Excel y en lo que se publica. El Excel de ajustes trae 33 capturas reales de Staging; la imagen 10 muestra un correo y una dirección tipeados a mano que parecen reales, y las demás exhiben beneficiarios, documentos y teléfonos. doc/ se publica en el sitio salvo reference/, y no hay autenticación: un .xlsx o una captura fuera de reference/, o pegados en este plan, quedan públicos. Los soportes subidos a un bucket nuevo (G1) son identificaciones. Mitigación: G0.2 (el .xlsx queda sin trackear hasta revisar las 33 imágenes; alternativa: un volcado de texto sin imágenes), este plan cita solo los MTCN que el cliente cita, ninguna entrega de este plan escribe nombres de archivo, montos ni datos del beneficiario en la metadata de Auditoría (H3-09; D3-25 aclara la regla para los importes), y se le pide al cliente que use datos de prueba (6.0).
  • R-10. Hay entregas bloqueadas por decisiones y la cola de decisiones es larga. Son 26 decisiones para Carlos (§3.3) y 35 preguntas vigentes para el cliente (§6.1; 39 numeradas, 4 retiradas o diferidas). Las que frenan son: D3-1 (G1), D3-12 y D3-13 (G6.B), D3-14 (G7), D3-15 (G11), D3-11 (migración de G8), D3-20, D3-21 y D3-26 (G13); y las de cliente QC-12, QC-16, QC-27, QC-30, QC-33 y QC-34 a QC-39. Mitigación: §2 marca qué se puede arrancar hoy; los valores por defecto de §6 permiten a Carlos autorizar el arranque sin respuesta, entrega por entrega y dejando constancia; nada de lo bloqueado está en el camino crítico de lo que sí se puede hacer.
  • R-11. El tamaño del plan. Son 14 entregas (8 M y 6 L, entre 25 y 45 días-persona sin las esperas), diecisiete PRs de entrega (cada uno una tajada desbloqueable, más el PR 0 y el 0b) y nueve entregas que pasan por security. Se pisan en PermissionService, TransactionController, DocumentacionPago.vue y useTransactionDocuments.ts. El riesgo es acumular PRs abiertos y resolver conflictos al final. Mitigación: apilar solo donde el código se pisa de verdad (G2→G4.1, G4.2, G4.6 y G4.7; G6.A→G6.B y G7; G10→G11; G12→G13; G5 sale después de G2), el orden de §2 y mergear de a uno, no abrir un PR de G13 mientras no haya respuestas; cada entrega termina con su documentación o no termina.
  • R-12. Confiar en una documentación que ningún test cuida. El CI de PR no corre vitest ni docs:build; el manual, la tabla de roles, el menú del sitemap y los motivos de fondeo son copias a mano (§5.7). Mitigación: G0.8 pone npm test (job frontend) y npm run docs:build (job nuevo docs, con working-directory: doc) en el CI de PR; hasta entonces, correrlos a mano antes de cada PR con front o documentación, y abrir los diagramas Mermaid que cambian.
  • R-13. Construir sobre una causa que se leyó pero no se reprodujo. RV3-14 (quién pagó y quién imprimió), RV3-17 (quién pagó la fila 2916186807), RV3-41 y H3-04 (la matriz de Staging), Escuintla Norte con 0 cajas (G7), H3-03 y H3-02. Mitigación: las diez consultas de solo lectura de G0.6 corren antes de la entrega que las usa, y eso supone el PR 0b ya promovido a Staging (sin él el comando diagnostico:v3 no existe allá); y para H3-03 el primer paso es escribir el test que reproduce el caso.
  • R-14. Un archivo que lee un regulador (G9). No se adivina la grafía de "Send/Sent" ni el idioma del Update; imprimir "C-" si Soterex no lo usa, o no imprimirlo si lo usa, son dos errores; renombrar un PDV cambia cómo se reimprimen recibos viejos; el A4 sin el quinto inciso puede dejar de desbordar los tests de densidad. Mitigación: configuración reversible (P3-8), la muestra con OK explícito (D3-23), y abrir el A4 y el Excel con datos de demo.
  • R-15. El estado de Staging no es el del código. StagingTestUsersSeeder no se corrió: sin la cuenta de Tesorería el cliente no ve el perfil y puede creer que no existe; StationSeeder es updateOrCreate: correrlo a mano revierte nombre, dirección y ubicación de los PDV reales; demo:reseed borra el estado de prueba del cliente; el login estuvo roto entre el 02/10 y el 04/10. Mitigación: las precondiciones de G0.4, y no correr ningún seeder en Staging sin avisar.
  • R-16. Tesorería: un número que cambia y una fricción que aparece (G12, G13). G12 cambia el saldo que ven hoy los usuarios con alcance parcial y revierte en parte una decisión consciente de ADR-015; G13 agrega una confirmación que, con un único perfil de Tesorería, puede hacer quien cargó el envío (en agosto Diego descartó la firma del Supervisor porque agregaba un paso sin trazabilidad). La alerta, sin mail, solo se ve si alguien abre la pantalla. Mitigación: la opción (b) de D3-19 no oculta pantallas; las confirmaciones nunca condicionan pagar ni cerrar la caja (P3-7); la autoconfirmación se muestra, no se bloquea.

8. Fuera de alcance (a propósito) ​

Cada ítem dice por qué; donde hay una condición para reabrirlo, también.

  • Un selector de perfil o una "asignación activa" (RV3-49): decisión firme de Carlos (D3-T2). Lo reabriría que la mezcla produzca un riesgo que ni la documentación ni la advertencia opcional (D3-24) cubran.
  • Un rol "Tesorería Local" o cualquier rol nuevo (RV3-48, RV3-73): decisión firme (D3-T1). Tesorería es un solo perfil y es regional por asignación. Tampoco una etiqueta "Regional / Local" derivada en la ficha de usuario (G12).
  • La integración C2P: C2PController, OAuth, SendRequest y Cancel no se tocan (P3-13). Las consultas a Soterex (6.2) son solo consulta. Tampoco se sincronizan las dos copias del OpenAPI de C2P (Anexo A-4).
  • El Escenario 2 de tesorería (Soterex prefondea a cada país): necesita el concepto de entidad y de pertenencia país → entidad. Está oculto en el archivo del cliente (RV3-70). Tampoco el "Saldo final CIS Holding" de 32.708 hasta QC-33.
  • Cambios al Dashboard (RV3-74, C3-13), hasta que el cliente defina el escenario.
  • Mail, push o scheduler para la alerta de reposición, un umbral distinto por nivel o entidad, la alerta en el Dashboard, un estado de "solicitud de prefondeo" (G13.A, "Fuera"). Los reabre QC-35 a QC-36. La columna de porcentaje en los extractos no está fuera de alcance: es G13.C (QC-39).
  • Un estado "pendiente" de recepción que no suma al saldo: rompe ADR-007 (D3-20 b). Las confirmaciones son una marca.
  • El pago por transferencia y un catálogo de formas de pago (D3-4, D3-5): si vuelve, no hay nada diseñado y no es un cambio chico. Tampoco reescribir los datos de pago de las PAID históricas (D3-4 c): son inmutables (ADR-011); la atribución al PDV sí se completa desde el ledger (D3-8).
  • Un control preventivo en backend contra "nadie fondea la caja que abrió" (D3-24 c): cambia una regla que Tesorería pidió detectiva (ADR-007 §4).
  • El costo bancario de la acreditación (RV3-58, C3-8): lo asume quien recibe y no es parte del control del prefondeo.
  • La comisión por tramos: sigue mandándola Soterex en cada transacción (RV3-69).
  • El dígito verificador del DPI (G11): no lo pidieron.
  • Cargar entidades dudosas (Somalilandia, Chipre del Norte, "Santo Tomas") y desactivar Antártida sin la respuesta de QC-27.
  • Mantener el orden "#" de la lista de países (QC-28): el desplegable sigue alfabético.
  • Una referencia (OpenAPI, Scalar) de la API interna: hoy no existe y este plan no la crea; el contrato queda en el ADR de cada entrega y en los tests (§5.6).
  • Tours nuevos o anclas nuevas (§5.4), capturas automatizadas del manual con Playwright (E4 del plan del manual), la auditoría de seguridad completa (E6) y todo lo que sea producción: nada de este plan se aplica a producción.
  • Cierre automático de caja y todo lo que necesite el scheduler de Staging.
  • Una "fecha valor" distinta de la fecha de carga en los extractos (RV3-22).

Anexo — Lo que encontramos al relevar y no es de este plan ​

Para que no se pierda. Cada uno dice su evidencia; ninguno está comprometido en G0 a G13 salvo A-1 y A-3 (G0.8).

  • A-1. Documentación desactualizada (ocho documentos con evidencia, más los siete planes de QA): ver §5.8. Los absorbe G0.3.
  • A-2. El PDF del manual probablemente sale vacío en Staging. Confianza media: leído, no ejecutado. ManualPdfService lee base_path('..').'/doc/manual' (backend/app/Services/ManualPdfService.php:31 y :183), que en el contenedor es /doc/manual. El workflow hace docker build ./backend, backend/Dockerfile copia solo backend/ y la task de ECS no monta ningún volumen (infra/terraform/modules/ecs/main.tf). En dev anda porque docker-compose.yml monta ./doc:/doc:ro (L112 y L168). El glob() daría vacío y el PDF saldría con portada y sin secciones. Los tests de CI no lo detectan porque corren en el checkout completo. Bajar un PDF desde Staging antes de prometerle al cliente "el manual por perfil actualizado" (G8 regenera los cuatro).
  • A-3. El CI de PR no valida la documentación. .github/workflows/ci.yml corre en el backend Pint y php artisan test (incluye ManualPdfTest y PerfilesMigrationTest) y en el frontend solo npm audit y el build; el paso type-check --if-present no hace nada si el script no existe. No corre npm test (G0.8 lo corrige): quedan afuera manual.spec.ts, AppLayout.spec.ts, firstAllowedRoute.spec.ts, guardPorPerfil.spec.ts, los de tour/ y PrefondeoView.spec.ts. Tampoco npm run docs:build: solo lo corre el job deploy-docs de deploy-staging.yml. No hay plantilla de PR ni CODEOWNERS (.github/ solo tiene workflows/), así que el checklist "si tocás una pantalla, revisá su archivo del manual" es puramente humano. Este plan lo toma como G0.8: sumar npm test (paso del job frontend) y npm run docs:build (job nuevo docs: el script está en doc/package.json, no en el del frontend) al CI de PR.
  • A-4. Dos copias a mano del OpenAPI de C2P que ya divergieron. doc/site/public/openapi.yaml (562 líneas, español, el portal Scalar detrás de login) y doc/integracion/cis-latam-soterex-c2p-openapi-v2.yaml (732 líneas, inglés, con el webhook y schemas más completos; la que se le mandó a Soterex y se actualizó en #57). Ningún test ni job las valida contra el código ni entre sí. No se toca (P3-13).
  • A-5. Decisiones tomadas y sin ADR. El formato de recibo por país y que el A4 conviva con la tirilla (P9) vive solo en el plan v2 (L142 y L159) y en 03-papeleta.md §3.1. CLAUDE.md dice que E7 todavía debe los ADR de "Pago como home de Backoffice", "Caja opcional por país" y "no aprobación de supervisor": están implementadas y falta el registro. La regla de unión de asignaciones estaba repartida entre ADR-014 §6, su Consequences, el manual y un docblock de PermissionService; D3-T2 la junta en un subapartado de ADR-014 §6.
  • A-6. El sitio publica más de lo que muestra. Se publican también doc/manual/*.md (huérfanos del menú), doc/integracion/ y doc/informes/, sin autenticación. Ver R-9.
  • A-7. Copias a mano de un mismo dato, sin test: la tabla 2.1 de 02-roles-permisos.md, el Mermaid del menú en 01-sitemap.md, las tablas de doc/manual/01-perfiles-y-menu.md, NAV y MOBILE_LABELS de AppLayout.vue, los motivos de fondeo y ajuste (05-ux §5.3 y manual 32), las 36 columnas del manual 61 contra ReporteCumplimientoService, los números de la planilla en 01-modelo-de-saldos.md §1.10 y ADR-015 §3, y las etiquetas de Auditoría (AuditoriaView.vue contra el manual 90). Lo que sí tiene red: la matriz, las etiquetas de módulo, la cantidad de archivos y secciones del manual y los enlaces internos.
  • A-8. Dos planes se llaman "v3". Este es Ajustes v3 (G0 a G13). Existe Plan v3 — Estabilización (doc/plans/2026-09-13-plan-v3-estabilizacion.md, F1 a F6), y el plan v2 cita "F2 del plan v3" para el aviso de sobregiro de la Holding (ADR-010), que sigue sin ejecutarse. G13 no lo toca: es otra familia de avisos. Conviene no mezclarlos al hablar.
  • A-9. La regla "sin montos en la metadata de Auditoría" hoy no se cumple para los importes del ledger: CASH_SESSION_OPENED/CLOSED guardan saldos y CASH_FUNDED, CASH_ADJUSTED, PREFUNDING_ENTRY_CREATED y COUNTRY_PREFUNDING_ENTRY_CREATED guardan el monto (D3-25). No bloquea nada; todo lo nuevo de este plan va sin montos.
  • A-10. Ruido al buscar en el repo. .claude/worktrees/** tiene ocho worktrees con copias de doc/ y frontend/ de otras ramas: un grep sin excluirlos devuelve resultados de versiones viejas. doc/plans/reference/ contiene .vue y .ts de referencia, no documentación, y doc/design/backoffice-home-final.html es un mock histórico.
  • A-11. Correcciones que se hicieron al cerrar este plan sobre el borrador de §1 a §4, por evidencia: (1) el borrador decía que tres PRs pasan por security y los encabezados de G2, G5 y G11 también lo piden (§2); (2) decía web_max_count = 4 para Staging y es 2 (infra/terraform/environments/staging/main.tf:84; 8 en producción, 4 el default del módulo); (3) la fila RV3-79 tenía pipes sin escapar que rompían la tabla de §1.1; (4) el conteo de G0 era "~45" y son 42 filas de §1.1 (38 se cierran solo con respuesta); (5) QC-5 y QC-18 no estaban definidas (QC-18 solo aparecía en el encabezado de G8) y se definieron a partir de su contexto en §6.1; (6) un nombre de migración con una fecha a medias (2026_10_XX) pasó a decir que el prefijo lo pone artisan make:migration; (7) §2 decía que G8 y G6.B cambian permisos de usuarios reales, pero G6.B, con la opción recomendada de D3-13, no toca la matriz; (8) §2 decía que el prefijo "C-" de G9 espera a QC-21 y depende de D3-18, que lo recomienda ahora y reversible (QC-21 solo lo confirma).
  • A-12. Correcciones que se hicieron al revisar este plan (2026-10-04, tres revisores independientes: completitud, consistencia y calidad de las entregas), por evidencia: (1) RV3-28 no era una pregunta: el cliente dibujó la línea en un cuadro de texto que el volcado a texto no muestra (G6.C pasa a ✅); (2) el Escenario 2 está oculto en el archivo del cliente (RV3-70 y RV3-71 pasan a informativos); (3) la columna de porcentaje del ejemplo no se descarta (G13.C, QC-39); (4) las capturas del cliente muestran un pago cuyo PDV no es el de su caja (RV3-17, causa 6; D3-7); (5) "confirmaron el 24 de julio" valía para multipaís y multi-PDV, no para sumar permisos dentro de un mismo país (D3-T2); (6) el 422 de G2.2 se montaba sobre un null ambiguo y pasa a salir con G4.1; (7) el permiso del porcentaje de reposición no puede ser abm_configuracion (D3-21); (8) D3-19 (b) y D3-7 revierten decisiones escritas que R-6 no nombraba (ADR-007 §1, E4-multi §2.3); (9) la corrección de cajas por transferencia exige abrir cada caja (D3-6); (10) la muestra para el OK sale después de G8, G9 y G12 (G0.9); (11) faltaban la sección "Cómo se ejecuta", los usuarios de prueba (G0.7), el job de CI (G0.8) y el canal de las consultas de G0.6; (12) G5, G6 y G8 pasan a L y se cortan en tajadas de PR; (13) la lista de entregas con security pasa de seis a nueve; (14) "Staging se promovió 11 veces" desde el 29/9 (eran 9 desde el 30/9); (15) la pregunta 21 de 06-preguntas-abiertas-caja.md no se cierra por silencio.
  • A-13. Correcciones de la segunda pasada (2026-10-05, verificación final contra el código y los workflows): (1) G0.8, §5.7, R-12 y A-3 ponían npm run docs:build en el job frontend, pero ese script vive en doc/package.json y el job corre con working-directory: frontend: pasa a un job nuevo docs (working-directory: doc, su propio npm ci); npm test sí queda en frontend; (2) la fila de G11 en §2 omitía el RV3-86 que §1.1 y el encabezado de G11 sí listan; (3) RV3-75 decía "225 + 23 + los 5 casos de RV3-76" (253); el desglose de G10 cierra en 255 (225 + 23 + 2 + 3 + #216 + Timor repetido); (4) la pregunta #6 de 06-preguntas-abiertas-caja.md (la caja que paga puede ser de otro PDV) la contesta D3-7 y no figuraba en los docs de G4 ni en §5.1; (5) las consultas de G0.6 con base de datos necesitan que el PR 0b esté mergeado y promovido a Staging (el comando diagnostico:v3 corre sobre la imagen ya desplegada), y el resumen, el orden recomendado y "Cómo se ejecuta" no lo decían; la consulta 7 (DevTools y CloudWatch) y la parte de la 10 que se lee en los logs del ALB no dependen de ese lote.

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