# ogGui - OpenGnsys Web Console

ogGui es una aplicación web frontend desarrollada en **Angular 18** que proporciona una interfaz de usuario completa e intuitiva para la gestión y administración de la herramienta **OpenGnsys**. OpenGnsys es un sistema de clonación y administración masiva de equipos informáticos orientado a entornos educativos y corporativos.

## 📋 Tabla de Contenidos

- [Descripción General](#-descripción-general)
- [Arquitectura Técnica](#-arquitectura-técnica)
- [Módulos Principales](#-módulos-principales)
- [Análisis de Componentes](#-análisis-de-componentes)
- [Servicios y Guards](#-servicios-y-guards)
- [Características Destacadas](#-características-destacadas)
- [Ambiente de Desarrollo](#-ambiente-de-desarrollo)
- [Instalación](#-instalación)
- [Configuración](#-configuración)
- [Integración con Servicios Externos](#-integración-con-servicios-externos)
- [Estructura del Proyecto](#-estructura-del-proyecto)

## 🎯 Descripción General

ogGui es la consola web de administración para OpenGnsys que permite a los administradores de sistemas gestionar de manera centralizada:

- **Clientes y equipos** organizados en aulas y unidades organizativas
- **Imágenes del sistema** (creación, despliegue, versionado con Git)
- **Tareas y comandos** (programados o inmediatos)
- **Configuraciones de red** (DHCP, PXE, arranque)
- **Usuarios y permisos** basados en roles
- **Hardware y software** (perfiles, inventarios)
- **Monitorización en tiempo real** del estado de los equipos

### Versión Actual
**v0.26.0** - Octubre 2025

## 🏗 Arquitectura Técnica

### Stack Tecnológico

| Tecnología | Versión | Propósito |
|------------|---------|-----------|
| **Angular** | 18.0.0 | Framework principal |
| **Angular Material** | 18.0.0 | Componentes UI |
| **TypeScript** | 5.4.5 | Lenguaje de programación |
| **RxJS** | 7.8.0 | Programación reactiva |
| **NGX-Translate** | 16.0.3 | Internacionalización |
| **NGX-Charts** | 20.5.0 | Gráficos y visualizaciones |
| **NGX-Toastr** | 19.0.0 | Notificaciones |
| **Joyride** | 2.5.0 | Tours guiados |
| **JWT-Decode** | 4.0.0 | Manejo de autenticación |
| **PapaParse** | 5.4.1 | Procesamiento CSV |

### Arquitectura de Aplicación

La aplicación sigue el patrón **Model-View-Component** de Angular con:

1. **Lazy Loading**: Módulos cargados bajo demanda
2. **Guards**: Protección de rutas basada en roles
3. **Interceptors**: Manejo centralizado de peticiones HTTP
4. **Services**: Lógica de negocio compartida
5. **Reactive Forms**: Formularios reactivos con validación
6. **Material Design**: Diseño consistente y moderno

### Estructura de Layouts

```
├── AuthLayoutComponent     → Layout para autenticación (Login)
└── MainLayoutComponent     → Layout principal de la aplicación
    ├── HeaderComponent     → Barra superior con navegación
    └── SidebarComponent    → Menú lateral colapsable
```

## 🧩 Módulos Principales

### 1. **Administración** (`admin/`)

Gestión de usuarios, roles y configuración del sistema.

#### Componentes:
- **UsersComponent**: CRUD de usuarios del sistema
- **RolesComponent**: Gestión de roles y permisos
- **EnvVarsComponent**: Configuración de variables de entorno

**Características:**
- Sistema de roles jerárquicos (Super Admin, OU Admin, OU Operator, OU Minimal)
- Cambio de contraseña
- Asignación de unidades organizativas
- Gestión de permisos granulares

---

### 2. **Grupos y Clientes** (`groups/`)

Módulo central para la gestión de equipos organizados en aulas y unidades organizativas.

#### Componentes principales:
- **GroupsComponent**: Vista principal de grupos
- **ClassroomViewComponent**: Vista de aula con distribución visual
- **ClientViewComponent**: Vista detallada de un cliente
- **ManageClientComponent**: Creación/edición de clientes
- **ShowOrganizationalUnitComponent**: Gestión de OUs
- **ClientDetailsComponent**: Detalles técnicos del cliente

#### Subcomponentes especializados:
- **PartitionAssistantComponent**: Asistente de particionado de discos
  - Soporte para múltiples discos
  - Tipos de partición (Primaria, Extendida, Lógica, EFI)
  - Sistemas de archivos (ext4, NTFS, FAT32, etc.)
  - Validación de tamaños y estructura
  
- **CreateClientImageComponent**: Creación de imágenes desde cliente
- **DeployImageComponent**: Despliegue de imágenes
- **RunScriptAssistantComponent**: Ejecución de scripts con variables

**Características:**
- Vista de árbol jerárquico de OUs
- Vista de tarjetas con estado en tiempo real
- Filtros avanzados por centro, estado, firmware
- Drag & Drop para organización
- Estados de cliente: desconectado, ocupado, inicializando, Linux, Windows, etc.
- Ejecución masiva de comandos

---

### 3. **Comandos** (`commands/`)

Sistema completo de gestión de comandos y tareas.

#### Componentes:
- **CommandsComponent**: Comandos individuales
- **CommandsGroupsComponent**: Grupos de comandos secuenciales
- **CommandsTaskComponent**: Tareas programadas y scripts

#### Subcomponentes:
- **CreateCommandComponent**: Creador de comandos personalizados
- **ExecuteCommandComponent**: Formulario de ejecución
- **CreateTaskComponent**: Planificador de tareas
- **CreateTaskScheduleComponent**: Tareas programadas con calendario
- **CreateTaskScriptComponent**: Tareas basadas en scripts

**Características:**
- Comandos predefinidos (no editables)
- Comandos personalizados
- Agrupación de comandos secuenciales
- Programación con calendarios
- Ejecución inmediata o diferida
- Variables parametrizables en scripts

---

### 4. **Repositorios e Imágenes** (`repositories/`, `images/`)

Gestión completa del ciclo de vida de imágenes del sistema.

#### Componentes principales:
- **RepositoriesComponent**: Lista de repositorios
- **MainRepositoryViewComponent**: Vista detallada de repositorio
- **ImagesComponent**: Gestión de imágenes

#### Operaciones con imágenes:
- **ManageRepositoryComponent**: Crear/editar repositorios
- **ImportImageComponent**: Importar imágenes externas
- **ExportImageComponent**: Exportar imágenes
- **BackupImageComponent**: Backup de imágenes
- **ConvertImageComponent**: Conversión de formatos
- **ConvertImageToVirtualComponent**: Conversión a imagen virtual
- **EditImageComponent**: Edición de metadatos
- **RenameImageComponent**: Renombrado de imágenes

#### Integración con Git:
- **ShowGitCommitsComponent**: Historial de commits
- **CreateTagModalComponent**: Etiquetado de versiones
- **CreateBranchModalComponent**: Gestión de ramas
- **BackupRepositoryModalComponent**: Backup de repositorio Git

**Características:**
- Versionado de imágenes con Git (OgGit)
- Imágenes monolíticas y Git
- Verificación de integridad
- Sincronización con repositorios remotos
- Gestión de usuarios SSH y puertos
- Cache de imágenes

---

### 5. **OgBoot - Arranque PXE** (`ogboot/`)

Configuración del sistema de arranque por red.

#### Componentes:
- **PXEimagesComponent**: Gestión de imágenes PXE (OgLives)
- **PxeComponent**: Templates de arranque PXE
- **PxeBootFilesComponent**: Archivos de arranque
- **OgbootStatusComponent**: Estado del servicio OgBoot

#### Funcionalidades:
- **CreatePXEImageComponent**: Creación de imágenes OgLive
- **CreatePxeTemplateComponent**: Templates de configuración
- **ShowTemplateContentComponent**: Visualización de templates

**Características:**
- Gestión de unidades de almacenamiento
- Precarga de modelos de templates
- Sincronización automática
- Gestión de BootfileNames

---

### 6. **OgDHCP - Servidor DHCP** (`ogdhcp/`)

Gestión del servidor DHCP integrado.

#### Componentes:
- **OgDhcpSubnetsComponent**: Gestión de subredes
- **StatusComponent**: Estado del servicio DHCP
- **CreateSubnetComponent**: Creación de subredes
- **AddClientsToSubnetComponent**: Asignación de clientes
- **ShowClientsComponent**: Búsqueda detallada de clientes

**Características:**
- Sincronización automática
- Nombres lógicos para IPs
- Asignación masiva de clientes
- Búsqueda avanzada de equipos

---

### 7. **Calendarios** (`calendar/`)

Sistema de calendarios para programación de tareas.

#### Componentes:
- **CalendarComponent**: Gestión de calendarios
- **CreateCalendarComponent**: Creación de calendarios
- **CreateCalendarRuleComponent**: Reglas de calendario

**Características:**
- Calendarios con reglas recurrentes
- Integración con tareas programadas
- Asignación a OUs

---

### 8. **Trazas y Logs** (`task-logs/`)

Monitorización de la ejecución de tareas.

#### Componentes:
- **TaskLogsComponent**: Historial de trazas
- **ClientTaskLogsComponent**: Logs por cliente
- **ClientPendingTasksComponent**: Cola de tareas pendientes
- **InputDialogComponent**: Diálogos de entrada
- **OutputDialogComponent**: Visualización de salidas

**Características:**
- Logs en tiempo real (Mercure)
- Integración con Grafana
- Filtros avanzados
- Cola de acciones
- Cancelación de tareas
- Marcado manual de completado
- Estados: enviado, en progreso, completado, error, ocupado

---

### 9. **Software y Perfiles** (`software/`, `software-profile/`)

Gestión de aplicaciones y perfiles de software.

#### Componentes:
- **SoftwareComponent**: Catálogo de software
- **SoftwareProfileComponent**: Perfiles de instalación
- **CreateSoftwareComponent**: Alta de aplicaciones
- **CreateSoftwareProfileComponent**: Creación de perfiles

**Características:**
- Inventario de software
- Perfiles reutilizables
- Asignación a particiones

---

### 10. **Hardware** (`hardware/`, `hardware-profile/`, `hardware-type/`)

Sistema de gestión de hardware.

#### Componentes:
- **HardwareComponent**: Inventario de hardware
- **HardwareProfileComponent**: Perfiles de hardware
- **HardwareTypeComponent**: Tipos de hardware
- **HardwareCollectionModalComponent**: Colecciones
- **ShowDetailsComponent**: Detalles de hardware

**Características:**
- Perfiles de hardware
- Tipos y categorías
- Inventario automático

---

### 11. **Sistemas Operativos** (`operative-system/`)

Gestión de sistemas operativos.

#### Componentes:
- **OperativeSystemComponent**: Lista de SOs
- **CreateOperativeSystemComponent**: Alta de SOs

---

### 12. **Menús** (`menus/`)

Configuración de menús de arranque.

#### Componentes:
- **MenusComponent**: Gestión de menús
- **CreateMenuComponent**: Creación de menús

---

### 13. **Estado Global** (`global-status/`)

Dashboard de monitorización general.

#### Componentes:
- **GlobalStatusComponent**: Vista general del sistema
- **StatusTabComponent**: Pestañas de estado

**Características:**
- Estado de clientes en tiempo real
- Estado de repositorios
- Gráficos y estadísticas
- Integración con Mercure

---

## 🔐 Servicios y Guards

### Servicios Principales

#### **AuthService** (`services/auth.service.ts`)
- Autenticación basada en JWT
- Gestión de tokens (access + refresh)
- Sistema de roles jerárquicos:
  - `super-admin`: Acceso total
  - `ou-admin`: Administrador de OU
  - `ou-operator`: Operador de OU
  - `ou-minimal`: Permisos mínimos
- Decodificación y validación de tokens
- Logout seguro

#### **ConfigService** (`services/config.service.ts`)
- Carga dinámica de configuración desde `config.json`
- Variables de entorno:
  - `apiUrl`: URL del backend
  - `mercureUrl`: URL del servidor Mercure

#### **TranslationService** (`services/translation.service.ts`)
- Gestión de idiomas (ES/EN)
- Integración con NGX-Translate

### Guards

#### **roleGuard** (`guards/role.guard.ts`)
- Protección de rutas por roles
- Verificación de permisos por página
- Redirección en caso de acceso no autorizado

#### **LogoutGuard** (`guards/logout.guard.ts`)
- Prevención de acceso a login si ya está autenticado

### Interceptors

#### **CustomInterceptor** (`core/services/custom.interceptor.ts`)
- Inyección automática de token JWT
- Manejo de errores HTTP
- Refresh automático de tokens

---

## ✨ Características Destacadas

### 🔄 Actualización en Tiempo Real
- Integración con **Mercure** para notificaciones push
- Actualización automática del estado de clientes
- Logs en tiempo real

### 📊 Visualizaciones
- Gráficos con NGX-Charts
- Vista de aula con distribución visual
- Dashboard de estado global

### 🌍 Internacionalización (i18n)
- Soporte multiidioma (Español/Inglés)
- Más de 600 traducciones
- Cambio dinámico de idioma

### 🎨 UX/UI Moderna
- Material Design
- Responsive (adaptable a móviles)
- Tours guiados (Joyride)
- Notificaciones toast
- Spinners de carga
- Modales overlay

### 🛡️ Seguridad
- Autenticación JWT
- Guards de rutas
- Roles granulares
- Interceptores HTTP

### 📦 Optimización
- Lazy Loading de módulos
- Tree Shaking
- AOT Compilation
- Código optimizado para producción

---

## 🖥 Ambiente de Desarrollo

### Requisitos del Sistema

- **Sistema Operativo**: Ubuntu 22.04 LTS (o superior)
- **Node.js**: v22.1.0
- **npm**: 10.7.0
- **Angular CLI**: 18.0.1
- **Angular Core**: 18.0.0
- **Angular Material**: 18.0.0

### Editor Recomendado
- Visual Studio Code 1.87.2 (o superior)

---

## 📦 Instalación

### 1. Instalar Node.js

```bash
# Descargar Node.js v22.1.0 desde:
# https://nodejs.org
```

### 2. Instalar npm (si no está incluido)

```bash
sudo apt install npm
```

### 3. Instalar Angular CLI

```bash
npm install -g @angular/cli
```

### 4. Clonar el repositorio

```bash
git clone <url-del-repositorio>
cd oggui
```

### 5. Instalar dependencias

```bash
cd ogWebconsole
npm install
```

### 6. Ejecutar en modo desarrollo

```bash
ng serve
```

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

### 7. Compilar para producción

```bash
ng build --configuration production
```

Los archivos compilados estarán en el directorio `dist/`

---

## ⚙️ Configuración

### Archivo de Configuración

**Ubicación**: `ogWebconsole/src/assets/config.json`

```json
{
    "apiUrl": "https://127.0.0.1:8443",
    "mercureUrl": "https://localhost:3000/.well-known/mercure"
}
```

### Variables Configurables

| Variable | Descripción | Ejemplo |
|----------|-------------|---------|
| `apiUrl` | URL del backend de OpenGnsys | `https://api.opengnsys.com:8443` |
| `mercureUrl` | URL del servidor Mercure para eventos en tiempo real | `https://mercure.example.com/.well-known/mercure` |

### Configuración de Nginx

Un archivo de configuración de ejemplo está disponible en:
```
etc/nginx/oggui.conf
```

---

## 🔗 Integración con Servicios Externos

### Backend OpenGnsys
- **Comunicación**: API REST (HTTPS)
- **Autenticación**: JWT (Bearer Token)
- **Formato**: JSON

### Mercure Hub
- **Propósito**: Notificaciones push en tiempo real
- **Protocolo**: Server-Sent Events (SSE)
- **Uso**: Estado de clientes, logs, trazas

### OgGit
- **Propósito**: Versionado de imágenes
- **Funcionalidades**:
  - Commits, tags, branches
  - Push/Pull
  - Backup de repositorios
  - Gestión de conflictos

### Grafana
- **Propósito**: Logs en tiempo real
- **Integración**: Enlaces directos a dashboards
- **Ámbito**: Clientes y componentes

---

## 📁 Estructura del Proyecto

```
oggui/
├── bin/
│   └── start-oggui.sh              # Script de inicio
├── debian/                         # Paquete Debian
├── docs/
│   └── VERSIONS.md
├── etc/
│   └── nginx/
│       └── oggui.conf              # Configuración Nginx
├── Jenkins/                        # CI/CD
├── ogWebconsole/                   # 🔥 Aplicación Angular principal
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/         # Componentes de la aplicación
│   │   │   │   ├── admin/          # Administración
│   │   │   │   ├── calendar/       # Calendarios
│   │   │   │   ├── commands/       # Comandos y tareas
│   │   │   │   ├── global-status/  # Estado global
│   │   │   │   ├── groups/         # Grupos y clientes
│   │   │   │   ├── hardware/       # Hardware
│   │   │   │   ├── images/         # Imágenes
│   │   │   │   ├── login/          # Autenticación
│   │   │   │   ├── menus/          # Menús
│   │   │   │   ├── ogboot/         # PXE Boot
│   │   │   │   ├── ogdhcp/         # DHCP
│   │   │   │   ├── operative-system/ # Sistemas operativos
│   │   │   │   ├── repositories/   # Repositorios
│   │   │   │   ├── software/       # Software
│   │   │   │   └── task-logs/      # Trazas
│   │   │   ├── core/
│   │   │   │   └── services/
│   │   │   │       └── custom.interceptor.ts
│   │   │   ├── guards/             # Guards de rutas
│   │   │   ├── layout/             # Layouts
│   │   │   ├── services/           # Servicios globales
│   │   │   ├── shared/             # Componentes compartidos
│   │   │   ├── app.module.ts
│   │   │   └── app-routing.module.ts
│   │   ├── assets/
│   │   │   ├── config.json         # 🔧 Configuración
│   │   │   └── images/             # Recursos gráficos
│   │   ├── locale/
│   │   │   ├── es.json             # Traducciones español
│   │   │   └── en.json             # Traducciones inglés
│   │   └── styles.css
│   ├── angular.json
│   ├── package.json
│   └── tsconfig.json
├── CHANGELOG.md                    # Historial de cambios
├── README.md                       # 📖 Este archivo
└── package.json
```

---

## 🧪 Testing

### Ejecutar tests unitarios

```bash
cd ogWebconsole
ng test
```

Los tests se ejecutan con **Karma** y **Jasmine**.

### Resultados

Los reportes JUnit se generan en:
```
ogWebconsole/test-results/ogGui-junit-report.xml
```

---

## 🚀 Despliegue

### Build de producción

```bash
cd ogWebconsole
ng build --configuration production
```

### Empaquetado Debian

El proyecto incluye archivos para crear un paquete `.deb`:

```bash
# Ver debian/ para la configuración del paquete
```

### CI/CD con Jenkins

Pipeline definido en:
```
Jenkins/Jenkinsfile-deb-pkg
```

---

## 🔄 Changelog

Para ver el historial detallado de cambios, consultar:
- [CHANGELOG.md](CHANGELOG.md)
- [docs/VERSIONS.md](docs/VERSIONS.md)

### Últimas actualizaciones (v0.26.0 - Oct 2025):
- ✅ Eliminados campos redundantes en creación/edición de clientes
- ✅ Autocompletado de disco en particionador cuando hay solo 1
- ✅ Filtrado de sistemas de archivos según tipo de partición

---

## 👥 Roles y Permisos

### Jerarquía de Roles

1. **Super Admin** (`ROLE_SUPER_ADMIN`)
   - Acceso completo a todas las funcionalidades
   - Gestión de usuarios y roles
   - Gestión de variables de entorno

2. **OU Admin** (`ROLE_ORGANIZATIONAL_UNIT_ADMIN`)
   - Gestión completa de su unidad organizativa
   - Todas las funcionalidades excepto administración global

3. **OU Operator** (`ROLE_ORGANIZATIONAL_UNIT_OPERATOR`)
   - Operaciones estándar en su OU
   - Permisos limitados

4. **OU Minimal** (`ROLE_ORGANIZATIONAL_UNIT_MINIMAL`)
   - Permisos mínimos de visualización

---

## 🛠 Tecnologías y Librerías

### Core
- **Angular 18**: Framework SPA
- **TypeScript**: Tipado estático
- **RxJS**: Programación reactiva

### UI/UX
- **Angular Material**: Componentes UI
- **NGX-Charts**: Gráficos
- **NGX-Toastr**: Notificaciones
- **NGX-Joyride**: Tours interactivos
- **Angular CDK**: Drag & Drop

### Utilidades
- **NGX-Translate**: i18n
- **JWT-Decode**: Tokens
- **PapaParse**: CSV
- **Karma/Jasmine**: Testing

---

## 📝 Convenciones de Código

- **Idioma**: Español para UI, comentarios en español
- **Estilo**: Angular Style Guide
- **Formato**: Prettier/ESLint
- **Componentes**: Modular y reutilizable
- **Servicios**: Singleton con `providedIn: 'root'`

---

## 📞 Soporte

Para reportar bugs o solicitar funcionalidades, utilizar el sistema de issues del repositorio.

---

## 📄 Licencia

[Especificar licencia del proyecto]

---

## 🙏 Contribuciones

Las contribuciones son bienvenidas. Por favor:
1. Fork del proyecto
2. Crear rama feature (`git checkout -b feature/nueva-funcionalidad`)
3. Commit de cambios (`git commit -m 'Añadir nueva funcionalidad'`)
4. Push a la rama (`git push origin feature/nueva-funcionalidad`)
5. Abrir Pull Request

---

**Desarrollado para OpenGnsys** - Sistema de clonación y administración de equipos