# AGENTS.md Este archivo contiene directrices y comandos para agentes de codificación que trabajan en este repositorio. ## Comandos de Build/Lint/Test ```bash # Desarrollo npm run dev # Iniciar servidor de desarrollo (Next.js) # Build y Producción npm run build # Construir para producción npm run start # Iniciar servidor de producción # Calidad de Código npm run lint # Ejecutar ESLint ``` **Nota**: Este proyecto NO tiene comandos de test configurados actualmente. Si se añaden tests, actualiza los scripts en package.json. ## Arquitectura del Proyecto Esta es una aplicación **Next.js 16** con **TypeScript** que sirve como dashboard para gestión de proyectos de Dolibarr. La aplicación utiliza: - **Framework UI**: Componentes shadcn/ui con primitivos Radix UI - **Estilos**: Tailwind CSS con sistema de diseño personalizado - **Gestión de Estado**: React hooks y context - **Integración API**: Cliente personalizado de Dolibarr - **Iconos**: Lucide React - **Fuentes**: Geist Sans y Geist Mono (Google Fonts) - **Layout**: Sistema de Sidebar con SidebarProvider de shadcn/ui ## Guías de Estilo de Código ### Imports y Dependencias ```typescript // 1. Imports de React primero import React from "react"; import { forwardRef } from "react"; // 2. Librerías de terceros (alfabético) import { cva, type VariantProps } from "class-variance-authority"; import { Slot } from "@radix-ui/react-slot"; // 3. Imports internos (usar aliases @/) import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; import { Project } from "@/types/project"; ``` ### Estructura de Componentes ```typescript "use client"; // Añadir para componentes cliente // Imports import { ComponentProps } from "react"; // Types/Interfaces interface ComponentProps { // props aquí } // Funciones helper (si las hay) function helper() { // implementación } // Componente principal export default function Component({ prop }: ComponentProps) { // implementación } ``` ### Directrices TypeScript - **Siempre usar tipos** para props, parámetros de función y valores de retorno - **Preferir interfaces** para formas de objetos, types para unions/primitivos - **Usar tipos genéricos** cuando sea apropiado: `React.FC`, `VariantProps` - **Modo estricto habilitado** - no implicit `any` - **JSX**: Se usa `jsx: "react-jsx"` (NO se requiere importar React en cada archivo) ### Convenciones de Nomenclatura - **Componentes**: PascalCase (`ProjectCard`, `DashboardHeader`) - **Funciones**: camelCase (`getInitials`, `mapDolibarrProject`) - **Constantes**: UPPER_SNAKE_CASE (`STATUS_CONFIG`, `API_BASE_URL`) - **Archivos**: kebab-case (`project-card.tsx`, `dolibarr-client.ts`) - **Types**: PascalCase con sufijos descriptivos (`ProjectStatus`, `DolibarrProject`) ### Patrones de Componentes shadcn/ui ```typescript // Usar cva para estilos con variantes const buttonVariants = cva( "clases-base", { variants: { variant: { default: "clases-variante", // otras variantes }, }, defaultVariants: { variant: "default", }, } ); // Forward ref para componentes composables const Component = React.forwardRef( ({ className, ...props }, ref) => { return (
); } ); Component.displayName = "Component"; ``` ### Directrices de Estilos - **Usar clases Tailwind** para todos los estilos - **Enfoque utility-first** - evitar CSS personalizado cuando sea posible - **Diseño responsivo**: prefijos `sm:`, `md:`, `lg:`, `xl:` - **Estilos de estado**: prefijos `hover:`, `focus:`, `disabled:` - **Usar utilidad cn()** para fusionar clases condicionalmente - **Design tokens**: Usar propiedades CSS custom de `globals.css` - **Colores importantes del proyecto**: - Gradientes: `from-blue-500 to-purple-600` (estilo principal) - Estados: gris (borrador), azul (abierto), rojo/verde (cerrado) ### Manejo de Errores ```typescript // Llamadas API - lanzar errores, manejar en el sitio de llamada export async function apiCall() { const res = await fetch(url); if (!res.ok) { console.error("API Error:", res.status, await res.text()); throw new Error("API request failed"); } return res.json(); } // Componentes - manejar errores graciosamente try { const data = await apiCall(); // renderizar datos } catch (error) { console.error("Failed to load data:", error); // renderizar estado de error o fallback } ``` ### Organización de Archivos ``` / ├── app/ # Next.js app router │ ├── layout.tsx # Layout principal con SidebarProvider │ ├── page.tsx # Página principal │ ├── globals.css # Estilos globales y variables CSS │ └── favicon.ico # Favicon ├── components/ # Componentes React │ ├── ui/ # Componentes shadcn/ui │ │ ├── button.tsx │ │ ├── card.tsx │ │ ├── badge.tsx │ │ ├── avatar.tsx │ │ ├── sidebar.tsx │ │ ├── sheet.tsx │ │ ├── tooltip.tsx │ │ ├── dropdown-menu.tsx │ │ ├── input.tsx │ │ ├── skeleton.tsx │ │ └── separator.tsx │ ├── dashboard/ # Componentes de feature │ │ ├── project-dashboard.tsx │ │ ├── project-grid.tsx │ │ ├── project-card.tsx │ │ ├── stats-overview.tsx │ │ └── dashboard-header.tsx │ └── app-sidebar.tsx # Sidebar principal de la app ├── hooks/ # Custom React hooks │ └── use-mobile.tsx # Hook para detectar mobile ├── lib/ # Utilidades, clientes API │ ├── dolibarrClient.ts # Cliente base de Dolibarr │ ├── projectsService.ts # Servicio de proyectos │ ├── usersService.ts # Servicio de usuarios │ └── utils.ts # Utilidades generales (cn, etc) ├── types/ # Definiciones de tipos TypeScript │ └── project.ts # Tipos de Proyecto, mappers, helpers ├── public/ # Activos estáticos └── node_modules/ # Dependencias ``` ### Path Aliases Configurados en `tsconfig.json`: - `@/*` → `./*` (todos los paths desde raíz) Ejemplos de uso: ```typescript import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; import { Project } from "@/types/project"; import { getProjects } from "@/lib/projectsService"; ``` ### Integración API (Dolibarr) #### Cliente Base El archivo `lib/dolibarrClient.ts` proporciona la función base: ```typescript export async function dolibarrFetch(endpoint: string, options: RequestInit = {}) ``` #### Variables de Entorno - **OBLIGATORIAS**: Usar `NEXT_PUBLIC_*` para acceso client-side - `NEXT_PUBLIC_API_URL` - URL base de la API de Dolibarr - `NEXT_PUBLIC_DOLIBARR_API_KEY` - API key de Dolibarr #### Servicios - **projectsService.ts**: Funciones para obtener y mapear proyectos - `getProjects()`: Obtiene proyectos en formato UI - `getDolibarrProjects()`: Obtiene datos crudos de Dolibarr - `getProjectById(id)`: Obtiene proyecto específico - **usersService.ts**: Funciones para gestión de usuarios #### Transformación de Datos - **Tipos**: `DolibarrProject` (API) → `Project` (UI) - **Mapper**: `mapDolibarrProject()` en `types/project.ts` - **Importante**: Los timestamps de Dolibarr vienen en segundos (multiplicar x1000 para Date) #### Estados de Proyecto ```typescript type ProjectStatus = '0' | '1' | '2'; // 0: borrador, 1: validado/abierto, 2: cerrado // Configuración de estados con helpers export const STATUS_CONFIG: Record string }> // Helper para obtener clases de color export function getStatusColorClasses(status: ProjectStatus): string ``` ### Directrices de Rendimiento - **Imports dinámicos**: Usar `next/dynamic` para componentes pesados - **Optimización de imágenes**: Usar componente Next.js Image - **Análisis de bundle**: Verificar tamaño con `npm run build` - **Memoización**: Usar `React.memo()` para componentes costosos - **"use client"**: Añadir SOLO cuando sea necesario (interactividad, hooks, eventos) ### Accesibilidad - **HTML semántico**: Usar elementos apropiados (`