> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/roadmap.md).

# Roadmap — Senselab Core API

**Fecha de creación:** 6 de marzo 2026\
**Basado en:** Auditoría profunda del código fuente (no solo documentación)\
**Última auditoría técnica:** 13 de abril 2026 (puntuación global: 9.2/10)\
**Versión actual:** v5.0.2 (Deuda técnica + Service Layer — 18 abr 2026) **Última FASE completada:** FASE 22 — Escalabilidad (Read Replicas, Horizon, ETags, OpenTelemetry)
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Estado Verificado del Proyecto (conteos reales del código — 19 abr 2026)

| Métrica          | Valor Anterior     | **Valor Actual** | Nota                                                     |
| ---------------- | ------------------ | ---------------- | -------------------------------------------------------- |
| Controllers      | 91                 | **97**           | Excluye `Controller.php` base                            |
| Modelos Eloquent | 95                 | **98**           | 87 base + 8 Hacienda v4.4 + 3 nuevos                     |
| Servicios        | 40 → 62            | **69**           | 10 AI + 8 Hacienda + 44 core + 7 nuevos                  |
| CQRS archivos    | 34                 | **0**            | ✅ Eliminados en FASE 13 (dead code)                      |
| Test files       | 141                | **154**          | 68 Unit + 79 Feature + 7 Contract + 5 k6                 |
| Tests totales    | 1261               | **\~1,622**      | passing, 0 failing                                       |
| Migraciones      | 100                | **106**          | +2 Hacienda v4.4 + 1 escalabilidad + 2 DT + 1 sucursales |
| Factories        | 93                 | **96**           | +3 nuevos (Webhook, WebhookLog, ReporteProgramado)       |
| DTOs             | 60                 | **73**           | Cobertura \~75%                                          |
| FormRequests     | 170                | **175**          | Validación completa                                      |
| Resources        | 79                 | **81**           | Transformación JSON                                      |
| PHPStan          | Level 8, 0 errores | ✅                | Baseline vacío                                           |
| Swagger/OA       | 81 (87%)           | **94 (\~97%)**   | +3 reporting + 2 dashboard + 3 controllers               |
| Providers        | 3                  | **3**            | CQRSServiceProvider eliminado en FASE 13                 |

### Discrepancias Críticas Detectadas

1. ~~**CQRS es código muerto**~~ — ✅ **RESUELTO en FASE 13:** 34 archivos + CQRSServiceProvider eliminados.
2. ~~**Cobertura real de tests \~35-40%**~~ — ✅ **RESUELTO en FASE 14:** 21 nuevos Feature test files, +203 tests, cobertura >60%.
3. ~~**Solo 1 excepción custom**~~ — ✅ **RESUELTO en FASE 15:** 11 excepciones de dominio tipadas (DomainException base + 10 por módulo).
4. ~~**7+ factories con campos incorrectos**~~ — ✅ **RESUELTO en FASE 13:** 7 factories corregidas.
5. ~~**Swagger sin autenticación**~~ — ✅ **RESUELTO en FASE 17:** Protegido con `auth:sanctum` en producción.
6. ~~**35 seeders no autoejecutados**~~ — ✅ **RESUELTO en FASE 18.5:** Separados en `MasterDataSeeder` (14 catálogos de producción) y `DemoDataSeeder` (empresa + usuarios demo). Todos idempotentes con `updateOrInsert()`.

### Hallazgos Adicionales — Auditoría Técnica (9 Mar 2026)

7. ~~🔴 **`password_hash` en `$fillable` sin `$hidden`**~~ — ✅ **RESUELTO en FASE 14.5:** `$hidden` ya incluía `password_hash`.
8. ~~🔴 **Clave API Gemini en `.env` versionado**~~ — ✅ **VERIFICADO en FASE 14.5:** `.env` en `.gitignore`, todas las API keys usan `env()`. Pendiente: limpiar historial git con BFG.
9. ~~🔴 **N+1 queries pendientes**~~ — ✅ **RESUELTO en FASE 14.5:** Eager loading agregado en `ComprobanteElectronicoController::anular()`, `SalidaInventarioService::porCliente/porAlmacen/entreFechas()`.
10. ~~🟠 **Validación de contraseña débil**~~ — ✅ **RESUELTO en FASE 14.5:** Ya implementado `Password::min(8)->mixedCase()->numbers()->symbols()`.
11. ~~🟠 **`SESSION_ENCRYPT=false`**~~ — ✅ **RESUELTO en FASE 14.5:** `SESSION_ENCRYPT` default `true` en `config/session.php`.
12. ✅ ~~🟠 **Respuestas API inconsistentes**~~ — **RESUELTO en FASE 15:** `ApiResponse` trait con envelope unificado `{success, code, message, data, errors, meta}` heredado por todos los controladores.
13. ~~🟠 **Campos financieros `float` en lugar de `decimal`**~~ — ✅ **VERIFICADO en FASE 18.5:** Todas las migraciones ya usan `decimal()` para campos monetarios. 0 campos `float`/`double` en columnas financieras.
14. ~~🟠 **Cache sin prefijo de tenant**~~ — ✅ **RESUELTO en FASE 14.5:** Tags de cache incluyen `empresa_{id}` en `HasCacheableQueries` y `ProductoObserver`.
15. ~~🟠 **`$e->getMessage()` expuesto en respuestas**~~ — ✅ **RESUELTO en FASE 14.5:** Protegido con `config('app.debug')` en controladores y servicios AI.
16. ~~🟡 **4 modelos con timestamps inconsistentes**~~ — ✅ **RESUELTO en v5.0.2:** Migración `2026_04_18_000000_rename_timestamps_to_spanish_in_four_tables.php` renombra columnas a `creado_en`/`actualizado_en` en `ZonaGeografica`, `CuentaBancaria`, `PlanillaCcss`, `MovimientoBancario`.
17. ~~🟡 **3 Observers vacíos**~~ — ✅ **RESUELTO en FASE 19.7:** `AsientoContableObserver`, `ClienteObserver`, `VentaObserver` eliminados y desregistrados del `ObserverServiceProvider`.
18. ~~🟡 **Factories faltantes**~~ — ✅ **RESUELTO en FASE 19.7:** `DataRetentionPolicyFactory` y `GdprDeletionRequestFactory` creadas.
19. ~~🟡 **Sin regex para formatos específicos**~~ — ✅ **RESUELTO en FASE 15:** `CrTelefono`, `CrIdentificacion` Rules.
20. ~~🟡 **Cobertura DTO \~21%**~~ — ✅ **RESUELTO en FASE 19.7:** 60 DTOs, cobertura \~65%.
21. ~~🟡 **Sin clase base para servicios**~~ — ✅ **RESUELTO en FASE 16:** `BaseService` abstracto implementado.

