Documentazione di Onboarding - People FE v2
Indice
- Panoramica del Progetto
- Prerequisiti
- Setup Iniziale
- Struttura del Progetto
- Stack Tecnologico
- Configurazione e Ambienti
- Architettura dell'Applicazione
- Routing e Navigazione
- Autenticazione e Sicurezza
- Componenti e Librerie
- Servizi
- Modelli e Tipi
- Stili e Temi
- Utilities e Helpers
- Build e Deployment
- Best Practices
- Troubleshooting
Panoramica del Progetto
People FE v2 è un'applicazione web Angular per la gestione aziendale sviluppata per Paradigma. L'applicazione permette di gestire:
- Persone/Utenti (Paradigmini): Gestione completa dei profili utente, informazioni personali, contratti, skills, progetti
- Recruiting: Gestione delle candidature e processi di selezione
- Business Units e Posizioni: Gestione dei dipartimenti aziendali e delle posizioni lavorative
- Skills: Gestione delle competenze aziendali
- Teams e Progetti: Gestione dei team e dei progetti aziendali
- Documenti: Gestione documentale
- Permessi: Gestione delle richieste e permessi
L'applicazione utilizza Angular 19 con architettura standalone components e PrimeNG come libreria UI principale.
Prerequisiti
Prima di iniziare, assicurati di avere installato:
- Node.js: versione v22.12.0 (come specificato in
amplify.yml) - npm: versione compatibile con Node.js v22.12.0
- Git: per il controllo versione
- Editor di codice: Visual Studio Code consigliato
Verifica installazioni
node --version # dovrebbe essere v22.12.0
npm --version
git --version
Setup Iniziale
1. Clonare il repository
git clone <repository-url>
cd people-fe-v2
2. Installare le dipendenze
nvm use
npm install
3. Avviare l'applicazione in modalità sviluppo
# Ambiente locale (development)
npm run start
# Ambiente stage
npm run start-stage
L'applicazione sarà disponibile su http://localhost:4200
4. Build per produzione
# Build production
npm run build
# Build stage
npm run build-stage
5. Linting
npm run lint
Struttura del Progetto
people-fe-v2/
├── src/
│ ├── app/ # Configurazione principale dell'app
│ │ ├── app.component.ts # Componente root
│ │ ├── app.config.ts # Configurazione providers e routing
│ │ └── app.routes.ts # Definizione delle route
│ │
│ ├── components/ # Componenti riutilizzabili dell'applicazione
│ │ ├── badge/
│ │ ├── button/
│ │ ├── header/
│ │ ├── sidebar/
│ │ └── ...
│ │
│ ├── lib/ # Libreria di componenti UI custom
│ │ ├── accordion/
│ │ ├── avatar/
│ │ ├── breadcrumb/
│ │ ├── dialog/
│ │ ├── input-text/
│ │ └── ...
│ │
│ ├── pages/ # Componenti pagina (route components)
│ │ ├── dashboard/
│ │ ├── users/
│ │ ├── login/
│ │ └── ...
│ │
│ ├── services/ # Servizi Angular (business logic)
│ │ ├── auth.service.ts
│ │ ├── people.service.ts
│ │ └── ...
│ │
│ ├── models/ # Interfacce e tipi TypeScript
│ │ ├── auth.ts
│ │ ├── users.ts
│ │ └── ...
│ │
│ ├── guards/ # Route guards
│ │ ├── auth.guard.ts
│ │ ├── businessunit.guard.ts
│ │ └── position.guard.ts
│ │
│ ├── interceptors/ # HTTP interceptors
│ │ └── auth.interceptor.ts
│ │
│ ├── directives/ # Direttive custom
│ │ ├── clickOutside.directive.ts
│ │ └── tabContent.directive.ts
│ │
│ ├── pipes/ # Pipes custom
│ │ ├── name.pipe.ts
│ │ └── ...
│ │
│ ├── utils/ # Funzioni utility e helpers
│ │ ├── endpoints.ts
│ │ ├── sidebar-items.ts
│ │ └── ...
│ │
│ ├── styles/ # File SCSS globali e variabili
│ │ ├── _variables.scss
│ │ ├── _mixins.scss
│ │ └── ...
│ │
│ ├── environments/ # Configurazioni ambiente
│ │ ├── environment.ts
│ │ ├── environment.stage.ts
│ │ └── environment.prod.ts
│ │
│ └── assets/ # File statici (immagini, font, icone)
│
├── angular.json # Configurazione Angular CLI
├── tsconfig.json # Configurazione TypeScript
├── package.json # Dipendenze e script npm
├── amplify.yml # Configurazione AWS Amplify per CI/CD
└── eslint.config.js # Configurazione ESLint
Stack Tecnologico
Core Framework
- Angular 19.1.6: Framework principale
- TypeScript 5.7.3: Linguaggio di programmazione
- RxJS 7.8.0: Libreria per programmazione reattiva
UI Libraries
- PrimeNG 19.0.6: Libreria di componenti UI
- PrimeIcons 7.0.0: Icone per PrimeNG
- Bootstrap 5.3.3: Framework CSS (utilizzato principalmente per JavaScript utilities)
Styling
- SCSS/Sass: Preprocessore CSS
- PrimeNG Themes (Lara): Tema PrimeNG personalizzato
Build Tools
- Angular CLI 19.1.7: Strumenti di build e sviluppo
- ESLint: Linter per TypeScript e HTML
- Karma + Jasmine: Framework di testing (configurato ma non utilizzato attivamente)
Utilities
- jwt-decode 4.0.0: Decodifica JWT tokens
Configurazione e Ambienti
File di Ambiente
Il progetto utilizza tre configurazioni di ambiente:
1. Development (environment.ts)
{
domain: 'paradigma.me',
production: false,
apiUrl: 'http://localhost:3000/dev',
idClient: '...', // Google OAuth Client ID
basicAuthorization: '...',
redirectUri: 'http://localhost:4200'
}
2. Stage (environment.stage.ts)
{
domain: 'paradigma.me',
production: false,
apiUrl: 'https://rk5nl4udi8.execute-api.eu-central-1.amazonaws.com/dev',
redirectUri: 'https://people-stage.paradigma.me'
}
3. Production (environment.prod.ts)
{
domain: 'paradigma.me',
production: true,
apiUrl: 'https://3q7v0mxo4f.execute-api.eu-west-1.amazonaws.com/prod',
redirectUri: 'https://people.paradigma.me'
}
Path Aliases (TypeScript)
Il progetto utilizza path aliases per import più puliti:
// Configurati in tsconfig.json
@components/* → ./src/components/*
@pages/* → ./src/pages/*
@pipes/* → ./src/pipes/*
@services/* → ./src/services/*
@models/* → ./src/models/*
@utils/* → ./src/utils/*
@styles/* → ./src/styles/*
@assets/* → ./src/assets/*
@environments/* → ./src/environments/*
@guards/* → ./src/guards/*
@interceptors/* → ./src/interceptors/*
@lib/* → ./src/lib/*
Esempio di utilizzo:
import { AuthService } from '@services/auth.service';
import { People } from '@models/users';
import { Endpoints } from '@utils/endpoints';
Architettura dell'Applicazione
Standalone Components
L'applicazione utilizza standalone components di Angular, quindi:
- Ogni componente è indipendente e non richiede un
NgModule - I componenti importano direttamente le dipendenze necessarie
- Il routing utilizza lazy loading con
loadComponent()
Esempio di Componente Standalone
@Component({
selector: 'app-example',
imports: [CommonModule, RouterModule],
templateUrl: './example.component.html',
styleUrl: './example.component.scss'
})
export class ExampleComponent {
// ...
}
Dependency Injection
I servizi utilizzano inject() function invece di constructor injection:
export class MyService {
private http = inject(HttpClient);
private router = inject(Router);
}
Signals
L'applicazione utilizza Angular Signals per la gestione dello stato reattivo:
export class AuthService {
loading = signal(false);
userLogged = signal<{ name: string | null }>({ name: null });
// Utilizzo
this.loading.set(true);
const user = this.userLogged();
}
Routing e Navigazione
Struttura delle Route
Le route sono definite in src/app/app.routes.ts:
export const routes: Routes = [
{
path: 'login',
canActivate: [AuthGuard],
loadComponent: () => import('@pages/login/login.component'),
},
{
path: 'dashboard',
canActivate: [AuthGuard],
loadComponent: () => import('@pages/dashboard/dashboard.component'),
children: [
{ path: '', redirectTo: 'home', pathMatch: 'full' },
{ path: 'home', loadComponent: () => import('...') },
// ...
],
},
];
Route Principali
/login- Pagina di login/dashboard- Container principale (richiede autenticazione)/dashboard/home- Home dashboard/dashboard/users- Gestione utenti (Paradigmini)/dashboard/users/:id- Dettaglio utente
/dashboard/recruiting- Gestione candidature/dashboard/recruiting/:id- Dettaglio candidato
/dashboard/company-info- Informazioni aziendali/dashboard/permissions- Richieste e permessi/dashboard/docs- Documenti/dashboard/teams- Gestione teams/dashboard/projects- Gestione progetti/dashboard/skills- Gestione skills/dashboard/positions-and-businessunit- Gestione posizioni e dipartimenti
Lazy Loading
Tutte le route utilizzano lazy loading per ottimizzare il bundle:
loadComponent: () => import('@pages/users/users.component')
Route Guards
AuthGuard
- Protegge le route richiedendo autenticazione
- Reindirizza a
/loginse non autenticato - Reindirizza a
/dashboardse si tenta di accedere a/logingià autenticati
BusinessUnitGuard e PositionGuard
CanDeactivateguards che gestiscono lo stato quando si esce da una route- Resettano lo stato di "aggiunta nuovo elemento" se presente
Breadcrumb
Le route supportano breadcrumb tramite data property:
{
path: 'users',
data: {
breadcrumb: 'Paradigmini',
showBreadcrumb: true,
}
}
Autenticazione e Sicurezza
Flusso di Autenticazione
- Login con Google OAuth
- L'utente clicca su "Login con Google"
- Viene reindirizzato a Google OAuth
- Google reindirizza con un
authCodenell'URL - Il codice viene catturato in
main.tse salvato inlocalStorage AuthService.handleLoginResponse()invia il codice al backend-
Il backend risponde con
accessTokenerefreshToken -
Gestione Token
- I token vengono salvati in
localStorage accessToken: token principale, scade primarefreshToken: token di refresh, scade dopo-
Entrambi hanno timestamp di scadenza salvati
-
HTTP Interceptor
authInterceptoraggiunge automaticamente l'headerAuthorizationa tutte le richieste- Se
accessTokenè valido, lo usa - Se
accessTokenè scaduto marefreshTokenè valido, usarefreshToken - Se entrambi sono scaduti, effettua logout automatico
AuthService
Servizio principale per l'autenticazione:
// Metodi principali
isLoggedIn() // Verifica se esiste un token
isAuthorized() // Verifica se l'utente ha un ruolo valido
isExecutive() // Verifica se l'utente è Executive
isSelf(email) // Verifica se l'email corrisponde all'utente loggato
getTokenInfo(type) // Ottiene informazioni sul token
isTokenExpired(expiry) // Verifica se un token è scaduto
logout() // Effettua logout e pulisce localStorage
Ruoli Utente
Definiti in @models/auth.ts:
enum RoleEnum {
PO = 'PRODUCT_OWNER',
SM = 'SCRUM_MASTER',
EX = 'EXECUTIVE',
EXS = 'EXECUTIVE_SUPPORT',
NR = 'NO_ROLE',
}
Storage
I dati di autenticazione sono salvati in localStorage:
accessToken: Token di accessorefreshToken: Token di refreshaccessTokenExpireIn: Timestamp di scadenza access tokenrefreshTokenExpireIn: Timestamp di scadenza refresh tokenrole: Ruolo dell'utenteauthCode: Codice OAuth temporaneo (rimosso dopo il login)
Componenti e Librerie
Struttura Componenti
Il progetto ha due tipi di componenti:
- Components (
src/components/): Componenti specifici dell'applicazione - Lib (
src/lib/): Libreria di componenti UI riutilizzabili
Componenti Principali dell'Applicazione
Layout Components
header/- Header principalesidebar/- Sidebar di navigazionenavbar/- Barra di navigazione (desktop/mobile)footer/- Footer
Feature Components
user-detail/- Dettaglio utente (con sottocomponenti)badge/- Badge per informazionibutton/- Pulsanti custombookmark/- Segnalibritag/- Tag per categorizzazione
Libreria UI (src/lib/)
Componenti riutilizzabili basati su PrimeNG:
accordion/- Accordion customavatar/- Avatar utentebreadcrumb/- Breadcrumb navigationcalendar/- Calendario date pickercheckbox/- Checkbox customdialog/- Dialog/Modalinput-text/- Input text custommulti-select/- Multi select dropdownradio-button/- Radio button customselect-button/- Select buttonslider/- Slider rangetab-view/- Tab viewtoast/- Toast notificationsprogress-bar/- Progress barskeleton/- Skeleton loadersteps/- Stepper component
Component Input Binding
Angular è configurato con withComponentInputBinding() che permette di ricevere parametri di route come input:
// Route: /dashboard/users/:id
@Component({...})
export class UserDetailComponent {
id = input<string>(); // Riceve automaticamente :id dalla route
}
Servizi
Servizi Principali
AuthService
- Gestione autenticazione e autorizzazione
- Login/logout
- Gestione token JWT
- Informazioni utente loggato
PeopleService
- CRUD operazioni per le persone/utenti
- Filtri e paginazione
- Gestione informazioni utente (profile, general, personal, contracts, skills, projects, workload)
PositionService
- Gestione posizioni lavorative
BusinessUnitService
- Gestione business units (dipartimenti)
SkillService
- Gestione skills aziendali
RecruitingService
- Gestione candidature e processi di recruiting
ToastService
- Gestione notifiche toast (wrapper su PrimeNG MessageService)
LoaderService
- Gestione stato di loading globale
ViewportService
- Gestione viewport e responsive breakpoints
MobileMenuService
- Gestione menu mobile
TableFiltersService
- Gestione filtri per tabelle
Pattern dei Servizi
I servizi utilizzano:
- Injectable con
providedIn: 'root'(tranneAuthServiceche è fornito inapp.config.ts) - Dependency Injection con
inject() - RxJS Observables per le chiamate HTTP
- Signals per lo stato reattivo (quando necessario)
Esempio Servizio
@Injectable({ providedIn: 'root' })
export class MyService {
private http = inject(HttpClient);
getData(): Observable<Data> {
return this.http.get<Data>(`${environment.apiUrl}${Endpoints.data}`);
}
}
Modelli e Tipi
Struttura Modelli
I modelli sono definiti in src/models/ come interfacce TypeScript.
Modelli Principali
Auth (auth.ts)
Auth: Risposta loginRoleEnum: Enum ruoli utenteToken: Costanti per chiavi localStorageJWTPayloadData: Payload JWT decodificato
Users (users.ts)
People: Interfaccia completa personaPerson2: Persona semplificataBusinessUnit: Business unitPosition: Posizione lavorativaSkill: Skill/competenzaProject: ProgettoContract: ContrattoCreatePerson: Payload creazione personaUpdateProfileInfo: Payload aggiornamento profilo
Altri Modelli Importanti
job-application.ts: Candidatureteams-response.ts: Teamtoast.ts: Configurazione toastsidebar.ts: Configurazione sidebarbreadcrumb.ts: Configurazione breadcrumbfilter-form.ts: Filtri e query params
Best Practices Modelli
- Interfacce over Types: Preferire
interfaceper oggetti - Pick/Partial: Utilizzare utility types quando possibile
- Const Assertions: Utilizzare
as constper valori costanti - Discriminated Unions: Per tipi con varianti
Stili e Temi
Struttura Stili
src/styles/
├── styles.scss # File principale (importa tutti gli altri)
├── _variables.scss # Variabili SCSS (colori, spacing, etc.)
├── _mixins.scss # Mixins riutilizzabili
├── _typography.scss # Stili tipografici
├── _font.scss # Font personalizzati
├── _font-icon.scss # Icone font
├── _material-icons.scss # Material Icons
├── _custom-primeng.scss # Personalizzazioni PrimeNG
└── utils.scss # Utility classes
Variabili e Mixins
Le variabili sono organizzate in mappe SCSS:
$colors: (
global: (
dark-blue: #...,
custom-white: #...,
),
neutral: (
50: #...,
100: #...,
)
);
Typography
Classi tipografiche predefinite:
.typography-title-h1,.typography-title-h2, etc..typography-body-book,.typography-body-medium, etc..typography-subhead
Font
Il progetto utilizza PP Neue Montreal come font principale.
PrimeNG Theme
Il tema utilizzato è Lara (light) senza dark mode.
Utility Classes
Classi CSS utility disponibili:
.pdg-container-dashboard-page- Container principale dashboard.pdg-container-info- Container informazioni.container-loader- Container loader.box,.box-rounded- Box per badge/tag.spacing-bottom- Spaziatura inferiore.pdg-label-wrapper- Wrapper per label
Responsive Design
Utilizzo di media queries con breakpoints Bootstrap:
@media screen and (min-width: 768px) { ... }
@media screen and (min-width: 1024px) { ... }
Utilities e Helpers
Endpoints (endpoints.ts)
Definisce tutti gli endpoint API:
export const Endpoints = {
login: '/v1/auth/login',
persons: '/v1/persons',
businessUnit: '/v1/businessunits',
positions: '/v1/positions',
skills: '/v1/skills',
teams: '/v1/teams',
jobApplications: '/v1/job-application',
} as const;
Sidebar Items (sidebar-items.ts)
Configurazione elementi sidebar:
export const sidebarItemsToCollapse: SidebarItem[] = [
{
label: 'Dashboard',
icon: 'dashboard',
routerLink: ['/dashboard/home'],
category: 'generali',
},
// ...
];
Table Utilities
table-query-params.ts: Gestione query params per tabelletable-users-input.ts: Configurazione tabelle utentitable-recruiting.ts: Configurazione tabelle recruiting
Altri Utilities
parseItalianDate.ts: Parsing date in formato italianouppercase.ts: Utility per uppercasedisableFields.ts: Logica per disabilitare campi formworkload-utils.ts: Utility per workloadapplication-status.ts: Gestione stati candidaturebookmarks.ts: Gestione bookmarksprime-ng-config.ts: Configurazione PrimeNG (traduzioni)
Build e Deployment
Scripts NPM
{
"start": "ng serve", // Development locale
"start-stage": "ng serve -c stage", // Stage locale
"build": "ng build", // Build production
"build-stage": "ng build -c stage", // Build stage
"watch": "ng build --watch --configuration development",
"test": "ng test",
"lint": "ng lint"
}
Configurazioni Build
Production
- File replacement:
environment.ts→environment.prod.ts - Ottimizzazioni abilitate
- Source maps disabilitate
- Budget: 500kb warning, 1mb error (initial), 2kb/4kb (component styles)
Stage
- File replacement:
environment.ts→environment.stage.ts - Ottimizzazioni abilitate
- Budget: 10mb warning, 20mb error
Development
- Ottimizzazioni disabilitate
- Source maps abilitate
AWS Amplify CI/CD
Il progetto utilizza AWS Amplify per il deployment automatico.
Configurazione (amplify.yml)
version: 1
frontend:
phases:
preBuild:
commands:
- nvm install v22.12.0
- npm install
build:
commands:
- npm run build-stage
artifacts:
baseDirectory: dist/people-fe-v2/browser
files:
- '**/*'
Deployment
- Stage: Push su branch
develop→ deploy automatico su stage - Production: Push su branch
main→ deploy automatico su production (non ancora attivo)
URL Deployment
- Stage:
https://people-stage.paradigma.me - Production:
https://people.paradigma.me(non ancora attivo con la v2)
Cache Headers
Configurati in amplify.yml:
customHeaders:
- pattern: '**/*'
headers:
- key: Cache-Control
value: public,max-age=0,must-revalidate
- key: X-Frame-Options
value: DENY
Redirects SPA
Configurato redirect per SPA (Single Page Application):
redirects:
- source: '</*>'
target: '/index.html'
status: '200'
Best Practices
Code Style
- Standalone Components: Tutti i componenti devono essere standalone
- Path Aliases: Utilizzare sempre gli alias invece di path relativi
- Dependency Injection: Utilizzare
inject()invece di constructor injection - Signals: Utilizzare signals per stato reattivo locale
- Observables: Utilizzare RxJS per operazioni asincrone
Naming Conventions
- Componenti: PascalCase (es.
UserDetailComponent) - Servizi: PascalCase con suffisso
Service(es.AuthService) - Interfacce/Tipi: PascalCase (es.
People,Auth) - Variabili/Funzioni: camelCase (es.
getUserData) - Costanti: UPPER_SNAKE_CASE (es.
RoleEnum) - File: kebab-case (es.
user-detail.component.ts)
Component Structure
Ogni componente dovrebbe avere:
@Component({
selector: 'app-example',
imports: [/* dependencies */],
templateUrl: './example.component.html',
styleUrl: './example.component.scss'
})
export class ExampleComponent implements OnInit {
// Properties
// Constructor/Dependency Injection
// Lifecycle hooks
// Methods
}
Service Structure
@Injectable({ providedIn: 'root' })
export class ExampleService {
private http = inject(HttpClient);
// Public methods
// Private methods
}
Error Handling
- Utilizzare
catchErrordi RxJS per gestire errori HTTP - Mostrare toast notifications per errori utente
- Loggare errori in console per debug
Type Safety
- Evitare
anyquando possibile - Utilizzare type guards per runtime type checking
- Utilizzare utility types (Pick, Partial, Omit) quando appropriato
Performance
- Utilizzare lazy loading per tutte le route
- Utilizzare
OnPushchange detection quando possibile - Evitare subscription leaks (utilizzare
takeUntiloasyncpipe) - Utilizzare
trackByper*ngForcon liste dinamiche
Accessibility
- Utilizzare semantic HTML
- Aggiungere
aria-labelquando necessario - Gestire focus e keyboard navigation
- Utilizzare colori con contrasto adeguato
Troubleshooting
Problemi Comuni
1. Errori di Build
Problema: Errori TypeScript durante il build
Soluzione:
- Verificare che tutte le dipendenze siano installate: npm install
- Verificare che la versione di Node.js sia corretta: node --version (dovrebbe essere v22.12.0)
- Pulire cache: rm -rf node_modules package-lock.json && npm install
2. Errori di Routing
Problema: Route non funzionano o redirect non corretti
Soluzione:
- Verificare che AuthGuard sia configurato correttamente
- Verificare che i componenti siano importati correttamente con lazy loading
- Verificare che i path aliases siano configurati in tsconfig.json
3. Errori di Autenticazione
Problema: Token scaduti o errori 401
Soluzione:
- Verificare che authInterceptor sia configurato in app.config.ts
- Verificare che i token siano salvati correttamente in localStorage
- Verificare che gli endpoint API siano corretti nell'environment
4. Errori di Stile
Problema: Stili non applicati o variabili SCSS non trovate
Soluzione:
- Verificare che tutti i file SCSS siano importati in styles.scss
- Verificare che le variabili siano definite in _variables.scss
- Verificare che i path aliases per @styles/* siano configurati
5. Errori PrimeNG
Problema: Componenti PrimeNG non funzionano
Soluzione:
- Verificare che providePrimeNG sia configurato in app.config.ts
- Verificare che i componenti PrimeNG siano importati nel componente
- Verificare che il tema sia configurato correttamente
6. Errori di Linting
Problema: Errori ESLint
Soluzione:
- Eseguire npm run lint per vedere gli errori
- Verificare la configurazione in eslint.config.js
- Alcuni errori possono essere ignorati se necessario (es. @typescript-eslint/no-explicit-any è disabilitato) -> verrà eseguito un refactor su questo
Debug
Browser DevTools
- Console: Verificare errori JavaScript/TypeScript
- Network: Verificare chiamate API e risposte
- Application: Verificare
localStoragee session storage - Sources: Debug del codice TypeScript (con source maps)
Angular DevTools
Installare l'estensione Angular DevTools per Chrome/Firefox per: - Inspectare component tree - Profilare performance - Verificare change detection
Logging
Per debug, utilizzare console.log, console.error, etc. Ricordarsi di rimuovere i log prima del commit in produzione.
Risorse Aggiuntive
Contatti
Per domande o supporto, contattare il team di sviluppo.