Template Angular Frontend LATAM

Propósito y Alcance

Este proyecto es una plantilla base para aplicaciones frontend desarrolladas con Angular en LATAM. Su propósito es proporcionar una estructura de proyecto robusta y preconfigurada, acelerando el inicio de nuevos desarrollos y asegurando la consistencia y adhesión a los estándares de LATAM.

Objetivos Principales:

Ofrecer una base con Angular (actualmente enfocado en Angular 17+).
Integración preconfigurada con Microsoft Azure Active Directory (Azure AD) y Azure B2C para autenticación y autorización mediante MSAL (Microsoft Authentication Library).
Soporte para internacionalización (i18n) con @ngx-translate.
Inclusión de Angular Material para componentes UI.
Configuración para Progressive Web Apps (PWA).
Estructura para pruebas unitarias (Karma/Jasmine) y pruebas E2E/automatizadas (WebDriverIO).
Guías y configuraciones para despliegue en GKE (Google Kubernetes Engine) mediante Jenkins.

Alcance:

Generación de la estructura base del proyecto Angular.
Configuración de herramientas de desarrollo, construcción y prueba.
Mecanismos de autenticación y gestión de sesión.
Ejemplos de componentes comunes y servicios (navegación, layout, manejo de errores HTTP).
Pipeline de CI/CD para despliegue en GKE.

Fuera del Alcance (a ser implementado por el equipo de desarrollo):

Lógica de negocio específica de la aplicación.
Diseño UI/UX detallado más allá de los componentes base de Material.
Conexiones a APIs de backend específicas (aunque se provee un interceptor HTTP).

Arquitectura

La plantilla sigue la arquitectura estándar de una aplicación Angular, basada en componentes, módulos y servicios.

Presentación: Componentes Angular y Angular Material.
Lógica de Aplicación/Servicios: Servicios Angular para lógica de UI, gestión de estado simple y comunicación con backend.
Autenticación: Integración con Azure AD/B2C usando MSAL Angular (MsalGuard, MsalInterceptor).
Internacionalización: ngx-translate para múltiples idiomas.
Servidor Web (en despliegue): Nginx sirve la aplicación estática construida.

Se recomienda que los equipos de desarrollo mantengan diagramas de arquitectura específicos de su aplicación derivados de esta plantilla.

Diagrama de Arquitectura General: [Enlace al diagrama si existe, o placeholder]
Diagrama de Flujo de Autenticación: [Enlace al diagrama si existe, o placeholder]

Tecnologías y Dependencias

Frontend:

Lenguaje: TypeScript (~5.7.3)
Framework Principal: Angular (~17.x / ~19.x según package.json, con soporte para Angular 17 confirmado en CHANGELOG.md)
UI Components: Angular Material (~19.x)
Gestión de Estado/Reactividad: RxJS (~7.8.0)
Internacionalización (i18n): @ngx-translate/core (~14.0.0), @ngx-translate/http-loader (~7.0.0)
Autenticación: @azure/msal-angular (~3.0.20), @azure/msal-browser (~3.17.0)
PWA: @angular/service-worker

Desarrollo y Herramientas:

CLI: Angular CLI (@angular/cli ~19.x)
Gestor de Paquetes: npm
Servidor de Desarrollo: ng serve (webpack dev server)
Pruebas Unitarias: Karma, Jasmine
Pruebas E2E/Automatizadas: WebdriverIO (@wdio/cli, @wdio/cucumber-framework)
Calidad de Código: SonarQube (implícito por sonar-scanner y script sonar)

Despliegue y Operaciones:

Contenedorización: Docker
Servidor Web (Producción): Nginx (base image redhat_ubi_8_nginx_1)
Orquestación: Google Kubernetes Engine (GKE)
CI/CD: Jenkins (pipelineLatam("gke-krane-angular"))
Artefactos: JFrog Artifactory (para dependencias npm corporativas)

Configuración Local

Prerrequisitos

Node.js (versión LTS recomendada, compatible con la versión de Angular)
npm (usualmente viene con Node.js)
Angular CLI: npm install -g @angular/cli
Git
Acceso a JFrog Artifactory LATAM.

Pasos de Configuración

Clonar el repositorio: Sigue los siguientes pasos
Configurar registro NPM de Artifactory:
```
npm config set registry https://artifactoryrepo1.appslatam.com/artifactory/api/npm/corp-libs-npm-release/
```
Puede ser necesario ejecutar npm login si es la primera vez, ingresando tus credenciales de Artifactory.
Instalar dependencias:
```
npm install
```

