David Frassi
176 lines
7.7 KiB
Markdown
176 lines
7.7 KiB
Markdown
# 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.
|