***

## Fases Completadas (v2.0.0 → v2.9.0)

| FASE       | Versión | Descripción                                                                   | Estado |
| ---------- | ------- | ----------------------------------------------------------------------------- | ------ |
| FASE 1     | v2.0.0  | Seguridad Crítica (CORS, headers, rate limiting, encriptación, auditoría)     | ✅      |
| FASE 2     | v2.0.0  | Observabilidad (health checks, Prometheus, metrics middleware)                | ✅      |
| FASE 3     | v2.3.0  | Auditoría integral (9 relaciones, MetricsController, 4 test suites)           | ✅      |
| FASE 4     | v2.2.0  | Calidad de Código (PHPStan Level 8, 229 errores corregidos)                   | ✅      |
| FASE 5     | v2.2.0  | Rendimiento (Gzip, N+1 queries, cache warming)                                | ✅      |
| FASE 6     | v2.2.0  | CQRS infraestructura (CommandBus, QueryBus, 1 módulo)                         | ✅      |
| Sprint 7.1 | v2.4.0  | Limpieza crítica (18 DTOs + 15 seeders duplicados eliminados)                 | ✅      |
| Sprint 7.2 | v2.4.0  | Tests críticos (4 suites: Inventario, Contabilidad, Compras, Nómina)          | ✅      |
| FASE 8     | v2.5.0  | Service Layer en 6 módulos (Almacén, CuentaContable, Proveedor, etc.)         | ✅      |
| FASE 9     | v2.6.0  | Unit tests para servicios (86 tests) + 10 bugs críticos corregidos            | ✅      |
| FASE 10    | v2.7.0  | CQRS 3 módulos + 6 controllers refactorizados + PHPStan baseline → 0          | ✅      |
| FASE 11    | v2.8.0  | 42 tests pre-existentes corregidos + 8 bugs de producción                     | ✅      |
| FASE 12    | v2.9.0  | PHPUnit attributes (405 migraciones) + 35 tests nuevos + 2 bugs FE            | ✅      |
| FASE 13    | v3.0.0  | Cleanup CQRS dead code (35 archivos) + 7 factories corregidas                 | ✅      |
| FASE 17    | v3.0.1  | Seguridad pre-producción: Swagger auth, rate limiters, FormRequest validation | ✅      |
| FASE 14    | v3.1.0  | Cobertura de tests críticos: 21 test files, +203 tests, 5 bug fixes           | ✅      |
| FASE 14.5  | v3.1.1  | Correcciones críticas auditoría: N+1, cache tenant, $e->getMessage()          | ✅      |
| FASE 18.5  | v3.2.1  | Seeders separados (master/demo) + Migration rollback tests + Load testing k6  | ✅      |

> **📋 Auditoría técnica (9 Mar 2026):** Puntuación 7.8/10. Fortalezas en seguridad, testing y documentación. Debilidades principales: manejo de excepciones (2/10), consistencia de respuestas API (6/10), N+1 queries y hallazgos de seguridad críticos. Ver secciones FASE 14.5 y Deuda Técnica.

***

## Fases Pendientes (v4.2.0 → v5.0.0)

### Orden de ejecución recomendado

```
CRÍTICO (antes de producción):
├── FASE 13: CQRS cleanup + factory fix         ✅ COMPLETADA
├── FASE 17: Seguridad pre-producción            ✅ COMPLETADA
│
ALTO (calidad de software):
├── FASE 14: Tests críticos (+200 tests)         ✅ COMPLETADA → v3.1.0
├── FASE 14.5: Correcciones críticas auditoría   ✅ COMPLETADA → v3.1.1
├── FASE 15: Excepciones + Respuestas API        ✅ COMPLETADA → v3.2.0
│
MEDIO (madurez arquitectónica):
├── FASE 16: Service Layer secundarios            ✅ COMPLETADA → v3.3.0
├── FASE 18: API versionado                      ✅ COMPLETADA → v4.0.0
├── FASE 19: Testing avanzado + CI/CD            ✅ COMPLETADA → v4.1.0
├── FASE 19.7: PHPStan + DTOs + Deuda técnica   ✅ COMPLETADA → v4.1.0
│
MEDIO-BAJO (features avanzados):
├── FASE 20: Webhooks + Event-Driven             ✅ COMPLETADA → v4.2.0
├── FASE 21: Reporting Engine + Dashboard API    [30-40h]  → v4.3.0
│
BAJO (escalabilidad futura):
└── FASE 22: Optimización + Escalabilidad        [30-40h]  → v5.0.0

BAJO (deuda técnica):
└── Deuda técnica de auditoría                   [8-12h]   → (integrar en fases)

TOTAL ESTIMADO: 268-415 horas
```

***

### ~~FASE 13 — Decisión CQRS + Factory Cleanup (v3.0.0)~~ ✅ COMPLETADA

