# SACG - Sistema Administrador de Cronogramas

Aplicación Angular 19 con PrimeNG para la gestión de cronogramas de concesiones, utilizando autenticación directa con Keycloak.

## Características Principales

- Autenticación DirectAuth con Keycloak (implementación moderna sin usar keycloak-angular)
- Componentes Standalone Angular 19
- Interfaz de usuario con PrimeNG
- Gestión de cronogramas y concesiones
- Exportación de datos a PDF y Excel

## Instalación

### Requisitos Previos

- Node.js (versión 20.x o superior)
- npm (incluido con Node.js)
- Keycloak Server (para autenticación)

### Pasos de Instalación

1. **Clonar el Repositorio**

   ```bash
   git clone <URL-del-repositorio>
   cd sacg-cronogramas
   ```

2. **Configurar Variables de Entorno**

   Copie el archivo de plantilla de entorno y configúrelo para su entorno:

   ```bash
   cp .env.template .env
   ```

   Edite el archivo `.env` con la configuración de su entorno de Keycloak:

   ```env
   # Keycloak Configuration
   KEYCLOAK_URL=http://localhost:8080
   KEYCLOAK_REALM=angular-app
   KEYCLOAK_CLIENT_ID=angular-app
   KEYCLOAK_CLIENT_SECRET=your-client-secret
   
   # API Configuration
   API_BASE_URL=/api
   
   # Environment
   NODE_ENV=development
   ```

3. **Instalar Dependencias**

   ```bash
   npm install
   ```

4. **Iniciar el Servidor de Desarrollo**

   ```bash
   npm start
   ```

   La aplicación estará disponible en `http://localhost:4200/`

## Configuración de Keycloak

### Configuración del Servidor

1. **Instalar y Ejecutar Keycloak**:
   - Descargue Keycloak desde [keycloak.org](https://www.keycloak.org/downloads)
   - Inicie el servidor: `bin/kc.[sh|bat] start-dev`
   - Acceda a la consola de administración: `http://localhost:8080/admin`

2. **Crear un Realm**:
   - Cree un nuevo realm llamado `angular-app`
   - Este nombre debe coincidir con su variable `KEYCLOAK_REALM` en `.env`

3. **Crear un Cliente**:
   - Cree un nuevo cliente con ID `angular-app` (debe coincidir con `KEYCLOAK_CLIENT_ID`)
   - Configure:
     - Access Type: `confidential` o `public` (según su caso)
     - Valid Redirect URIs: `http://localhost:4200/*`
     - Web Origins: `http://localhost:4200` (o agregar `+` para permitir cualquier origen)

4. **Configurar Usuarios y Roles**:
   - Cree usuarios para pruebas
   - Configure roles como `admin`, `user`, etc.
   - Asigne roles a los usuarios

### Integración con la Aplicación

La aplicación utiliza una implementación moderna de autenticación directa con Keycloak, sin depender del paquete keycloak-angular que está deprecado. En su lugar:

- Utiliza el protocolo OpenID Connect para autenticación directa
- Gestiona tokens manualmente para mayor control
- Implementa renovación automática de tokens
- Provee detección de inactividad de usuario

## Entornos de Ejecución

Los archivos de entorno están configurados en `src/environments/`:

- **environment.ts**: Configuración para desarrollo local
- **environment.prod.ts**: Configuración para producción

Las variables de entorno relacionadas con Keycloak se definen en estos archivos y se cargan desde los valores configurados en `.env`.

## Flujo de Autenticación

1. **Login**:
   - Usuario ingresa credenciales en la pantalla de login
   - La aplicación realiza una solicitud directa al endpoint de token de Keycloak
   - Después de una autenticación exitosa, se almacena el token JWT

2. **Manejo de Tokens**:
   - El token se almacena en localStorage para persistencia entre sesiones
   - Se configura un temporizador para renovación automática del token
   - Se decodifica el token para extraer información del usuario

3. **Protección de Rutas**:
   - Las rutas protegidas utilizan el guardia `authGuard`
   - La verificación se basa en la validez del token almacenado

4. **Interceptor HTTP**:
   - Todas las solicitudes HTTP incluyen automáticamente el token de autenticación
   - En caso de error 401, se intenta renovar el token automáticamente

## Comandos Disponibles

| Comando | Descripción |
|---------|-------------|
| `npm start` | Inicia servidor de desarrollo en http://localhost:4200 |
| `npm run build` | Compila el proyecto para desarrollo |
| `npm run build:prod` | Compila para producción con optimizaciones |
| `npm test` | Ejecuta pruebas unitarias |

## Estructura del Proyecto

```
/sacg-cronogramas/
├── src/
│   ├── app/
│   │   ├── components/        # Componentes compartidos
│   │   ├── guards/            # Guardias de ruta (authGuard)
│   │   ├── interceptors/      # Interceptores HTTP (authInterceptor)
│   │   ├── models/            # Interfaces de datos
│   │   ├── pages/             # Componentes de página
│   │   ├── services/
│   │   │   ├── direct-auth.service.ts  # Implementación DirectAuth
│   │   │   └── ...            # Otros servicios
│   │   └── utils/             # Utilidades
│   ├── environments/          # Configuración de entornos
│   │   ├── environment.ts     # Desarrollo
│   │   └── environment.prod.ts # Producción
│   ├── pipes/                 # Pipes personalizados
│   ├── index.html             # HTML principal
│   ├── main.ts                # Punto de entrada
│   └── styles.scss            # Estilos globales
├── public/                    # Recursos estáticos
│   └── keycloak.json          # Configuración de Keycloak
├── .env.template              # Plantilla para variables de entorno
├── angular.json               # Configuración de Angular
├── package.json               # Dependencias y scripts
└── README.md                  # Esta documentación
```

## Solución de Problemas

### Problemas Comunes de Autenticación

1. **No se puede iniciar sesión**:
   - Verifique que las credenciales sean correctas
   - Asegúrese de que el servidor Keycloak esté ejecutándose
   - Compruebe que el realm y client ID en `.env` coincidan con su configuración de Keycloak

2. **Token expirado o inválido**:
   - La aplicación debería renovar automáticamente el token
   - Si persiste, intente cerrar sesión y volver a iniciar sesión

3. **Redirecciones en bucle**:
   - Limpie el localStorage del navegador
   - Verifique la configuración de URLs en el cliente Keycloak

## Recursos Adicionales

- [Documentación oficial de Keycloak](https://www.keycloak.org/documentation)
- [Angular Security Best Practices](https://angular.io/guide/security)
- [Tutorial completo de Keycloak](tutorial-keycloak-completo.md)