> 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/docs/archive/auditoria_pre_sprint_9.md).

# AUDITORÍA PRE-SPRINT 9 - Estado Real del Proyecto

**Fecha:** 25 de noviembre de 2025\
**Objetivo:** Verificación exhaustiva del estado del proyecto antes de continuar con Sprint 9\
**Alcance:** Análisis completo del codebase sin confiar en documentación de sprints anteriores

***

## 📊 RESUMEN EJECUTIVO

### ⚠️ HALLAZGOS CRÍTICOS

| Categoría             | Estado            | Crítico  |
| --------------------- | ----------------- | -------- |
| **Multi-tenancy**     | ❌ **INCOMPLETO**  | ✅ SÍ     |
| **PHPStan (Nivel 5)** | ❌ **162 ERRORES** | ✅ SÍ     |
| **Tests (MySQL)**     | ⚠️ **BLOQUEADO**  | ⚠️ MEDIO |
| **Policies/RBAC**     | ✅ **PARCIAL**     | ⚠️ MEDIO |
| **FormRequests**      | ✅ **BUENO**       | ❌ NO     |
| **Swagger Docs**      | ✅ **GENERADO**    | ❌ NO     |

### 🎯 Prioridades Inmediatas para Sprint 9

1. **\[CRÍTICO]** Completar refactor multi-tenancy (2 controllers pendientes + correcciones)
2. **\[CRÍTICO]** Resolver 162 errores PHPStan (15 flushCache, 3 cacheQueryIfEnabled, relaciones)
3. **\[ALTO]** Validar suite de tests (requiere Docker/MySQL)
4. **\[MEDIO]** Auditar cobertura de Policies en todos los endpoints
5. **\[BAJO]** Optimizaciones y mejoras técnicas

***

## 1️⃣ MULTI-TENANCY: INCOMPLETO ❌

### Estado Documentado vs Real

**Documentación dice:** "24/24 controladores refactorizados, 100% completado"\
**Realidad:** ❌ **2 controladores SIN refactorizar + 1 con implementación no estándar**

### 🔴 Controladores Sin HasEmpresaContext Trait

#### 1. InventarioProductoController

```php
// ❌ LÍNEA 17: Acceso directo NO refactorizado
$empresaId = $request->user()->empresa_id;

// NO usa trait HasEmpresaContext
// NO tiene getEmpresaId()
// NO tiene cache isolation por empresa_id
```

**Ubicación:** `app/Http/Controllers/InventarioProductoController.php`\
**Impacto:** Vulnerabilidad multi-tenant, datos de inventario NO aislados por empresa\
**Métodos afectados:** `index()` (línea 17)

#### 2. EntidadEtiquetaController

```php
// ❌ LÍNEA 25: Acceso directo NO refactorizado
$empresaId = $request->user()->empresa_id;

// NO usa trait HasEmpresaContext
// NO tiene getEmpresaId()
// NO tiene cache isolation por empresa_id
```

**Ubicación:** `app/Http/Controllers/EntidadEtiquetaController.php`\
**Impacto:** Vulnerabilidad multi-tenant, etiquetas NO aisladas por empresa\
**Métodos afectados:** `index()` (línea 25)

#### 3. ConsecutivoFEController (Implementación No Estándar)

```php
// ✅ TIENE método getEmpresaId() pero es PRIVADO (debería usar trait)
private function getEmpresaId(): int
{
    /** @var \App\Models\Usuario $user */
    $user = auth()->user();
    return $user->empresa_id;
}
```

**Ubicación:** `app/Http/Controllers/ConsecutivoFEController.php`\
**Problema:** Método privado duplicado en lugar de usar trait estándar\
**Impacto:** Inconsistencia en el patrón, dificulta mantenimiento

### 📊 Verificación por Grep

```bash
# Búsqueda de accesos directos a empresa_id
grep -rn "\$request->user()->empresa_id" app/Http/Controllers/
```

**Resultados:**

* ✅ `app/Http/Controllers/API/*Controller.php` → 0 coincidencias (LIMPIO)
* ❌ `app/Http/Controllers/InventarioProductoController.php:17` → 1 coincidencia
* ❌ `app/Http/Controllers/EntidadEtiquetaController.php:25` → 1 coincidencia

**Total:** 2 accesos directos NO refactorizados (no 0 como documenta Sprint 8)

### 🎯 Acciones Requeridas

