nis2-agile/agile-services-istructio.md

# AgileServices — Istruzioni Operative per Progetti Integrati

> **Questo file deve essere copiato nella root di ogni progetto che usa AgileServices.**
> Serve a Claude (e al team) per capire immediatamente come integrare e ampliare la piattaforma.
>
> Agile Technology SRL — Versione 1.1 — 2026-02-17

---

## 1. Cos'è AgileServices

AgileServices è la piattaforma di **microservizi condivisi e riutilizzabili** di Agile Technology SRL.
Tutti i progetti interni (CertiSource Pro, MadeByCloud Pro, TRPG Pro, ecc.) usano questi servizi come building blocks.

**Non duplicare mai** funzionalità già esistenti — cerca prima in AgileServices.

```
Percorso sorgente:  /projects/agile-services/
Registry servizi:   /projects/agile-services/SERVICES.md
Stato progetto:     /projects/agile-services/progetto.md
Questo file:        /projects/agile-services/agile-services-istructio.md
```

---

## 2. Regola Fondamentale

```
PRIMA di costruire qualcosa → leggi SERVICES.md
SE esiste già               → usalo con l'API key del tuo tenant
SE non esiste               → crealo in /projects/agile-services/ e documentalo in SERVICES.md
MAI creare codice duplicato in un progetto specifico
```

---

## 3. Prerequisito: Avviare l'Infrastruttura

**OBBLIGATORIO** — senza questo nessun microservizio funziona.

```bash
cd /projects/agile-services/infrastructure/docker-compose
docker-compose up -d
```

Questo avvia (una volta sola, poi rimane attivo):

| Container | Host:Porta | Credenziali |
|-----------|-----------|------------|
| `agile-mysql` | `localhost:3306` | root / AgileRoot2026! |
| `agile-postgres` | `localhost:5433` | agile / AgilePostgres2026! |
| `agile-redis` | `localhost:6379` | pass: AgileRedis2026! |
| `agile-rabbitmq` | `localhost:5672` | agile / AgileQueue2026! |
| `agile-rabbitmq` UI | `localhost:15672` | agile / AgileQueue2026! |
| `agile-kong` proxy | `localhost:8000` | — |
| `agile-kong` admin | `localhost:8001` | — |
| `agile-grafana` | `localhost:3000` | admin / AgileGrafana2026! |
| `agile-mailpit` | `localhost:8025` | — |

### Network Docker

Tutti i microservizi condividono la rete `agile-services-network`.
Nel `docker-compose.yml` di ogni MS dichiarare sempre:

```yaml
networks:
  agile-services-network:
    external: true
    name: agile-services-network
```

---

## 4. Tenant del Progetto Corrente

Ogni progetto ha un **tenant dedicato** con la propria API key.

### Tenant pre-registrati (dev)

| Progetto | Tenant Code | API Key dev |
|---------|------------|-------------|
| CertiSource Pro | `certisource` | `certisource_ak_dev_1234567890abcdef` |
| MadeByCloud Pro | `madebycloud` | `madebycloud_ak_dev_abcdef1234567890` |
| TRPG Pro | `trpg` | `trpg_ak_dev_trpg1234567890abcd` |

### Creare un nuovo tenant

```bash
# Richiede infrastruttura attiva (agile-mysql deve girare)
cd /projects/agile-services
./scripts/create-tenant.sh
# → inserire: tenant code, nome, piano, modalità database
# → output: API key da salvare nel .env del progetto
```

### Variabili d'ambiente nel progetto

```env
# AgileServices — aggiungere nel .env del progetto
AGILE_TENANT_CODE=trpg
AGILE_API_KEY=trpg_ak_dev_trpg1234567890abcd

# URL microservizi usati da questo progetto (solo quelli necessari)
VAULT_MS_URL=http://localhost:8001
PAYMENT_MS_URL=http://localhost:8003
CONTENT_GENERATION_MS_URL=http://localhost:4001
EMAIL_AUTOMATION_MS_URL=http://localhost:4004
ANALYTICS_MS_URL=http://localhost:4005
```

---

## 5. Microservizi Disponibili

