documenti di planning per clonazione canti

2026-06-18 14:08:41 +02:00
parent 68d455289d
commit 2607c9c1a8
2 changed files with 395 additions and 0 deletions
@@ -0,0 +1,220 @@
+# 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`.
@@ -0,0 +1,175 @@
+# Studio di Dettaglio: Opzione 2 - Angular Workspace Monorepo
+
+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 2: Angular Workspace Monorepo**.
+
+Con questo approccio, il repository viene strutturato per ospitare **due applicazioni distinte** (`canti` e `stereocomics`) e **una o più librerie condivise** (`shared-core`) che conterranno la logica di business comune (servizi audio, parser di testi, database locale, integrazioni API).
+
+---
+
+## 1. Architettura e Struttura delle Cartelle
+
+Nel modello Monorepo, la struttura dei file viene riorganizzata per isolare l'interfaccia utente (pagine, componenti, temi) e condividere i servizi fondamentali.
+
+```mermaid
+graph TD
+    subgraph Monorepo Workspace
+        Shared[Libreria Condivisa: @shared/core]
+        AppCanti[App 1: Canti]
+        AppStereo[App 2: Stereocomics]
+    end
+    
+    AppCanti --> Shared
+    AppStereo --> Shared
+```
+
+La struttura delle cartelle diventerà simile alla seguente:
+```text
+canti/
+├── angular.json
+├── package.json
+├── tsconfig.json
+├── src/                      <-- Diventa l'applicazione Canti originale
+│   ├── app/
+│   │   ├── pages/            <-- Pagine specifiche di Canti
+│   │   └── app.module.ts
+│   └── assets/               <-- Asset di Canti
+├── projects/
+│   ├── shared-core/          <-- Libreria condivisa generata
+│   │   ├── src/
+│   │   │   ├── public-api.ts
+│   │   │   └── lib/
+│   │   │       └── services/ <-- AudioEngine, LyricsParser, CantiService, ecc.
+│   └── stereocomics/         <-- Nuova applicazione Stereocomics
+│       ├── src/
+│       │   ├── app/
+│       │   │   ├── pages/    <-- Pagine e UI customizzate di Stereocomics
+│       │   │   └── app.module.ts
+│       │   ├── assets/       <-- Asset di Stereocomics
+│       │   └── theme/        <-- Fogli di stile di Stereocomics
+```
+
+---
+
+## 2. Passaggi Operativi per l'Implementazione
+
+### Passo 2.1: Inizializzazione della Libreria Condivisa
+Generiamo una libreria Angular per ospitare i servizi condivisi.
+
+```bash
+ng generate library shared-core --prefix=shared
+```
+
+Questo comando creerà la cartella `projects/shared-core/` e aggiornerà [angular.json](file:///Users/davidfrassi/SRC/agenti/canti/angular.json) e [tsconfig.json](file:///Users/davidfrassi/SRC/agenti/canti/tsconfig.json) inserendo il path alias (es. `@shared/core`).
+
+---
+
+### Passo 2.2: Migrazione dei Servizi Core
+Sposteremo tutti i servizi non legati direttamente alla UI da `src/app/services/` a `projects/shared-core/src/lib/services/`.
+
+Servizi da migrare:
+* [audio-engine.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/audio-engine.service.ts)
+* [canti.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/canti.service.ts)
+* [lyrics-parser.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/lyrics-parser.service.ts)
+* Eventuali altri helper o interfacce dati comuni.
+
+Esponiamo i servizi nel file `projects/shared-core/src/public-api.ts`:
+```typescript
+export * from './lib/services/audio-engine.service';
+export * from './lib/services/canti.service';
+export * from './lib/services/lyrics-parser.service';
+```
+
+Aggiorneremo quindi gli import all'interno dell'applicazione principale `canti` (e successivamente `stereocomics`):
+```typescript
+// Da:
+import { CantiService } from '../services/canti.service';
+// A:
+import { CantiService } from '@shared/core';
+```
+
+---
+
+### Passo 2.3: Generazione della Nuova Applicazione Stereocomics
+Creiamo la seconda applicazione all'interno del workspace:
+
+```bash
+ng generate application stereocomics --routing --style=scss
+```
+
+In [angular.json](file:///Users/davidfrassi/SRC/agenti/canti/angular.json) verrà aggiunto un nuovo progetto denominato `stereocomics`. 
+
+#### Integrazione Ionic
+Per abilitare le funzionalità Ionic (componenti UI, gesture, ecc.) nella nuova applicazione, occorre:
+1. Importare `IonicModule.forRoot()` nel file `projects/stereocomics/src/app/app.module.ts`.
+2. Copiare o adattare la struttura di theming da `src/theme/` a `projects/stereocomics/src/theme/`.
+
+---
+
+### Passo 2.4: Personalizzazione delle Pagine e dei Componenti
+A differenza dell'Opzione 1 (dove le pagine HTML sono identiche), nell'Opzione 2 `stereocomics` ha le sue pagine indipendenti in `projects/stereocomics/src/app/pages/`. 
+
+È possibile:
+* Creare layout completamente differenti.
+* Aggiungere nuove feature o pagine esclusive (es. una sezione "Comics" o "Store") senza intaccare minimamente l'applicazione `canti`.
+* Importare i servizi core da `@shared/core` in ciascuna pagina per gestire la logica dei canti e dell'audio.
+
+---
+
+### Passo 2.5: Script in `package.json`
+Modificheremo gli script di avvio e build per differenziare i target:
+
+```json
+"scripts": {
+  "start:canti": "ng serve app --port=4200",
+  "start:stereocomics": "ng serve stereocomics --port=4300",
+  "build:shared": "ng build shared-core",
+  "build:canti": "npm run build:shared && ng build app --configuration=production",
+  "build:stereocomics": "npm run build:shared && ng build stereocomics --configuration=production"
+}
+```
+
+---
+
+### Passo 2.6: Gestione di Capacitor (Mobile Apps Separate)
+Per compilare le due app per iOS/Android in modo totalmente indipendente:
+1. L'app `canti` continuerà ad usare la configurazione di Capacitor a livello di root, oppure verrà spostata in una sottocartella.
+2. Inizializziamo Capacitor specificamente per `stereocomics` posizionando un file `capacitor.config.ts` all'interno di `projects/stereocomics/`:
+
+```typescript
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'it.stereocomics.app',
+  appName: 'Stereocomics',
+  webDir: '../../dist/stereocomics', // Punterà alla cartella di build di Angular
+  bundledWebRuntime: false
+};
+
+export default config;
+```
+
+---
+
+## 3. Vantaggi e Svantaggi dell'Opzione 2
+
+### Vantaggi:
+1. **Massima Libertà di Design e UX**: L'applicazione `stereocomics` può avere una struttura di navigazione, pagine e flussi utente completamente diversi da `canti`.
+2. **Isolamento del Codice UI**: I cambiamenti estetici o le nuove feature di interfaccia introdotte su Stereocomics non rischiano di rompere l'applicazione Canti originale.
+3. **Riutilizzo della Logica di Business**: Tutta la logica complessa dei database locali, del lettore audio e dei parser rimane centralizzata e testata una volta sola nella libreria `@shared/core`.
+
+### Svantaggi:
+1. **Sforzo Iniziale Elevato**: Richiede un refactoring iniziale importante per estrarre tutti i servizi e ridefinire i path di importazione in tutto il progetto.
+2. **Build più Lente**: La compilazione richiede prima la build delle librerie condivise e poi dell'applicazione specifica.
+3. **Gestione delle Dipendenze**: Sebbene condividano lo stesso `package.json`, l'aggiornamento di una libreria esterna (es. Ionic o Angular) deve essere testato su entrambe le applicazioni per evitare regressioni.
+
+---
+
+## 4. Criteri di Accettazione e Verifica (Verification Plan)
+
+### Verifica dello Sviluppo Locale
+1. Eseguire `npm run start:canti` -> Verificare il funzionamento completo dell'app principale sulla porta `4200`.
+2. Eseguire `npm run start:stereocomics` -> Verificare che la nuova app risponda sulla porta `4300` con il layout personalizzato.
+
+### Verifica della Compilazione Condivisa
+1. Apportare una modifica al servizio `CantiService` (es. aggiungere un log).
+2. Verificare che la modifica sia visibile ed efficace sia su `canti` che su `stereocomics` dopo aver compilato la libreria condivisa.