1. **Aplicar trait** `HasEmpresaContext` a `InventarioProductoController`
2. **Aplicar trait** `HasEmpresaContext` a `EntidadEtiquetaController`
3. **Refactorizar** `ConsecutivoFEController` para usar trait en lugar de método privado
4. **Reemplazar** `$empresaId = $request->user()->empresa_id;` con `$empresaId = $this->getEmpresaId();`
5. **Agregar** empresa\_id a cache keys en métodos index

***

## 2️⃣ PHPSTAN: 162 ERRORES (NIVEL 5) ❌

### Análisis Ejecutado

```bash
vendor/bin/phpstan analyse app/Http/Controllers --level=5 --no-progress
```

**Resultado:** 162 errores encontrados en 48 archivos

### Categorización de Errores

#### 🔴 Categoría 1: Firmas de Método Incorrectas (18 errores)

**Problema:** `flushCache()` invocado con parámetros cuando acepta 0

**Archivos afectados:**

* `CabyController.php` → 3 errores (líneas 221, 355, 429)
* `CodigoActividadEconomicaController.php` → 3 errores (líneas 73, 103, 117)
* `DeduccionLegalController.php` → 3 errores (líneas 78, 113, 127)
* `LogAccesoSistemaController.php` → 3 errores (líneas 82, 112, 126)
* `UrlShortenerController.php` → 3 errores (líneas 102, 166, 199)

**Ejemplo de error:**

```php
// ❌ INCORRECTO
$this->flushCache(['cabys', 'catalogos', 'hacienda']);

// ✅ CORRECTO
$this->flushCache(); // Usa $this->cacheTags internamente
```

**Total controllers afectados:** 5\
**Total líneas a corregir:** 15

#### 🔴 Categoría 2: cacheQueryIfEnabled con 3 Parámetros (3 errores)

**Problema:** Método invocado con 3 parámetros cuando acepta 2

**Archivos afectados:**

* `CuentaPorPagarController.php` → línea 82
* `MovimientoBancarioController.php` → línea 60
* `HorarioRutaController.php` → línea 124

**Ejemplo de error:**

```php
// ❌ INCORRECTO (3 parámetros)
$this->cacheQueryIfEnabled($cacheKey, function() {...}, $this->cacheTags);

// ✅ CORRECTO (2 parámetros)
$this->cacheQueryIfEnabled($cacheKey, function() {...});
```

**Nota:** Sprint 8 documentó que esto se corrigió, pero **NO es cierto** para estos 3 controllers

#### 🟡 Categoría 3: Relaciones Eloquent Indefinidas (15 errores)

**Archivos críticos:**

* `HorarioRutaController.php` → `tiquetesDetalle()` no existe (3 errores)
* `OrdenCompraController.php` → `detalles()` no encontrada
* `PresupuestoController.php` → `detalles()` no encontrada (4 errores)
* `PagoNominaController.php` → `metodoPago()` no encontrada (3 errores)
* `TipoCuentaController.php` → `cuentasContables()` no encontrada (2 errores)
* `ModeloBusController.php` → `busesUnidades()` no existe
* `TiqueteDetalleController.php` → `tiquetesDetalle()` no existe

**Impacto:** Posibles errores en runtime al acceder a relaciones no definidas

#### 🟡 Categoría 4: Tipos de Retorno Incorrectos (20 errores)

**Patrón:** Métodos documentan retornar `JsonResponse` pero retornan `Resource`

**Ejemplos:**

```php
// app/Http/Controllers/API/AlmacenController.php
public function index(): JsonResponse // ← Dice JsonResponse
{
    return AlmacenResource::collection($almacenes); // ← Retorna AnonymousResourceCollection
}
```

**Archivos afectados:**

* `AlmacenController`, `EmpresaController`, `CuentaBancariaController`
* `SucursalController`, `ProveedorController`, `TipoClienteController`
* `TipoComprobanteFeController`, `DeclaracionTributariaController`
* `RetencionImpuestoController`, `ZonaGeograficaController`

**Total:** \~20 métodos (index, show, update)

#### 🟡 Categoría 5: Acceso a Propiedades Indefinidas (40 errores)

**Patrón:** Acceso a `$request->user()->empresa_id` sin PHPDoc

```php
// ❌ PHPStan no sabe que Authenticatable tiene empresa_id
Access to an undefined property Illuminate\Contracts\Auth\Authenticatable::$empresa_id
```

**Archivos afectados:**

* `CategoriaProductoController.php` → 5 errores
* `EmpleadoController.php` → 6 errores
* `UsuarioController.php` → 8 errores
* `ArchivoController.php`, `EtiquetaController.php`, `NotificacionController.php`
* `MensajeHaciendaController.php`, `PlanillaCcssController.php`

