← Dashboard

📘 Istruzioni per Claude

Guida completa per aggiornare, creare e gestire i progetti su sviluppo.mclmedia.eu

1. Cos'è Sviluppo Hub

Sviluppo Hub è il portale centralizzato di MCL Media SRL dove vengono tracciati tutti i progetti in corso. Ogni progetto è un file JSON nella cartella /projects/. Il portale mostra una dashboard con KPI, stato di avanzamento, task completate e prossimi step per ogni progetto.

Questo portale viene aggiornato dagli agenti Claude a fine sessione. Il proprietario è Luca Macaluso.

2. Regola fondamentale

⚠️ REGOLA OBBLIGATORIA: Ad ogni conversazione che tocca un progetto, Claude DEVE proporre di aggiornare sviluppo.mclmedia.eu a fine sessione con la frase: "Aggiorniamo sviluppo.mclmedia.eu?"

Non importa se la sessione è stata breve o lunga. Se si è lavorato su un progetto, va tracciato.

3. Come funziona l'aggiornamento

Claude non può chiamare API esterne direttamente dalla chat (CSP di claude.ai lo impedisce). Il flusso è:

1. Claude lavora con Luca su un progetto

2. A fine sessione, Claude genera un blocco JSON nel formato standard

3. Luca copia il JSON

4. Luca va su sviluppo.mclmedia.eu/aggiorna-progetti.php e lo incolla

5. Clicca "Applica" → il portale si aggiorna istantaneamente

💡 TIP: Il bottone "📝 Aggiorna" nell'header del portale rimanda direttamente alla pagina di aggiornamento.

4. Formato JSON standard

Claude deve sempre generare un unico blocco JSON con un array actions. Ogni azione specifica il tipo di operazione e il progetto target.

Struttura base

{
  "actions": [
    { ... azione 1 ... },
    { ... azione 2 ... },
    { ... azione N ... }
  ]
}

Le azioni disponibili sono 4: add_log, update, update_tasks, create.

4.1 — add_log (aggiungere al changelog)

Aggiunge una entry al changelog del progetto. Usare SEMPRE almeno un add_log per sessione.

{
  "action": "add_log",
  "project": "travel-hub",
  "entry": "Deploy completato per Gallipoli e Vieste con 45 hotel sincronizzati",
  "log_type": "milestone"
}

Valori possibili per log_type:

milestone = traguardo importante (deploy, feature completata, test superato)
update = aggiornamento generico (modifiche, iterazioni, progress)
fix = bug risolto o problema fixato
note = osservazione, decisione presa, informazione da ricordare

4.2 — update (aggiornare campi del progetto)

Merge parziale: aggiorna solo i campi specificati, lasciando intatti gli altri.

{
  "action": "update",
  "project": "travel-hub",
  "data": {
    "progress": 60,
    "status": "attivo",
    "info": {
      "Siti online": "22 regionali + 8 destinazioni",
      "Ultimo deploy": "Gallipoli (08/03/2026)"
    }
  }
}

Campi aggiornabili: name, description, status, progress, priority, owner, tags, tech_stack, info, links, notes, icon, icon_bg.

Valori possibili per status: attivo, in_sviluppo, pianificato, in_pausa, completato, critico.

Valori possibili per priority: alta, media, bassa.

4.3 — update_tasks (aggiornare la lista task)

⚠️ ATTENZIONE: Questo comando SOVRASCRIVE tutte le task del progetto. Devi sempre includere la lista completa (task fatte + da fare). Il progresso viene ricalcolato automaticamente (done / totale × 100). 
{
  "action": "update_tasks",
  "project": "travel-hub",
  "tasks": [
    {"text": "Siti regionali deploy (16+ regioni)", "done": true},
    {"text": "Deploy wizard su base con AI", "done": true},
    {"text": "Deploy Gallipoli e Vieste", "done": true},
    {"text": "Deploy restanti 42 destinazioni", "done": false},
    {"text": "Migrazione su OVH Dedicato", "done": false}
  ]
}
💡 TIP: La home page del portale mostra le ultime 3 task completate e i prossimi 3 step per ogni progetto. Tieni le task aggiornate per avere sempre il quadro chiaro.

