> ## 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

# Constrói a tua primeira funcionalidade

Um percurso de ponta a ponta, do esquema ao ecrã publicado.

## Passo a passo para iniciantes

Pré-requisitos: Leia os dois guias para iniciantes abaixo, conclua a configuração local da Web e abra este monorepo na raiz do seu editor. As configurações da Web pertencem a `apps/web/.env.local`; Next.js não lê a raiz `.env`. `/dashboard` no modo falso padrão é uma demonstração sem banco de dados; `/auth` precisa de um banco de dados migrado.

Termos rápidos: um espaço de trabalho consiste em usuários, dados e configurações separados de uma equipe. O servidor é o back-end confiável; mantenha as chaves do provedor fora do navegador e do código do telefone. Uma migração é uma alteração de versão do banco de dados que cria ou atualiza tabelas. Um modelo de IA é o mecanismo que responde; o catálogo de modelos é a lista do servidor de IDs e preços de modelos disponíveis. Um provedor é um serviço externo, como IA, e-mail ou serviço de cobrança. Um direito é uma concessão que permite que um espaço de trabalho use um recurso. Um webhook é uma mensagem que um serviço envia para o URL de outro serviço.

1. Abra o VS Code na raiz do repositório e peça ao seu agente de codificação para criar `apps/web/app/reports/page.tsx` e `apps/web/src/reports.ts`. Forneça a ele os campos do relatório e as funções permitidas; exigem verificações de associação no servidor e uma consulta filtrada por `workspaceId`.

2. Abra `/reports` como membro conectado e confirme apenas se os registros do espaço de trabalho aparecem.

3. Experimente uma conta desconectada e uma conta de segundo espaço de trabalho; se algum deles puder ler os registros, pare e corrija a verificação do servidor.

Para código personalizado, comece com o `prompts/README.md` fornecido e copie o prompt mais próximo: `prompts/new-app-screen.md` para uma tela de aplicativo ou `prompts/new-landing-page.md` para uma página pública. Para trabalho de servidor, banco de dados ou provedor, dê ao seu agente de codificação a tarefa deste guia e peça-lhe para ler `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e espelhos `.ai/` correspondentes; inspecione os arquivos de origem exatos nomeados aqui; listar arquivos e verificações antes de editar; preservar a propriedade do espaço de trabalho e os segredos apenas do servidor; e mostrar a diferença. Informe o comportamento desejado, campos de entrada e saída, funções permitidas, sucessos e erros esperados e a conta de teste, provedor ou dispositivo. Use valores de amostra; nunca cole um segredo real.

[Antes de começar](https://supastack.dev/pt/docs/web/before-you-start.md)

[Noções básicas sobre terminais](https://supastack.dev/pt/docs/web/terminal-basics.md)

[Configuração local da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md)

[Avisos do agente e memória do projeto](https://supastack.dev/pt/docs/web/agents.md)


## Crie a rota

Adicione uma página abaixo de `apps/web/app/`. Comece no painel ou na rota de conteúdo para reutilizar sua sessão e a resolução do espaço de trabalho ativo. Existe uma rota quando sua pasta contém `page.tsx`; use um componente de servidor para leituras protegidas.

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


## Resolver propriedade no servidor

Leia a identidade conectada e o espaço de trabalho ativo por meio dos auxiliares de autenticação/espaço de trabalho existentes. Verifique a associação antes de carregar os registros. Filtre cada consulta pelo `workspaceId` resolvido; nunca obtenha um identificador de proprietário de um formulário ou saída de modelo.

Verifique as permissões de proprietário/administrador para ações de gerenciamento. Quando um recurso é pago, verifique seu direito no limite de leitura ou ação antes de retornar dados protegidos; um botão oculto não impõe acesso.


## Verifique o acesso e a recuperação

Teste o acesso anónimo, um membro válido, um membro de outro espaço de trabalho, uma sessão revogada e a função necessária. Adicione estados de carregamento vazio e com falha com uma ação de recuperação. Mantenha a rota fora do mapa do site público e adicione seu prefixo às proibições de robôs.

[Isolamento do espaço de trabalho](https://supastack.dev/pt/docs/web/security.md)

[Verificações de direitos](https://supastack.dev/pt/docs/web/setup-payments.md)


## Modela o registo

Todo o registo de produto começa no esquema da base de dados. Adiciona uma tabela em packages/db com uma coluna workspaceId, gera a migração e escreve os helpers de repositório que resolvem o workspace antes de ler ou escrever.

```
// 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
```


## Autoriza a ação

Cria uma server action que resolve a sessão, o workspace e o entitlement por essa ordem. Valida a entrada com um esquema zod, corre a mutação através do repositório e devolve um resultado tipado que a interface consegue renderizar.

A ordem importa: uma mutação que escreve antes de verificar a propriedade do workspace já cruzou a fronteira. Deriva a propriedade no servidor — nunca confies num workspace id enviado pelo browser.


## Compõe a superfície

Constrói a página a partir de componentes e tokens partilhados — os blocks do kit e os primitivos ui-web cobrem os padrões comuns. Trata estados de loading, erro e vazio; uma funcionalidade que só renderiza o caminho feliz não está terminada.


## Seguinte

[Desenvolva com um agente de codificação](https://supastack.dev/pt/docs/web/agents.md)