AdminGit2026/nis2-agile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[CORE] Aggiunto integrazione agile-services: istruzioni + CLAUDE.md aggiornato

Browse Source
This commit is contained in:
DFM Dev 2026-02-18 08:05:36 +00:00
parent 52fd45fac9
commit 4bd2326910
2 changed files with 480 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
CLAUDE.md
View File

@ -21,6 +21,22 @@ Target: PMI, Enterprise, Consulenti/CISO.
- VCS: Gitea (git.certisource.it)
- URL Produzione: https://certisource.it/nis2/
## Microservizi Condivisi (agile-services)
**IMPORTANTE**: Questo progetto utilizza i microservizi condivisi di **agile-services**, montati in `/projects/agile-services` (sola lettura).
### Regole di integrazione
1. **Leggere SEMPRE** `agile-services-istructio.md` nella root del progetto per capire come interagire con i servizi
2. **NON modificare** i file in `/projects/agile-services` (montato read-only)
3. I servizi disponibili includono: autenticazione, database, messaging, monitoring, API gateway
4. Le credenziali di accesso ai servizi sono documentate in `agile-services-istructio.md`
5. Ogni nuovo servizio creato per NIS2 deve essere registrato anche in agile-services per essere riutilizzabile
### Accesso
- Path nel container: `/projects/agile-services` (read-only)
- File istruzioni: `./agile-services-istructio.md` (nella root del progetto)
## Regola Fondamentale
Il progetto NIS2 Agile e' COMPLETAMENTE ISOLATO dagli altri applicativi (CertiSource, AGILE_DFM). Database dedicato, utente dedicato, path dedicati. Non condividere MAI credenziali tra applicativi.

464
agile-services-istructio.md Normal file
View File

@ -0,0 +1,464 @@
# 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*