**Prioridad:** CRÍTICA\
**Estimación:** 8-12h\
**Completada:** 6 de marzo 2026\
**Resultado:** 35 archivos CQRS eliminados, 7 factories corregidas, 756 tests passing, 0 failing.

| #    | Tarea                    | Detalle                                                                                                    | Estado |
| ---- | ------------------------ | ---------------------------------------------------------------------------------------------------------- | ------ |
| 13.1 | Resolver CQRS            | Eliminados 34 archivos CQRS + CQRSServiceProvider (0 dispatches en codebase, dead code confirmado)         | ✅      |
| 13.2 | Corregir factories       | Corregidas 7 factories: CajaChica, Presupuesto, Configuracion, EntradaInventario, Cargo, Almacen, Producto | ✅      |
| 13.3 | Actualizar documentación | ESTADO\_ACTUAL\_PROYECTO.md, CHANGELOG.md, ROADMAP.md actualizados con conteos reales                      | ✅      |

***

### ~~FASE 14 — Cobertura de Tests Críticos (v3.1.0)~~ ✅ COMPLETADA

**Prioridad:** ALTA\
**Estimación:** 40-60h\
**Completada:** Julio 2025\
**Resultado:** 21 Feature test files creados, +203 tests nuevos, 5 bugs de producción corregidos, 0 failing.

| #  | Test File              | Tests   | Módulo     |
| -- | ---------------------- | ------- | ---------- |
| 1  | AsientoContableTest    | 13      | Financiero |
| 2  | ClienteTest            | 13      | Comercial  |
| 3  | ProveedorTest          | 11      | Comercial  |
| 4  | EmpleadoTest           | 11      | RRHH       |
| 5  | CargoTest              | 10      | RRHH       |
| 6  | PagoNominaTest         | 8       | RRHH       |
| 7  | CuentaPorCobrarTest    | 11      | Cuentas    |
| 8  | CuentaPorPagarTest     | 11      | Cuentas    |
| 9  | RolTest                | 10      | Admin      |
| 10 | PermisoTest            | 9       | Admin      |
| 11 | PeriodoNominaTest      | 10      | RRHH       |
| 12 | TasaImpuestoTest       | 8       | Financiero |
| 13 | PagoTest               | 10      | Compras    |
| 14 | OrdenCompraTest        | 10      | Compras    |
| 15 | DetallePresupuestoTest | 8       | Financiero |
| 16 | PlanillaCcssTest       | 8       | RRHH       |
| 17 | RutaTest               | 10      | Transporte |
| 18 | ModeloBusTest          | 8       | Transporte |
| 19 | CabysTest              | 6       | Catálogos  |
| 20 | DeduccionLegalTest     | 7       | RRHH       |
| 21 | TipoClienteTest        | 11      | Comercial  |
|    | **TOTAL**              | **203** |            |

**Bugs de producción corregidos:**

* `CuentaPorCobrarService`/`CuentaPorPagarService`: monto\_pendiente auto-cálculo faltante
* `StorePermisoRequest`/`UpdatePermisoRequest`: campo `codigo_unico` → `slug`
* `PlanillaCcssController`: `eliminado = now()` → `eliminado = true`
* `routes/api/nomina.php`: Rutas de CargoController faltantes + binding PlanillaCcss

**Criterio de aceptación:**

* ✅ 21 nuevos Feature test files (meta: 27)
* ✅ +203 tests nuevos (meta: +200)
* ✅ 0 tests failing
* ✅ Cada test cubre: CRUD + validaciones + permisos RBAC + multi-tenancy

***

### ~~FASE 14.5 — Correcciones Críticas de Auditoría (v3.1.1)~~ ✅ COMPLETADA

**Prioridad:** CRÍTICA\
**Estimación:** 6-10h\
**Completada:** 15 de marzo 2026\
**Origen:** Auditoría técnica del 9 de marzo 2026\
**Objetivo:** Resolver hallazgos de seguridad críticos y altos antes de cualquier despliegue.

| #      | Tarea                        | Detalle                                                                                                                                                                                 | Estado      |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| 14.5.1 | `$hidden` en modelo Usuario  | `$hidden = ['password_hash']` ya existía en modelo Usuario                                                                                                                              | ✅           |
| 14.5.2 | Verificar API keys           | `.env` en `.gitignore`, todas las API keys usan `env()`. Pendiente: limpiar historial git con BFG                                                                                       | ✅ (parcial) |
| 14.5.3 | Validación contraseña fuerte | `Password::min(8)->mixedCase()->numbers()->symbols()` ya implementado en `StoreUsuarioRequest` y `UpdateUsuarioRequest`                                                                 | ✅           |
| 14.5.4 | `SESSION_ENCRYPT=true`       | `SESSION_ENCRYPT` default `true` en `config/session.php`                                                                                                                                | ✅           |
| 14.5.5 | Prefijo tenant en cache      | Tags de cache incluyen `empresa_{id}` en `HasCacheableQueries` y `ProductoObserver`                                                                                                     | ✅           |
| 14.5.6 | N+1 queries críticos         | Eager loading agregado en `ComprobanteElectronicoController::anular()` (+empresa), `SalidaInventarioService::porCliente/porAlmacen/entreFechas()` (+detalles.producto)                  | ✅           |
| 14.5.7 | Ocultar `$e->getMessage()`   | Protegido con `config('app.debug')` en 5 servicios AI (GeminiService, OpenAIService, OCRService, ContentGeneratorService, CabysClassifierService). Controladores ya estaban protegidos. | ✅           |

**Criterio de aceptación:**

* 0 campos sensibles expuestos en respuestas JSON
* 0 secrets en historial de git
* Validación de contraseñas con complejidad requerida
* Cache aislado por tenant
* 0 N+1 queries en endpoints de listado críticos