### 5.1 Core Services (PHP — MySQL — porte 8001-8011)

#### `vault-ms` — ✅ Pronto — porta 8001

Gestione credenziali criptate AES-256-GCM. Usa questo per salvare API key di provider esterni, password, token. **Non mettere mai segreti nel `.env` applicativo.**

```bash
# Avvia
cd /projects/agile-services/vault-ms && docker-compose up -d

# Crea credenziale
curl -X POST http://localhost:8001/v1/credentials \
  -H "X-API-Key: trpg_ak_dev_trpg1234567890abcd" \
  -H "Content-Type: application/json" \
  -d '{"provider": "stripe", "key": "secret_key", "value": "sk_test_..."}'

# Leggi credenziale
curl http://localhost:8001/v1/credentials?provider=stripe \
  -H "X-API-Key: trpg_ak_dev_trpg1234567890abcd"
```

#### `payment-ms` — 🔄 In Dev — porta 8003

Gateway pagamenti (Revolut). Usa vault-ms per le credenziali del provider.

```bash
cd /projects/agile-services/payment-ms && docker-compose up -d
```

#### Altri core services — 📋 Planned

`document-ms` (8002), `certificate-ms` (8004), `subscription-ms` (8005), `billing-ms` (8006), `practice-ms` (8007), `company-ms` (8008), `supplier-ms` (8009), `investigation-ms` (8010), `whatsapp-ms` (8011)

---

### 5.2 Marketing Services (Node.js — PostgreSQL — porte 4001-4006)

#### `content-generation-ms` — 🔄 In Dev — porta 4001

Generazione contenuti AI con GPT-4. Supporta brand voice multipli e template.

```bash
cd /projects/agile-services/content-generation-ms && docker-compose up -d

# Genera contenuto
curl -X POST http://localhost:4001/generate \
  -H "Content-Type: application/json" \
  -d '{
    "brandVoice": "trpg",
    "template": "email",
    "input": {"topic": "Nuova campagna TRPG", "painPoint": "sessioni difficili da organizzare"},
    "count": 3,
    "language": "it"
  }'

# Crea brand voice
curl -X POST http://localhost:4001/brand-voices \
  -H "Content-Type: application/json" \
  -d '{"name": "TRPG Pro", "industry": "gaming", "tone": ["professionale", "appassionato"]}'
```

#### `ads-orchestrator-ms` — 🔄 In Dev — porta 4002

Gestione campagne ads multi-canale (Meta, Google, LinkedIn).

```bash
cd /projects/agile-services/ads-orchestrator-ms && docker-compose up -d

# Crea campagna
curl -X POST http://localhost:4002/campaigns \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "trpg-pro",
    "name": "Lancio Winter Campaign",
    "platform": "meta",
    "objective": "conversion",
    "budget": {"total": 500, "daily": 50},
    "targeting": {"locations": ["IT"], "ageRange": [25, 45]}
  }'

# Performance campagna
curl http://localhost:4002/campaigns/1/performance
```

#### `crm-pipeline-ms` — 🔄 In Dev — porta 4003

CRM lead pipeline interno. Sostituisce SuperAGI.

```bash
cd /projects/agile-services/crm-pipeline-ms && docker-compose up -d

# Crea lead
curl -X POST http://localhost:4003/leads \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "firstName": "Mario", "source": "meta_ads", "productId": "trpg-pro"}'

# Pipeline overview
curl http://localhost:4003/pipelines/trpg-pro
```

#### `email-automation-ms` — 🔄 In Dev — porta 4004

Sequenze email automatiche con Handlebars templates e trigger-based enrollment.

```bash
cd /projects/agile-services/email-automation-ms && docker-compose up -d

# Crea sequenza onboarding
curl -X POST http://localhost:4004/sequences \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding TRPG Pro",
    "productId": "trpg-pro",
    "trigger": "registration",
    "emails": [
      {"delay": 0, "subject": "Benvenuto in TRPG Pro!", "body": "<h1>Ciao {{firstName}}!</h1>"},
      {"delay": 3, "subject": "Come iniziare la tua prima campagna", "body": "..."}
    ]
  }'

# Trigger sequenza per un lead
curl -X POST http://localhost:4004/sequences/1/trigger \
  -H "Content-Type: application/json" \
  -d '{"leadId": "lead_123", "customData": {"firstName": "Mario"}}'

# Stats sequenza
curl http://localhost:4004/sequences/1/stats
```