Configurar MSAL para desarrollo local (Azure AD o B2C):

Para Azure AD: Copia src/assets/configuration-localhost.json a src/assets/config/configuration.json.
Para Azure B2C: Copia src/assets/configuration-b2c-localhost.json a src/assets/config/configuration.json.
Modifica src/assets/config/configuration.json con los valores correctos para tu aplicación (clientId, authority, redirectUri, etc.). Este archivo (src/assets/config/configuration.json) está en .gitignore y no debe ser subido al repositorio con credenciales/configuraciones reales.

Ejemplo de src/assets/config/configuration.json (para Azure AD):

{
  "storage": {
    "azure_use_redirect": 0, // 0 para popup, 1 para redirect
    "server_url": "https://tu-api-backend.com" // URL de tu backend si aplica
  },
  "msal": {
    "auth": {
      "clientId": "TU_CLIENT_ID_AZURE_AD",
      "authority": "https://login.microsoftonline.com/TU_TENANT_ID",
      "redirectUri": "http://localhost:4200/"
    },
    "cache": {
      "cacheLocation": "localStorage", // o "sessionStorage"
      "storeAuthStateInCookie": false
    }
  },
  "guard": {
    "interactionType": "redirect", // o "popup"
    "authRequest": {
      "scopes": ["user.read", "directory.read.all"], // Scopes necesarios
      "prompt": "select_account"
    }
  },
  "interceptor": {
    "interactionType": "redirect", // o "popup"
    "protectedResourceMap": [
      ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
      ["URL_DE_TU_API_PROTEGIDA", ["SCOPE_DE_TU_API"]]
    ]
  }
}

Ejecutar la aplicación en modo desarrollo:
```
ng serve
```
La aplicación estará disponible en http://localhost:4200/.

Despliegue

El despliegue se gestiona a través de Jenkins pipelines y Krane para GKE.

Proceso General de Despliegue (Manual/Setup Inicial)

Collocated Design (JIRA): Crear un issue en JIRA para solicitar los recursos (repositorios, pipelines, configuración Azure AD/B2C).
Preparar Código: Usar esta plantilla como base para el nuevo proyecto.
Push a Repositorio: Subir el código al repositorio proporcionado.

Configurar Ingress (GKE): Editar el archivo deployment.yaml.erb en el repositorio gke-resources (ruta específica será provista) para añadir la ruta del servicio. Ejemplo:

- path: /mi-aplicacion # Ajustar el path
  pathType: Prefix
  backend:
    service:
      name: <%= owner_name %>-{nombre_repo}-service
      port:
        number: 80

Personalizar Valores de Entorno (Opcional): Modificar deploy/env/<entorno>.yaml (ej. dev.yaml) para añadir variables específicas que se inyectarán en configuration.json durante el despliegue.

steps_test: false
steps_automated_test: false
dns_record: "mi-app.dev.appslatam.com"
# Variables personalizadas
mi_variable_custom: "valor_custom"
azure_client_id: "client_id_para_este_entorno" # Sobreescribir si es necesario

Personalizar deployment.yaml.erb (Opcional): Si se necesitan más parámetros de configuración en assets/config/configuration.json o assets/config/configuration_b2c.json que se inyecten desde los archivos deploy/env/<entorno>.yaml, modificar la sección ConfigMap en deploy/gke/deployment.yaml.erb. Ejemplo de la sección ConfigMap en deployment.yaml.erb para configuration.json:

apiVersion: v1
kind: ConfigMap
metadata:
  name: "<%= owner_name %>-<%= repository_name %>-settings"
data:
  configuration.json: |-
    {
      "storage": {
        "azure_use_redirect": <%= azure_use_redirect_storage_value %>, // Usa variables de entorno.yaml
        "server_url": "https://<%= dns_record %>",
        "key1": "<%= key1_value %>" // Ejemplo de valor personalizado
      },
      "msal": {
        "auth": {
          "clientId": "<%= azure_client_id %>",
          "authority": "<%= azure_authority %>",
          "redirectUri": "https://<%= dns_record %>"
        },
        // ... más configuración msal
      },
      // ... más configuración guard/interceptor
    }

Pipeline de Jenkins

El archivo Jenkinsfile en la raíz del proyecto define el pipeline:
```
pipelineLatam("gke-krane-angular")
```
Al hacer push a la rama configurada (ej. dev, main), Jenkins se dispara automáticamente, construye la imagen Docker y la despliega en GKE.

