# Contexto de Empresa Activa — QSR Platform

## ¿Qué es?

Varios modelos del sistema filtran sus datos por la empresa con la que el usuario está trabajando en ese momento (p. ej. `Sector`, `Auditor`, `Norma`, `Tiposervicio`). Este contexto se resuelve mediante el helper `empresa_activa_id()` definido en `app/Helpers/helpers.php`.

---

## Cómo se resuelve el ID de empresa

El helper intenta obtener el ID en este orden de prioridad:

| Prioridad | Fuente | Cuándo aplica | Validada |
|---|---|---|---|
| 1 | `session('idEmpresaActiva')` | Blade / navegador con cookie de sesión | ✅ Al guardar en sesión |
| 2 | Header HTTP `X-Empresa-Id` | Vue, axios, fetch desde SPA | ✅ En el helper |
| 3 | Input `idEmpresaId` (body o query) | Postman, curl, clientes REST | ✅ En el helper |
| 4 | Primera empresa del usuario autenticado | Fallback sin contexto | ✅ Solo empresas asignadas |

Las opciones 2 y 3 verifican que el ID enviado pertenezca al usuario autenticado antes de usarlo. Si se manda una empresa no asignada, el helper cae al fallback (primera empresa del usuario).

Si ninguna fuente provee un ID válido y el usuario no tiene empresas, el helper devuelve `null` y el modelo **no filtra por empresa**.

---

## Instrucciones por cliente

### Blade / Navegador

No requiere ningún cambio. Al hacer login con el formulario web, la sesión guarda automáticamente `idEmpresaActiva` cuando el usuario selecciona su empresa en el selector. Todas las requests posteriores del navegador incluyen la cookie de sesión.

---

### Vue / SPA (axios)

Agrega el header `X-Empresa-Id` en cada request que necesite contexto de empresa. Lo más práctico es configurarlo globalmente en la instancia de axios:

```js
// src/plugins/axios.js (o donde configures tu instancia)
import axios from 'axios'

const http = axios.create({
    baseURL: import.meta.env.VITE_API_URL,
})

// Interceptor: inyecta empresa activa en todas las requests
http.interceptors.request.use(config => {
    const idEmpresa = localStorage.getItem('idEmpresaActiva') // o tu store/pinia
    if (idEmpresa) {
        config.headers['X-Empresa-Id'] = idEmpresa
    }
    return config
})

export default http
```

Cuando el usuario cambia de empresa en el frontend, actualiza `localStorage.getItem('idEmpresaActiva')` y el interceptor lo tomará en la siguiente request.

---

### Postman / curl / clientes REST

Tienes dos opciones equivalentes:

**Opción A — Header:**
```
X-Empresa-Id: 2
```

**Opción B — Body o query param:**
```json
{
  "idEmpresaId": 2
}
```
O como query string: `?idEmpresaId=2`

Ejemplo completo en curl:
```bash
curl -X POST https://tudominio.com/api/operacion/sector/listar \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "X-Empresa-Id: 2" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

## Cómo usarlo en un modelo nuevo

En cualquier modelo que necesite filtrar por empresa, usa el helper directamente:

```php
public static function lista(array $request = []): mixed
{
    $query = self::query();

    $idEmpresa = empresa_activa_id();
    if ($idEmpresa) {
        $query->whereHas('empresas', fn($q) => $q->where('base_empresa.idEmpresa', $idEmpresa));
    }

    // resto de filtros...
    return $query->paginate($request['porPagina'] ?? 15);
}
```

No uses `session('idEmpresaActiva')` directamente — usa siempre `empresa_activa_id()` para que funcione en todos los contextos.

---

## Documentación Scribe

Si el endpoint recibe `idEmpresaId` opcionalmente (modo Postman/body), documéntalo así:

```php
/**
 * @bodyParam idEmpresaId int optional ID de empresa activa (solo necesario en clientes API sin sesión). Example: 2
 */
```

---

## Archivos relacionados

| Archivo | Rol |
|---|---|
| `app/Helpers/helpers.php` | Define `empresa_activa_id()` |
| `routes/modulos/default/inicio-view.php` | Ruta `activar-empresa` — guarda `idEmpresaActiva` en sesión tras login |
| `routes/modulos/base/empresa-view.php` | Ruta `cambiar` — guarda `idEmpresaActiva` al cambiar empresa desde el admin |
| `app/Models/Modulos/Operacion/Sector.php` | Ejemplo de uso |
| `app/Models/Modulos/Operacion/Auditor.php` | Ejemplo de uso |
| `app/Models/Modulos/Operacion/Norma.php` | Ejemplo de uso |
| `app/Models/Modulos/Operacion/Tiposervicio.php` | Ejemplo de uso |