4.4 — create (creare un nuovo progetto)

Crea un nuovo progetto. Lo slug deve essere lowercase, solo lettere/numeri/trattini. Se il progetto esiste già, restituisce errore — in quel caso usa update.

{
  "action": "create",
  "project": "nome-progetto",
  "data": {
    "name": "Nome Progetto Visibile",
    "description": "Descrizione breve del progetto",
    "icon": "🆕",
    "icon_bg": "rgba(59,130,246,0.15)",
    "status": "pianificato",
    "priority": "media",
    "progress": 0,
    "owner": "Luca",
    "tags": ["tag1", "tag2"],
    "tech_stack": ["PHP", "Laravel"],
    "info": {
      "URL": "https://...",
      "Server": "IP o hostname"
    },
    "links": [
      {"label": "Sito", "url": "https://...", "icon": "🌐"}
    ],
    "tasks": [
      {"text": "Prima cosa da fare", "done": false}
    ],
    "changelog": [],
    "notes": "Note iniziali sul progetto"
  }
}

Icone suggerite per icon: 🎬 video, ✈️ travel, 📰 content, 🏗 gestionale, 🔗 SEO, 💎 premium, 🏡 immobiliare, 💰 affiliate, 🖥 server, 🧠 sviluppo, 🆕 nuovo.

Colori suggeriti per icon_bg:

Rosso: rgba(239,68,68,0.15) · Blu: rgba(59,130,246,0.15) · Verde: rgba(16,185,129,0.15) · Ambra: rgba(245,158,11,0.15) · Viola: rgba(139,92,246,0.15) · Cyan: rgba(6,182,212,0.15) · Grigio: rgba(107,114,128,0.15)

5. Esempio completo di fine sessione

Scenario: Claude ha lavorato con Luca sul Travel Hub. Ha completato il deploy di Gallipoli, fixato un bug sulle immagini, e discusso il prossimo step (deploy Vieste).

{
  "actions": [
    {
      "action": "add_log",
      "project": "travel-hub",
      "entry": "Deploy Gallipoli completato: 12 hotel, 6 attrazioni, content AI generato. Fix bug cover image che non appariva su mobile.",
      "log_type": "milestone"
    },
    {
      "action": "add_log",
      "project": "travel-hub",
      "entry": "Fix: cover image non visibile su mobile per mancanza di fallback Unsplash",
      "log_type": "fix"
    },
    {
      "action": "update",
      "project": "travel-hub",
      "data": {
        "progress": 62,
        "info": {
          "Server": "VPS OVH 152.228.162.32",
          "Gestionale": "base.mclmedia.eu",
          "Regionali online": "16+",
          "Destinazioni singole": "6 online (Cefalù, Tropea, Taormina, Alberobello, Procida, Gallipoli)",
          "Target": "50 destinazioni",
          "Prossimo deploy": "Vieste"
        }
      }
    },
    {
      "action": "update_tasks",
      "project": "travel-hub",
      "tasks": [
        {"text": "Siti regionali deploy (16+ regioni)", "done": true},
        {"text": "Deploy wizard su base con AI content generation", "done": true},
        {"text": "Sistema task immagini per Salvina", "done": true},
        {"text": "Template single_dest completo", "done": true},
        {"text": "Deploy Cefalù, Tropea, Taormina, Alberobello, Procida", "done": true},
        {"text": "Deploy Gallipoli", "done": true},
        {"text": "Fix cover image mobile", "done": true},
        {"text": "Deploy Vieste", "done": false},
        {"text": "Deploy restanti 43 destinazioni", "done": false},
        {"text": "Migrazione su OVH Dedicato", "done": false},
        {"text": "Integrazione GetYourGuide API", "done": false}
      ]
    }
  ]
}

6. Progetti attivi e relativi slug

Usa sempre lo slug esatto nel campo project. Ecco la lista aggiornata in tempo reale:

SlugProgettoStatoProgresso
child-master-admin-plugin Child Master Admin - Plugin Attivo 78%
worldfilia-affiliate Siti Affiliate Worldfilia Attivo 80%
backly Backly.it — Marketplace Backlink In Sviluppo 41%
gestionale-discover Gestionale Discover Attivo 78%
travel-hub MCL Travel Hub Attivo 55%
sviluppo-hub Sviluppo Hub (sviluppo.mclmedia.eu) Attivo 88%
skyview-cefalu Acquisizione Skyview Cefalù In Sviluppo 45%
video-generator MCL Video Generator Attivo 80%
gestionale-base Gestionale Base (base.mclmedia.eu) Attivo 75%
quickspot QuickSpot — Portale Video Spot AI In Pausa 70%
infrastruttura-server Infrastruttura Server In Sviluppo 30%
portale-premium Portale Premium — Siti di Qualità Pianificato 10%

7. Cosa aggiornare a fine sessione

Checklist per Claude prima di generare il JSON:

✅ SEMPRE: Almeno un add_log con il riassunto della sessione

🔄 SE NECESSARIO:

→ Task completate? Usa update_tasks con la lista completa
→ Progresso cambiato? Usa update con il nuovo valore (oppure update_tasks lo ricalcola automaticamente)
→ Stato cambiato? (es. da pianificato a in_sviluppo) Usa update
→ Nuovi dati tecnici? (server, URL, date) Aggiorna il campo info
→ Informazioni importanti da ricordare? Aggiorna il campo notes
→ Progetto nuovo emerso nella conversazione? Usa create

8. Struttura JSON completa di un progetto

Riferimento per capire tutti i campi disponibili:

{
  "name": "Nome Progetto",
  "description": "Descrizione breve",
  "icon": "🎬",
  "icon_bg": "rgba(239,68,68,0.15)",
  "status": "attivo | in_sviluppo | pianificato | in_pausa | completato | critico",
  "priority": "alta | media | bassa",
  "progress": 0-100,
  "owner": "Luca | Luca + Alessandro | ...",
  "tags": ["tag1", "tag2"],
  "info": {"chiave": "valore", "altra chiave": "altro valore"},
  "tech_stack": ["PHP", "Laravel", "GPT-4o"],
  "links": [{"label": "Nome", "url": "https://...", "icon": "🔗"}],
  "tasks": [
    {"text": "Descrizione task", "done": true},
    {"text": "Task da completare", "done": false}
  ],
  "changelog": [
    {"date": "2026-03-08 12:00", "text": "Cosa è successo", "type": "milestone", "agent": "claude"}
  ],
  "notes": "Note libere, testo multiriga con \\n",
  "created_at": "2026-03-08 00:00:00",
  "updated_at": "auto-generato"
}

9. Errori comuni da evitare

❌ Usare create su un progetto che esiste già → Restituisce errore. Usa update.

❌ Usare update_tasks con solo le task nuove → Sovrascrive TUTTO. Includi sempre la lista completa.

❌ Dimenticare il campo project → Ogni azione deve avere lo slug del progetto target.

❌ Usare slug sbagliati → Controlla la tabella nella sezione 6. Gli slug sono lowercase con trattini.

❌ Generare JSON malformato → Attenzione alle virgole finali, alle virgolette e ai caratteri speciali nelle stringhe. Usa \n per andare a capo nelle note.

❌ Non proporre l'aggiornamento → La regola fondamentale è: se si è lavorato su un progetto, va tracciato. Sempre.

10. File e cartelle del portale

sviluppo.mclmedia.eu/
├── index.php                  ← Dashboard + dettaglio progetto
├── config.php                 ← Helper functions PHP
├── aggiorna-progetti.php      ← Pagina paste JSON per aggiornamenti
├── istruzioni-claude.php      ← Questa pagina
├── README_CLAUDE.md           ← Versione markdown di queste istruzioni
├── api/
│   └── update.php             ← API REST (usabile anche via curl da SSH)
└── projects/
    ├── quickspot.json
    ├── video-generator.json
    ├── travel-hub.json
    ├── gestionale-discover.json
    ├── gestionale-base.json
    ├── backly.json
    ├── portale-premium.json
    ├── skyview-cefalu.json
    ├── worldfilia-affiliate.json
    ├── infrastruttura-server.json
    └── sviluppo-hub.json