# Sistema de Menú Deshabilitado por Institución Faltante

## 📋 Descripción General

En lugar de obligar a los operadores a registrar una institución antes de acceder al sistema, ahora **se muestra todo el menú pero deshabilitado** hasta que registren su institución.

## 🎯 Comportamiento

### Para operadores sin institución registrada:
1. **Menú visible pero inactivo**: El menú y todas sus opciones se muestran en gris (opacidad reducida)
2. **Overlay transparente**: Se muestra un overlay sobre el menú que impide clics
3. **Mensajes informativos**: Al intentar hacer clic en cualquier opción del menú, aparece:
   - Tooltip: "Registre su institución para habilitar esta función"
   - Notificación Toast: "Debe registrar su institución para usar esta función"
4. **Acceso a registro**: El operador puede:
   - Navegar al formulario de registro de institución desde la página de "Mi Perfil" o "Configuración"
   - Acceder directamente a `?controller=operador&action=registrarInstitucion`

### Para operadores con institución registrada:
- El menú funciona completamente normal
- Todas las opciones están habilitadas
- Se pueden ejecutar todas las funciones del sistema

## 🔧 Implementación Técnica

### 1. **config/autoload.php** - Validación Global
```php
// Verifica si el operador tiene institución
$_SESSION['operador_sin_institucion'] = !$tieneInstitucion;
```
- En cada carga de página se valida si el operador tiene `id_institucion`
- Si no la tiene, establece la bandera `operador_sin_institucion = true`

### 2. **views/user/template/header.php** - CSS Deshabilitador
```html
<div id="sidebar-container" class="sin-institucion">
    <!-- Menú aquí -->
</div>
```

**Estilos CSS aplicados:**
- `opacity: 0.5` al menú para que se vea translúcido
- `pointer-events: none` para bloquear clics
- `::before` overlay transparente que cubre todo el menú

### 3. **views/user/template/footer.php** - JavaScript Interactivo
```javascript
// Intercepta clics en links del menú deshabilitado
sidebarContainer.find('a.nav-link').on('click', function(e) {
    e.preventDefault();
    toastr.info('Debe registrar su institución...');
});
```

### 4. **views/user/registro_institucion.php** - Formulario de Registro
- Mensaje actualizado a "Paso Inicial Recomendado" (no obligatorio)
- Color de alerta azul (info) en lugar de rojo (warning)
- **Validación de RUC centralizada** usando `/spi/public/assets/js/ruc-validator.js`
- El operador puede ir a registrar su institución en cualquier momento

## 📝 Validación de RUC Centralizada

### ✨ Nueva Característica: RUC Validator Centralizado

El campo RUC ahora utiliza la misma validación que la página de creación de instituciones (`institucion_create.php`). Los cambios incluyen:

#### Archivo de Validación: `/spi/public/assets/js/ruc-validator.js`
- **Clase `RUCValidator`**: Valida RUCs ecuatorianos con algoritmo completo
- **Métodos principales**:
  - `validarRucEcuatoriano(ruc)`: Validación completa del RUC
  - `validarCedulaEcuatoriana(cedula)`: Validación de cédula (para RUC de persona natural)
  - `validarDigitoRucSociedad(ruc)`: Validación de RUC de sociedad pública
  - `validarDigitoRucInstitucion(ruc)`: Validación de RUC de institución pública

#### Validaciones Realizadas:
1. ✅ Exactamente 13 dígitos numéricos
2. ✅ Los primeros dos dígitos corresponden a provincia válida (01-24)
3. ✅ El tercer dígito debe estar entre 0-6 o ser 9 (no 7 u 8)
4. ✅ Validación de dígito verificador según tipo de RUC
5. ✅ Para RUC de persona natural: debe terminar en 001

#### Mensajes de Validación:
- **✅ Success**: "RUC [tipo] válido"
- **❌ Error**: Mensaje específico del error encontrado

#### Características de UX:
- Validación en tiempo real mientras se escribe
- Solo permite números (0-9)
- Límite máximo de 13 caracteres
- Bloquea pegar contenido no numérico
- Estilos visuales: `is-valid` / `is-invalid` para Bootstrap

### Integración en `registro_institucion.php`:
```javascript
// Uso del validador centralizado
const rucValidation = RUCValidator.validarRucEcuatoriano(ruc);
if (!rucValidation.isValid) {
    // Mostrar error específico
    errorMessages.push('RUC: ' + rucValidation.message);
}
```

## 📍 Flujo de Operador Sin Institución