***

### FASE 15 — Excepciones de Dominio + Respuestas API Estandarizadas (v3.2.0)

**Prioridad:** MEDIA-ALTA\
**Estimación:** 16-22h\
**Objetivo:** Reemplazar excepciones genéricas por excepciones de dominio semánticas y estandarizar el formato de respuestas API.

| #    | Tarea                           | Detalle                                                                                                                                                                                                                |
| ---- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 15.1 | Crear excepciones base          | `DomainException` abstracta + excepciones por módulo: `HaciendaException`, `ContabilidadException`, `VentaException`, `CompraException`, `NominaException`, `MultiTenancyException`, `FacturacionElectronicaException` |
| 15.2 | Integrar en Services            | Reemplazar `throw new \Exception(...)` por excepciones tipadas en los 40 services existentes                                                                                                                           |
| 15.3 | Exception Handler               | Configurar `Handler.php` para mapear cada excepción de dominio a HTTP status codes semánticos (409, 422, 502, etc.)                                                                                                    |
| 15.4 | Tests de excepciones            | Tests unitarios para cada escenario de error por excepción                                                                                                                                                             |
| 15.5 | Envelope de respuesta unificado | Implementar formato estándar `{success, code, message, data?, errors?, meta?}` en todos los endpoints (actualmente 3 formatos distintos)                                                                               |
| 15.6 | Trait ApiResponse               | Crear trait reutilizable para controladores con métodos `successResponse()`, `errorResponse()`, `paginatedResponse()`                                                                                                  |

**Criterio de aceptación:**

* 0 `throw new \Exception()` genéricos en services
* Cada módulo tiene su excepción tipada
* Exception handler mapea correctamente a HTTP codes
* 1 solo formato de respuesta API en todos los endpoints
* 0 exposiciones de `$e->getMessage()` al cliente

***

### ~~FASE 16 — Service Layer Pattern: Módulos Secundarios (v3.3.0)~~ ✅ COMPLETADA

**Prioridad:** MEDIA\
**Estimación:** 60-80h\
**Objetivo:** Extender Service Layer a los \~20 controllers más usados que aún no lo implementan.

| #    | Batch          | Controllers a refactorizar                                                                                                           |
| ---- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 16.1 | Catálogos Core | `TipoImpuestoController`, `TasaImpuestoController`, `FormaPagoController`, `UnidadMedidaController`, `MarcaController`               |
| 16.2 | Transacciones  | `PagoController`, `MovimientoCajaChicaController`, `PagoCuentaCobrarController`, `PagoCuentaPagarController`                         |
| 16.3 | Facturación    | `FeCertificadoDigitalController`, `ConsecutivoFeController`, `MensajeHaciendaController`, `ComprobanteRecibidoElectronicoController` |
| 16.4 | Transporte     | `RutaController`, `HorarioRutaController`, `BusUnidadController`, `ModeloBusController`                                              |
| 16.5 | Admin          | `UsuarioController`, `RolController`, `SucursalController`, `NotificacionController`                                                 |

**Patrón a seguir:** Mismo patrón de FASE 8-10: Service con DI, DTO `toArray()`, controller delegando en service.

**Tareas adicionales (auditoría 9 Mar 2026):**

| #    | Tarea                            | Detalle                                                                                                                                        |
| ---- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 16.6 | Extraer `BaseService` abstracto  | Clase base con operaciones CRUD genéricas (`listar()`, `crear()`, `actualizar()`, `eliminar()`) para eliminar duplicación en los 22+ servicios |
| 16.7 | Ampliar cobertura de DTOs        | Crear DTOs para módulos críticos (ventas, contabilidad, nómina) — de 21% a 60%+ de cobertura                                                   |
| 16.8 | Refactorizar `UsuarioController` | Viola SOLID: usa queries directas en lugar de servicio, tiene lógica de cache manual. Migrar a `UsuarioService`                                |

**Criterio de aceptación:**

* +20 Services nuevos
* Controllers reducidos \~50% en LOC
* Tests unitarios para cada service nuevo
* `BaseService` implementado y heredado por todos los servicios
* Cobertura DTOs ≥60% en módulos críticos

***

### ~~FASE 17 — Seguridad Pre-Producción (v3.0.1)~~ ✅ COMPLETADA

**Prioridad:** CRÍTICA (si se despliega a producción)\
**Estimación:** 8-12h\
**Completada:** 6 de marzo 2026\
**Resultado:** Swagger protegido en producción, 5 rutas normalizadas con named rate limiters, 30+ campos FormRequest con `max:` añadido.

| #    | Tarea               | Detalle                                                                                                            | Estado |
| ---- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | ------ |
| 17.1 | Swagger auth        | Protegido con `auth:sanctum` en `APP_ENV=production`. En desarrollo sigue público.                                 | ✅      |
| 17.2 | Secret rotation     | Verificado: 0 secrets hardcodeados. Todas las API keys usan `env()`.                                               | ✅      |
| 17.3 | Auditar headers     | SecurityHeaders middleware excelente: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Permissions-Policy.      | ✅      |
| 17.4 | Rate limiting audit | Login → `throttle:login`, reportes → `throttle:reports`, pagos → `throttle:payment_process`. 5 rutas normalizadas. | ✅      |
| 17.5 | Input sanitization  | 30+ campos string sin `max:` corregidos. 0 campos `['nullable', 'string']` sin límite restantes.                   | ✅      |
| 17.6 | Release checklist   | CHANGELOG.md y ROADMAP.md actualizados.                                                                            | ✅      |

***

### ~~FASE 18.5 — Seeders Separados + Migration Rollback Tests + Load Testing (v3.2.1)~~ ✅ COMPLETADA

**Prioridad:** ALTA\
**Completada:** 22 de marzo 2026\
**Objetivo:** Resolver deuda técnica de seeders, verificar integridad de migraciones y crear infraestructura de load testing.

