netgescon-day0/docs/ai/RUNBOOK.md

NetGescon – RUNBOOK (Linux)

Ambiente

• OS: Ubuntu (VM Proxmox) – host: netgescon-master – IP: 192.168.0.200
• Path progetto: /home/michele/netgescon/netgescon-laravel
• Shell: bash
• Repo: Gitea http://192.168.0.200:3000/ (ssh)

Obiettivo

• Questo file contiene i comandi e le procedure per ripartire velocemente dopo reboot/crash senza rispiegare tutto.

Avvio rapido (checklist)

1. Vai nel progetto: cd /home/michele/netgescon/netgescon-laravel
2. Verifica mount produzione (RO): mount | egrep -i 'gescon-archives|cifs' || true
3. Avvia stack / servizi (scegli in base a come lo usi oggi):
   • Docker: docker compose up -d
   • Nginx/PHP-FPM: sudo systemctl status nginx php8.3-fpm --no-pager
   • MySQL/MariaDB: sudo systemctl status mysql --no-pager
4. App Laravel:
   • php -v ; composer -V
   • php artisan --version

• Avvio server (DEV):
  • VS Code Task: "Start Laravel Server"
  • CLI equivalente: php artisan serve --host=0.0.0.0 --port=8000

VS Code / Prestazioni

• Workspace settings: .vscode/settings.json (exclude watcher/search già impostati)
• IMPORTANT: apri un workspace che punti direttamente a netgescon-laravel.
  • OK: Miki-Bug-workspace/NetGescon-Laravel.code-workspace
  • OK: Miki-Bug-workspace/NetGescon-Development.code-workspace (ora allineato: non punta più alla cartella padre)
  • DA EVITARE: workspace che includono /home/michele/netgescon (troppo grande → indicizzazione/estensioni possono inchiodare VS Code)
• Nota: evitare di indicizzare node_modules/, vendor/, storage/, bootstrap/cache/

Database (DEV/TEST)

• Dove gira il DB di test (scegli una sola verità):
  • Local service: mysql (systemd) oppure container docker
• Comandi utili:
  • Stato: sudo systemctl status mysql --no-pager
  • Connessione: mysql -u <user> -p -h <host> <db>

Produzione (dati in sola lettura)

• Mount RO: /mnt/gescon-archives (CIFS)
• Scopo: leggere dati aggiornati per import/estrazioni
• Verifica rapida:
  • ls /mnt/gescon-archives | head
• Se la share non risponde, NON deve bloccare il boot (automount/timeout configurati)

Estrarre dati (procedura standard)

• Script/entrypoint da usare (scegli e mantieni 1 procedura):
  • ./manage-database.sh <azione>
  • oppure php artisan <comando>
• Esempi (riempi con quelli che usi davvero):
  • Query/estrazione anagrafiche: <TODO>
  • Import dati legacy: <TODO>
  • Verifica integrità: <TODO>

Stato attuale (da aggiornare dopo ogni sessione)

• Ultimo focus:
  • <es: fix X su modulo Y>
• Cose fatte:
  • <bullet>
• Cose da fare:
  • <bullet>
• Decisioni importanti:
  • <bullet>

“Se il sistema salta” (ripartenza)

• 1. fsck solo se serve (initramfs), poi reboot
• 1. controlla mount produzione
• 1. avvia servizi/docker
• 1. apri VS Code e riparti da “Stato attuale”

Continuità chat (anti-blocco contesto)

• La chat può comunque raggiungere un limite di contesto: non si elimina del tutto, ma si evita di perdere il filo con checkpoint brevi.
• Regola pratica: ogni blocco di lavoro importante aggiorna docs/ai/SESSION_HANDOFF.md con:
  • obiettivo corrente,
  • file toccati,
  • comandi reali eseguiti + output sintetico,
  • prossimo step immediato.
• Prompt di ripartenza standard:
  • Riparti da docs/ai/SESSION_HANDOFF.md e continua dal prossimo step senza rieseguire analisi generale.

Regola di utilizzo consigliata

• Evita chat infinite: usa 1 chat per argomento/capitolo.
• Apri una nuova chat quando:
  • chiudi un blocco funzionale,
  • cambi argomento,
  • superi ~80-120 richieste,
  • noti rallentamenti.
• Prima di cambiare chat, esegui sempre task: AI: Continuity Auto (Safe).

Ripartenza veloce

• Esegui task: AI: Restart Brief.
• Fai leggere all'agent in ordine:
  1. docs/ai/SESSION_HANDOFF.md
  2. docs/ai/TOPICS_INDEX.md
  3. docs/ai/LATEST_2_CHATS_RECOVERY.md
  4. docs/ai/topics/<topic>.md
• Per guida completa: docs/ai/START-HERE-AGENT.md