**Solución:** Usar trait `HasEmpresaContext` en lugar de acceso directo

#### 🟡 Categoría 6: Tipos de Asignación Incompatibles (10 errores)

**Patrón:** `$model->eliminado = 1` cuando propiedad espera `Carbon|string`

```php
// Ejemplo en CargoController.php:302
Property App\Models\Cargo::$eliminado (Carbon\Carbon|string) does not accept int.
```

**Archivos afectados:**

* `CargoController`, `CategoriaProductoController`, `FormaPagoController`
* `MarcaController`, `UnidadMedidaController`, `PermisoController`
* `RolController`, `EmpleadoController`, `UsuarioController`

**Causa raíz:** Modelos usan trait `HasCustomSoftDeletes` con cast incorrecto

#### 🔵 Categoría 7: Otros Errores (56 errores)

* PHPDoc tags incompatibles (10 errores)
* Parámetros con tipos incorrectos (15 errores)
* Closures no resueltos (8 errores)
* Case-sensitive class names (13 errores en `ConsecutivoFEController`)
* Propiedades modelo indefinidas (10 errores)

### 📊 Resumen por Prioridad

| Prioridad    | Categoría                    | Errores | Esfuerzo |
| ------------ | ---------------------------- | ------- | -------- |
| **🔴 ALTA**  | Firmas flushCache            | 15      | 1 hora   |
| **🔴 ALTA**  | Firmas cacheQueryIfEnabled   | 3       | 30 min   |
| **🔴 ALTA**  | Acceso empresa\_id sin trait | 40      | 2 horas  |
| **🟡 MEDIA** | Relaciones indefinidas       | 15      | 3 horas  |
| **🟡 MEDIA** | Tipos retorno incorrectos    | 20      | 2 horas  |
| **🟡 MEDIA** | Cast eliminado incorrecto    | 10      | 1 hora   |
| **🔵 BAJA**  | Otros errores menores        | 59      | 4 horas  |

**Total:** 162 errores → **Estimado 13.5 horas** de corrección

***

## 3️⃣ SUITE DE TESTS: BLOQUEADA ⚠️

### Estado Actual

**Archivos de test:** 24 tests encontrados

```
tests/Feature/
- EmpresaTest.php
- VentaTest.php
- CuentaBancariaTest.php
- MovimientoBancarioTest.php
- RetencionImpuestoTest.php
- TipoComprobanteFeTest.php
- DeclaracionTributariaTest.php
- PermissionTest.php
- TipoClienteTest.php
- AuthTest.php

tests/Unit/
- HasCustomSoftDeletesTest.php
- HasAuditFieldsTest.php
- UsuarioTest.php
- RoleTest.php
- HasActiveScopeTest.php
- Jobs/GeneratePdfReportJobTest.php
- Jobs/ProcessImportJobTest.php
- Jobs/SendEmailJobTest.php
- Jobs/SyncHaciendaJobTest.php
- Jobs/CleanCacheJobTest.php
```

### Último Intento de Ejecución

```bash
php artisan test --parallel
```

**Error:**

```
FAILED - QueryException: SQLSTATE[HY000] [2002] 
php_network_getaddresses: getaddrinfo for mysql failed: 
Temporary failure in name resolution
```

**Causa raíz:** `.env` configurado para Docker (`DB_HOST=mysql`) pero Docker no está corriendo

### Configuración de Entorno

**`.env` actual:**

```env
DB_CONNECTION=mysql
DB_HOST=mysql  # ← Apunta a servicio Docker
DB_PORT=3306
DB_DATABASE=senselab_core_db
DB_USERNAME=senselab_user
DB_PASSWORD=***
```

**Opciones para resolver:**

#### Opción 1: Usar Docker (RECOMENDADO)

```bash
docker-compose up -d mysql
php artisan migrate --env=testing
php artisan test
```

#### Opción 2: MySQL Local

```bash
# Crear .env.testing con host local
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=senselab_core_test

# Ejecutar
php artisan test
```

### Coverage Desconocido

**Línea base documentada:** Sprint 4 menciona "75% completado", FASE 10 "127/127 tests pasando"

**Realidad:** ❓ **NO SE PUEDE VERIFICAR** sin ejecutar suite

**Pendiente:**

* Número real de tests ejecutables
* Coverage actual por módulo
* Tests fallidos vs pasando
* Assertions totales