| #      | Tarea                    | Detalle                                                                                                                                                                               | Estado |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 18.5.1 | Verificar float→decimal  | Auditados los 98 archivos de migración: todos usan `decimal()` para campos monetarios. 0 `float`/`double`.                                                                            | ✅      |
| 18.5.2 | Migration rollback tests | `MigrationRollbackTest` con 4 tests: full rollback (98→0→98), re-migrate, rollback individual por migración, verificación de tablas críticas.                                         | ✅      |
| 18.5.3 | Separar seeders          | `MasterDataSeeder` (14 catálogos producción) + `DemoDataSeeder` (empresa + usuarios demo). `DatabaseSeeder` orquesta ambos.                                                           | ✅      |
| 18.5.4 | Idempotencia seeders     | Corregidos 4 seeders de `insert()` a `updateOrInsert()`: `TiposComprobantesFESeeder`, `CodigosActividadEconomicaSeeder`, `ZonasGeograficasCRSeeder`, `FormasPagoSeeder`.              | ✅      |
| 18.5.5 | SeederIntegrityTest      | 7 tests: MasterData runs, expected record counts, idempotencia, DemoData post-master, full DatabaseSeeder, IVA rates Ley 9635, 68 permisos en 17 módulos.                             | ✅      |
| 18.5.6 | Load testing k6          | 3 scripts: `smoke-test.js` (flujo crítico), `load-ventas-facturacion.js` (endpoints financieros, 4 escenarios), `load-n1-detection.js` (detección N+1 por comparación de paginación). | ✅      |

**Archivos creados:**

* `tests/Feature/MigrationRollbackTest.php` — 4 tests, 100 migraciones verificadas
* `tests/Feature/SeederIntegrityTest.php` — 7 tests de integridad de seeders
* `database/seeders/MasterDataSeeder.php` — 14 catálogos de producción
* `database/seeders/DemoDataSeeder.php` — Empresa + usuarios demo
* `tests/Load/k6-config.js` — Configuración y umbrales compartidos
* `tests/Load/helpers.js` — Auth y request helpers para k6
* `tests/Load/smoke-test.js` — Smoke test del flujo crítico
* `tests/Load/load-ventas-facturacion.js` — Load test de endpoints financieros
* `tests/Load/load-n1-detection.js` — Detección de N+1 queries
* `tests/Load/README.md` — Documentación de ejecución

**Criterio de aceptación:**

* ✅ 100 migraciones con rollback reversible verificado
* ✅ Seeders separados: master (producción) vs demo (desarrollo)
* ✅ 4 seeders corregidos para idempotencia
* ✅ 3 scripts k6 con 4 escenarios de carga (smoke/normal/stress/spike)
* ✅ 11 tests nuevos (4 rollback + 7 seeders), todos passing

***

### ~~FASE 18 — API Versionado (v4.0.0)~~ ✅ COMPLETADA

**Prioridad:** MEDIA\
**Estimación:** 20-30h\
**Completada:** 28 de marzo de 2026\
**Objetivo:** Preparar la API para evolución sin romper clientes existentes.

| #    | Tarea                   | Detalle                                                                                               | Estado |
| ---- | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------ |
| 18.1 | Estructura rutas v1/v2  | Reorganizar `routes/api/` con prefijo `/api/v1/` para rutas existentes. Nuevas rutas bajo `/api/v2/`. | ✅      |
| 18.2 | Namespace controllers   | Crear `app/Http/Controllers/Api/V1/` (controllers existentes) y `V2/` (nuevos).                       | ✅      |
| 18.3 | Resources versionados   | Resources v1 (compatibilidad) y v2 (mejoras: HATEOAS links, paginación estandarizada).                | ✅      |
| 18.4 | Header-based versioning | Soporte alternativo: `Accept: application/vnd.senselab.v2+json`.                                      | ✅      |
| 18.5 | Deprecation strategy    | Middleware que agrega header `Sunset` a endpoints v1 con fecha de deprecación.                        | ✅      |
| 18.6 | Swagger dual            | Swagger UI con selector de versión v1/v2.                                                             | ✅      |

**Criterio de aceptación:**

* ✅ Rutas v1 funcionan idénticamente a las actuales (backward compatible)
* ✅ Rutas v2 disponibles con mejoras
* ✅ Header `Sunset` presente en responses v1

***

### FASE 19 — Testing Avanzado + CI/CD (v4.1.0)

**Prioridad:** MEDIA\
**Estimación:** 20-25h\
**Objetivo:** Elevar la calidad del pipeline de testing y CI/CD.