```
┌─────────────────────────────────────┐
│ Operador accede al sistema          │
│ Sin id_institucion registrada       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ autoload.php detecta situación      │
│ $_SESSION['operador_sin_institucion']│
│ = true                              │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ header.php aplica clase             │
│ "sin-institucion" al menú           │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ CSS deshabilita visualmente:        │
│ - Opacidad reducida                 │
│ - Overlay bloqueador                │
│ - Puntero deshabilitado             │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ footer.php JavaScript:              │
│ - Intercepta clics                  │
│ - Muestra notificaciones            │
│ - Sugiere registrar institución     │
└──────────────┬──────────────────────┘
               │
               ▼ (Usuario va a registro)
┌─────────────────────────────────────┐
│ registro_institucion.php:           │
│ - RUC validado con RUCValidator     │
│ - Validación centralizada           │
│ - Mensajes de error específicos     │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ Operador completa formulario        │
│ de registro de institución          │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ OperadorController::registrarInstit │
│ actualiza sesión:                   │
│ $_SESSION['operador_institucion_id']│
│ = $nuevo_id_institucion             │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ En próxima carga:                   │
│ autoload.php detecta institucion    │
│ operador_sin_institucion = false    │
│ Menú se habilita completamente      │
└─────────────────────────────────────┘
```

## 🎨 Cambios Visuales

### Menú Deshabilitado:
- Color gris (reduced opacity)
- Overlay transparente visible
- Cursor: `not-allowed`
- Tooltips informativos

### Menú Habilitado:
- Color normal
- Sin overlay
- Cursor: `pointer`
- Funcionalidad completa

### Campo RUC:
- **Validación en tiempo real** mientras se escribe
- **Indicador visual**: Borde rojo si inválido, verde si válido
- **Mensaje descriptivo**: Debajo del campo especificando qué está mal
- **Input solo numérico**: Rechaza automáticamente caracteres no numéricos

## 📝 Archivos Modificados

| Archivo | Cambio | Razón |
|---------|--------|-------|
| `config/autoload.php` | Cambio de redirección obligatoria a validación silenciosa | Permitir acceso pero con UI deshabilitada |
| `views/user/template/header.php` | Añadido CSS y clase `sin-institucion` | Aplicar estilos de deshabilitado |
| `views/user/template/footer.php` | Añadido JavaScript para interceptar clics | Mostrar notificaciones interactivas |
| `views/user/registro_institucion.php` | Actualizado mensaje, integrado RUCValidator centralizado | Cambiar tono a recomendado y usar validación estándar |

## ✅ Ventajas del Nuevo Sistema

1. **Mejor UX**: El usuario ve todo lo que puede hacer, pero deshabilitado
2. **Menos restrictivo**: Permite exploración visual del sistema
3. **Más intuitivo**: El mensaje es sugestivo, no obligatorio
4. **Flexibilidad**: El operador puede registrar institución cuando lo desee
5. **Visual claro**: La deshabilitación es obviamente visible
6. **Validación consistente**: RUC validado con mismo algoritmo que en admin
7. **Mensajes específicos**: El usuario sabe exactamente qué está mal con su RUC

## 🧪 Pruebas Recomendadas

### Test 1: Operador sin institución
1. Crear operador sin institucion asignada
2. Ingresar al sistema
3. ✅ Verificar que menú aparece gris/deshabilitado
4. ✅ Hacer clic en opción de menú
5. ✅ Verificar que muestra notificación

### Test 2: Validación de RUC
1. Navegar a registro de institución
2. Intentar ingresar RUCs inválidos:
   - RUC con menos de 13 dígitos
   - RUC con más de 13 dígitos
   - RUC con caracteres no numéricos
   - RUC con provincia inválida (00, 25+)
   - RUC con dígito verificador incorrecto
3. ✅ Verificar que muestra mensaje de error específico
4. ✅ Verificar que campo tiene borde rojo

### Test 3: Registro de institución válido
1. Ingresar RUC válido ecuatoriano (ej: 1768013430001)
2. ✅ Verificar que campo tiene borde verde
3. ✅ Verificar que muestra "RUC [tipo] válido"
4. Completar resto del formulario
5. ✅ Después de guardar, menú debe estar habilitado

### Test 4: Operador con institución
1. Crear operador con institución asignada
2. Ingresar al sistema
3. ✅ Menú debe estar completamente habilitado
4. ✅ Poder hacer clic en cualquier opción

## 🔍 Debug

Para ver el estado en la consola:
```javascript
console.log($_SESSION['operador_sin_institucion']);
console.log($('#sidebar-container').hasClass('sin-institucion'));

// Para validar RUC manualmente
console.log(RUCValidator.validarRucEcuatoriano('1768013430001'));
```

## 📌 Notas de Desarrollo

- La validación sucede en `autoload.php` ANTES de cargar cualquier controlador
- El estado se guarda en `$_SESSION['operador_sin_institucion']` para fácil acceso
- Los estilos CSS se aplican inline en el header para máxima compatibilidad
- El JavaScript usa jQuery para máxima compatibilidad con AdminLTE
- El archivo `ruc-validator.js` es reutilizable en otros formularios
- La clase `RUCValidator` es agnóstica al framework y puede usarse en cualquier contexto