***

## 4️⃣ POLICIES Y RBAC: PARCIAL ✅

### Inventario de Policies

**Total policies creadas:** 73 archivos en `app/Policies/`

**Muestreo:**

* ✅ `AlmacenPolicy`, `ProductoPolicy`, `ClienteController` → extienden `BasePolicy`
* ✅ `OrdenCompraPolicy`, `VentaPolicy`, `EmpresaPolicy` → estructura RBAC completa
* ⚠️ `AuditoriaActividadPolicy`, `ArchivoPolicy` → NO extienden BasePolicy
* ⚠️ `SesionUsuarioPolicy`, `RegimenTributarioPolicy` → estructura diferente

### Uso de $this->authorize()

**Búsqueda realizada:**

```bash
grep -rn "\$this->authorize(" app/Http/Controllers/
```

**Resultado:** 50+ coincidencias encontradas (más resultados disponibles)

**Controladores con authorize() verificados:**

* ✅ `PagoNominaController` → 5 authorize() (viewAny, create, view, update, delete)
* ✅ `ProveedorController` → 5 authorize()
* ✅ `ClienteController` → 5 authorize()
* ✅ `ProductoController` → 5 authorize()
* ✅ `RutaController` → 5 authorize()
* ✅ `ConfiguracionController` → 5 authorize()

**Patrón consistente encontrado:**

```php
public function index() {
    $this->authorize('viewAny', Model::class);
}

public function store(Request $request) {
    $this->authorize('create', Model::class);
}

public function show(Model $model) {
    $this->authorize('view', $model);
}

public function update(Request $request, Model $model) {
    $this->authorize('update', $model);
}

public function destroy(Model $model) {
    $this->authorize('delete', $model);
}
```

### ⚠️ Verificación Pendiente

**NO auditados exhaustivamente:**

* Controladores sin authorize() en métodos CRUD
* Métodos custom (index/store/update/destroy tienen authorize, ¿pero qué hay de `resumen()`, `estadisticas()`, etc.?)
* Controladores root (`InventarioProductoController`, `EntidadEtiquetaController`, `ConsecutivoFEController`, `RolPermisoController`, `RolUsuarioController`)

**Acción requerida:** Grep exhaustivo con conteo por archivo

***

## 5️⃣ FORMREQUESTS: BUENO ✅

### Inventario

**Total FormRequests:** 163 archivos en `app/Http/Requests/`

**Categorías encontradas:**

* Store/Update Requests (mayoría)
* Requests de negocio específico:
  * `LoginRequest`, `AsignarRolesRequest`, `AsignarPermisosRequest`
  * `ConvertirMonedaRequest`, `BuscarCabyRequest`
  * `ObtenerSiguienteConsecutivoRequest`, `ResetearConsecutivoRequest`
  * `LibroMayorRequest`, `BalanceComprobacionRequest`
  * `TasaImpuestoVigenteRequest`, `PorNaturalezaRequest`

### Cobertura Estimada

**Controladores principales:** \~70\
**FormRequests creados:** 163\
**Ratio:** \~2.3 requests por controller (Store + Update promedio)

**Conclusión:** ✅ Cobertura parece **completa**

### ⚠️ Verificación Pendiente

* Validar que TODOS los métodos store/update usen FormRequest (no `Request`)
* Verificar reglas de validación en requests críticos (Venta, OrdenCompra, etc.)
* Asegurar consistencia en rules() entre Store y Update

***

## 6️⃣ SWAGGER DOCUMENTATION: GENERADO ✅

### Estado Actual

**Archivo generado:** `storage/api-docs/api-docs.json` (1.1 MB)