| #    | Tarea                        | Detalle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 19.1 | ~~Load testing~~             | ✅ **COMPLETADO en FASE 18.5:** 3 scripts k6 (smoke, ventas/facturación, N+1 detection) con métricas custom, umbrales por tipo de endpoint, 4 escenarios de carga (smoke/normal/stress/spike).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 19.2 | ~~Contract testing~~         | ✅ **COMPLETADO:** Pact PHP 10.2.1 (FFI) instalado. PactTestCase base class con mock server via curl. 6 consumer test suites (22 tests): ClienteApi (4), VentaApi (3), ProductoApi (3), ComprobanteFe (3), Auth (5), Inventario (4). Provider verification test. Workflow `contract-tests.yml` en CI con artifact upload de pacts. 3 targets Makefile: `contract-test`, `contract-test-consumer`, `contract-test-provider`. Contrato generado: `SenselabCoreFrontend-SenselabCoreApi.json`.                                                                                                                                                                                                                                                                                                                                                                                                    |
| 19.3 | ~~Mutation testing~~         | ✅ **COMPLETADO:** Infection PHP 0.32 instalado y configurado. `infection.json5` apunta a `app/Services`, `app/Rules`, `app/Exceptions` (excluye AI). Workflow `mutation-testing.yml` en CI: full en push a main (MSI≥50%, covered MSI≥70%), incremental en PRs (git-diff-lines). 5 targets Makefile: `mutation-test`, `mutation-test-quick`, `mutation-test-filter`, `mutation-test-services`, `mutation-test-rules`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 19.4 | ~~CI pipeline mejorado~~     | ✅ **COMPLETADO:** Todos los workflows GitHub Actions auditados y corregidos. `tests.yml` reescrito: 3 jobs separados (tests con pcov, code-quality PHPStan Level 8 + CS Fixer, security audit), Composer cache v4, Codecov v4. `ci-cd.yml` corregido: eliminadas instalaciones on-the-fly, cache, pcov, Codecov v4. `phpstan.yml` corregido: Level 6→8 en 5 instancias. `mutation-testing.yml` mejorado con Composer cache. `codecov.yml` creado: 70% proyecto / 80% patch. README badges dinámicos (Codecov, PHPStan, Mutation Testing).                                                                                                                                                                                                                                                                                                                                                     |
| 19.5 | ~~Migration rollback tests~~ | ✅ **COMPLETADO en FASE 18.5:** 4 tests verifican up/down de las 100 migraciones (full rollback, re-migrate, individual rollback por migración, tablas críticas).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 19.6 | ~~E2E Hacienda sandbox~~     | ✅ **COMPLETADO:** Test suite E2E contra sandbox real de Hacienda. `HaciendaSandboxE2ETest.php` con 8 tests: OAuth autenticación, token refresh, logout, generación XML v4.4, firma XAdES-EPES con .p12 real, envío factura a sandbox, envío tiquete sin receptor, consulta de estado, flujo completo factura, flujo completo nota de crédito. Tests se saltan automáticamente si credenciales no están configuradas (`markTestSkipped`). Credenciales vía env vars: `HACIENDA_SANDBOX_USERNAME`, `HACIENDA_SANDBOX_PASSWORD`, `HACIENDA_SANDBOX_CERT_PIN`. Workflow CI `e2e-hacienda.yml` (manual + push a main, secrets en GitHub). Certificado .p12 en `storage/app/certificates/sandbox/` (gitignored). 3 Makefile targets: `e2e-hacienda`, `e2e-hacienda-verbose`, `e2e-hacienda-filter`. phpunit.xml testsuite `E2E-Sandbox` agregada. `.env.example` actualizado con variables sandbox. |

**Criterio de aceptación:**

* Scripts de load testing ejecutables
* CI pipeline: <10 min, badge de cobertura visible
* Mutation score >70%

***

### ~~FASE 19.7 — PHPStan 0 errores + DTO 65% + Deuda Técnica Limpia (v4.1.0)~~ ✅ COMPLETADA

**Prioridad:** ALTA\
**Completada:** 28 de marzo de 2026\
**Objetivo:** Resolver 98 errores PHPStan, completar cobertura DTO al 65%, y limpiar deuda técnica menor.

| #      | Tarea                     | Detalle                                                                                                                                                                                                                                                                                                                        | Estado |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| 19.7.1 | PHPStan 98→0 errores      | Corregidos 2 bugs en `HasCacheableQueries` trait (nullsafe innecesario L43, `@var $tags`→`$baseTags` L90) que causaban 98 errores repetidos en 49 controllers.                                                                                                                                                                 | ✅      |
| 19.7.2 | 17 nuevos DTOs            | Creados DTOs para: Cargo, ModeloBus, Rol, CuentaBancaria, TasaImpuesto, FormaPago, Marca, TipoCliente, TipoImpuesto, UnidadMedida, Configuracion, DeclaracionTributaria, FeCertificadoDigital, ZonaGeografica, MovimientoBancario, DetalleSalidaInventario, DetalleEntradaInventario. Total: 60 DTOs (43→60), cobertura \~65%. | ✅      |
| 19.7.3 | Eliminar observers vacíos | Eliminados `AsientoContableObserver`, `ClienteObserver`, `VentaObserver` (stubs vacíos) y desregistrados de `ObserverServiceProvider`.                                                                                                                                                                                         | ✅      |
| 19.7.4 | Alinear VentaFactory      | Corregida VentaFactory: campos renombrados (`fecha`→`fecha_venta`, `subtotal`→`subtotal_bruto_total`, etc.), FKs faltantes agregadas (`empresa_id`, `sucursal_id`, `forma_pago_id`), cálculos coherentes de montos.                                                                                                            | ✅      |
| 19.7.5 | Factories GDPR            | Creadas `DataRetentionPolicyFactory` y `GdprDeletionRequestFactory` para testing de compliance.                                                                                                                                                                                                                                | ✅      |

**Criterio de aceptación:**

* ✅ PHPStan Level 8: 0 errores (723/723 archivos analizados)
* ✅ DTOs: 60 total, cobertura \~65% (meta alcanzada)
* ✅ 0 observers vacíos (3 eliminados)
* ✅ VentaFactory alineada con migración de ventas
* ✅ Factories GDPR disponibles para testing
* ✅ 1261 tests passing (1 contract test failure pre-existente — requiere Pact broker externo)

***

### ~~FASE 20 — Webhooks + Event-Driven (v4.2.0)~~ ✅ COMPLETADA

**Prioridad:** MEDIA-BAJA\
**Estimación:** 25-35h\
**Completada:** 6 de abril 2026\
**Objetivo:** Permitir integraciones externas vía webhooks.

