Skip to content

Prompt de ejecución — Ajustes v2 (Soterex GT) ​

Date: 2026-10-01 Uso: copiar el bloque de abajo como primer mensaje de una sesión nueva de Claude Code en este repo. El plan que ejecuta es doc/plans/2026-10-01-ajustes-v2-cliente-gt.md.


Sos el product owner de este proyecto (Soterex / CIS Latam) y coordinás la ejecución de un plan ya
aprobado. Activá el skill `product-owner` y usá los agentes o skills que necesites:
`backend-dev`, `frontend-dev`, `ui-engineer` para el recibo A4 y las pantallas de extracto,
`architect` para los tres ADRs, `tech-writer` para el manual y el análisis funcional,
`code-reviewer` antes de cada PR, y `security` antes del PR de perfiles (B6) y sobre el reporte de
Cumplimiento (B4), que exporta datos personales.

Carlos está durmiendo. Nadie va a contestar preguntas durante la ejecución: trabajá de corrido y
dejá todo por escrito.

Leé primero `CLAUDE.md` y respetá todo lo que dice: el stack está cerrado (Vue 3 + Laravel 13 +
Aurora; no propongas alternativas), toda decisión de arquitectura nueva va a un ADR en
`doc/architecture/`, y el estilo del repo es español rioplatense, con comentarios que explican el
PORQUÉ y no el qué.

## Qué vas a hacer

Ejecutar las entregas **B1 a B7** del plan `doc/plans/2026-10-01-ajustes-v2-cliente-gt.md`. Ese
plan es tu fuente de verdad. Leelo entero antes de tocar código, en especial:
- §1 qué respondió el cliente y por qué existe cada entrega.
- §3 **Decisiones** (C1–C13 del cliente, P1–P13 del product owner): ya están tomadas, no las
  reabras.
- §4 el alcance y el "terminado cuando" de cada entrega.
- §5 riesgos. §6 lo que está fuera de alcance. §7 lo que falta del cliente.

**B1.5 no se hace**: está bloqueada por un adjunto que no tenemos.

Las referencias archivo:línea del plan salen de leer el código el 2026-10-01. Verificalas antes de
apoyarte en ellas: pueden haberse movido.

El material del cliente está en `doc/reference/2026-10-01-respuesta-ajustes-v1/`. El Excel del
reporte de Cumplimiento y el modelo Word del recibo **no están en el repo a propósito** (tienen
datos de personas reales): todo lo que necesitás de ellos está transcripto en el plan. No los
busques, no los pidas y no uses datos reales en tests ni en seeders.

## Branches y PRs

Son **tres PRs apilados**, separados por riesgo:

| PR | Branch | Sale de | Base del PR | Entregas |
|---|---|---|---|---|
| 1 | `docs/plan-ajustes-v2-gt` | ya existe, tiene este plan | `main` | B1, B2, B3, B4, B5 |
| 2 | `feature/ajustes-v2-perfiles-menu` | la punta del branch de PR 1 | `docs/plan-ajustes-v2-gt` | B6 |
| 3 | `feature/ajustes-v2-tesoreria` | la punta del branch de PR 2 | `feature/ajustes-v2-perfiles-menu` | B7 |

Al arrancar:

    git fetch origin
    git checkout docs/plan-ajustes-v2-gt
    git pull origin docs/plan-ajustes-v2-gt

Si `main` avanzó, traelo con `git merge origin/main` en el branch de PR 1 y propagalo hacia arriba
con merge. No hagas rebase ni force-push.

## Orden

En secuencia: **B1 → B2 → B3 → B4 → B5**, después **B6**, después **B7**.

- B2 construye el cálculo de saldo corrido que B7 reusa: hacelo reutilizable desde el principio.
- B4 agrega la ciudad del PDV, que B5 imprime.
- B6 crea el rol Tesorería, que B7 necesita.

Si una entrega se traba de verdad, dejá escrito en el PR qué pasó y hasta dónde llegaste, y seguí
con la siguiente que no dependa de ella. B2, B3 y B4 no dependen entre sí.

## Cómo trabajar cada entrega

1. Releé la sección de la entrega y armá tu lista de tareas.
2. Implementá. Los tests van **en el mismo commit** que el código que prueban. Poné el prefijo de
   la entrega en los mensajes de commit (por ejemplo, `feat(caja): B3.2 — la caja opera solo el
   día en que se abrió`).
3. Corré todo lo que aplique y **pegá la salida real** en tu resumen:
   - Backend: `docker exec soterex-backend-1 php artisan test` y `vendor/bin/pint --test`
     (confirmá el nombre del contenedor con `docker ps`)
   - Frontend: `npm run test` y `npm run build` (el build corre `vue-tsc`)
   - Si tocaste Markdown de `doc/`: `npm run docs:build` dentro de `doc/`. Un link roto ahí corta
     el deploy de la documentación.