**Especificación:**

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Senselab Core API - ERP System",
    "version": "1.0.0"
  },
  "servers": [
    {"url": "http://localhost:8000"},
    {"url": "https://api.senselab.com"}
  ],
  "paths": { ... }
}
```

**Generación exitosa:** Sí (después de limpiar config cache de Docker)

### ⚠️ Cobertura Desconocida

**NO verificado:**

* Número total de endpoints documentados
* Endpoints faltantes sin documentación
* Schemas definidos vs necesarios
* Consistencia entre routes/api.php y Swagger

**Acción requerida:** Parsing de JSON para contar paths y comparar con routes

***

## 7️⃣ BASE DE DATOS: BUENO ✅

### Inventario

* **Migraciones:** 86 archivos
* **Seeders:** 23 archivos
* **Modelos:** 79 archivos

### Estructura

**Seeders encontrados:**

```
database/seeders/
- DatabaseSeeder.php (seeder principal)
- RegimenesSeeder, FormasPagoSeeder, TiposCuentaSeeder
- UnidadesMedidaSeeder, PermisosSeeder, RolesSeeder
- ... (17 seeders adicionales)
```

**Relaciones:** Documentadas en `MODELS_RELATIONS.md` (Sprint anterior)

### ⚠️ Integridad No Verificada

**Pendiente sin ejecución de migraciones:**

* Foreign keys correctas
* Índices aplicados
* Campos `empresa_id` en todas las tablas multi-tenant
* Consistencia entre schema y modelos

***

## 8️⃣ OTROS HALLAZGOS

### Controllers Fuera de API Namespace

**Encontrados en root `app/Http/Controllers/`:**

1. `Controller.php` (base controller - OK)
2. `InventarioProductoController.php` ⚠️
3. `EntidadEtiquetaController.php` ⚠️
4. `ConsecutivoFEController.php` ⚠️
5. `RolPermisoController.php` ⚠️
6. `RolUsuarioController.php` ⚠️

**Problema:** Inconsistencia de namespace (resto están en `API/`)

**Impacto:**

* Rutas probablemente en root (`/inventario-producto`) en lugar de `/api/`
* Middleware de autenticación puede no aplicar
* CORS puede fallar

**Verificación requerida:** Revisar `routes/api.php` y `routes/web.php`

### Trait HasCacheableQueries

**Uso verificado:** Aplicado en 50+ controllers

**Método `flushCache()`:**

```php
// Firma actual en trait
protected function flushCache(): void
{
    if (config('cache.enabled')) {
        Cache::tags($this->cacheTags)->flush();
    }
}
```

**Problema:** 15 invocaciones pasan parámetros que ignora (ver PHPStan)

***

## 📋 PLAN DE ACCIÓN SPRINT 9

### 🔴 FASE 1: Correcciones Críticas Multi-Tenancy (4 horas)

#### Task 1.1: Refactorizar Controllers Pendientes

* [ ] Aplicar trait `HasEmpresaContext` a `InventarioProductoController`
* [ ] Aplicar trait `HasEmpresaContext` a `EntidadEtiquetaController`
* [ ] Refactorizar `ConsecutivoFEController` para usar trait
* [ ] Reemplazar `$request->user()->empresa_id` con `$this->getEmpresaId()`
* [ ] Agregar `'empresa_id' => $empresaId` a cache keys
* [ ] Commit: "fix(tenancy): completar refactor en 3 controllers finales"

#### Task 1.2: Mover Controllers a Namespace API

* [ ] Mover 5 controllers de root a `app/Http/Controllers/API/`
* [ ] Actualizar namespace a `App\Http\Controllers\API`
* [ ] Actualizar rutas en `routes/api.php`
* [ ] Verificar middleware `auth:sanctum` aplicado
* [ ] Commit: "refactor: mover controllers a namespace API estándar"

**Entregable:** 0 accesos directos a `empresa_id`, todos los controllers en API namespace

***

### 🔴 FASE 2: Correcciones PHPStan Alta Prioridad (4 horas)

#### Task 2.1: Firmas de Cache (15 errores)

```bash
# Reemplazo batch con sed
find app/Http/Controllers/API -name "*.php" -exec sed -i \
  's/\$this->flushCache(\[.*\]);/\$this->flushCache();/g' {} \;
```

**Archivos:**

* `CabyController.php`
* `CodigoActividadEconomicaController.php`
* `DeduccionLegalController.php`
* `LogAccesoSistemaController.php`
* `UrlShortenerController.php`

**Commit:** "fix(cache): corregir firmas flushCache en 5 controllers"

#### Task 2.2: cacheQueryIfEnabled con 3 Params (3 errores)

```php
// Corrección manual en:
// - CuentaPorPagarController.php línea 82
// - MovimientoBancarioController.php línea 60
// - HorarioRutaController.php línea 124

