Construye tu primera funcionalidad

Guía paso a paso para principiantes

Requisitos previos: lea las dos guías para principiantes a continuación, finalice la configuración local web y abra este monorepo en la raíz de su editor. La configuración web pertenece a apps/web/.env.local; Next.js no lee la raíz .env. /dashboard en el modo falso predeterminado es una demostración sin base de datos; /auth necesita una base de datos migrada.

Términos breves: un espacio de trabajo son los usuarios, datos y configuraciones separados de un equipo. El servidor es el backend confiable; Mantenga las claves del proveedor fuera del código del navegador y del teléfono. Una migración es un cambio de base de datos versionada que crea o actualiza tablas. Un modelo de IA es el motor que responde; el catálogo de modelos es la lista del servidor de ID de modelos disponibles y precios. Un proveedor es un servicio externo, como inteligencia artificial, correo electrónico o servicio de facturación. Un derecho es una concesión que permite que un espacio de trabajo utilice una función. Un webhook es un mensaje que un servicio envía al URL de otro servicio.

1. Abra VS Code en la raíz del repositorio y solicite a su agente de codificación que cree apps/web/app/reports/page.tsx y apps/web/src/reports.ts. Dale los campos del informe y los roles permitidos; requieren comprobaciones de membresía del lado del servidor y una consulta filtrada por workspaceId.

2. Abra /reports como miembro registrado y confirme que solo aparezcan los registros del espacio de trabajo.

3. Pruebe con una cuenta cerrada y una cuenta de segundo espacio de trabajo; Si cualquiera de ellos puede leer los registros, detenga y corrija la verificación del servidor.

Para obtener código personalizado, comience con el prompts/README.md proporcionado y copie el mensaje más cercano: prompts/new-app-screen.md para una pantalla de aplicación o prompts/new-landing-page.md para una página pública. Para trabajos de servidor, base de datos o proveedor, asigne a su agente de codificación la tarea de esta guía y pídale que lea AGENTS.md, .ai/PROJECT_CONTEXT.md y los espejos .ai/ correspondientes; inspeccionar los archivos fuente exactos nombrados aquí; enumerar archivos y verificaciones antes de editarlos; preservar la propiedad del espacio de trabajo y los secretos exclusivos del servidor; y mostrarte la diferencia. Dígale el comportamiento que desea, los campos de entrada y salida, los roles permitidos, los éxitos y errores esperados y la cuenta, proveedor o dispositivo de prueba. Utilice valores de muestra; Nunca pegues un verdadero secreto.

• Antes de comenzar
• Conceptos básicos de terminales
• Configuración local web
• Mensajes del agente y memoria del proyecto

Crea la ruta

Añade una página dentro de apps/web/app/. Parte de la ruta del panel o de contenido para reutilizar la resolución de sesión y del espacio de trabajo activo. Una carpeta se convierte en ruta cuando contiene page.tsx; usa un Server Component para las lecturas 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

Resuelve la propiedad en el servidor

Lee la identidad de la persona que inició sesión y el espacio de trabajo activo mediante los helpers existentes de autenticación y espacios de trabajo. Comprueba la membresía antes de cargar registros. Filtra cada consulta por el workspaceId resuelto; nunca aceptes un identificador de propietario procedente de un formulario o de la salida de un modelo.

Comprueba los permisos de owner/admin para las acciones de gestión. Si una función es de pago, comprueba su derecho en el límite de lectura o acción antes de devolver datos protegidos; ocultar un botón no aplica el control de acceso.

Verifica el acceso y la recuperación

Prueba el acceso anónimo, el de un miembro válido, el de un miembro de otro espacio de trabajo, una sesión revocada y el rol requerido. Añade estados para cargas vacías y fallidas con una acción de recuperación. Mantén la ruta fuera del sitemap público y añade su prefijo a las exclusiones de robots.

• Aislamiento del espacio de trabajo
• Verificaciones de derechos

Modelar el registro

Todo registro de producto empieza en el esquema de base de datos. Añade una tabla en packages/db con una columna workspaceId, genera la migración y escribe los helpers de repositorio que resuelven el workspace antes de leer o escribir.

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

Autorizar la acción

Crea una server action que resuelva la sesión, el workspace y el entitlement en ese orden. Valida la entrada con un esquema zod, ejecuta la mutación a través del repositorio y devuelve un resultado tipado que la interfaz pueda renderizar.

El orden importa: una mutación que escribe antes de comprobar la pertenencia al workspace ya ha cruzado la frontera. Deriva la pertenencia en el servidor — nunca confíes en un id de workspace enviado por el navegador.

Componer la superficie

Construye la página con componentes compartidos y tokens — los blocks y las primitivas ui-web del kit cubren los patrones habituales. Gestiona los estados de carga, error y vacío; una funcionalidad que solo renderiza su camino feliz no está terminada.