Skip to content

Ambiente: Development ​

Status: ✅ Stack completo levantable con ./start-dev.sh Última actualización: 2026-10-02 (B7 — qué usuario de prueba ve qué extracto de tesorería; antes, B6.7: cuatro perfiles y un usuario de Tesorería, y B1.2: los datos de referencia llegan con migrate)

Qué corre hoy en Dev (todo vía Docker Compose) ​

ServicioImagen/BuildPuertoRol
frontendfrontend/Dockerfile.dev (Vue 3 + Vite)5173 (+ detrás de traefik)UI de la web app
backendbackend/Dockerfile.dev (Laravel 13 + PHP 8.5)3000 → 8000API propia
backend-queuemismo build que backend—php artisan queue:work (jobs encolados)
backend-schedulermismo build que backend—php artisan schedule:work: corre c2p:expire (el vencimiento del MTCN) y notifications:deliver (el outbox de Notifications a Soterex) cada minuto, en ese orden
postgrespostgres:17-alpine5432Base de datos (en staging/prod: Aurora PostgreSQL — ver ADR-003)
redisredis:7-alpine6379Cache + colas
firebase-emulatorinfra/firebase-emulator/Dockerfile9099 (auth) / 4000 (UI)Firebase Auth sin tocar el proyecto real
admineradminer:latest8081Administración visual de Postgres
docsnginx:alpine (sirve doc/site/public/)— (detrás de traefik)Portal de documentación de API (Scalar + login vía emulador)
traefiktraefik:v3.380Reverse proxy — expone frontend, docs-vitepress y docs en sus dominios .localhost
docs-vitepressdoc/Dockerfile.dev (VitePress)— (detrás de traefik)Sitio de documentación del proyecto (Análisis Funcional, ADRs, planes, QA)

Todavía no conectado: integración real con Soterex (sandbox) y el proyecto Laravel existente de Soterex que el cliente va a compartir (ver ADR-002).

Cómo levantar el ambiente Dev ​

bash
git clone git@github.com:raxardev/soterex.git
cd soterex
./start-dev.sh

El script:

  1. Verifica que Docker/Docker Compose v2 estén instalados.
  2. Genera backend/.env y frontend/.env.local desde sus .env.example la primera vez (nunca pisa un .env que ya exista).
  3. Levanta todo el stack con docker compose up --build.

URLs una vez levantado:

Datos iniciales y usuarios de desarrollo (seed) ​

bash
docker compose exec backend php artisan migrate --seed

Se puede correr las veces que haga falta sin duplicar nada. Crea el catálogo base (roles + matriz de permisos del funcional §2.1, países — Guatemala con el módulo Caja activo y quetzales como moneda local — y los catálogos de los combos del pago: la lista de países de Cumplimiento (251, G10), departamentos y municipios de Guatemala, tipos de identificación DPI y Pasaporte con su formato, G11) y, solo en local, la estructura de desarrollo: 4 PDVs de Guatemala y los 4 usuarios dev (uno por perfil).

Los seeders pisan lo que hayas editado. CatalogCountrySeeder y CatalogGuatemalaSeeder usan updateOrCreate: si en tu base local desactivaste un ítem, le cambiaste la etiqueta o editaste las reglas de formato de un tipo de identificación (G11) desde la pantalla Catálogos, un db:seed completo lo deja como el seeder. RoleSeeder hace lo mismo con la matriz de permisos: revierte a la del seeder cualquier permiso que hayas editado desde la app. Para volver a crear solo los usuarios de desarrollo (por ejemplo, tras reiniciar el emulador) alcanza con docker compose exec backend php artisan db:seed --class=DevUserSeeder, que no toca catálogos.

Los datos de referencia también llegan con migrate (B1.2) ​

Desde el 2026-10-01 (doc/plans/2026-10-01-ajustes-v2-cliente-gt.md, B1.2) los datos de referencia no dependen de que alguien corra db:seed: la migración 2026_10_01_100000_b1_datos_de_referencia_y_permiso_abm_catalogos.php crea, en una base que ya tiene roles, la fila de permiso abm_catalogos (Admin con todo, el resto en 0) y, si además tiene países, los catálogos base. Es lo que hace el deploy a Staging, que corre migrate y no seeders (ver doc/environments/staging.md).

