Files

T

David Frassi 2607c9c1a8 documenti di planning per clonazione canti

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

7.7 KiB

Raw Blame History

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.

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:

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.

ng generate library shared-core --prefix=shared

Questo comando creerà la cartella projects/shared-core/ e aggiornerà angular.json e 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
canti.service.ts
lyrics-parser.service.ts
Eventuali altri helper o interfacce dati comuni.

Esponiamo i servizi nel file projects/shared-core/src/public-api.ts:

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

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

ng generate application stereocomics --routing --style=scss

In angular.json verrà aggiunto un nuovo progetto denominato stereocomics.

Integrazione Ionic

Per abilitare le funzionalità Ionic (componenti UI, gesture, ecc.) nella nuova applicazione, occorre:

Importare IonicModule.forRoot() nel file projects/stereocomics/src/app/app.module.ts.
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:

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

L'app canti continuerà ad usare la configurazione di Capacitor a livello di root, oppure verrà spostata in una sottocartella.
Inizializziamo Capacitor specificamente per stereocomics posizionando un file capacitor.config.ts all'interno di projects/stereocomics/:

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:

Massima Libertà di Design e UX: L'applicazione stereocomics può avere una struttura di navigazione, pagine e flussi utente completamente diversi da canti.
Isolamento del Codice UI: I cambiamenti estetici o le nuove feature di interfaccia introdotte su Stereocomics non rischiano di rompere l'applicazione Canti originale.
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:

Sforzo Iniziale Elevato: Richiede un refactoring iniziale importante per estrarre tutti i servizi e ridefinire i path di importazione in tutto il progetto.
Build più Lente: La compilazione richiede prima la build delle librerie condivise e poi dell'applicazione specifica.
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

Eseguire npm run start:canti -> Verificare il funzionamento completo dell'app principale sulla porta 4200.
Eseguire npm run start:stereocomics -> Verificare che la nuova app risponda sulla porta 4300 con il layout personalizzato.

Verifica della Compilazione Condivisa

Apportare una modifica al servizio CantiService (es. aggiungere un log).
Verificare che la modifica sia visibile ed efficace sia su canti che su stereocomics dopo aver compilato la libreria condivisa.

7.7 KiB Raw Blame History