Endpoints de la API

Esta es una aplicación frontend y no expone endpoints de API. Consume APIs de backend. La configuración para interactuar con APIs protegidas se gestiona a través del MsalInterceptor y la protectedResourceMap en assets/config/configuration.json.

Componentes Específicos

Autenticación (MSAL - Azure AD / B2C)

Módulos Clave: @azure/msal-angular, @azure/msal-browser.
Configuración Dinámica: MsalConfigDynamicModule (src/app/msal-config-dynamic.module.ts) carga la configuración de MSAL desde assets/config/configuration.json (o configuration_b2c.json) al inicio de la aplicación. Esto permite tener diferentes configuraciones de MSAL por entorno sin re-compilar.
Archivos de Configuración:
- src/assets/config/configuration.json: Para Azure AD.
- src/assets/config/configuration_b2c.json: Para Azure B2C.
- src/assets/configuration-localhost.json: Plantilla para config local con Azure AD.
- src/assets/configuration-b2c-localhost.json: Plantilla para config local con Azure B2C.
Variables de Configuración Importantes (en configuration.json / configuration_b2c.json):
- msal.auth.clientId: ID de cliente de la aplicación registrada en Azure.
- msal.auth.authority: URL de la autoridad emisora de tokens (Ej: https://login.microsoftonline.com/TENANT_ID para AD, o https://{b2cDomain}.b2clogin.com/{b2cDomain}.onmicrosoft.com/{policyName} para B2C).
- msal.auth.redirectUri: URI a la que Azure redirige después de la autenticación.
- msal.auth.knownAuthorities (para B2C): Array con los dominios de autoridad de B2C. Ej: ["latamb2c.b2clogin.com"].
- storage.B2C: "1" si se usa Azure B2C, "0" o ausente para Azure AD. Determina qué configuración se usa.
- storage.azure_use_redirect: "1" para login con redirect, "0" para login con popup.
- interceptor.protectedResourceMap: Mapeo de URLs de API a scopes necesarios para adjuntar tokens.
Servicios y Guardias:
- AdService / B2cService: Servicios helper para iniciar el flujo de login.
- SessionService: Maneja la información de sesión y el token.
- MsalGuard: Protege rutas que requieren autenticación.
- MsalInterceptor: Adjunta automáticamente tokens a las peticiones HTTP salientes a recursos protegidos.
Implementación: Ver LoginComponent para el inicio de sesión. Las rutas protegidas usan AuthGuardService (que a su vez puede invocar MsalGuard).

Internacionalización (i18n) con `@ngx-translate`

Módulos Clave: @ngx-translate/core, @ngx-translate/http-loader.
Configuración: En AppModule, se configura TranslateModule para usar HttpLoaderFactory, que carga archivos JSON desde src/assets/i18n/{{lang}}.json (ej. es.json, en.json, pt.json).
Uso:
- Inyectar TranslateService en componentes/servicios para traducciones programáticas.
- Usar el pipe | translate en las plantillas HTML: {{ 'MI_CLAVE_DE_TRADUCCION' | translate }}.
Gestión de Idioma: HeaderComponent permite cambiar el idioma y lo guarda en localStorage. AppComponent inicializa el idioma por defecto y carga el guardado.

Componentes UI (Angular Material)

Módulo: MaterialModule (src/app/common/modules/material.module.ts) importa y exporta los módulos de Angular Material necesarios.
Tematización: Se usa el tema preconstruido indigo-pink.css. Estilos globales en src/styles.scss.
Uso: Importar MaterialModule en los módulos de Angular donde se necesiten componentes de Material.

Progressive Web App (PWA)

Módulo: @angular/service-worker.
Configuración:
- src/manifest.webmanifest: Define metadatos de la aplicación (nombre, iconos, colores).
- src/ngsw-config.json: Configura el comportamiento del Service Worker (caching de assets, etc.).
- Se registra en AppModule.

Pruebas

Pruebas Unitarias

Herramientas: Karma (test runner) y Jasmine (framework de pruebas).
Ejecución:
```
ng test
```
Archivos: Los archivos de prueba (.spec.ts) se encuentran junto a los archivos de código fuente que prueban (ej. app.component.spec.ts).
Configuración: karma.conf.js en la raíz del proyecto. tsconfig.spec.json para la configuración de TypeScript para pruebas.

Pruebas Automatizadas (E2E con WebdriverIO)

La plantilla incluye una configuración para pruebas E2E con WebdriverIO.

Ubicación: src/tests/wdio-web/

Prerrequisitos (antes de ejecutar):

Modificar package.json (el principal del proyecto Angular, no el de wdio-web) y añadir "type": "module" bajo la definición de name:
```
{
  "name": "latam-angular-template", // o el nombre de tu proyecto
  "type": "module",
  "version": "0.0.0"
  // ...
}
```

Crear y configurar el archivo .env en src/tests/wdio-web/ con las credenciales necesarias (ej. para login en la aplicación, BrowserStack, Jira si se usa la integración). Ejemplo de src/tests/wdio-web/.env:

WEB_URL=http://localhost:4200/  # o la URL del entorno de pruebas
LOGIN_USERNAME=tu_usuario_azure
LOGIN_PASSWORD=tu_contraseña_azure
# Para BrowserStack (si se usa)
BROWSERSTACK_USERNAME=tu_usuario_bs
BROWSERSTACK_ACCESS_KEY=tu_access_key_bs
# Para Jira Zephyr (si se usa)
JIRA_USERNAME=tu_usuario_jira
JIRA_TOKEN=tu_api_token_jira
GOOGLE_CHAT_KEY=tu_google_chat_key #opcional
GOOGLE_CHAT_TOKEN=tu_google_chat_token #opcional

Ejecución Local: Desde la raíz del proyecto Angular:
```
npm run local
```
Esto ejecutará los tests definidos en src/tests/wdio-web/tests/features/ usando la configuración de src/tests/wdio-web/wdio.conf.js.
Ejecución en BrowserStack: Desde la raíz del proyecto Angular:
```
npm run browserstack
```
Esto ejecutará los tests usando la configuración de src/tests/wdio-web/browserstack.conf.js.
Ver Informes: Los informes HTML de Cucumber se generan en:
- Local: src/tests/wdio-web/reports/local/cucumber-html/
- BrowserStack: src/tests/wdio-web/reports/browserstack/cucumber-html/ Se puede usar Allure para informes más detallados (después de la ejecución):
```
cd src/tests/wdio-web
npm run report # (ejecuta: allure generate allure-results --clean && allure open)
cd ../../..
```
Estructura de Pruebas WebdriverIO:
- features/: Archivos Gherkin (.feature).
- step-definitions/: Implementaciones de los pasos Gherkin en JavaScript.
- page-objects/: Abstracciones de páginas para interactuar con la UI.
- utils/: Helpers para reportes, constantes, integración con Jira, etc.

Consideraciones de Seguridad

Autenticación y Autorización: Utilizar MSAL para Azure AD/B2C es el método principal. Asegurar que los scopes solicitados sean los mínimos necesarios.
Gestión de Secretos:
- Local: Utilizar el archivo .env dentro de src/tests/wdio-web/ para credenciales de prueba. Este archivo está en el .gitignore de esa carpeta. El archivo src/assets/config/configuration.json (generado a partir de plantillas) contiene configuraciones de MSAL y no debe subirse con valores sensibles al repositorio principal; se gestiona por entorno en el despliegue.
- CI/CD (Jenkins): Las credenciales deben ser gestionadas como "secrets" en Jenkins e inyectadas en el pipeline según sea necesario, no hardcodeadas en los archivos de configuración del repositorio.
Configuración de MSAL: La protectedResourceMap en configuration.json debe ser configurada cuidadosamente para asegurar que los tokens solo se envíen a los dominios de API previstos.
Dependencias: Mantener las dependencias actualizadas (npm audit) para mitigar vulnerabilidades conocidas.
HTTPS: Asegurar que todos los despliegues en producción usen HTTPS.
Content Security Policy (CSP): Considerar implementar una CSP robusta para mitigar riesgos de XSS.
PWA Security: Considerar las implicaciones de seguridad del Service Worker y el caching.

Propósito y Alcance​

Arquitectura​

Tecnologías y Dependencias​

Configuración Local​

Prerrequisitos​

Pasos de Configuración​

Despliegue​

Proceso General de Despliegue (Manual/Setup Inicial)​

Pipeline de Jenkins​

Endpoints de la API​

Componentes Específicos​

Autenticación (MSAL - Azure AD / B2C)​

Internacionalización (i18n) con @ngx-translate​

Componentes UI (Angular Material)​

Progressive Web App (PWA)​

Pruebas​

Pruebas Unitarias​

Pruebas Automatizadas (E2E con WebdriverIO)​

Consideraciones de Seguridad​