@open-rlb/ng-app

1Panoramica

Un progetto basato su @open-rlb/ng-app ha due livelli:

• Il core: l'applicazione Angular che si avvia. Contiene solo la configurazione (environment.ts), i provider e il componente radice con <rlb-app-container>.
• Le app: unità funzionali descritte da un AppDescriber (identità, rotte, provider) e registrate nel core con provideApp(). Ogni app può essere limitata a certi domini e a certe azioni ACL, e può esistere in più istanze (per esempio una per azienda o risorsa).

Tutto il resto (store, router, auth, ACL, traduzioni, gestione errori, layout) è fornito da una sola chiamata: provideRlbConfig(environment).

2Avvio rapido

Si parte da un workspace Angular senza applicazioni; ng add crea l'app core.

ng new my-workspace --no-create-application
cd my-workspace
ng add @open-rlb/ng-app
npm start

Cosa fa ng add

• Installa le dipendenze della libreria, più @angular/build e @angular/cdk alla versione Angular del workspace.
• Registra il progetto core in angular.json sotto newProjectRoot, con le configurazioni production, staging e development, gli stili Bootstrap/ng-bootstrap, gli asset serviti da src/assets e un budget iniziale di 4 MB.
• Crea solo i file necessari all'avvio.
• Imposta gli script di package.json e un postinstall che sincronizza le skill Claude.

projects/core/
  tsconfig.app.json
  src/index.html
  src/main.ts
  src/assets/favicon.ico
  src/assets/i18n/en.json, it.json
  src/environments/environment.ts
  src/app/app.config.ts          provideRlbConfig + RLB_INIT_PROVIDER
  src/app/app-init.provider.ts   assegna un id a ogni app registrata
  src/app/app.component.ts       <rlb-app-container> + configurazione del chrome
  src/app/app.routes.ts          rotte del core (vuote)

Opzioni: --name <nome> (default core), --skip-skills, --skip-skills-auto-sync. Se il progetto esiste già, lo schematic si ferma con un errore.

Il core minimo

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(),
    provideRlbConfig(environment),
    provideRouter(routes),
    { provide: RLB_INIT_PROVIDER, useClass: AppInitProvider },
    // provideApp(myAppDescriber), una riga per ogni app
  ],
};

<!-- template del componente radice -->
<rlb-app-container modal-container-id="modal-c-1" toast-container-ids="toast-c-1" />

3Macro-parti

4Configurazione

Tutta la configurazione sta in un unico oggetto ProjectConfiguration<T> (IConfiguration & { production } & T): T permette di aggiungere campi propri del progetto. Ogni sezione si può iniettare con il suo token.

Messaggi di errore HTTP

ErrorManagementService cerca il messaggio nelle traduzioni in quest'ordine: errors.http.<status> → errors.http.default → testo del backend ("<status>: <messaggio>"). Ogni gruppo ha title, message e un messageRetry opzionale che può usare {{minutes}}, {{seconds}} e {{status}}.

5App e micro-frontend

Ogni app si descrive con un AppDescriber e si registra con provideApp():

export const chatDescriber: AppDescriber = {
  info: {
    type: 'chat',
    enabled: true,
    actions: ['chat-read', 'chat-admin'],
    core:     { title: 'Chat', description: '…', url: 'chat', icon: 'bi bi-chat', auth: true },
    settings: { title: 'Chat settings', description: '…', url: 'settings/chat', icon: 'bi bi-gear', auth: true },
  },
  routes,
  providers: [],
};

Istanze multiple

Un type può produrre più istanze: ogni AppContextActions.finalizeApp({ appType, appId, data }) con lo stesso tipo e un appId diverso clona l'app. È il meccanismo multi-tenant (un'istanza per azienda o risorsa ACL).

providers: [
  ...provideForDomains(PARTNER_DOMAINS, [
    { provide: HTTP_INTERCEPTORS, useClass: PartnerInterceptor, multi: true },
  ]),
]

Leggere le app da un componente

private readonly apps = inject(AppsService);

visibleApps = this.apps.apps;          // AppInfo[] filtrate per dominio e ACL
current     = this.apps.currentApp;    // AppInfo | null
currentId   = this.apps.currentAppId;  // string | undefined

this.apps.checkPermissionInCurrentApp('chat-admin');
this.apps.selectApp(app, 'app', '/chat');

6Avvio del core

