first

2026-09-08 07:21:34 -04:00
commit a4b224da8e
169 changed files with 27483 additions and 0 deletions
@@ -0,0 +1,395 @@
+# ASF — Guida Primi Passi (Solo Frontend 🎨)
+
+> **ASF = Azurian Software Factory** · *SaaS Platform multi-tenant AI-native*
+>
+> **Motto**: *"From Requirement to Production — everything is contextualized, traceable and AI-accessible."*
+>
+> **Principio centrale**: ***Everything is an Artifact*** — requisiti, task, PR, commit, build, test, deploy, incidenti, analisi AI, segnalazioni di sicurezza: tutto è un Artifact ASF collegato da Relazioni semantiche.
+
+Questa guida usa **solo il browser** (frontend Next.js su `http://localhost:3000`) — zero curl, zero chiamate API a mano.
+L'obiettivo è insegnarti a **usare ASF dal punto di vista dell'utente finale**: navigare le pagine, filtrare i dati, ispezionare gli artifact nel loro contesto, marcare i code smell come risolti, sottomettere job asincroni da UI, interrogare l'AI sul grafo.
+
+---
+
+## 0. Prerequisito (1 comando solo per popolare dati)
+
+ASF MVP non ha ancora (in questa release) le pagine "Create Organization / Create Project / Create Artifact / Create Relationship via form frontend.
+Per avere dati reali con cui giocare nel browser, lancia **UNA SOLA VOLTA** questo comando dal terminale (seed demo):
+```bash
+cd /root/ASF && make seed-clean
+```
+
+Questo comando (wrapper `scripts/seed-demo.sh --clean --jobs`) fa per te:
+1. Crea Organization demo + Project demo
+2. Popola 21 artifact (Requirements / Task / PR / Build / Deploy / Test / Docs / Commits / Security findings / Incidents / Source files / Code smells)
+3. Crea 9 relazioni semantiche
+4. In coda 5 job echo (devops / testing / code analysis) per provare la pagina Jobs
+5. Mostra un report finale: `Artifacts totali / Jobs counts / Graph nodes·edges`
+
+Poi avvia il frontend (se non già attivo):
+```bash
+make start
+```
+
+Controlla che tutto sia vivo:
+```bash
+make status
+```
+
+Quando vedi `asf-core :8000 UP · asf-web :3000 UP · asf-worker ALIVE` puoi iniziare.
+
+**Apri il browser**: `http://localhost:3000`
+
+---
+
+## 🧭 Concetti Chiave da Sapere (prima di cliccare)
+
+```
+Organization (il tuo Team) → Project → Artifact ← Relationship → Artifact
+```
+
+- **Artifact (17 tipi)**: requirement, epic, story, task, architecture_decision, document, source_file, commit, pull_request, build, test, security_finding, deployment, release, runtime_event, incident, ai_analysis.
+- **Relationship (12 predicati semantici)**: implements / verifies / generated_from / documented_by / deployed_as / caused_by / related_to …
+- **Tutto è cliccabile**: un nodo nel grafo → apre il dettaglio Context. Una riga in tabella → apre il dettaglio. Un badge ID → apre il dettaglio.
+- **Isolamento per Tenant**: il frontend MVP usa dev-trust headers (t-demo-003 / u-mario) già iniettati per te, quindi tutte le pagine mostrano solo i dati del tuo progetto demo.
+
+---
+
+## 🏠 Pagina 1: Overview Dashboard (`/`)
+
+### Cosa vedi
+9 cards in alto (da Bootstrap Prompt §9) + numeri veri:
+
+| Card | Come interpretarla |
+|---|---|
+| Project Health % | Media pesata: req coverage + deploy success + security backlog. Oggi: **94.5%** ✅ |
+| Requirements count · per status | Quanti requisiti ci sono? Aperti / In progress / Chiusi |
+| Implementation Coverage | Requisiti con ≥1 task collegati |
+| Test Coverage | % PR / Deploy con ≥1 test che li "verifica" |
+| Traceability Completeness | Quanti artifact hanno catene complete Req→Task→PR→Test→Deploy |
+| Deployments last 7d | Quanti deploy · rate di successo |
+| Active AI Jobs | Coda attiva: queued / running · usage ultima ora |
+| Failed Builds last 7d | Build fallite |
+| Security Findings OPEN | Conteggio per severità: CRITICAL/red · HIGH/amber · MEDIUM/brand · LOW/neutral |
+
+### Cosa fare
+- **Click sul numero Projects**: ti salta alla pagina **Requirements** (prossima).
+- **Click su Security Findings**: ti salta a **Code Analysis** per vedere gli smell aperti.
+- **Click su Jobs**: vai a **Jobs (Activity)**.
+
+---
+
+## 📋 Pagina 2: Requirements (`/requirements`)
+
+### Header in alto
+Titolo + 4 strumenti di filtraggio + 1 pulsante:
+1. **Search field** (ricerca libera per external_id, title, content)
+2. **Project filter** (tutti o 1 progetto specifico)
+3. **Status filter** (open / in_progress / done / fixed / resolved)
+4. **Type filter** (requirement / epic / story / task / document)
+5. **🆕 New Requirement** — ⚠️ *placeholder UI*: in questa MVP non si può creare requirement da form. Usare il make seed per aggiungere nuovi record.
+
+### Tabella Sticky Header
+| Colonna | Cosa mostra |
+|---|---|
+| ID | external_id monospace (REQ-103) | badge + badge tipo (REQ / colorato |
+| Title | titolo lungo artifact |
+| Status | Badge tone (amber=open · brand=in_progress · green=fixed · blue=active) |
+| Project | nome progetto NON-UUID (es. "ASF SaaS MVP" invece di UUID) |
+| Source | product-board / jira / github / pytest / argo / etc. |
+| Updated | data relativa "2h fa / 3d fa |
+
+### Cosa fare (esercizio 2 clic)
+1. Scrivi nella Search: `SSO` → filtra subito i requirements che matchano title/content.
+2. Status filter = `Open`.
+3. **Click sulla riga REQ-103**. → **ti porta automaticamente a Context Explorer con REQ-103 selezionato**.
+   Questo è il pattern ASF: **ogni riga è un link diretto al contesto.
+
+---
+
+## 🔍 Pagina 3: Context Explorer (`/context`) — IL CUORE DI ASF
+
+Questa è la pagina più potente. **5 tab** per 5 modi diversi di vedere lo STESSO artifact selezionato.
+
+### Layout
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ Artifact Picker (SX)          │  Contenuto Destra (Tabs 1 di 5)      │
+│ Search x project                  │                                   │
+│ ┌────────────────────────────┐│                                   │
+│ │ - REQ-103  ← selezionato ││  [Metadata] [Relationships]       │
+│ │ - TASK-101                 ││  [Related 2-hop] [Graph ⭐]        │
+│ │ - PR#88                    ││  [History timeline]                │
+│ │ - BUILD-910 / DEP-44 ...  ││                                   │
+│ └────────────────────────────┘│                                   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Tab 1 — Metadata (Informazioni statiche
+- **Title · external_id · type · status · version · source · created_at · updated_at
+- Griglia 2x2: Version / Source / Created / Updated
+- Source preview `<pre>` bg-slate-900 mono (se è un source_file o un content lungo)
+- Side card destra: **Remediation** (per i code smell) + **Traceability** (collegamenti rapidi)
+
+### Tab 2 — Relationships (Liste dirette)
+- **Outgoing** (edge uscenti: cosa è questo artifact → altri)
+- **Incoming** (edge entranti: altri artifact → questo)
+- Ogni riga mostra badge `relationship_type` + target title + external_id clickable
+
+### Tab 3 — Related (2-hop)
+Tutti i vicini a **2 salti** (artifact direttamente collegati + i loro collegati). Utile per:
+"Se modifico REQ-103, cosa viene influenzato indirettamente?"
+- 2 gruppi Hop1 e Hop2 con badge di profondità, colore distinto
+
+### Tab 4 — GRAPH (3 anelli concentrici) ⭐ IL PIÙ BELLO
+Vedi il tuo artifact **al centro**, poi hop1 → hop2.
+- **Layout radiale**:
+  - 🟦 Centro → artifact selezionato · bordo indigo + badge SELECTED
+  - 🟣 Anello interno (R1 = 220px di raggio · bordo violetto · pillola **HOP1**
+  - ⬜ Anello esterno (R2 = R1+220+ ~ raggio · bordo slate · pillola **HOP2**)
+- **Edges a 2 livelli visivi:
+  - Tier 1 (Sel↔Hop1): **SOLIDO 2.1px** colore REL_COLORS
+  - Tier 2 (Hop1↔Hop2): **TRATTEGGIATO strokeDasharray + opacity 0.78
+- **11 colori per tipo relazione** (legenda in alto a destra: implements/verifies/generated_from/deployed_as/documented_by/related_to/caused_by …)
+- Controlli: drag per spostare, scroll zoom, pulsanti Controls in basso a SX, **MiniMap** colori per layer (indigo / violet / slate)
+
+**Clicca QUALSIASI nodo** nel grafo**:
+→ Context si sposta il centro e ricentra sul nuovo artifact!**
+
+### Tab 5 — History Timeline
+Eventi ordinati per data:
+- 🟣 created_at CREATED viola
+- 🔵 updated_at UPDATED blu
+- 🟢 version_bump VERSION verde
+- 🟠 rel_added / relationship creazione edge arancione
+
+---
+
+## 🧠 Esercizio Pratico Context (3 click!)
+1. Nel Picker SX clicca **SEC-025 (security finding SQL injection severity=high
+2. Vai in Tab **Related → vedi il nodo SEC-025 e "related_to PR#88
+3. Vai in Tab **Graph** → vedi SEC al centro · RELATED_TO PR (edge slate · Hop1
+4. Click PR → **Clicca il nodo PR#88 nel graph** → Ora PR#88 è il nuovo centro
+5. Tab RELATED del PR → vedi tutti i 2-hop: TASK · BUILD · TEST · DEP · COMMIT · DOC...
+
+Questo è il "perché del progetto: capire l'impatto a cascata.
+
+---
+
+## 💻 Pagina 4: Code Analysis (`/code`)
+
+Analisi di codice + code smells. **2 useQuery separate TanStack (source_file e ai_analysis.kind=code_smell).
+
+### 6 Filtri (Client Side)
+1. **Search** libera (title · external_id · remediation · source_path)
+2. **Scope**: `All / Source / Smells`
+3. **Language**: `All / python / ts / java`
+4. **Severity** (solo smells): `Critical / High / Medium / Low`
+5. **Status**: `All / open / in_progress / fixed / resolved
+6. **Project**: `All / ASF SaaS MVP`
+
+### 5 StatCards in alto
+1. Source files caricati
+2. Smells trovati
+3. Criticali (Badge rosso AlertOctagon)
+4. Alti (Badge amber AlertTriangle)
+5. Medi+Bassi
+
+### Tabella Righe
+Riga = 1 artifact (può essere source_file O smell.
+
+### DetailView (click sulla riga)
+Apre pannello info 2 colonne:
+```
+┌──────────────────────────────────────┬──────────────────────────────┐
+│ <Source preview pre>                 │ Info 2x2                     │
+│ linguaggio color syntax                  │ version / source / created /     │
+│ linee evidenziate in ROSE se linesToHighlight │ Remediation suggerita  │
+│ (righe colpevoli di codice)              │ Traceability              │
+│                                    │ Status badge severity:                  │
+│                                    │  │
+│                                    │ ⭐ BUTTON "Mark as fixed"     │
+└──────────────────────────────────────┴──────────────────────────────┘
+```
+
+### ⭐ AZIONE PRINCIPALE: **Mark as Fixed (PATCH status=fixed)
+Prima devi selezionare un **smell** (source files non hanno il tasto).
+
+**Procedura (5 step click!):
+1. Filtra Severity = **High**
+2. Click la riga **CS-003 pytype ASF-SEC-203 (source consumer.py lines 8-16
+3. Dettaglio sulla DX → in alto header un bottone verde **Mark as fixed
+4. Click → Attendi ~300ms
+5. Sparisce il pulsante → appare un Badge **🟢 Resolved**
+
+**Cosa succede dietro le quinte? useMutation `markFixedM`:
+1. `PATCH /artifacts/:id { status: "fixed" }`
+2. `onSuccess`: **invalidateQueries(["code-source", "code-smells"]
+3. TanStack ricarica le 2 query (tabella si aggiorna automaticamente
+
+Verifica visiva: torna nel filtro Status = fixed → il tuo smell è in fixed!
+
+---
+
+## 🧬 Pagina 5: Traceability Graph (/)
+**Grafo GLOBALE del progetto intero** (Context Graph solo di 1 artifact.
+
+### Cosa vedilaid out
+- Layout layered DAG React Flow
+- **21 nodes · 9 edges demo seed)
+- Nodi colorati per tipo artifact type (color map 11 colori)
+- refetchInterval 5s auto-aggiorna)
+- Pannello Inspector a DX:
+  - **selezionato: seleziona
+  - **Title · ID · Project
+  - **Relationships dirette
+
+### Esercizio Trace (2 click!)
+1. Click il nodo arancione **INC-77 (incidente login failure)
+2. Guarda Inspector **caused_by DEP-44
+3. Click DEP-44 → Inspector deployed_as → BUILD → generated_from PR → implements → task → REQ-103 → Questo è il ciclo completo.
+
+---
+
+## 🚀 Pagina 6: Jobs (Activity) (/)
+TUTTI i job. Auto-refresh ogni **3s** (non devi ricarica la pagina manualmente).
+
+### 6 StatCards in alto
+Queued / Running / Completed / Failed / Cancelled / Total
+
+### Tabella
+| Colonna | Cosa |
+|---|---|
+| Job ID | ID corto UUID+ clickable |
+| Title | titolo descrittivo |
+| Queue | code DIRECT pill devops/testing/code_analysis/... |
+| Status | Badge tone |
+| Worker | asf-worker-1 o quale macchina |
+| Priority | 0-100 |
+| Usage ms | tempo CPU time 42ms |
+| Cost | USD estimate (demo |
+| Updated | relativo "4s fa · 1m fa |
+| Actions | |
+
+### ⭐ Creare un Job da UI (Form completo) (useMutation submitM + Modal
+1. In alto a DX click **Enqueue job** → Apre **MODALE DIALOG 720w
+2. Compila il form (7 campi):
+   a. **Queue* (select): ai.interactive / ai.background / indexing / code_analysis / testing / devops / notifications
+   b. **Job Type** (stesso nome queue)
+   c. **Title** (campo libero)
+   d. Priority** (0-100)
+   e. Correlation ID (opzionale)
+   f. Payload** (editor JSON validato - se JSON invalido → disable button, 422 fallback
+   g. Notes (opzionale)
+3. Click **Enqueue** (in basso a DX pulsante primario Submit 2 pulsanti Cancel · Submit!)
+→ Dopo 2 modal si chiude · useMutation:
+   - `onSuccess: 1. POST /jobs/submit
+   - 2. invalidateQueries(["jobs"])
+   - 3. setFilters resetta filtri → Tabella si aggiorna **new job diventa Queued Poi in ~3 secondi lo vede il worker → Running → **Completed** (echo handler demo)
+
+### Detail Modal (Click sulla riga Job)
+- **JSON completo del job`:
+```
+{ id, title, status, queue, payload, priority, created_at, started_at, completed_at, result, usage, error, worker_id, correlation_id, metadata }
+```
+- Progress 0-100:
+  - queued/cancelled: 0%
+  - running = progressivo
+  - completed = 100%, failed 100% rosso
+- Meta pills Queue / Status
+- Actions: View similar (precompila la modale Enqueue)
+
+---
+
+## 🤖 Pagina 7: Ask ASF (AI Chat) (`/ask-asf`)
+
+Chat UI stile ChatGPT.
+
+### Layout
+```
+┌──────────────────────────────┬─────────────────────────────────────┐
+│ Sidebar DX:               │ Bolle chat SX                       │
+│ · 🔍 Context Scope          │ 👤 Utente                       │
+│ · (source_context=true            │ 🤖 AI Risposta                  │
+│ · include_relationships=true  │ [box digitando…                 │
+│ · max_depth 2                │                                    │
+│ · max_nodes 50               │                                    │
+│ · send_trace                   │ Prompt input + enter send + shift enter newline │
+│ · clear chat              │                                    │
+└──────────────────────────────┴─────────────────────────────────────┘
+```
+
+### Flusso completo (passo per passo utente)
+1. Scrivi nel prompt:
+   > *"Cosa causa l'incidente INC-77? Traccia la catena fino al requirement originario, e suggerisci 2 azioni di rimozione"*
+2. **Invia con Enter (Shift+Enter = newline nel testo
+3. 👤 La tua bolla appare subito (azzurra)
+4. 202 accepted → gear rotante "In attesa di risposta dall'AI..." (polling every 2s · max 120 itera 2 minuti
+5. Appena il job status=COMPLETED 🟢
+6. 🤖 AI Answer: pickAnswer legge `job.result.message/answer/summary/response/text`
+7. **JobMeta pills**: queue=ai.interactive status=completed timestamp
+8. **Copy**: icona Copy → clipboard
+9. **Clear**: icona Clear
+10. Prompt ancora una domanda diversa
+
+### MVP attuale
+Senza provider LLM attivo → **fallback del AI Gatewa.
+**Tutto il resto è FUNZIONANTE
+- 202 accettato 2
+- 02:
+- : 00 iterato
+- Risposta renderizzata in bolla
+- Context sidebar & Scope pills + History multiple domande
+
+---
+
+## 🧾 Cheat Sheet: Pagine & Azioni Frontend (Riepilogo)
+
+| Pagina Route | Come ci arrivi dalla Sidebar | Cosa ci fai |
+|---|---|---|
+| `/` | 🏠 Overview | 9 cards KPIs · dashboard generale |
+| `/settings` | ⚙️ Settings | **Crea Org (slug regex 3-60)** · **Crea Proj (key A-Z 2-20)** · tabelle lista |
+| `/requirements` | 📋 Requirements | Cerca · filtra · **pulsante "New Requirement" modale form completo** · click riga → Context |
+| `/context` | 🔍 Context | **pulsante "New Artifact" (17 tipi!)** · **pulsante "Link" (12 rel. types!)** · Ispeziona 5 Tabs · Graph 3 anelli · click nodi ricentra |
+| `/code` | 💻 Code Analysis | Filtra smells · **Click riga smell → "Mark as fixed" |
+| `/traceability` | 🧬 Trace | Grafo globale · Click nodo → Inspector |
+| `/jobs` | 🚀 Jobs (Activity) | **Modale "Enqueue job" form completo** · Detail JSON modal |
+| `/ask-asf` | 🤖 Ask ASF (AI) | Fai domande sul grafo · 202 + poll · Chat |
+
+---
+
+## ✅ Stato Copertura Frontend vs API
+
+Tutte le operazioni CRUD principali **ora hanno UI** (0 comandi curl necessari):
+
+| Operazione | UI nel frontend? | Dove la trovi |
+|---|---|---|
+| Creare Organization | ✅ | **/settings → "New organization" |
+| Creare Project | ✅ | **/settings → "New project" |
+| Creare Requirement | ✅ | **/requirements → pulsante "New Requirement" |
+| Creare Artifact GENERICO (17 tipi: task, epic, story, commit, source_file, ai_analysis, deployment, incident, security_finding, …) | ✅ | **/context → pulsante **"New Artifact" |
+| Creare Relazioni tra artifact (12 tipi: implements, verifies, generated_from, documented_by, depends_on, deployed_as, caused_by, related_to, …) | ✅ | **/context → pulsante **"Link"** |
+| Upload source code smell | ✅ | Context → New Artifact → `type=ai_analysis` + metadata `{"kind":"code_smell","severity":"high"}` |
+| Mark smell come fisso | ✅ | /code → DetailView → **Mark as fixed** |
+| Sottomettere Job | ✅ | /jobs → Modale **Enqueue job** completo |
+| Interrogare AI grafo | ✅ | /ask-asf → Chat UI 202 + poll |
+
+---
+
+## ✅ Checklist Primo Progetto Frontend (solo click, ZERO curl)
+
+- [ ] Stack attivo: `make seed-clean` + `make start` + `make status` → **UP (tutti verdi)
+- [ ] /settings → **New organization**: fill name=NuovaOrg, slug=nuova-org-001 (3-60 lowercase+dash), plan=Free → **Submit → riga apparsa in tabella Organizations ✅
+- [ ] /settings → **New project**: fill name="Demo Proj 1", key="DEMO1" (A-Z 2-20), branch=main → Submit → riga apparsa Projects tabella ✅
+- [ ] /requirements → **pulsante "New Requirement" → fill Title="SSO Login OK", Project=DEMO1, Content="Login with Okta/OAuth2", Status=backlog → Create → apparsa in lista ✅
+- [ ] /requirements → Cerca "SSO" + click riga → Context
+- [ ] /context → **New Artifact**: Type=task · Title="Implementa Okta middleware" · External_id="TASK-900" · Project=DEMO1 · Status=todo → Create → selezionata in picker ✅ (17 tipi artifact!)
+- [ ] /context → **Link** pulsante: Source=REQ (il SSO appena creato) · Type=implements · Target=Task900 (search "Okta" filter) → Create Relationship → Tab "Relationships" mostra implements→ task 🔗
+- [ ] /context → Graph 3 anelli: hop0 (centro) · hop1 (solid task) · hop2 (dashed se esistevano) → Click nodo task (si ricentra) ✅
+- [ ] /code → Filtro Severity High → riga CS-003 → click → **Mark as fixed" → Badge 🟢 Resolved ✅
+- [ ] /traceability → Click nodo INC-77 → Inspector caused_by DEP-44 → Click DEP → chain completa
+- [ ] /jobs → pulsante **Enqueue job → compila form titolo="Smoke test job", queue=testing, priority=normal → Invia → Attesa 3s → Status queued → Running → **Completed 100% ✅
+- [ ] Jobs riga completata → Click → JSON modale Detail 100% completati → Usage result
+- [ ] /ask-asf → Invia domanda: "Quale task implementa il requirement SSO?" → Attendi 202+poll → bolle user e AI → Copy clipboard ✅
+- [ ] `make tsc` → 0 errors
+- [ ] `make test` → 12+6+8+7+4 = 37/37 ✅ GREEN