# Studio di Dettaglio: Opzione 1 - White-Label / Multi-Configuration Questo documento descrive in dettaglio la strategia, la configurazione e i passaggi necessari per implementare la clonazione del progetto **canti** per la variante **stereocomics** attraverso l'**Opzione 1: White-Label**. Con questo approccio, il codice sorgente rimane **unico al 100%**. La differenziazione tra l'applicazione originale (Canti) e il clone (Stereocomics) avviene esclusivamente a tempo di compilazione (build-time) o di esecuzione (run-time) tramite file di configurazione ambientale di Angular (`environment`), fogli di stile dedicati, e sostituzione degli asset. --- ## 1. Architettura e Flusso di Configurazione Il concetto chiave è l'utilizzo delle funzionalità native di Angular CLI (`angular.json`) per iniettare le configurazioni specifiche del brand. ```mermaid graph TD A[Codice Sorgente Comune] --> B{Build Command} B -- "ng build" --> C[Canti App] B -- "ng build --configuration=stereocomics" --> D[Stereocomics App] subgraph Sostituzioni Stereocomics E[environment.ts -> environment.stereocomics.ts] F[variables.scss -> variables.stereocomics.scss] G[Asset Generici -> Asset Stereocomics] end D -.-> Sostituzioni Stereocomics ``` --- ## 2. Passaggi Operativi per l'Implementazione ### Passo 2.1: Creazione dei File Ambientali (Environments) Attualmente in `src/environments/` abbiamo `environment.ts` e `environment.prod.ts`. Creeremo le varianti per Stereocomics: #### [NEW] [environment.stereocomics.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/environments/environment.stereocomics.ts) ```typescript export const environment = { production: false, contactEmail: 'info@stereocomics.it', appName: 'Stereocomics', apiAuthUser: 'stereocomics', apiAuthPass: 'stereo2026', brand: 'stereocomics' // Flag utile per abilitare o disabilitare funzionalità specifiche run-time }; ``` #### [NEW] [environment.stereocomics.prod.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/environments/environment.stereocomics.prod.ts) ```typescript export const environment = { production: true, contactEmail: 'info@stereocomics.it', appName: 'Stereocomics', apiAuthUser: 'stereocomics', apiAuthPass: 'stereo2026_prod', brand: 'stereocomics' }; ``` --- ### Passo 2.2: Configurazione di `angular.json` Per permettere ad Angular di caricare la configurazione corretta, dobbiamo aggiungere una nuova build configuration in [angular.json](file:///Users/davidfrassi/SRC/agenti/canti/angular.json). Sotto `projects -> app -> architect -> build -> configurations`, aggiungeremo il blocco `stereocomics`: ```json "stereocomics": { "buildOptimizer": true, "optimization": true, "vendorChunk": false, "extractLicenses": true, "sourceMap": false, "namedChunks": false, "fileReplacements": [ { "replace": "src/environments/environment.ts", "with": "src/environments/environment.stereocomics.prod.ts" }, { "replace": "src/theme/variables.scss", "with": "src/theme/variables.stereocomics.scss" } ], "assets": [ { "glob": "**/*", "input": "src/assets/stereocomics", "output": "assets" }, { "glob": "**/*", "input": "public/stereocomics", "output": "." } ] } ``` E sotto `projects -> app -> architect -> serve -> configurations`: ```json "stereocomics": { "buildTarget": "app:build:development", "fileReplacements": [ { "replace": "src/environments/environment.ts", "with": "src/environments/environment.stereocomics.ts" }, { "replace": "src/theme/variables.scss", "with": "src/theme/variables.stereocomics.scss" } ], "assets": [ { "glob": "**/*", "input": "src/assets/stereocomics", "output": "assets" }, { "glob": "**/*", "input": "public/stereocomics", "output": "." } ] } ``` --- ### Passo 2.3: Stile e Theming Creeremo un file di variabili SCSS specifico per ridefinire i colori primari di Ionic in chiave "Stereocomics" (es. arancione/viola invece del blu/verde tipico dei Canti). #### [NEW] [variables.stereocomics.scss](file:///Users/davidfrassi/SRC/agenti/canti/src/theme/variables.stereocomics.scss) Questo file conterrà le medesime variabili CSS di `src/theme/variables.scss` ma con la palette colori e i font scelti per Stereocomics: ```scss // Stereocomics Palette :root { --ion-color-primary: #ff5722; --ion-color-primary-rgb: 255,87,34; --ion-color-primary-contrast: #ffffff; --ion-color-primary-contrast-rgb: 255,255,255; --ion-color-primary-shade: #e04d1d; --ion-color-primary-tint: #ff6838; // Font personalizzati --app-font-family: 'Outfit', sans-serif; } ``` Nel file [global.scss](file:///Users/davidfrassi/SRC/agenti/canti/src/global.scss) o nei componenti useremo la variabile `--app-font-family` per rendere dinamico il font. --- ### Passo 2.4: Gestione Asset e Icone PWA Per evitare di caricare icone e manifest di CantiCristiani su Stereocomics: 1. Creeremo due sottocartelle in `src/assets/`: - `src/assets/canti/` (per i loghi e immagini originali) - `src/assets/stereocomics/` (per i loghi e immagini di Stereocomics) 2. Durante la build di `stereocomics`, mapperemo la cartella `src/assets/stereocomics` direttamente sull'output `assets/` (come specificato in `angular.json`), garantendo che i percorsi `/assets/logo.png` rimangano identici nel codice HTML, ma cambino fisicamente nel pacchetto generato. 3. Creeremo un file `manifest.stereocomics.webmanifest` in `public/stereocomics/manifest.webmanifest` contenente il nome "Stereocomics" e i riferimenti alle icone corrette per la PWA. --- ### Passo 2.5: Script in `package.json` Aggiungeremo comandi dedicati in [package.json](file:///Users/davidfrassi/SRC/agenti/canti/package.json) per facilitare lo sviluppo e la pubblicazione: ```json "scripts": { "start:canti": "ng serve --configuration=development", "start:stereocomics": "ng serve --configuration=stereocomics", "build:canti": "ng build --configuration=production", "build:stereocomics": "ng build --configuration=stereocomics" } ``` --- ### Passo 2.6: Gestione Capacitor (Mobile Native App) Se l'app deve essere compilata per iOS/Android tramite Capacitor: - Possiamo creare un file di configurazione dinamico `capacitor.config.ts` che esporta la configurazione a seconda di una variabile d'ambiente (es. `process.env['BRAND']`). ```typescript import { CapacitorConfig } from '@capacitor/cli'; const brand = process.env['BRAND'] || 'canti'; const config: CapacitorConfig = { appId: brand === 'stereocomics' ? 'it.stereocomics.app' : 'it.canticristiani.app', appName: brand === 'stereocomics' ? 'Stereocomics' : 'Canti Cristiani', webDir: 'www', bundledWebRuntime: false }; export default config; ``` --- ## 3. Vantaggi e Svantaggi dell'Opzione 1 ### Vantaggi: 1. **Zero Duplicazione di Codice**: Se viene corretto un bug nella pagina di riproduzione audio o nel parser dei testi, la modifica è istantaneamente attiva per entrambi i brand. 2. **Semplicità di Manutenzione**: Un'unica pipeline di CI/CD che esegue i test unitari una sola volta per la codebase comune. 3. **Flessibilità Controllata**: È comunque possibile introdurre comportamenti run-time personalizzati leggendo `environment.brand` nel codice TypeScript (es. `if (environment.brand === 'stereocomics') { ... }`). ### Svantaggi: 1. **Complessità Condizionale**: Se a lungo andare Stereocomics necessita di pagine con layout o logiche radicalmente diversi da Canti, il codice si riempirà di blocchi `if/else` o direttive condizionali (`*ngIf="isStereocomics"`), riducendo la leggibilità del codice. --- ## 4. Criteri di Accettazione e Verifica (Verification Plan) ### Verifica dello Sviluppo Locale 1. Eseguire `npm run start:canti` -> Verificare che il logo sia quello di CantiCristiani e il colore dominante sia il blu/verde originale. 2. Eseguire `npm run start:stereocomics` -> Verificare che l'interfaccia risponda con il branding Stereocomics (colore primario cambiato, nome app cambiato in testata, logo corretto). ### Verifica PWA e Build di Produzione 1. Eseguire `npm run build:stereocomics`. 2. Controllare che la cartella `/www` contenga il file `manifest.webmanifest` con i riferimenti a Stereocomics. 3. Verificare che l'email di contatto visualizzata sia `info@stereocomics.it`.