frassidavid/stereocomics
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: fork from canti

Browse Source
This commit is contained in:
David Frassi
2026-09-26 09:00:54 +02:00
commit 34bf3ea391
154 changed files with 45131 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documenti/clonazione_opzione_1.md
+220
View File
@@ -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`.
documenti/clonazione_opzione_2.md
+175
View File
@@ -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.
documenti/clonazione_stereocomics.md
+164
View File
@@ -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).
documenti/implementation_plan_stereocomics.md
+72
View File
@@ -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.