Skip to content

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

Date: 2026-09-28 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-09-28-ajustes-v1-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`, `architect` para el ADR, `tech-writer` para el manual
y la documentación funcional, `code-reviewer` antes de cada PR, y `security` si una entrega toca
permisos o PII (A3 y A5 lo hacen).

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 **A1, A3, A4, A5 y A6** del plan
`doc/plans/2026-09-28-ajustes-v1-cliente-gt.md`. Ese plan es tu fuente de verdad. Leelo entero antes
de tocar código, en especial:
- §2 **Decisiones aprobadas (D1–D12)**: ya están tomadas, no las reabras.
- §3 el alcance y el "terminado cuando" de cada entrega.
- §4 riesgos.
- §5 lo que está fuera de alcance.

**Los perfiles no se tocan.** Siguen los tres roles actuales (Backoffice, Supervisor, Admin). Donde
el plan o el Excel del cliente dicen "cajero", es el rol **Backoffice** actual. A2, A7 y A8 **no**
se hacen.

Las referencias file:line del plan salen de leer el código el 2026-09-28. Verificalas antes de
apoyarte en ellas: pueden haberse movido.

## Branch

**Todo se trabaja en el branch `docs/plan-ajustes-v1-gt`**, el mismo que ya tiene este plan. No
crees branches por entrega. Al arrancar:

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

Si `main` avanzó mientras trabajás, traelo con `git merge origin/main`. No hagas rebase ni
force-push: es un branch compartido.

## Orden

Como es un solo branch, las entregas van en secuencia:

1. **A1** (arreglos rápidos): primero. Toca archivos que después modifica A3.
2. **A4** (catálogos) y **A3** (datos antes del pago), en ese orden, así A3 ya usa los combos. Si
   A4 se traba esperando algo, hacé A3 con texto libre y conectá los combos al cerrar A4.
3. **A5** (vistas por perfil).
4. **A6** (documentos pendientes): después de A3.

## 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(pago): A1.2 — buscar solo por MTCN`).
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`
   - Frontend: `npm run test` y `npm run build` (el build corre `vue-tsc`)
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 a `docs/plan-ajustes-v1-gt`. **Al terminar A1**, abrí **un solo PR** contra `main` con
   `gh pr create`. Con cada entrega siguiente, actualizá la descripción del PR con una sección por
   entrega (qué cambió y cómo se verifica).
6. Avisá en el chat con el resumen de la entrega y el link del PR, y seguí con la siguiente sin
   esperar respuesta.

Autorización de Carlos (2026-09-28) para este plan: podés implementar, testear, commitear,
pushear a `docs/plan-ajustes-v1-gt` y abrir o actualizar el PR de A1, A3, A4, A5 y A6 **sin pedir
confirmación en cada paso**.

**Siempre necesita el ok explícito de Carlos en el chat:**
- mergear a `main`;
- cualquier push, merge o deploy a `staging` o `production`;
- cualquier operación destructiva (force-push, reset --hard, rebase del branch compartido,
  `migrate:fresh` contra algo que no sea tu entorno local);
- cualquier decisión que no esté en el plan ni se deduzca por analogía directa con algo ya
  implementado. **Preguntá antes de decidirla vos.**

## Reglas que no se negocian

- **Nunca escribas `role_permissions` fuera de `RolePermission::withoutEvents()`.** La cascada
  `can_write ⇒ can_read` rompió la pantalla Pago del Backoffice una vez (ver el comentario de
  `RoleSeeder::run`). A5.1 cambia justo eso: **reproducí primero** qué dependía de que Backoffice
  no leyera transacciones y cubrilo con un test.
- **Los permisos se deciden por permiso y alcance** (`PermissionService`, middleware `perm:`), no
  preguntando el nombre del rol.
- **El backend manda.** Toda regla nueva (datos obligatorios, datos inmutables, quién sube
  soportes, bloqueo del cierre) se valida en el backend con su código de error y su test. El
  frontend solo la refleja.
- **Ningún saldo se materializa** (ADR-005, ADR-007): los saldos se derivan del ledger. La vista
  de totales por PDV de A5 también.
- **Nada de PII ni de plata en logs.** La comisión (`fee`) no se muestra en pantallas operativas.
  No amplíes la PII que devuelve la búsqueda de Pago más allá de las transacciones que el usuario
  puede operar (A1.3).
- **Los documentos son inmutables** y **los ítems de catálogo no se borran** (se desactivan).
- Los `data-tour` del recorrido guiado (ADR-009) apuntan a controles reales. Si movés o sacás uno,
  actualizá el paso del tour.
- ADR-010 ya existe. El ADR nuevo de A3 es **ADR-011**.
- Si el cambio altera lo que ve el usuario, actualizá el manual
  (`/documentacion/manual-usuario`, los Markdown por módulo) en la misma entrega.

## 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, con `docker ps`)
y usá los datos de `php artisan demo:reseed`.

- **A1:** abrí Reportes con Chrome en español y comprobá que no ofrezca traducir y que todos los
  montos salgan igual. Buscá en Pago por nombre (no tiene que encontrar) y por MTCN. Pagá una tx,
  reabrila y comprobá que los datos se vean y no se puedan editar. Imprimí la papeleta y mirá el
  teléfono y el mail. Exportá Transacciones con un filtro y compará con la pantalla.
- **A3:** con una tx ACCEPTED, intentá confirmar con un dato faltante (deshabilitado, con el
  motivo en pantalla). Completá, pagá y comprobá que todo quede en solo lectura. Con otro
  Backoffice, intentá subir un soporte a esa tx: tiene que dar 403.
- **A4:** como Admin, creá una ciudad, usala en un pago, desactivala y comprobá que la tx vieja
  siga mostrándose bien.
- **A5:** entrá como Backoffice. Transacciones muestra solo lo tuyo, la URL de una tx ajena no
  abre, Pago sigue siendo tu inicio y en Caja no ves saldos ajenos. Entrá como Supervisor y
  recorré los totales por PDV.
- **A6:** pagá sin subir la papeleta firmada. Comprobá el aviso, intentá cerrar la caja
  (rechazado, con la lista), subí la papeleta y cerrá.

Contá lo que verificaste y lo que no. 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 lleguen las respuestas del cliente.
  2. Congela los perfiles de forma explícita. El Excel del cliente habla de 5 perfiles. Sin esa aclaración, es fácil que el agente "arregle" la matriz para que coincida con el Excel.
  3. Marca A5.1 como el cambio peligroso. Ya rompió la pantalla Pago una vez en E2.
  4. Pone la verificación manual por encima de los tests. En este proyecto ya pasó que los tests estaban verdes y la pantalla no funcionaba (plan v3, F3).

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