4. Pasá `code-reviewer` sobre el diff de la entrega y corregí lo que marque. Si no estás de acuerdo
   con un hallazgo, explicá por qué.
5. Push al branch que corresponda. **Al terminar B1**, abrí el PR 1 con `gh pr create`. Con cada
   entrega siguiente, actualizá la descripción del PR con una sección por entrega: qué cambió, cómo
   se verifica, y qué supuestos tomaste. Los PRs 2 y 3 se abren al terminar B6 y B7.
6. Seguí con la siguiente sin esperar respuesta.

**Autorización de Carlos para este plan** (la da al pegar este prompt): podés implementar, testear,
commitear, crear los dos branches nuevos, pushear a los tres branches y abrir o actualizar los tres
PRs **sin pedir confirmación en cada paso**.

**Lo que NO hacés, bajo ninguna circunstancia, porque necesita el ok explícito de Carlos en el
chat y Carlos no está:**
- mergear cualquier PR, a `main` o a otro branch;
- cualquier push, merge o deploy a `staging` o `production`;
- disparar workflows de GitHub Actions a mano (`run-artisan-command`, `terraform-apply`, deploys);
- correr seeders, migraciones o comandos contra staging o producción;
- cualquier operación destructiva (force-push, reset --hard, rebase de un branch pusheado,
  `migrate:fresh` contra algo que no sea tu entorno local);
- mandar mails o mensajes a nadie.

**Si aparece una decisión que el plan no cubre** ni se deduce por analogía directa con algo ya
implementado: no la inventes y no te frenes. Tomá la opción más conservadora y reversible, dejala
detrás de una configuración o de una celda de la matriz si se puede, y anotala en la sección
"Decisiones que tomé sin Carlos" del PR. Si la decisión toca plata, permisos o datos personales y
no hay una opción conservadora clara, dejá esa parte sin hacer y explicá qué falta.

## Reglas que no se negocian

- **Nunca escribas `role_permissions` con los eventos del modelo prendidos.** El hook `saving`
  fuerza `can_delete ⇒ can_write ⇒ can_read` y ya rompió la pantalla Pago una vez (leé el
  comentario de `RoleSeeder::run`). Las migraciones de datos de B1.2 y B6.2 escriben sin eventos.
- **El rol se renombra, no se recrea.** `RoleSeeder` busca por nombre: si cambiás la clave de
  `MATRIX` de `Backoffice` a `Cajero` sin renombrar antes la fila, creás un rol nuevo y dejás a
  todos los usuarios en el viejo. El renombre va en la migración de datos, primero (B6.2).
- **Los cambios de permisos viajan por migración de datos, no por "correr el seeder".** El deploy
  solo corre `migrate`, y `RoleSeeder` pisa lo que se editó desde la app. La migración toca solo
  las celdas que el plan lista.
- **Los permisos se deciden por permiso y alcance** (`PermissionService`, middleware `perm:`), no
  preguntando el nombre del rol. B6.5 saca el caso que queda.
- **No cambies claves de módulo, `name` de rutas ni `data-tour`.** El menú nuevo cambia etiquetas y
  agrupación, nada más.
- **El backend manda.** Toda regla nueva (caja de un día anterior, pagar vs. cancelar, quién ve
  cada extracto, quién exporta Cumplimiento) se valida en el backend con su código de error y su
  test. El frontend solo la refleja. Cada restricción de acceso se prueba también **por API**, no
  solo mirando que el botón no esté.
- **Ningún saldo se materializa** (ADR-005, ADR-007). El saldo corrido de B2 y los extractos de B7
  se derivan del ledger. B7 no cambia cómo se calcula ningún saldo que ya existe.
- **Nada de datos personales ni de plata en logs ni en la metadata de auditoría.** Los extractos de
  tesorería muestran MTCN y montos, nunca datos del beneficiario. El reporte de Cumplimiento se
  audita sin su contenido.
- **Los ítems de catálogo no se borran** (se desactivan) y una migración de datos **no pisa** lo
  que un Admin editó.
- **El medio de pago es siempre efectivo.** No diseñes nada nuevo sobre transferencia.
- **No toques la integración C2P** (`C2PController`, OAuth, `SendRequest`, `Cancel`): está en
  staging esperando a Soterex. La cancelación por API no pasa por los permisos de B6.
- **No mergees `origin/feature/e6-reporte-regulatorio`.** Usalo como material de lectura para B4.
- ADR-012 es el último que existe. Los nuevos son **ADR-013** (B3), **ADR-014** (B6) y **ADR-015**
  (B7). Agregalos a `doc/architecture/index.md`.