// Cambiar de:
$this->cacheQueryIfEnabled($key, $callback, $tags);
// A:
$this->cacheQueryIfEnabled($key, $callback);
```

**Commit:** "fix(cache): corregir cacheQueryIfEnabled en 3 controllers"

#### Task 2.3: Eliminar Accesos Directos empresa\_id (40 errores)

**Controllers a refactorizar:**

* `CategoriaProductoController` (5 errores)
* `EmpleadoController` (6 errores)
* `UsuarioController` (8 errores)
* `ArchivoController`, `EtiquetaController`, `NotificacionController`
* `MensajeHaciendaController`, `PlanillaCcssController`

**Patrón:**

```php
// Cambiar:
$empresaId = $request->user()->empresa_id;
// Por:
$empresaId = $this->getEmpresaId();
```

**Commit:** "fix(tenancy): aplicar HasEmpresaContext en 8 controllers API adicionales"

**Entregable:** 58 errores PHPStan resueltos (de 162)

***

### 🟡 FASE 3: Relaciones Eloquent Faltantes (3 horas)

#### Task 3.1: Agregar Relaciones en Modelos

**HorarioRuta model:**

```php
public function tiquetesDetalle(): HasMany
{
    return $this->hasMany(TiqueteDetalle::class, 'horario_ruta_id');
}
```

**OrdenCompra model:**

```php
public function detalles(): HasMany
{
    return $this->hasMany(DetalleOrdenCompra::class, 'orden_compra_id');
}
```

**Presupuesto model:**

```php
public function detalles(): HasMany
{
    return $this->hasMany(DetallePresupuesto::class, 'presupuesto_id');
}
```

**PagoNomina model:**

```php
public function metodoPago(): BelongsTo
{
    return $this->belongsTo(FormaPago::class, 'forma_pago_id');
}
```

**TipoCuenta model:**

```php
public function cuentasContables(): HasMany
{
    return $this->hasMany(CuentaContable::class, 'tipo_cuenta_id');
}
```

**ModeloBus model:**

```php
public function busesUnidades(): HasMany
{
    return $this->hasMany(BusUnidad::class, 'modelo_bus_id');
}
```

**Commit:** "fix(models): agregar 6 relaciones Eloquent faltantes"

**Entregable:** 15 errores PHPStan resueltos (total acumulado: 73/162)

***

### 🟡 FASE 4: Tipos de Retorno y Casts (3 horas)

#### Task 4.1: Corregir Tipos de Retorno Resource

**Opción A - Cambiar PHPDoc:**

```php
/**
 * @return \Illuminate\Http\Resources\Json\AnonymousResourceCollection
 */
public function index(): JsonResponse
```

**Opción B - Cambiar firma (RECOMENDADO):**

```php
public function index() // Sin tipo de retorno explícito
{
    return AlmacenResource::collection($almacenes);
}
```

**Archivos:** 20 métodos en 10 controllers

**Commit:** "fix(types): corregir tipos de retorno en Resource responses"

#### Task 4.2: Corregir Cast de `eliminado`

**En modelos con `HasCustomSoftDeletes`:**

```php
protected $casts = [
    'eliminado' => 'boolean', // ← Cambiar de 'datetime' a 'boolean'
    'activo' => 'boolean',
];
```

**Modelos afectados:** 10 (Cargo, CategoriaProducto, FormaPago, etc.)

**Commit:** "fix(models): corregir cast de campo eliminado a boolean"

**Entregable:** 30 errores adicionales resueltos (total: 103/162)

***

### 🔵 FASE 5: Tests y Validación (4 horas)

#### Task 5.1: Configurar Entorno de Testing

```bash
# Opción Docker
docker-compose up -d mysql
php artisan migrate:fresh --seed --env=testing

