AdminGit2026/nis2-agile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4bd2326910
nis2-agile/agile-services-istructio.md

14 KiB
Raw Blame History

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.

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:

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

# 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

# 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.

# 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.

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.

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

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.

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.

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.

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.

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:

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

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

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

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