#### `analytics-ms` — 🔄 In Dev — porta 4005

Dashboard metriche multi-prodotto con alerting e report automatici.

```bash
cd /projects/agile-services/analytics-ms && docker-compose up -d

# Traccia metrica
curl -X POST http://localhost:4005/metrics/track \
  -H "Content-Type: application/json" \
  -d '{"tenantCode": "trpg", "productId": "trpg-pro", "metric": "new_registration", "value": 1}'

# Dashboard overview
curl http://localhost:4005/dashboard/overview

# Dashboard prodotto
curl http://localhost:4005/dashboard/product/trpg-pro

# Configura alert
curl -X POST http://localhost:4005/alerts/configure \
  -H "Content-Type: application/json" \
  -d '{"tenantCode": "trpg", "metric": "churn_rate", "operator": "gt", "threshold": 5}'
```

#### `ai-sdr-ms` — 🔄 In Dev — porta 4006

Outbound automation AI-powered per prospecting e outreach personalizzato.

```bash
cd /projects/agile-services/ai-sdr-ms && docker-compose up -d

# Crea campagna outbound
curl -X POST http://localhost:4006/campaigns/outbound \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Outreach Q1 2026",
    "productId": "trpg-pro",
    "icp": {"roles": ["Game Master", "Dungeon Master"], "locations": ["IT"]},
    "prospectCount": 200,
    "outreachMethod": "email",
    "messageTemplate": "Ciao {{firstName}}, gestisci sessioni TRPG?",
    "schedule": {"dailyLimit": 30, "timezone": "Europe/Rome"}
  }'

# Prospect qualificati
curl http://localhost:4006/prospects/qualified?productId=trpg-pro
```

---

## 6. Autenticazione

I **Core Services (PHP)** richiedono autenticazione su ogni chiamata:

```http
X-API-Key: <tenant_api_key>
Content-Type: application/json
```

I **Marketing Services (Node.js)** sono in sviluppo — l'autenticazione `X-API-Key` verrà aggiunta. Attualmente accettano chiamate senza auth ma isolano i dati tramite `tenant_code` nel body/query.

---

## 7. Avviare Tutti i Microservizi

```bash
# 1. Infrastruttura (OBBLIGATORIO per primo)
cd /projects/agile-services/infrastructure/docker-compose && docker-compose up -d

# 2. Core Services PHP
cd /projects/agile-services/vault-ms && docker-compose up -d
cd /projects/agile-services/payment-ms && docker-compose up -d

# 3. Marketing Services Node.js
cd /projects/agile-services/content-generation-ms && docker-compose up -d
cd /projects/agile-services/ads-orchestrator-ms && docker-compose up -d
cd /projects/agile-services/crm-pipeline-ms && docker-compose up -d
cd /projects/agile-services/email-automation-ms && docker-compose up -d
cd /projects/agile-services/analytics-ms && docker-compose up -d
cd /projects/agile-services/ai-sdr-ms && docker-compose up -d

# Verifica health
curl http://localhost:8001/health   # vault-ms
curl http://localhost:4001/health   # content-generation-ms
curl http://localhost:4004/health   # email-automation-ms
curl http://localhost:4005/health   # analytics-ms
```

---

## 8. Creare un Nuovo Microservizio Specifico

Se la funzionalità necessaria **non esiste** in AgileServices (verifica su `SERVICES.md`):

```bash
cd /projects/agile-services
./scripts/create-microservice.sh --name="trpg-character-ms" --port=4200
```

### Convenzioni obbligatorie