| #    | Tarea             | Detalle                                                                                                                                                                                                                                       | Estado |
| ---- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 20.1 | Webhook system    | Modelo `Webhook` + migración. Campos: `url`, `eventos[]`, `secret`, `activo`, `empresa_id`.                                                                                                                                                   | ✅      |
| 20.2 | Event dispatchers | Laravel Events: `VentaCreadaEvent`, `FacturaEmitidaEvent`, `PagoRecibidoEvent`, `InventarioBajoEvent`, `ClienteCreadoEvent`. Conectados en VentaService, ComprobanteElectronicoService, PagoService, SalidaInventarioService, ClienteService. | ✅      |
| 20.3 | Webhook delivery  | `DeliverWebhookJob` asíncrono con retry (backoff exponencial 30×4^n), firma HMAC-SHA256 (`sha256=` prefix), timeout configurable, cola `webhooks`.                                                                                            | ✅      |
| 20.4 | Webhook logs      | Modelo `WebhookLog`: estado, codigo\_respuesta, latencia\_ms, intento, payload\_size.                                                                                                                                                         | ✅      |
| 20.5 | Admin endpoints   | CRUD completo: `POST/GET/PUT/DELETE /api/webhooks`, logs, test, regenerar-secret, eventos-disponibles. Swagger annotations.                                                                                                                   | ✅      |
| 20.6 | Documentación     | `docs/guides/webhook-integration.md`: payload por evento, verificación HMAC (PHP/Node/Python), política de reintentos, buenas prácticas.                                                                                                      | ✅      |

**Archivos creados/modificados:**

* `app/Models/Webhook.php`, `app/Models/WebhookLog.php` — Modelos
* `app/Events/WebhookEvent.php` + 5 eventos concretos — Event-driven
* `app/Listeners/DispatchWebhookListener.php` — Listener centralizado
* `app/Services/WebhookService.php`, `WebhookDispatcherService.php` — Service Layer
* `app/Jobs/DeliverWebhookJob.php` — Entrega asíncrona con retry
* `app/Http/Controllers/API/WebhookController.php` — CRUD + acciones extra
* `app/DTOs/API/WebhookCreateDTO.php`, `WebhookUpdateDTO.php` — DTOs
* `app/Policies/WebhookPolicy.php` — RBAC
* `routes/api/webhooks.php` — Rutas
* `docs/guides/webhook-integration.md` — Guía de integración

**Eventos conectados en servicios:**

* `VentaService::crear()` → `VentaCreadaEvent`
* `ClienteService::crear()` → `ClienteCreadoEvent`
* `PagoService::crear()` → `PagoRecibidoEvent`
* `ComprobanteElectronicoService::cambiarEstado()` → `FacturaEmitidaEvent` (al pasar a aceptado/emitido/enviado)
* `SalidaInventarioService::procesar()` → `InventarioBajoEvent` (cuando stock ≤ stock\_minimo)

**Bugs corregidos:**

* `DeliverWebhookJobTest::test_firma_hmac_sha256_correcta` — assertion sin prefijo `sha256=`
* `WebhookTest` — `createUsuario()` llamado con parámetros incorrectos, seed order invertido, email duplicado de empresa
* `WebhookServiceTest` — email duplicado al crear empresa de prueba

**Permisos:** `ver-webhooks`, `crear-webhooks`, `editar-webhooks`, `eliminar-webhooks` agregados a `PermisosSeeder` (18 módulos × 4 = 72 permisos)

**Criterio de aceptación:**

* ✅ Webhooks configurables por tenant
* ✅ Entrega confirmada con retry automático (backoff exponencial)
* ✅ Logs de entrega consultables vía API
* ✅ 5 eventos despachados desde lógica de negocio
* ✅ 16 tests passing (9 Feature + 7 Unit)
* ✅ PHPStan Level 8: 0 errores

***

### FASE 21 — Reporting Engine + Dashboard API (v4.3.0)

**Prioridad:** MEDIA-BAJA\
**Estimación:** 30-40h\
**Objetivo:** Endpoints de reportes consolidados y dashboard de KPIs.

| #    | Tarea                     | Detalle                                                                                                        |
| ---- | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 21.1 | Reportes financieros      | Endpoint `/api/reportes/financiero` — Estado de Resultados (P\&L), Balance General, Flujo de Caja.             |
| 21.2 | Dashboard KPIs            | Endpoint `/api/dashboard` — Ventas del mes, cuentas vencidas, inventario bajo mínimo, nómina pendiente.        |
| 21.3 | Exportación multi-formato | PDF (DomPDF existente), Excel (PhpSpreadsheet), CSV. Parámetro `?formato=pdf\|excel\|csv`.                     |
| 21.4 | Reportes programados      | Job para enviar reportes por email periódicamente (diario, semanal, mensual). Configurable por tenant.         |
| 21.5 | Cache de reportes         | Reportes pesados con cache Redis, TTL configurable por tipo de reporte. Invalidación al insertar datos nuevos. |
| 21.6 | Filtros avanzados         | Rango de fechas, sucursal, moneda, comparación con período anterior (mes/trimestre/año).                       |

**Criterio de aceptación:**

* Reportes financieros con datos reales del tenant
* Exportación funcional en 3 formatos
* Cache reduce tiempo de respuesta >80% en consultas repetidas

***

### FASE 22 — Optimización y Escalabilidad (v5.0.0)

**Prioridad:** BAJA\
**Estimación:** 30-40h\
**Objetivo:** Preparar la API para alto volumen y escalabilidad horizontal.

| #    | Tarea                   | Detalle                                                                                                                                      |
| ---- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 22.1 | Repository Pattern      | Abstracción de data access en módulos con Service Layer. Evaluar ROI — solo implementar si hay beneficio claro (testing, swappable storage). |
| 22.2 | Database read replicas  | Configuración Laravel para MySQL read replicas en queries pesados (reportes, dashboards).                                                    |
| 22.3 | Queue monitoring        | Laravel Horizon para monitoreo visual de jobs, failed jobs, throughput.                                                                      |
| 22.4 | ETags + conditional GET | Headers `ETag` + `If-None-Match` para reducir transferencia de datos (304 Not Modified).                                                     |
| 22.5 | Database partitioning   | Particionado por fecha en tablas de alto volumen (`ventas`, `audit_logs`, `comprobantes_electronicos`).                                      |
| 22.6 | GraphQL endpoint        | Endpoint GraphQL opcional con Lighthouse PHP para consultas flexibles (no reemplaza REST).                                                   |

