Files

T

David Frassi 2607c9c1a8 documenti di planning per clonazione canti

2026-06-18 14:08:41 +02:00

8.3 KiB

Raw Permalink Blame History

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.

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

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

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.

Sotto projects -> app -> architect -> build -> configurations, aggiungeremo il blocco stereocomics:

"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:

"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

Questo file conterrà le medesime variabili CSS di src/theme/variables.scss ma con la palette colori e i font scelti per Stereocomics:

// 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 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:

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)
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.
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 per facilitare lo sviluppo e la pubblicazione:

"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']).

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:

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.
Semplicità di Manutenzione: Un'unica pipeline di CI/CD che esegue i test unitari una sola volta per la codebase comune.
Flessibilità Controllata: È comunque possibile introdurre comportamenti run-time personalizzati leggendo environment.brand nel codice TypeScript (es. if (environment.brand === 'stereocomics') { ... }).

Svantaggi:

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

Eseguire npm run start:canti -> Verificare che il logo sia quello di CantiCristiani e il colore dominante sia il blu/verde originale.
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

Eseguire npm run build:stereocomics.
Controllare che la cartella /www contenga il file manifest.webmanifest con i riferimenti a Stereocomics.
Verificare che l'email di contatto visualizzata sia info@stereocomics.it.

8.3 KiB Raw Permalink Blame History