provideRlbConfig registra store, effects, rotte di default, OIDC, i18n, HttpClient, service worker, registri di modali e toast, e tre app initializer. L'ordine di avvio è questo:

1. i18n: attende il caricamento delle traduzioni (LanguageService.ready$).
2. AppsService viene costruito subito:
   • sceglie il provider OIDC: quello già nello store, altrimenti l'unico configurato, altrimenti quello con l'hostname corrente in domains. Nessun match o due match: errore in dev, log di errore in produzione;
   • si mette in ascolto di NavigationEnd.
3. AuthenticationService.checkAuthMultiple():
   • verifica la sessione OIDC; con oauth-code-ep-retry prova prima un refresh dal refresh token salvato;
   • utente autenticato: imposta il provider, carica l'ACL da endpoints[acl.endpointKey].baseUrl/acl.path, chiama RLB_INIT_PROVIDER.finalizeApps(resources, store, acl) e ripristina l'URL salvato prima del login;
   • ospite: finalizeApps([]);
   • emette authReady$ e, se autenticato, authenticated$ (che avvia il watchdog del token).

Nel frattempo AppContextEffects aggiunge allo store ogni app registrata con provideApp.

Selezione dell'app corrente

A ogni navigazione AppsService aspetta che tutte le app abbiano un id, poi:

1. Root con una sola app: redirect a core.url.
2. Root con più app: hub delle app (currentApp = null), a meno che un'app abbia autoRedirectOnRootEnabled.
3. Deep link: seleziona l'app i cui routes o core.url corrispondono al path.

L'app scelta viene salvata in localStorage (c-app-id) e il container naviga al suo URL.

7Shell: navbar e sidebar

Il template della shell si sceglie per rotta di primo livello con data: { template }: 'app' (default) mostra navbar e sidebar, 'basic' solo il contenuto.

Navbar e sidebar si configurano con azioni NgRx, di solito nel componente radice:

this.store.dispatch(NavbarActions.setActionsLayout({ layout: 'dropdown' }));
this.store.dispatch(NavbarActions.setSettingsVisible({ visible: true }));
this.store.dispatch(SidebarActions.setItems({ items: [
  { title: 'Menu' },
  { label: 'Home', url: '/', icon: 'bi bi-house' },
  { label: 'Admin', url: '/admin', icon: 'bi bi-shield', action: 'sysadmin' },
]}));

La proprietà action delle voci passa per la direttiva *roles: le voci sono filtrate per ACL.

Componenti custom

// nei providers del describer
{ provide: RLB_APP_NAVCOMP, useValue: {
    left:   [{ name: 'my-item', component: MyItemComponent }],
    right:  [{ name: 'my-item', component: MyItemComponent }],
    mobile: [{ name: 'my-menu', component: MyMenuComponent }],   // opzionale
} },
{ provide: RLB_APP_SIDEBARCOMP, useValue: {
    footer: [{ name: 'my-footer', component: MyFooterComponent }],
} },

// poi si attivano
this.store.dispatch(NavbarActions.setRightItems({ items: ['my-item'] }));
this.store.dispatch(SidebarActions.setFooterComponent({ name: 'my-footer' }));

Sotto il breakpoint lg i componenti left e right non vengono mostrati: al loro posto c'è un menu laterale con i mobileItems (che usano right se mobile manca), la griglia delle app e le impostazioni. Un componente può sapere dove si trova con inject(RLB_NAV_SURFACE, { optional: true }), che vale 'navbar' o 'mobile-menu'.

Tema, lingua, template di pagina

• AppContextActions.setTheme('light' | 'dark') imposta data-bs-theme e lo salva.
• AppContextActions.setLanguage e setSupportedLanguages agiscono su ngx-translate. Entrambi si cambiano anche da /settings/general.
• Template per le pagine: <rlb-base-template title subtitle breadcrumb>, <rlb-content-template>, <rlb-cms-template contentId>.
• AppBreadcrumbService.breadcrumbs() costruisce il breadcrumb da data.breadcrumb delle rotte.

8Autenticazione

L'autenticazione usa OIDC con authorization code flow e refresh token, tramite angular-auth-oidc-client.