Qué significa para tu entorno local:

  • Una base local anterior a B1.2, que ya tiene roles y países, recibe esos datos con un php artisan migrate, sin necesidad de db:seed. La migración crea lo que falta y no pisa lo que existe, y correrla de nuevo no cambia nada.
  • Un clone nuevo necesita migrate --seed (o migrate:fresh --seed) la primera vez. Con migrate solo la base queda sin roles ni países: la migración de datos nunca los crea, así que salta todo lo demás y no falla. Los roles y los países los siembran RoleSeeder y CountrySeeder.
  • Un módulo nuevo en la matriz de permisos, un ítem nuevo de catálogo o el cambio de la etiqueta de uno que ya existe necesita una migración de datos (helpers EnsureRolePermissions, EnsureCatalogItems y EnsureCatalogLabels, en backend/app/Support/DataMigrations/; este último renombra solo lo que sigue siendo la etiqueta sembrada). Con agregarlo a RoleSeeder::MATRIX o a backend/database/data/*.php alcanza para tu base local (db:seed), pero no llega a Staging.

También crea los usuarios de desarrollo en el emulador y en la base (DevUserSeeder):

EmailPasswordRolAlcance
admin@cislatam.testAdmin123!AdminGuatemala, todos los PDVs
supervisor@cislatam.testSuper123!SupervisorGT-CAP-001 + GT-QUE-002
backoffice@cislatam.testBackoffice123!CajeroGT-CAP-001
tesoreria@cislatam.testTesoreria123!TesoreríaGuatemala, todos los PDVs

Son contraseñas de prueba, y no todas valen solo para el emulador: admin@, supervisor@ y backoffice@ son las mismas que StagingTestUsersSeeder creó en el Firebase real de Staging, y siguen siendo esas hasta que se roten (pendiente de Carlos, ver Staging). La de tesoreria@ sí es solo local: en Staging esa cuenta no usa esta, el seeder la crea con una contraseña generada.

supervisor@ tiene dos PDV y ningún PDV activo (G2.2/G4a, ADR-020): para subir el primer documento de una transacción o pagar necesita una caja abierta (el PDV de la transacción es el de esa caja) o que admin@ le fije el PDV activo en su ficha. Sin ninguna de las dos, el sistema responde 422 ACTIVE_STATION_REQUIRED. Es lo previsto, no un bug de los datos de demo.

El Cajero conserva el mail backoffice@. Es el Backoffice de antes: la migración de B6 renombró el rol (no creó otro) y el usuario ya existía en el emulador y en Firebase, y los Demo*Seeder lo buscan por ese mail. Cambiarle el mail rompería los datos de demostración sin ganar nada. Cada usuario sirve para mirar un perfil entero: el Cajero cae en Pago, el Supervisor, Tesorería y el Admin en el Dashboard (ver el manual).

Para probar los extractos de tesorería (B7): tesoreria@ y admin@ ven los cuatro (Prefondeo Soterex y Fondeo PDVs, con sus pestañas); supervisor@ entra a Fondeo PDVs y ve solo la pestaña PDV de GT-CAP-001 y GT-QUE-002 — por API, el extracto de otro PDV de Guatemala (por ejemplo GT-MIX-003) y los otros tres extractos le responden 403. Esos usuarios están solo en Guatemala y la base tiene también los países SV y HN, pero inactivos y sin movimientos, y un país así no cuenta como uno que falta (G12): los dos extractos de la Holding y la tarjeta de Prefondeo Soterex salen sin aviso de parcial. Para ver el aviso azul y la tarjeta Saldo de la Holding — de sus países hace falta que a la persona le falte un país que cuente: lo más simple es activar SV desde Parámetros › Países con admin@ (y desactivarlo al terminar). Un país inactivo con movimientos también cuenta, pero un asiento de la Holding queda para siempre —los asientos no se borran desde la app— y demo:reseed solo limpia los de Guatemala. Los pasos de prueba están en el plan de pruebas de G12. Para volver a los números base de Guatemala, php artisan demo:reseed contra la base local.

El emulador pierde los usuarios en cada restart del contenedor (base en memoria): volver a correr php artisan db:seed los recrea sin duplicar nada (o, más liviano y sin tocar catálogos, php artisan db:seed --class=DevUserSeeder).

Esto deja el ambiente "recién instalado": catálogo + estructura, sin transacciones ni movimiento de caja — para eso ver la siguiente sección.

Datos de demostración (demo:reseed) ​

Plan v3, F1 (doc/plans/2026-09-13-plan-v3-estabilizacion.md): las transacciones, las tres capas de prefondeo, el módulo Caja y la auditoría de ejemplo ya no las siembra db:seed — las siembran Database\Seeders\Demo*Seeder, orquestados por un comando aparte:

bash
docker compose exec backend php artisan demo:reseed

Por qué es un comando aparte y no parte de db:seed: el seeder viejo escribía fechas relativas al momento de correrlo y nunca se volvía a ejecutar (saltaba por MTCN existente), así que a la semana todo el dataset quedaba fuera de las ventanas móviles del Dashboard (hoy/ayer/30 días/8 semanas) y el sistema parecía roto — ver doc/informes/2026-09-13-auditoria-pre-estable.md §3. demo:reseed resuelve esto siendo explícitamente re-ejecutable: borra todo lo que él mismo sembró en la corrida anterior (nunca países/estaciones/usuarios/roles) y lo vuelve a sembrar con fechas relativas a "ahora" — correrlo dos veces seguidas deja el mismo estado, no el doble. Corré demo:reseed cada vez que el dataset se sienta viejo (el KPI "pagado hoy" en cero es la señal más clara). Desde B3 (ADR-013) hay otra señal: las sesiones de caja de la demo se abren "hoy", así que al día siguiente aparecen como "Caja vencida" y no pagan hasta cerrarlas y abrirlas de nuevo. Es la regla funcionando; para volver a un estado limpio, demo:reseed.

Deja: ≈120 ACCEPTED en la bolsa compartida, ≥90 PAID de los últimos 60 días (con pagos de hoy y de ayer), ≥20 CANCELLED, las tres capas de prefondeo cargadas y coherentes entre sí, el módulo Caja con cajas/sesión abierta/movimientos, y auditoría con variedad de acciones. Al terminar imprime un resumen (cantidades por estado, rango de fechas, saldos) para verificar de un vistazo.

Bloqueado fuera de local/staging (--force para saltear el chequeo, nunca en production): a diferencia de los seeders de catálogo, este comando borra transacciones y movimientos de caja de Guatemala.

⚠️ Catch-up puntual (2026-10-02, B6): los cuatro perfiles. Si tu base local es anterior a B6 —el rol sigue llamándose Backoffice y no existe Tesorería— alcanza con

bash
docker compose exec backend php artisan migrate
docker compose exec backend php artisan db:seed --class=DevUserSeeder

La migración de datos (2026_10_02_130000_b6_perfiles_y_matriz_de_cuatro_roles.php) renombra la filaBackoffice a Cajero —tus usuarios siguen asignados al mismo rol—, crea Tesorería y deja la matriz de cuatro perfiles; el seeder crea solo lo que falta (el usuario de Tesorería, en el emulador y en la base). No corras db:seed completo ni RoleSeeder para esto: pisan los permisos que hayas editado desde la app, y el deploy tampoco los corre (ver staging.md). Un db:seed suelto sobre una base sin migrar tampoco crea un Cajero vacío: RoleSeeder renombra primero.

La migración solo toca las celdas que cambian de B6. Una base local muy vieja puede tener otras celdas que el seeder cambió después, y que la migración no trae (por ejemplo, transacciones con lectura apagada para el Cajero, que de A5.1 en adelante tiene que leer lo suyo): se nota porque «Reporte individual» no aparece en su menú. Para alinear TODO con el seeder en una base de desarrollo, db:seed --class=RoleSeeder, sabiendo que revierte cualquier permiso que hayas editado a mano.

Crear un usuario de prueba adicional en el Firebase Auth Emulator ​

Los usuarios estándar de desarrollo los crea el seed (ver sección anterior). Para un usuario ad-hoc extra:

bash
curl -X POST 'http://localhost:9099/identitytoolkit.googleapis.com/v1/accounts:signUp?key=fake-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"email":"otro@cislatam.test","password":"secreto123","returnSecureToken":true}'

O manual: abrir http://localhost:4000 → pestaña Authentication → agregar usuario con email/password. Ojo: un usuario creado así existe solo en el emulador — no tiene fila en users ni rol asignado en la base.

Variables de entorno (Dev) ​

Ver backend/.env.example y frontend/.env.example — se copian automáticamente a .env / .env.local la primera vez que se corre start-dev.sh, que además genera el APP_KEY y una service account fake en backend/storage/firebase/dev-service-account.json (el SDK de Firebase exige una credencial con forma válida aunque hable con el emulador; nunca se commitea).

Validación end-to-end (2026-07-25) ​

Primera corrida real de composer install + ./start-dev.sh en un entorno con acceso a Packagist. Todo el stack levanta y quedó validado end-to-end:

  • composer install OK (Laravel 13.22, PHP 8.5.8) — hubo que corregir constraints inventados del scaffold: laravel/sanctum ^5.0 → ^4.0 (v5 no existe), laravel/tinker ^2.10 → ^3.0 y kreait/laravel-firebase ^6.1 → ^7.0 (las versiones anteriores no soportan Laravel 13). composer.lock commiteado a partir de acá.
  • Las 11 migraciones corren limpias contra Postgres 17.
  • Auth end-to-end: usuario creado en el Auth Emulator → GET /api/transacciones con Authorization: Bearer <idToken> → 200; sin token → 401.
  • Health check: GET http://localhost:3000/up → 200. Queue worker y scheduler corriendo.

Arreglos de scaffold que hicieron falta (ya aplicados): .firebaserc faltante en infra/firebase-emulator/, start-dev.sh sin permiso de ejecución, bootstrap/cache/ y storage/framework/* faltantes (con sus .gitignore), backend/.gitignore faltante, y el @import de Google Fonts después de Tailwind en frontend/src/style.css (el browser lo ignoraba y las fuentes no cargaban).

Segunda ronda (frontend, validado con browser real headless — login + API):

  • frontend/.env.example venía con VITE_FIREBASE_API_KEY vacía → getAuth() tiraba auth/invalid-api-key y la app no montaba. En dev contra el emulador alcanza cualquier string no vacío (fake-api-key) + VITE_FIREBASE_PROJECT_ID=demo-soterex — ya vienen cargados en el example.
  • El router guard trataba loading=true como "dejar pasar" → cualquier ruta privada renderizaba sin sesión en el primer load. Ahora el guard espera (untilReady()) a que Firebase resuelva el estado inicial.
  • Carrera intermitente al loguear: signIn() resolvía antes de que onAuthStateChanged poblara el store y el guard rebotaba al login. El store ahora setea el user directo del credential.
  • VITE_API_PROXY_TARGET del example apuntaba a backend:3000 (puerto/host inválido en todos los escenarios) → localhost:3000 (docker-compose lo pisa con backend:8000).

E2E de browser verificado (3 corridas): deep-link sin sesión → redirect a /login?redirect=… → login contra el emulador → vuelve a la ruta pedida → api.get('/transacciones') con el Bearer token real → 200 con el email del usuario. Cero errores de consola.

Tests de backend (phpunit) ​

bash
docker compose exec backend php artisan test

Antes de correr la suite completa la primera vez en una sesión nueva, correr el test canario de aislamiento — no toca ninguna tabla, solo confirma que la conexión activa es soterex_test:

bash
docker compose exec backend ./vendor/bin/phpunit --filter=DatabaseIsolationTest

Si ese test falla, no correr nada más — ver el incidente documentado en doc/plans/2026-07-25-plan-desarrollo-modulos.md (aislamiento de base de datos en tests): la suite completa usa RefreshDatabase, que si pierde el aislamiento vacía la base de dev por completo (recuperable con php artisan db:seed, pero mejor evitarlo).

Tests de frontend y qué corre el CI ​

bash
docker compose exec frontend npm run test     # vitest run
docker compose exec frontend npm run build    # vue-tsc (tipos) + build de Vite

El CI (.github/workflows/ci.yml, en cada PR a main, staging o production y en cada push a main) corre tres jobs:

  • Frontend: npm audit, el type-check, el build y los tests de vitest (npm run test). Los specs no corrían en CI hasta el 2026-10-05: una pantalla rota no hacía fallar el PR. Los specs necesitan las VITE_FIREBASE_* (sin ellas getAuth() falla al importar services/api), así que el job copia el .env.example, que trae valores falsos, a .env.local, igual que hace start-dev.sh.
  • Docs — los dos OpenAPI de la API C2P son idénticos: cmp doc/site/public/openapi.yaml doc/integracion/cis-latam-soterex-c2p-openapi-v2.yaml. El contrato con Soterex está publicado en esos dos archivos (ADR-017) y tienen que ser el mismo: un cambio en uno exige el mismo cambio en el otro, o el job falla. La forma de hacerlo es editar uno y copiarlo sobre el otro (cp).
  • Backend: Pint, composer audit y la suite de phpunit contra Postgres 17 y un Firebase Auth Emulator.

Próximos pasos para completar Dev ​

  1. En un clone nuevo, migrar y sembrar la base la primera vez: docker compose exec backend php artisan migrate --seed. Con migrate solo la base queda sin roles, países ni catálogos (ver "Los datos de referencia también llegan con migrate").
  2. Pasar Soterex de mock a real en Configuración cuando Soterex mande la URL de Notifications y el secret de la firma. Es Soterex quien llama a CIS (ADR-012): no hay credenciales de sandbox de Soterex que esperar. En pausa hasta que lleguen esos dos datos (ver Staging).
  3. Cuando el cliente comparta el proyecto Laravel existente de Soterex, evaluar reuso de su cliente de integración (ver ADR-002).

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