diff --git a/documenti/clonazione_stereocomics.md b/documenti/clonazione_stereocomics.md new file mode 100644 index 0000000..579c8b0 --- /dev/null +++ b/documenti/clonazione_stereocomics.md @@ -0,0 +1,164 @@ +# Guida alla Creazione di "stereocomics" tramite Angular Workspace Monorepo + +Questo documento descrive dettagliatamente la strategia dell'**Opzione 2 (Monorepo)**. L'obiettivo è trasformare l'attuale struttura del progetto in un Workspace Angular multi-applicazione, dove le logiche funzionali (servizi, parser, gestione audio) risiedono in una libreria condivisa, mentre le applicazioni `canti` e `stereocomics` rimangono indipendenti per quanto riguarda interfacce grafiche, stili, asset e configurazioni. + +--- + +## Struttura Finale del Workspace Monorepo + +Al termine del processo, la struttura delle cartelle del progetto si presenterà così: + +```text +canti/ (Root del Workspace) +├── angular.json # Configurazione di build per entrambi i progetti +├── package.json # Dipendenze condivise +├── tsconfig.json # Configurazione TypeScript con path alias per il core +├── src/ # Codice sorgente dell'applicazione originale "canti" +│ ├── app/ # Componenti, pagine e routing specifici di canti +│ └── assets/ # Immagini, loghi e risorse di canti +└── projects/ + ├── core/ # LIBRERIA CONDIVISA (TypeScript puro) + │ └── src/ + │ ├── public-api.ts # Esporta i servizi core + │ └── lib/ + │ └── services/ # I servizi estratti (audio, parser, canti, settings, ecc.) + └── stereocomics/ # NUOVA APPLICAZIONE "stereocomics" + ├── src/ + │ ├── app/ # Pagine, componenti e routing specifici di stereocomics + │ ├── assets/ # Loghi, immagini e splash screen di stereocomics + │ └── theme/ # CSS/SCSS personalizzato (variabili di colore diverse) + └── capacitor.config.ts # Configurazione Capacitor specifica (es. per iOS/Android) +``` + +--- + +## Fasi di Implementazione Dettagliate + +### Fase 1: Creazione della Libreria Condivisa (`core`) +Il primo passo consiste nel creare un modulo di libreria all'interno del workspace. + +1. **Generazione della libreria**: + Utilizzando l'Angular CLI dalla root del progetto: + ```bash + ng generate library core --prefix=core + ``` + Questo comando creerà la cartella `projects/core` e configurerà automaticamente i path alias nel file `tsconfig.json` (es. `"@core/*"` o `"core"`). + +2. **Migrazione dei Servizi**: + Sposteremo i file dei servizi core da `src/app/services/` a `projects/core/src/lib/services/`. I file principali da migrare includono: + - [lyrics-parser.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/lyrics-parser.service.ts) + - [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) + - [playlist.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/playlist.service.ts) + - [settings.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/settings.service.ts) + - [comunita.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/comunita.service.ts) + - E gli altri servizi correlati. + +3. **Esportazione delle API**: + Nel file `projects/core/src/public-api.ts`, esporteremo tutti i servizi migrati in modo che siano importabili dalle applicazioni esterne: + ```typescript + export * from './lib/services/canti.service'; + export * from './lib/services/lyrics-parser.service'; + // ... altre esportazioni + ``` + +4. **Compilazione iniziale**: + Si compila la libreria core affinché sia disponibile per i progetti: + ```bash + ng build core + ``` + +--- + +### Fase 2: Adeguamento dell'Applicazione `canti` +Dopo aver spostato i servizi nella libreria condivisa, dobbiamo aggiornare l'applicazione originale affinché consumi la libreria anziché i vecchi file locali. + +1. **Aggiornamento degli Import**: + In tutti i componenti e pagine di `canti` (es. `src/app/home/home.page.ts`), modificheremo gli import dei servizi: + *Prima:* + ```typescript + import { CantiService } from '../services/canti.service'; + ``` + *Dopo:* + ```typescript + import { CantiService } from 'core'; + ``` + +2. **Rimozione dei Vecchi Servizi**: + Elimineremo la cartella `src/app/services/` ormai vuota. + +3. **Test di Verifica**: + Avvieremo `canti` con `npm run start` (o `ng serve`) per assicurarci che l'applicazione funzioni correttamente importando i servizi dalla libreria. + +--- + +### Fase 3: Generazione dell'Applicazione `stereocomics` +Ora che le fondamenta condivise sono pronte, creiamo la nuova applicazione `stereocomics`. + +1. **Generazione**: + Sempre tramite Angular CLI: + ```bash + ng generate application stereocomics --style=scss --routing=true + ``` + Questo configurerà un nuovo blocco chiamato `stereocomics` in `angular.json` e creerà la cartella `projects/stereocomics`. + +2. **Integrazione con Ionic**: + Aggiungeremo il supporto a Ionic nella nuova applicazione importando `IonicModule.forRoot()` nel file `projects/stereocomics/src/app/app.module.ts`. + +--- + +### Fase 4: Sviluppo e Personalizzazione di `stereocomics` +A questo punto abbiamo un'applicazione vergine che possiamo strutturare come vogliamo, riutilizzando però i servizi core. + +1. **Struttura delle Pagine**: + Possiamo decidere di copiare le pagine esistenti di `canti` (se vogliamo che `stereocomics` parta con lo stesso layout per poi essere modificato) oppure creare pagine del tutto nuove. + Ad esempio, per generare una pagina specifica in stereocomics: + ```bash + ng generate page pages/home --project=stereocomics + ``` + +2. **Consumo dei Servizi Shared**: + Nel codice di `stereocomics`, per caricare i dati useremo la libreria condivisa: + ```typescript + import { Component, OnInit } from '@angular/core'; + import { CantiService } from 'core'; + + @Component({ ... }) + export class HomePage implements OnInit { + constructor(private cantiService: CantiService) {} + + ngOnInit() { + // Possiamo accedere a tutte le funzioni storiche + this.cantiService.loadCanti(); + } + } + ``` + +3. **Personalizzazione Visiva (Branding)**: + - Modificheremo `projects/stereocomics/src/theme/variables.scss` per definire la palette di colori di `stereocomics` (ad es. tonalità arancioni o viola, differenziandosi dal blu di `canti`). + - Sostituiremo gli asset in `projects/stereocomics/src/assets/` con loghi, icone e immagini dedicati a stereocomics. + +--- + +### Fase 5: Configurazione dei Comandi di Build +Aggiungeremo o modificheremo gli script nel file `package.json` per facilitare lo sviluppo parallelo: + +```json +"scripts": { + "start:canti": "ng serve app", + "start:stereocomics": "ng serve stereocomics", + "build:canti": "ng build app --configuration production", + "build:stereocomics": "ng build stereocomics --configuration production", + "watch:core": "ng build core --watch" +} +``` + +Durante lo sviluppo, se modifichi un servizio core, il comando `watch:core` ricompilerà automaticamente la libreria in background, aggiornando istantaneamente l'app che stai servendo localmente. + +--- + +## Vantaggi di questo Approccio + +* **Sorgente di Verità Unica (Single Source of Truth)**: La complessa logica di business (algoritmi di parsing, logica audio per i player, caching, sync) viene scritta, testata e manutenuta in un solo posto (`projects/core`). +* **Autonomia Grafica ed Esperienziale**: `stereocomics` ha le sue pagine HTML e i suoi fogli di stile CSS/SCSS. Può avere una navigazione a tab, mentre `canti` usa un menu laterale (sidemenu), senza alcun conflitto. +* **Semplicità di Aggiornamento delle Dipendenze**: Entrambe le applicazioni utilizzano gli stessi pacchetti npm (configurati nel `package.json` globale nella root), riducendo il disallineamento delle versioni delle librerie terze (es. Capacitor, Ionic, Angular). diff --git a/documenti/implementation_plan_stereocomics.md b/documenti/implementation_plan_stereocomics.md new file mode 100644 index 0000000..376acdf --- /dev/null +++ b/documenti/implementation_plan_stereocomics.md @@ -0,0 +1,72 @@ +# Piano Operativo: Clonazione e Personalizzazione in "stereocomics" + +Questo piano descrive le opzioni e le fasi operative per creare un clone del progetto **canti** denominato **stereocomics**. Il clone condividerà le stesse librerie funzionali di base (servizi, parser, logica audio, ecc.) offrendo al contempo completa libertà di personalizzazione (grafica, asset, configurazioni, ed eventuali pagine specifiche). + +--- + +## Opzioni Architetturali Proposte + +Prima di procedere con l'implementazione, è fondamentale scegliere l'approccio strutturale più adatto: + +### Opzione 1: White-Label / Multi-Configuration (Consigliata per Manutenibilità) +*Se l'applicazione stereocomics differisce principalmente per branding, colori, logo, configurazioni e alcuni testi, ma condivide la quasi totalità delle pagine e dei flussi.* +- **Come funziona**: Si mantiene un unico codice sorgente. Si usano i file di configurazione ambientale di Angular (`src/environments/`) e file CSS personalizzati per caricare dinamicamente loghi, stili (tramite variabili CSS/SCSS), e comportamenti in base alla build (es. `ng build --configuration=stereocomics`). +- **Pro**: Semplicità assoluta di manutenzione. Qualsiasi bug fix o nuova funzionalità su un servizio o una pagina si riflette istantaneamente su entrambi i brand senza duplicazione di codice. +- **Contro**: Meno flessibilità se le pagine di `stereocomics` dovranno divergere drasticamente a livello di layout HTML o logica di navigazione rispetto a `canti`. + +### Opzione 2: Angular Workspace Monorepo (Consigliata per Massima Personalizzazione) +*Se stereocomics deve avere pagine, componenti e flussi di navigazione diversi da canti, pur riutilizzando gli stessi servizi (audio, parser, database local, ecc.).* +- **Come funziona**: Si trasforma il progetto in un workspace Angular multi-applicazione. + 1. Si crea una libreria condivisa (es. `projects/shared-core`) dove vengono spostati tutti i servizi di base (`src/app/services/*`). + 2. L'applicazione attuale viene configurata come progetto `canti`. + 3. Viene generata una nuova applicazione Angular/Ionic nello stesso workspace (`projects/stereocomics`) che importa i servizi da `shared-core` ma ha le sue pagine, i suoi componenti e la sua veste grafica indipendenti. +- **Pro**: Massimo controllo. Ciascuna app ha la sua struttura di pagine, ma condividono al 100% la logica complessa dei servizi. +- **Contro**: Richiede una ristrutturazione iniziale dei path di importazione dei servizi nel progetto attuale. + +### Opzione 3: Repository / Cartella Indipendente +*Se si desidera un progetto completamente separato in una nuova cartella `/Users/davidfrassi/SRC/agenti/stereocomics`.* +- **Come funziona**: Si clona il progetto in una nuova cartella e si personalizza in modo indipendente. Per condividere le librerie, si può creare un package locale (`npm link`) o importare i servizi come sottomodulo git. +- **Pro**: Isolamento totale. +- **Contro**: Rischio elevato di divergenza del codice. I bug fix sui servizi in un progetto dovranno essere riportati manualmente o gestiti tramite rilasci di pacchetti. + +--- + +## User Review Required + +> [!IMPORTANT] +> Si prega di verificare quale delle tre opzioni si adatta meglio alle esigenze di sviluppo a lungo termine di **stereocomics**. +> +> - Se il clone differisce solo per loghi, colori e piccoli dettagli, l'**Opzione 1 (White-Label)** è la più rapida ed efficiente. +> - Se il clone deve avere un'interfaccia utente o funzionalità molto diverse pur usando la stessa logica di lettura/parsing, l'**Opzione 2 (Monorepo)** è la scelta ideale. + +--- + +## Fasi del Piano Operativo (Esempio basato sull'Opzione 2 - Monorepo) + +Se si sceglie l'approccio Monorepo, i passi saranno i seguenti: + +### Fase 1: Preparazione e Ristrutturazione (Refactoring dei Servizi) +1. Spostare i servizi core (ad es. [lyrics-parser.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/lyrics-parser.service.ts), [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)) in una libreria condivisa o in una cartella core dedicata configurata con path alias in `tsconfig.json` (es. `@shared/services`). +2. Aggiornare gli import in tutto il progetto `canti` per utilizzare il nuovo path alias. + +### Fase 2: Creazione del Progetto Stereocomics +1. Generare la nuova applicazione all'interno del workspace o duplicare la struttura configurando il nuovo target in [angular.json](file:///Users/davidfrassi/SRC/agenti/canti/angular.json). +2. Configurare gli asset (immagini, loghi, splash screen) per `stereocomics` in una cartella dedicata. +3. Creare il file di configurazione specifico per stereocomics (`environment.stereocomics.ts`). + +### Fase 3: Personalizzazione e Stile +1. Creare un tema CSS/SCSS personalizzato per `stereocomics` modificando le variabili di colore Ionic/CSS. +2. Sviluppare eventuali componenti o pagine specifiche per `stereocomics`. + +### Fase 4: Configurazione della Build e Deploy +1. Configurare gli script npm in `package.json` per avviare e buildare specificamente il nuovo target (es. `npm run start:stereocomics`, `npm run build:stereocomics`). +2. Configurare Capacitor/PWA per il nuovo brand (nuovo package ID, nome dell'app, icone). + +--- + +## Verification Plan + +### Manual Verification +- Avvio di `canti` in modalità sviluppo per verificare che il refactoring dei servizi non abbia introdotto regressioni. +- Avvio di `stereocomics` per verificare il caricamento del nuovo tema, logo e impostazioni personalizzate. +- Test delle funzionalità core (riproduzione, parsing testi) in entrambe le applicazioni.