@smdv/localization

Librería Angular para localización dinámica, sesión, permisos y auditoría.

✨ Características

• Carga remota de recursos de idioma (multi-módulo)
• Manejo de sesión y permisos (guards + interceptor HTTP)
• Registro de eventos (event log)
• Tipos e interfaces reutilizables

✅ Requisitos

• Angular >= 14 (recomendado 16+)
• HttpClientModule disponible

📦 Instalación

npm install @smdv/localization

⚙️ Configuración del módulo

Usar forRoot para inyectar la configuración (environment de la librería):

import { LocalizationModule } from '@smdv/localization';

@NgModule({
	imports: [
		LocalizationModule.forRoot({
			msLocalizationApiUrl: 'https://api.example.com/localization',
			msConfigurationsApiUrl: 'https://api.example.com/config',
			application: 'my-app'
		})
	]
})
export class AppModule {}

🧪 Uso del servicio de localización

import { LocalizationService } from '@smdv/localization';

constructor(private loc: LocalizationService) {}

ngOnInit() {
	this.loc.loadLocales(['general', 'dashboard']);
	const mensaje = this.loc.getLocalization('welcome');
}

🔐 Sesión y permisos

Guard de activación (ejemplo conceptual):

// SessionCanActiveService protege rutas según sesión válida
{
	path: 'panel',
	canActivate: [SessionCanActiveService],
	loadChildren: () => import('./panel/panel.module').then(m => m.PanelModule)
}

Interceptor HTTP: Se registra automáticamente al importar el módulo (si está configurado en providers en el futuro). Asegúrate de no duplicar interceptores globales.

🚦 Permisos por nombre y feature flags (rollout progresivo)

Además del modelo de permisos basado en módulos/funciones/acciones, PermitsService ofrece un segundo esquema más granular: permisos identificados por nombre único (útil para controlar visibilidad de botones, pestañas o secciones específicas dentro de una pantalla), pensado para adoptarse de forma progresiva sin reemplazar el esquema existente.

import { PermitsService } from '@smdv/localization';

constructor(public permitsService: PermitsService) {}

async ngOnInit() {
  // Verifica si una funcionalidad está habilitada para el usuario/rol actual
  const enabled = await this.permitsService.isFeatureEnabled('nueva-funcionalidad');

  if (enabled) {
    // Carga el catálogo de permisos por nombre asociado al rol
    await this.permitsService.loadPermissionsMenu();
  }
}

En la plantilla, usa canaryCan(nombre) para mostrar/ocultar elementos de forma segura durante un rollout progresivo: si el catálogo de permisos por nombre nunca se cargó (porque la funcionalidad no está habilitada para ese usuario), el método no oculta nada — preserva la experiencia actual. Solo aplica la validación real una vez que el catálogo está disponible.

<section *ngIf="permitsService.canaryCan('SectionShow'); else noAccess">
  ...
</section>
<ng-template #noAccess>No tienes permiso para ver esta sección.</ng-template>

| Método | Descripción | |--------|-------------| | isFeatureEnabled(name) | Consulta si una feature flag está habilitada para el usuario/rol autenticado | | loadPermissionsMenu(roleId?) | Carga el catálogo de permisos por nombre asociado a un rol, agrupado por módulo | | hasPermission(name) | Indica si el rol actual tiene asignado el permiso name (requiere haber llamado loadPermissionsMenu antes) | | canaryCan(name) | Variante seria de hasPermission para gating progresivo: si el catálogo nunca se cargó, retorna true (no oculta nada); de lo contrario aplica la validación real | | loadedPermissionsMenu | Acceso de solo lectura al catálogo cargado | | hasLoadedPermissionsMenu | Indica si loadPermissionsMenu ya resolvió |

Este esquema es ideal para introducir permisos de visibilidad de UI sin necesidad de mapear cada elemento a un endpoint backend, y para validar nuevas funcionalidades con un grupo reducido de usuarios antes de habilitarlas globalmente.

🧱 Interfaces clave

Ubicadas en services/interfaces/ (posible futura carpeta models/):

• AuthSession
• Permits
• EventLog
• PaginatedData<T>
• ResponseApi<T>
• PermissionMenuItem / PermissionMenuModule — entradas del catálogo de permisos por nombre

🌐 Carga de recursos

El método loadLocales(modulos: string[]) obtiene y cachea recursos por módulo. Luego getLocalization(key: string) retorna el texto asociado.

🛠 Scripts útiles

| Acción | Comando | |--------|---------| | Build | ng build localization | | Tests | ng test localization | | Producción | ng build localization --configuration production | | Publicar | npm publish (desde dist/localization) |

🧬 Publicación

1. Incrementar versión en projects/localization/package.json (semver).
2. ng build localization.
3. cd dist/localization.
4. npm publish (usar --access public si es necesario / registro privado si aplica).

🧹 Limpieza local

rm -rf node_modules dist .angular
npm ci
ng build localization

🗺 Roadmap sugerido

• Refactor de enviroment a environment
• Módulo separado para auditoría si crece
• Migrar interfaces a models/
• Añadir tests de integración (módulo + interceptor + guard)

🤝 Contribuir

1. Rama: feature/nombre
2. Commits claros
3. PR con descripción funcional / breaking changes

📄 Licencia

Privado / Interno (definir si se publica públicamente más adelante)

Mantén este README actualizado conforme evolucione la API.