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)
| Servicio | Imagen/Build | Puerto | Rol |
|---|---|---|---|
frontend | frontend/Dockerfile.dev (Vue 3 + Vite) | 5173 (+ detrás de traefik) | UI de la web app |
backend | backend/Dockerfile.dev (Laravel 13 + PHP 8.5) | 3000 → 8000 | API propia |
backend-queue | mismo build que backend | — | php artisan queue:work (jobs encolados) |
backend-scheduler | mismo 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 |
postgres | postgres:17-alpine | 5432 | Base de datos (en staging/prod: Aurora PostgreSQL — ver ADR-003) |
redis | redis:7-alpine | 6379 | Cache + colas |
firebase-emulator | infra/firebase-emulator/Dockerfile | 9099 (auth) / 4000 (UI) | Firebase Auth sin tocar el proyecto real |
adminer | adminer:latest | 8081 | Administración visual de Postgres |
docs | nginx:alpine (sirve doc/site/public/) | — (detrás de traefik) | Portal de documentación de API (Scalar + login vía emulador) |
traefik | traefik:v3.3 | 80 | Reverse proxy — expone frontend, docs-vitepress y docs en sus dominios .localhost |
docs-vitepress | doc/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
git clone git@github.com:raxardev/soterex.git
cd soterex
./start-dev.shEl script:
- Verifica que Docker/Docker Compose v2 estén instalados.
- Genera
backend/.envyfrontend/.env.localdesde sus.env.examplela primera vez (nunca pisa un.envque ya exista). - Levanta todo el stack con
docker compose up --build.
URLs una vez levantado:
- Frontend (Vue): http://localhost:5173, o http://soterex.localhost (sin puerto, vía
traefik) - Backend (API Laravel): http://localhost:3000
- Firebase Emulator UI: http://localhost:4000
- Adminer: http://localhost:8081 (sistema: PostgreSQL, servidor:
postgres, usuario/pass:postgres/postgres, base:soterex) - Sitio VitePress del proyecto (Análisis Funcional, ADRs, planes, QA): http://docs.soterex.localhost (sin puerto — vía
traefik;.localhostresuelve a loopback solo, no hace falta tocar/etc/hosts). Es el link "Funcional" del sidebar (VITE_DOCS_URL). - Portal de documentación de API (Scalar + login): http://docs.api.soterex.localhost — mismos usuarios del seed (en producción se despliega a Firebase Hosting, ver
doc/site/README.md)
Datos iniciales y usuarios de desarrollo (seed)
docker compose exec backend php artisan migrate --seedSe 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.
CatalogCountrySeederyCatalogGuatemalaSeederusanupdateOrCreate: 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, undb:seedcompleto lo deja como el seeder.RoleSeederhace 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 condocker 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 dedb: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(omigrate:fresh --seed) la primera vez. Conmigratesolo 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 siembranRoleSeederyCountrySeeder. - 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,EnsureCatalogItemsyEnsureCatalogLabels, enbackend/app/Support/DataMigrations/; este último renombra solo lo que sigue siendo la etiqueta sembrada). Con agregarlo aRoleSeeder::MATRIXo abackend/database/data/*.phpalcanza 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):
| Password | Rol | Alcance | |
|---|---|---|---|
admin@cislatam.test | Admin123! | Admin | Guatemala, todos los PDVs |
supervisor@cislatam.test | Super123! | Supervisor | GT-CAP-001 + GT-QUE-002 |
backoffice@cislatam.test | Backoffice123! | Cajero | GT-CAP-001 |
tesoreria@cislatam.test | Tesoreria123! | Tesorería | Guatemala, 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:
docker compose exec backend php artisan demo:reseedPor 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
Backofficey no existeTesorería— alcanza conbashdocker compose exec backend php artisan migrate docker compose exec backend php artisan db:seed --class=DevUserSeederLa migración de datos (
2026_10_02_130000_b6_perfiles_y_matriz_de_cuatro_roles.php) renombra la filaBackofficeaCajero—tus usuarios siguen asignados al mismo rol—, creaTesoreríay 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 corrasdb:seedcompleto niRoleSeederpara esto: pisan los permisos que hayas editado desde la app, y el deploy tampoco los corre (verstaging.md). Undb:seedsuelto sobre una base sin migrar tampoco crea unCajerovacío:RoleSeederrenombra 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,
transaccionescon 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:
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 installOK (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.0ykreait/laravel-firebase ^6.1 → ^7.0(las versiones anteriores no soportan Laravel 13).composer.lockcommiteado a partir de acá.- Las 11 migraciones corren limpias contra Postgres 17.
- Auth end-to-end: usuario creado en el Auth Emulator →
GET /api/transaccionesconAuthorization: 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.examplevenía conVITE_FIREBASE_API_KEYvacía →getAuth()tirabaauth/invalid-api-keyy 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=truecomo "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 queonAuthStateChangedpoblara el store y el guard rebotaba al login. El store ahora setea el user directo del credential. VITE_API_PROXY_TARGETdel example apuntaba abackend:3000(puerto/host inválido en todos los escenarios) →localhost:3000(docker-compose lo pisa conbackend: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)
docker compose exec backend php artisan testAntes 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:
docker compose exec backend ./vendor/bin/phpunit --filter=DatabaseIsolationTestSi 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
docker compose exec frontend npm run test # vitest run
docker compose exec frontend npm run build # vue-tsc (tipos) + build de ViteEl 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 lasVITE_FIREBASE_*(sin ellasgetAuth()falla al importarservices/api), así que el job copia el.env.example, que trae valores falsos, a.env.local, igual que hacestart-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 audity la suite de phpunit contra Postgres 17 y un Firebase Auth Emulator.
Próximos pasos para completar Dev
- En un clone nuevo, migrar y sembrar la base la primera vez:
docker compose exec backend php artisan migrate --seed. Conmigratesolo la base queda sin roles, países ni catálogos (ver "Los datos de referencia también llegan conmigrate"). - Pasar Soterex de
mockarealen 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). - Cuando el cliente comparta el proyecto Laravel existente de Soterex, evaluar reuso de su cliente de integración (ver ADR-002).