auth: {
  protocol: 'oauth',
  storage: 'localStorage',              // 'cookies' | 'localStorage' | 'sessionStorage'
  interceptor: 'oauth-code-ep-retry',
  renewal: { publicPaths: ['/register'] },
  enableCompanyInterceptor: true,
  allowedUrls: ['https://api.example.com'],
  providers: [{
    configId: 'default',
    domains: ['app.example.com'],       // un provider per portale, scelto per hostname
    authority: 'https://login.example.com/realms/my-realm',
    clientId: 'my-client',
    redirectUrl: 'https://app.example.com',
    postLogoutRedirectUri: 'https://app.example.com',
    scope: 'openid profile offline_access',
    acl: { endpointKey: 'api', path: 'acl/resources' },
  }],
}

Interceptor

Con enableCompanyInterceptor le richieste verso gli allowedUrls ricevono come query param i valori di currentApp.data indicati in acl.interceptorMapping.

Rinnovo del token (oauth-code-ep-retry)

Login, logout e dati utente

• Login e logout con AuthActions.login() / AuthActions.logout() oppure con AuthFeatureService. Il login salva l'URL corrente e ci torna dopo il rientro.
• RLB_AUTH_URL_HANDLER permette di aprire la pagina di login in modo diverso; in Electron succede in automatico.
• AuthenticationService espone isAuthenticated$, userInfo$, accessToken$, idToken$, refreshToken$, roles$, authReady$, authenticated$.
• Esiste anche un flusso con password grant: OauthPasswordService e oauthPasswordGuard.

9Autorizzazione (ACL)

Dopo il login la libreria scarica le risorse dell'utente:

UserResource[] = [
  { companyId: 'acme', resources: [
      { resourceId: 'chat-1', actions: ['chat-read'], friendlyName: 'Chat Acme' },
  ] },
]

Un'app è collegata a una risorsa tramite data[acl.businessIdKey] e data[acl.resourceIdKey]. Le istanze si creano in RLB_INIT_PROVIDER:

@Injectable()
export class AppInitProvider implements RlbInitProvider {
  async finalizeApps(resources: UserResource[], store: Store<BaseState>, acl: AclConfiguration | null) {
    for (const company of resources) {
      for (const res of company.resources) {
        store.dispatch(AppContextActions.finalizeApp({
          appType: 'chat',
          appId: `chat-${res.resourceId}`,
          data: { title: res.friendlyName, [acl!.businessIdKey]: company.companyId, [acl!.resourceIdKey]: res.resourceId },
        }));
      }
    }
  }
}

Dove si applica

action può essere una stringa o un array: basta averne una. Le guard aspettano che l'ACL sia caricata prima di decidere; un rifiuto porta sempre a /forbidden.

<button *roles="'sysadmin'">Solo admin</button>
<button *roles="['manager', 'director']">Approva</button>
<span *roles="'editor'; not: true">Sola lettura</span>
<button *roles="'convert'; else noConvert">Converti</button>
<ng-template #noConvert>Non disponibile</ng-template>

Senza azione (undefined, '' o []) l'elemento è pubblico.

10Store NgRx

private readonly store = inject(Store<BaseState>);
currentApp = this.store.selectSignal(s => s[appContextFeatureKey].currentApp);

I gruppi *Internal sono usati dagli effects della libreria e non vanno dispacciati dall'app.

11Pagine standard

Le voci status e logger compaiono nelle impostazioni ma le rotte vanno create dal progetto, con pagePermissionGuard se hanno un'action.

12Servizi aggiuntivi

13Limiti noti

Punti emersi dall'analisi del codice, da tenere presenti finché non vengono corretti:

• LocalCacheService legge la cache con JSON.parse(key) invece del valore: la cache non viene mai usata e con chiavi non JSON getData genera un errore (impatta StrapiService).
• CompanyInterceptor usa come nome del query param il valore di interceptorMapping invece della chiave.
• Alcuni campi di configurazione non sono letti: appLogo, appTitle, navbarDisabled, ssr, phone, i18n.useLanguageBrowser, storeSelectedLanguage, cookieStoreName, cms.contentLanguages, ProviderConfiguration.roleClaim (roles$ legge sempre il claim roles).
• pages.*.path non cambia il percorso: le rotte sono fisse (per esempio /notFound).
• Al primo avvio il container imposta tema dark e lingua en, ignorando i18n.defaultLanguage.
• I flag loginVisible, searchVisible, settingsVisible e appsVisible della sidebar sono nello store ma il template non li usa.
• Il template data.template accetta solo 'app' e 'basic', anche se il tipo prevede anche 'cms' e 'content'.