# Opción MySQL Local
cp .env .env.testing
# Editar .env.testing: DB_HOST=127.0.0.1
php artisan migrate:fresh --seed --env=testing
```

#### Task 5.2: Ejecutar Suite Completa

```bash
php artisan test --parallel --coverage-html coverage
```

**Registrar:**

* Total tests ejecutados
* Tests pasando/fallando
* Coverage por módulo
* Errores críticos

#### Task 5.3: Corregir Tests Fallidos

**Prioridad:**

1. Tests de RBAC (PermissionTest, RoleTest)
2. Tests de multi-tenancy (EmpresaTest)
3. Tests de negocio (VentaTest, OrdenCompraTest)

**Entregable:** Reporte de cobertura actualizado, mínimo 80% tests pasando

***

### 🔵 FASE 6: Auditoría de Policies (2 horas)

#### Task 6.1: Verificación Exhaustiva

```bash
# Generar reporte de authorize() por controller
for file in app/Http/Controllers/API/*.php; do
    echo "=== $(basename $file) ==="
    grep -n "\$this->authorize(" "$file" || echo "  ❌ SIN AUTHORIZE"
done > policies_audit.txt
```

#### Task 6.2: Agregar Authorize Faltantes

**En métodos CRUD sin protección:**

```php
public function resumen() {
    $this->authorize('viewAny', Model::class); // ← Agregar
    // ...
}

public function estadisticas() {
    $this->authorize('viewAny', Model::class); // ← Agregar
    // ...
}
```

**Entregable:** 100% métodos públicos con authorize()

***

### 📊 FASE 7: Documentación y Reporte (2 horas)

#### Task 7.1: Validar Swagger Coverage

```bash
# Parsear JSON y contar endpoints
cat storage/api-docs/api-docs.json | jq '.paths | keys | length'

# Comparar con routes
php artisan route:list --json | jq '[.[] | select(.uri | startswith("api/"))] | length'
```

#### Task 7.2: Generar Reporte Final Sprint 9

**Contenido:**

* Estado inicial (esta auditoría)
* Cambios realizados fase por fase
* Métricas finales (PHPStan, tests, coverage)
* Pendientes para Sprint 10

**Entregable:** `SPRINT_9_COMPLETADO.md`

***

## 📊 MÉTRICAS DE ÉXITO SPRINT 9

### Objetivos Cuantitativos

| Métrica                               | Estado Actual | Meta Sprint 9 | Crítico |
| ------------------------------------- | ------------- | ------------- | ------- |
| **Accesos directos empresa\_id**      | 2             | 0             | ✅       |
| **Errores PHPStan Nivel 5**           | 162           | ≤ 50          | ✅       |
| **Controllers sin HasEmpresaContext** | 2             | 0             | ✅       |
| **Firmas cache incorrectas**          | 18            | 0             | ✅       |
| **Tests ejecutados**                  | 0 (bloqueado) | 24            | ⚠️      |
| **Tests pasando**                     | ?             | ≥ 20 (83%)    | ⚠️      |
| **Controllers sin authorize()**       | ?             | 0             | ⚠️      |
| **Relaciones faltantes**              | 6             | 0             | ⚠️      |
| **Namespace inconsistente**           | 5 controllers | 0             | ❌       |

### Criterios de Aceptación

**✅ Sprint 9 se considera EXITOSO si:**

1. ✅ **Multi-tenancy 100% completo** (0 accesos directos, trait en todos los controllers)
2. ✅ **PHPStan ≤ 50 errores** (reducción 69% desde 162)
3. ✅ **Suite de tests ejecutable** (MySQL/Docker configurado)
4. ⚠️ **≥ 80% tests pasando** (mínimo 20 de 24)
5. ⚠️ **Swagger coverage ≥ 90%** (endpoints documentados)

**❌ Sprint 9 NO se considera completo si:**

* Quedan accesos directos a `empresa_id`
* PHPStan > 100 errores
* Tests no ejecutables

***

## 🎯 ESTIMACIÓN DE ESFUERZO

| Fase                  | Horas   | Días (6h/día) |
| --------------------- | ------- | ------------- |
| Fase 1: Multi-tenancy | 4h      | 0.7 días      |
| Fase 2: PHPStan Alta  | 4h      | 0.7 días      |
| Fase 3: Relaciones    | 3h      | 0.5 días      |
| Fase 4: Tipos/Casts   | 3h      | 0.5 días      |
| Fase 5: Tests         | 4h      | 0.7 días      |
| Fase 6: Policies      | 2h      | 0.3 días      |
| Fase 7: Docs          | 2h      | 0.3 días      |
| **TOTAL**             | **22h** | **3.7 días**  |

**Contingencia (+20%):** 26.4 horas → **4.4 días laborables**

**Plazo recomendado:** 5 días calendario

***

## 🚨 RIESGOS IDENTIFICADOS

### Riesgo 1: Vulnerabilidad Multi-Tenant Activa

**Probabilidad:** Alta\
**Impacto:** Crítico\
**Descripción:** 2 controllers (`InventarioProducto`, `EntidadEtiqueta`) pueden exponer datos entre empresas\
**Mitigación:** Priorizar Fase 1, deploy urgente post-corrección

### Riesgo 2: Tests Bloqueados Sin Validación

**Probabilidad:** Media\
**Impacto:** Alto\
**Descripción:** Cambios no validados, posibles regresiones en producción\
**Mitigación:** Configurar Docker inmediatamente, testing manual intensivo

### Riesgo 3: Relaciones Faltantes → Runtime Errors

**Probabilidad:** Media\
**Impacto:** Medio\
**Descripción:** 6 relaciones Eloquent pueden causar errores en endpoints activos\
**Mitigación:** Validar logs de producción, agregar relaciones en Fase 3

### Riesgo 4: PHPStan Warnings Acumulados

**Probabilidad:** Baja\
**Impacto:** Bajo\
**Descripción:** 162 errores dificultan detección de nuevos problemas\
**Mitigación:** Baseline temporal, corrección gradual por sprint

***

## 📌 CONCLUSIONES

### ✅ Fortalezas del Proyecto

1. **Arquitectura sólida:** Traits, Policies, FormRequests bien estructurados
2. **Cobertura de Policies:** 73 policies creadas, RBAC implementado
3. **FormRequests completos:** 163 requests, validación centralizada
4. **Swagger generado:** OpenAPI 3.0, 1.1 MB de documentación
5. **Base de datos robusta:** 86 migraciones, 79 modelos, 23 seeders

### ❌ Debilidades Críticas

1. **Multi-tenancy INCOMPLETO:** 2 controllers vulnerables + 1 no estándar
2. **PHPStan con 162 errores:** Calidad de código comprometida
3. **Tests bloqueados:** Imposible validar regresiones
4. **Documentación inconsistente:** Sprints reportan "100% completado" cuando no es cierto
5. **Namespace inconsistente:** 5 controllers fuera de API namespace

### 🎯 Recomendación Final

**PRIORIDAD MÁXIMA:** Ejecutar Sprint 9 siguiendo plan de acción de 7 fases

**NO continuar con desarrollo nuevo hasta:**

* ✅ Multi-tenancy 100% verificado
* ✅ PHPStan < 50 errores
* ✅ Suite de tests ejecutable y pasando

**Sprint 10 debe enfocarse en:**

* Performance optimization
* Cache warming strategies
* Rate limiting fine-tuning
* Monitoring y observability

***

**Auditor:** GitHub Copilot\
**Método:** Análisis estático completo sin confiar en documentación previa\
**Herramientas:** grep, PHPStan, file\_search, código fuente directo\
**Fecha:** 25 de noviembre de 2025

***

## 📎 ANEXOS

### A. Comandos de Verificación Ejecutados

```bash
# Multi-tenancy
grep -rn "\$request->user()->empresa_id" app/Http/Controllers/
grep -l "use HasEmpresaContext" app/Http/Controllers/*.php | wc -l

# PHPStan
vendor/bin/phpstan analyse app/Http/Controllers --level=5 --error-format=json

# Tests
find tests -name "*.php" -type f | wc -l

# Policies
find app/Policies -name "*Policy.php" | wc -l
grep -rn "\$this->authorize(" app/Http/Controllers/ | wc -l

# FormRequests
find app/Http/Requests -name "*.php" | wc -l

# Base de datos
ls -la database/migrations/ | wc -l
ls -la database/seeders/*.php | wc -l
find app/Models -name "*.php" | wc -l

# Controllers root
ls -la app/Http/Controllers/*.php

# Cache issues
grep -rn "flushCache(\[" app/Http/Controllers/
grep -rn "cacheQueryIfEnabled.*,.*,.*)" app/Http/Controllers/
```

### B. Archivos Clave para Sprint 9

```
app/
├── Http/
│   ├── Controllers/
│   │   ├── InventarioProductoController.php ← CRÍTICO
│   │   ├── EntidadEtiquetaController.php ← CRÍTICO
│   │   ├── ConsecutivoFEController.php ← CRÍTICO
│   │   └── API/
│   │       ├── CategoriaProductoController.php ← PHPStan
│   │       ├── EmpleadoController.php ← PHPStan
│   │       ├── UsuarioController.php ← PHPStan
│   │       ├── CabyController.php ← flushCache
│   │       ├── CodigoActividadEconomicaController.php ← flushCache
│   │       └── ... (48 archivos con errores PHPStan)
│   └── Requests/ (163 archivos ✅)
├── Models/
│   ├── HorarioRuta.php ← Relación faltante
│   ├── OrdenCompra.php ← Relación faltante
│   ├── Presupuesto.php ← Relación faltante
│   ├── PagoNomina.php ← Relación faltante
│   ├── TipoCuenta.php ← Relación faltante
│   └── ModeloBus.php ← Relación faltante
├── Policies/ (73 archivos ✅)
└── Traits/
    └── HasEmpresaContext.php ✅

tests/ (24 archivos, estado desconocido ⚠️)
```

***

**FIN DE AUDITORÍA PRE-SPRINT 9**


---

# 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/docs/archive/auditoria_pre_sprint_9.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.