396 lines
20 KiB
Markdown
396 lines
20 KiB
Markdown
# 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
|