- **La documentación es parte de cada entrega, no un pase al final.** El plan tiene una tabla
  ("Documentación: qué se actualiza en cada entrega", al final de §4) con los archivos del análisis
  funcional (`doc/functional/`) y del manual (`doc/manual/`) que toca cada una. Van en los mismos
  commits que el código. Usá `tech-writer`. Una entrega con la pantalla cambiada y el manual viejo
  no está terminada.

## Cómo verificar que cada entrega sirvió (no alcanza con que los tests pasen)

Levantá el stack local (`./start-dev.sh` o los contenedores que ya estén corriendo) y usá los datos
de `php artisan demo:reseed`. Usá el navegador de la sesión para mirar las pantallas.

- **B1:** en una base migrada sin `db:seed`, entrá como Admin a Catálogos: abre en Guatemala y
  están DPI y Pasaporte. Creá un tipo de identificación y usalo en un pago. En el formulario de
  pago, todos los campos menos Notas tienen asterisco. Con un dato faltante, se lee cuál falta sin
  pasar el mouse por el botón.
- **B2:** abrí Estado de Situación y sumá a mano tres filas: el balance final de cada una cierra con
  la anterior y el último coincide con la tarjeta. Exportá a Excel y compará. Poné el filtro de PDV:
  la columna desaparece con su explicación.
- **B3:** abrí una caja, cambiale `opened_at` a ayer en la base local y probá pagar, fondear y
  ajustar (rechazados, con el aviso en Pago y en Caja). Cerrá, abrí y pagá. Mirá el reporte de
  cierres por día.
- **B4:** exportá el reporte y contá las columnas contra la tabla del plan, una por una. Verificá
  que ciudad, provincia y tipo de identificación salgan con la etiqueta. Entrá como Supervisor: la
  pestaña no está y la URL del export da 403.
- **B5:** pagá una transacción con nombre y dirección largos, generá el recibo y **abrí el PDF**:
  una sola hoja A4, dos copias, todos los campos, nada cortado ni encimado.
- **B6:** aplicá la migración sobre una base con la matriz vieja y usuarios Backoffice. Logueate con
  **cada uno de los cuatro perfiles**, en desktop y en ancho de celular: a qué pantalla cae, qué ve
  en el menú, y probá por API lo que no debería poder hacer (Cajero cancelar, Supervisor fondear,
  Admin pagar, Tesorería abrir una transacción).
- **B7:** cargá a mano el ejemplo de la planilla del cliente (tabla de "terminado cuando" de B7) y
  compará los cuatro extractos número por número. Entrá como Supervisor de un PDV e intentá ver el
  extracto de otro.

## Al terminar

Dejá en el chat, y en la descripción del último PR que hayas tocado, un resumen para que Carlos lo
lea al despertarse:

1. Los links de los tres PRs y el estado del CI de cada uno.
2. Por entrega: hecha, parcial o sin hacer, qué verificaste a mano y qué no, y **qué archivos de
   documentación actualizaste** contra la tabla del plan.
3. **Decisiones que tomaste sin Carlos**, una por línea, con qué cambiaría si se revierte.
4. Lo que le toca hacer a él, en orden: revisar y mergear PR 1, después 2, después 3; avisarle al
   cliente antes del deploy de B6; el deploy a staging; correr el seeder de usuarios de prueba.
5. Lo que encontraste roto o raro y no era de este plan.

Si algo quedó sin probar, decilo: es más útil que un "listo" que no se sostiene.

Por qué el prompt está escrito así ​

  1. No repite el plan: apunta a él. Así no hay dos versiones de la verdad si el plan se ajusta cuando llegue el adjunto que falta.
  2. Asume que nadie contesta. El de la v1 decía "preguntá antes de decidir". De noche eso frena todo. Este dice qué hacer con una decisión no cubierta: la opción conservadora, anotada, o dejar la parte sin hacer.
  3. Lista lo prohibido por nombre, incluidos los workflows manuales y los seeders contra staging. B6 cambia permisos de usuarios reales: lo único que separa un PR de un incidente es que nadie lo despliegue sin mirar.
  4. Marca el renombre del rol como el cambio peligroso. El camino obvio (cambiar la clave del seeder) crea un rol nuevo en silencio y deja a todos con los permisos viejos.
  5. Pide probar las restricciones por API. En este proyecto ya pasó que el botón no estaba y el endpoint respondía igual.
  6. Pone la verificación manual por encima de los tests, con un paso por entrega que solo se puede hacer mirando: el recibo, el menú de cada perfil, los números de la planilla.

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