From 8003aa2a55e7754b87b5e43fd1120eceb69eef70 Mon Sep 17 00:00:00 2001 From: Levi Planelles Date: Wed, 28 Jan 2026 11:26:20 +0100 Subject: [PATCH] add/update AGENTS.md --- AGENTS.md | 376 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 267 insertions(+), 109 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5acf2a9..62676a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,102 +1,105 @@ # AGENTS.md -This file contains guidelines and commands for agentic coding agents working in this repository. +Este archivo contiene directrices y comandos para agentes de codificación que trabajan en este repositorio. -## Build/Lint/Test Commands +## Comandos de Build/Lint/Test ```bash -# Development -npm run dev # Start development server (Next.js) +# Desarrollo +npm run dev # Iniciar servidor de desarrollo (Next.js) -# Build & Production -npm run build # Build for production -npm run start # Start production server +# Build y Producción +npm run build # Construir para producción +npm run start # Iniciar servidor de producción -# Code Quality -npm run lint # Run ESLint +# Calidad de Código +npm run lint # Ejecutar ESLint ``` -**Note**: This project does not have test commands configured. If tests are added, update the scripts in package.json. +**Nota**: Este proyecto NO tiene comandos de test configurados actualmente. Si se añaden tests, actualiza los scripts en package.json. -## Project Architecture +## Arquitectura del Proyecto -This is a **Next.js 16** application with **TypeScript** that serves as a dashboard for Dolibarr project management. The app uses: +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: -- **UI Framework**: shadcn/ui components with Radix UI primitives -- **Styling**: Tailwind CSS with custom design system -- **State Management**: React hooks and context -- **API Integration**: Custom Dolibarr client -- **Icons**: Lucide React +- **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 -## Code Style Guidelines +## Guías de Estilo de Código -### Imports & Dependencies +### Imports y Dependencias ```typescript -// 1. React imports first +// 1. Imports de React primero import React from "react"; import { forwardRef } from "react"; -// 2. Third-party libraries (alphabetical) +// 2. Librerías de terceros (alfabético) import { cva, type VariantProps } from "class-variance-authority"; import { Slot } from "@radix-ui/react-slot"; -// 3. Internal imports (use @/ aliases) +// 3. Imports internos (usar aliases @/) import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; import { Project } from "@/types/project"; ``` -### Component Structure +### Estructura de Componentes ```typescript -"use client"; // Add for client components +"use client"; // Añadir para componentes cliente // Imports import { ComponentProps } from "react"; // Types/Interfaces interface ComponentProps { - // props here + // props aquí } -// Helper functions (if any) +// Funciones helper (si las hay) function helper() { - // implementation + // implementación } -// Main component +// Componente principal export default function Component({ prop }: ComponentProps) { - // implementation + // implementación } ``` -### TypeScript Guidelines +### Directrices TypeScript -- **Always use types** for props, function parameters, and return values -- **Prefer interfaces** for object shapes, types for unions/primitives -- **Use generic types** when appropriate: `React.FC`, `VariantProps` -- **Strict mode enabled** - no implicit `any` +- **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) -### Naming Conventions +### Convenciones de Nomenclatura -- **Components**: PascalCase (`ProjectCard`, `DashboardHeader`) -- **Functions**: camelCase (`getInitials`, `mapDolibarrProject`) -- **Constants**: UPPER_SNAKE_CASE (`STATUS_CONFIG`, `API_BASE_URL`) -- **Files**: kebab-case (`project-card.tsx`, `dolibarr-client.ts`) -- **Types**: PascalCase with descriptive suffixes (`ProjectStatus`, `DolibarrProject`) +- **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`) -### shadcn/ui Component Patterns +### Patrones de Componentes shadcn/ui ```typescript -// Use cva for variant styling +// Usar cva para estilos con variantes const buttonVariants = cva( - "base-classes", + "clases-base", { variants: { variant: { - default: "variant-classes", - // other variants + default: "clases-variante", + // otras variantes }, }, defaultVariants: { @@ -105,8 +108,8 @@ const buttonVariants = cva( } ); -// Forward ref for composable components -const Component = forwardRef( +// Forward ref para componentes composables +const Component = React.forwardRef( ({ className, ...props }, ref) => { return (
( Component.displayName = "Component"; ``` -### Styling Guidelines +### Directrices de Estilos -- **Use Tailwind classes** for all styling -- **Utility-first approach** - avoid custom CSS when possible -- **Responsive design**: `sm:`, `md:`, `lg:`, `xl:` prefixes -- **State styling**: `hover:`, `focus:`, `disabled:` prefixes -- **Use cn() utility** for conditional class merging -- **Design tokens**: Use CSS custom properties from `globals.css` +- **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) -### Error Handling +### Manejo de Errores ```typescript -// API calls - throw errors, handle at call site +// Llamadas API - lanzar errores, manejar en el sitio de llamada export async function apiCall() { const res = await fetch(url); if (!res.ok) { @@ -142,87 +148,239 @@ export async function apiCall() { return res.json(); } -// Components - handle errors gracefully +// Componentes - manejar errores graciosamente try { const data = await apiCall(); - // render data + // renderizar datos } catch (error) { console.error("Failed to load data:", error); - // render error state or fallback + // renderizar estado de error o fallback } ``` -### File Organization +### Organización de Archivos ``` -src/ -├── app/ # Next.js app router -├── components/ # React components -│ ├── ui/ # shadcn/ui components -│ └── dashboard/ # Feature components -├── hooks/ # Custom React hooks -├── lib/ # Utilities, API clients -├── types/ # TypeScript type definitions -└── public/ # Static assets +/ +├── 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 -Use these configured path aliases: -- `@/components` → `./components` -- `@/lib` → `./lib` -- `@/hooks` → `./hooks` -- `@/utils` → `./lib/utils` -- `@/ui` → `./components/ui` +Configurados en `tsconfig.json`: +- `@/*` → `./*` (todos los paths desde raíz) -### API Integration +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"; +``` -- **Environment variables**: Use `NEXT_PUBLIC_*` for client-side access -- **Dolibarr client**: Use `dolibarrFetch()` from `@/lib/dolibarrClient` -- **Data transformation**: Map API responses to UI types using helper functions -- **Error boundaries**: Implement error handling for API failures +### Integración API (Dolibarr) -### Performance Guidelines +#### Cliente Base +El archivo `lib/dolibarrClient.ts` proporciona la función base: +```typescript +export async function dolibarrFetch(endpoint: string, options: RequestInit = {}) +``` -- **Dynamic imports**: Use `next/dynamic` for heavy components -- **Image optimization**: Use Next.js Image component -- **Bundle analysis**: Check bundle size with `npm run build` -- **Memoization**: Use `React.memo()` for expensive components +#### 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 -### Accessibility +#### 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 -- **Semantic HTML**: Use appropriate elements (`