> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Costruisci la tua prima feature

Un percorso end-to-end dallo schema alla schermata pubblicata.

## Procedura dettagliata per principianti

Prerequisiti: leggi le due guide per principianti di seguito, completa la configurazione locale del Web e apri questo monorepo alla radice nel tuo editor. Le impostazioni Web appartengono a `apps/web/.env.local`; Next.js non legge la radice `.env`. `/dashboard` nella modalità falsa predefinita è una demo senza database; `/auth` necessita di un database migrato.

Termini rapidi: uno spazio di lavoro è costituito da utenti, dati e impostazioni separati di un team. Il server è il backend affidabile; mantenere le chiavi del provider fuori dal browser e dal codice del telefono. Una migrazione è una modifica del database con versione che crea o aggiorna tabelle. Un modello AI è il motore che risponde; il catalogo dei modelli è l'elenco del server degli ID e dei prezzi dei modelli disponibili. Un fornitore è un servizio esterno come un servizio di intelligenza artificiale, posta elettronica o fatturazione. Un diritto è una concessione che consente a un'area di lavoro di utilizzare una funzionalità. Un webhook è un messaggio che un servizio invia allo URL di un altro servizio.

1. Apri VS Code nella root del repository e chiedi al tuo agente di codifica di creare `apps/web/app/reports/page.tsx` e `apps/web/src/reports.ts`. Forniscigli i campi del report e i ruoli consentiti; richiedono controlli di appartenenza lato server e una query filtrata da `workspaceId`.

2. Apri `/reports` come membro che ha effettuato l'accesso e verifica che vengano visualizzati solo i record dell'area di lavoro.

3. Prova un account disconnesso e uno del secondo spazio di lavoro; se uno dei due riesce a leggere i record, interrompere e correggere il controllo del server.

Per il codice personalizzato, inizia con `prompts/README.md` in dotazione e copia il prompt più vicino: `prompts/new-app-screen.md` per la schermata di un'app o `prompts/new-landing-page.md` per una pagina pubblica. Per il lavoro su server, database o provider, assegna al tuo agente di codifica il compito di questa guida e chiedigli di leggere `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e i mirror `.ai/` corrispondenti; controllare gli esatti file sorgente nominati qui; elencare file e controlli prima della modifica; preservare la proprietà dello spazio di lavoro e i segreti solo del server; e mostrarti la differenza. Indicagli il comportamento desiderato, i campi di input e output, i ruoli consentiti, i successi e gli errori previsti e l'account, il fornitore o il dispositivo di prova. Utilizzare valori campione; non incollare mai un vero segreto.

[Prima di iniziare](https://supastack.dev/it/docs/web/before-you-start.md)

[Nozioni di base sui terminali](https://supastack.dev/it/docs/web/terminal-basics.md)

[Configurazione locale Web](https://supastack.dev/it/docs/web/ship-in-5-minutes.md)

[Messaggi dell'agente e memoria del progetto](https://supastack.dev/it/docs/web/agents.md)


## Crea il percorso

Aggiungi una pagina sotto `apps/web/app/`. Inizia dalla dashboard o dal percorso del contenuto in modo da riutilizzarne la sessione e la risoluzione dell'area di lavoro attiva. Una rotta esiste quando la sua cartella contiene `page.tsx`; utilizzare un componente server per le letture protette.

```
apps/web/app/reports/page.tsx
apps/web/src/reports.ts
.ai/apps/web/app/reports/page.md
.ai/apps/web/src/reports.md
```


## Risolvere la proprietà sul server

Leggere l'identità di accesso e l'area di lavoro attiva tramite gli assistenti di autenticazione/area di lavoro esistenti. Verificare l'appartenenza prima di caricare i record. Filtra ogni query in base allo `workspaceId` risolto; non prendere mai un identificatore del proprietario da un modulo o dall'output di un modello.

Controlla le autorizzazioni del proprietario/amministratore per le azioni di gestione. Quando una funzionalità è a pagamento, verificane il diritto al limite di lettura o azione prima di restituire i dati protetti; un pulsante nascosto non impone l'accesso.


## Verificare l'accesso e il ripristino

Testare l'accesso anonimo, un membro valido, un membro di un'altra area di lavoro, una sessione revocata e il ruolo richiesto. Aggiungi gli stati vuoto e di caricamento non riuscito con un'azione di ripristino. Mantieni il percorso fuori dalla mappa del sito pubblica e aggiungi il suo prefisso a robots disallows.

[Isolamento dello spazio di lavoro](https://supastack.dev/it/docs/web/security.md)

[Controlli dei diritti](https://supastack.dev/it/docs/web/setup-payments.md)


## Modella il record

Ogni record di prodotto parte dallo schema del database. Aggiungi una tabella in packages/db con una colonna workspaceId, genera la migrazione e scrivi gli helper di repository che risolvono il workspace prima di leggere o scrivere.

```
// packages/db/src/schema.ts
export const ideas = pgTable("idea", {
  id: uuid().primaryKey(),
  workspaceId: uuid().notNull().references(() => workspaces.id),
  title: text().notNull(),
  createdAt: timestamp().defaultNow(),
});

corepack pnpm --filter @supastack/db db:generate
```


## Autorizza l'azione

Crea una server action che risolve sessione, workspace ed entitlement in quest'ordine. Valida l'input con uno schema zod, esegui la mutazione tramite il repository e restituisci un risultato tipizzato che l'interfaccia può renderizzare.

L'ordine conta: una mutazione che scrive prima di verificare la proprietà del workspace ha già superato il confine. Deriva la proprietà sul server — non fidarti mai di un workspace id inviato dal browser.


## Componi la superficie

Costruisci la pagina da componenti e token condivisi — i block del kit e i primitivi ui-web coprono i pattern comuni. Gestisci gli stati di caricamento, errore e vuoto; una feature che renderizza solo il percorso felice non è finita.


## Successivo

[Costruisci con un agente di codice](https://supastack.dev/it/docs/web/agents.md)