| Aspetto | Regola | Esempio |
|---------|--------|---------|
| Nome | `kebab-case` + suffisso `-ms` | `trpg-character-ms` |
| Porta | 4200+ per servizi custom | 4200, 4201, ... |
| Endpoint | `/kebab-case` | `/character-sheets` |
| Env var | `UPPER_SNAKE_CASE` | `CHARACTER_MS_URL` |
| Database | 1 DB per servizio | `trpg_character_db` |
| Health | `GET /health` obbligatorio | vedi sotto |
| Errori | formato standard | vedi sotto |
| Test | coverage >= 70% | `npm test` |

```json
// GET /health — risposta standard obbligatoria
{
  "status": "ok",
  "service": "trpg-character-ms",
  "version": "1.0.0",
  "uptime": 12345,
  "dependencies": { "database": "ok" }
}

// Errore standard obbligatorio
{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "Personaggio non trovato" }
}
```

### docker-compose.yml del nuovo servizio

```yaml
version: '3.8'
services:
  trpg-character-ms:
    build: .
    container_name: trpg-character-ms
    ports:
      - "4200:4200"
    environment:
      PORT: 4200
      DB_HOST: agile-postgres
      DB_PORT: 5432
      DB_NAME: trpg_character_db
      DB_USER: agile
      DB_PASSWORD: AgilePostgres2026!
    networks:
      - agile-services-network
    restart: unless-stopped
networks:
  agile-services-network:
    external: true
    name: agile-services-network
```

### Dopo aver creato il servizio — obbligatorio

1. Aggiungere riga in `/projects/agile-services/SERVICES.md`
2. Aggiungere `CREATE DATABASE trpg_character_db;` in `init-postgres.sql`
3. Creare `README.md` con documentazione API
4. Aggiornare `/projects/agile-services/progetto.md`

---

## 9. Strategia Database Multi-Tenant

| Modalità | Usare quando | Isolamento |
|---------|-------------|-----------|
| **Shared** | Startup, tenant piccoli | `tenant_code` column in ogni tabella |
| **Dedicated** | Enterprise, compliance | DB separato per tenant |
| **Hybrid** | Mix di piani | Shared per small, dedicated per enterprise |

La modalità viene scelta al setup del tenant tramite `create-tenant.sh`.

---

## 10. Comandi Claude Code

```
//ms-list          Lista tutti i microservizi con status
//ms-status        Health check di tutti i microservizi in esecuzione
//ms-create        Wizard per creare un nuovo microservizio
//tenant-create    Crea un nuovo tenant (con pre-flight checks)
//wizard           Wizard configurazione microservizio specifico
```

---

## 11. Checklist Integrazione Nuovo Progetto

- [ ] Infrastruttura avviata (`docker-compose up -d` nella cartella infra)
- [ ] Tenant creato con `create-tenant.sh` — registrato nel DB, non solo in JSON
- [ ] API key salvata nel `.env` del progetto
- [ ] Letti `SERVICES.md` e `progetto.md` per capire cosa esiste già
- [ ] Microservizi necessari avviati (ognuno nella propria cartella)
- [ ] Eventuali nuovi MS creati con porte 4200+
- [ ] Nuovi MS documentati in `SERVICES.md` e `progetto.md`
- [ ] Credenziali sensibili salvate in `vault-ms`, non in `.env`
- [ ] `GET /health` implementato su ogni nuovo servizio
- [ ] Test coverage >= 70%

---

## 12. Riferimenti Rapidi

| Documento | Percorso |
|-----------|---------|
| Registry completo servizi | `/projects/agile-services/SERVICES.md` |
| Stato progetto e decisioni | `/projects/agile-services/progetto.md` |
| Infrastructure docker-compose | `/projects/agile-services/infrastructure/docker-compose/` |
| Init MySQL (tenant + core DB) | `infrastructure/docker-compose/init-databases.sql` |
| Init PostgreSQL (marketing DB) | `infrastructure/docker-compose/init-postgres.sql` |
| Script crea tenant | `/projects/agile-services/scripts/create-tenant.sh` |
| Script crea microservizio | `/projects/agile-services/scripts/create-microservice.sh` |

**Supporto**: dev@agile.software | Slack: #agile-services

---

*Agile Technology SRL — © 2026 — Tutti i diritti riservati*
*Versione 1.1 — Aggiornato: 2026-02-17*