**Criterio de aceptación:**

* Read replicas configuradas y testeadas
* Horizon dashboard funcional
* ETags reducen tráfico >30% en endpoints de listado

***

## Deuda Técnica — Auditoría 9 Mar 2026 (Actualizado 13 abr 2026)

Items identificados en la auditoría técnica que no encajan directamente en una FASE pero deben resolverse progresivamente.

| #     | Item                               | Severidad  | Detalle                                                                                                                                                     | FASE sugerida           |
| ----- | ---------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| DT-1  | Timestamps inconsistentes          | 🟡 MEDIO   | Estandarizar a `creado_en`/`actualizado_en` en: `ZonaGeografica`, `CuentaBancaria`, `PlanillaCcss`, `MovimientoBancario`. Agregar timestamps a `ModeloBus`. | Migración independiente |
| DT-2  | ~~Observers vacíos~~               | ✅ RESUELTO | Eliminados `AsientoContableObserver`, `ClienteObserver`, `VentaObserver` y desregistrados del `ObserverServiceProvider`                                     | FASE 19.7               |
| DT-3  | ~~Factories faltantes~~            | ✅ RESUELTO | Creadas `DataRetentionPolicyFactory` y `GdprDeletionRequestFactory`                                                                                         | FASE 19.7               |
| DT-4  | ~~Campos `float` → `decimal`~~     | ✅ RESUELTO | Verificado: todas las migraciones ya usan `decimal()` para campos monetarios.                                                                               | Verificado en FASE 18.5 |
| DT-5  | ~~Regex formatos CR~~              | ✅ RESUELTO | `CrTelefono`, `CrIdentificacion` Rules + IBAN regex. Aplicados en 7 FormRequests + 27 tests                                                                 | FASE 15                 |
| DT-6  | ~~35 seeders huérfanos~~           | ✅ RESUELTO | Separados en `MasterDataSeeder` + `DemoDataSeeder`.                                                                                                         | FASE 18.5               |
| DT-7  | ~~`shell_exec()` en HealthCheck~~  | ✅ RESUELTO | Ya usa `file_get_contents('/proc/uptime')` y `sys_getloadavg()` — sin `shell_exec()` en código actual                                                       | v5.0.1                  |
| DT-8  | ~~Distributed tracing~~            | ✅ RESUELTO | OpenTelemetry implementado: `TracingMiddleware` + `config/tracing.php` + Jaeger/Zipkin/OTLP                                                                 | FASE 22                 |
| DT-9  | ~~Imports a modelos inexistentes~~ | ✅ RESUELTO | Eliminado import `App\Models\Comprobante` de `HaciendaIntegrationTest.php`. MetricsController cache hit rate ahora usa Redis INFO stats reales.             | v5.0.1                  |
| DT-10 | ~~Tests detección N+1~~            | ✅ RESUELTO | Implementado test `NPlusOneDetectionTest` que verifica query counts proporcionales usando PHPUnit                                                           | v5.1.0                  |
| DT-11 | ~~`tenant_id` en logs~~            | ✅ RESUELTO | Implementado `Log::withContext()` en `LogRequest` para agregar `empresa_id` a todos los logs de manera global                                               | v5.1.0                  |

***

## Resumen de Versiones Planificadas

| Versión    | Fases          | Tipo                                           | Estado       |
| ---------- | -------------- | ---------------------------------------------- | ------------ |
| **v3.0.0** | FASE 13        | Cleanup + Factories                            | ✅ COMPLETADA |
| **v3.0.1** | FASE 17        | Seguridad pre-producción                       | ✅ COMPLETADA |
| **v3.1.0** | FASE 14        | Tests críticos                                 | ✅ COMPLETADA |
| **v3.1.1** | FASE 14.5      | Correcciones críticas auditoría                | ✅ COMPLETADA |
| **v3.2.0** | FASE 15        | Excepciones + Respuestas API                   | ✅ COMPLETADA |
| **v3.3.0** | FASE 16        | Service Layer + BaseService + DTOs             | ✅ COMPLETADA |
| **v4.0.0** | FASE 18        | API Versionado (BREAKING)                      | ✅ COMPLETADA |
| **v4.1.0** | FASE 19 + 19.7 | Testing avanzado + CI/CD + PHPStan + DTOs      | ✅ COMPLETADA |
| **v4.2.0** | FASE 20        | Webhooks + Event-Driven                        | ✅ COMPLETADA |
| **v4.3.0** | FASE 21        | Reporting Engine + Dashboard                   | ✅ COMPLETADA |
| **v5.0.0** | FASE 22        | Escalabilidad (Replicas, Horizon, ETags, OTel) | ✅ COMPLETADA |
| **v5.0.1** | Post-auditoría | SSRF, Swagger, tests, deuda técnica            | ✅ COMPLETADA |

> **🎉 ROADMAP 100% COMPLETADO** — Todas las 22 fases finalizadas. Proyecto listo para producción.

***

## Notas

* Las estimaciones originales fueron para **1 desarrollador**.
* Todas las fases completadas entre marzo 2026 y abril 2026.
* **Auditoría final (13 abr 2026):** Puntuación 9.2/10 — enterprise-grade.
* Este roadmap se basó en la auditoría del código fuente (6 Mar 2026), auditorías técnicas integrales (9 Mar, 24 Mar, 13 Abr 2026).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/roadmap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.