add/update AGENTS.md

2026-01-28 11:26:20 +01:00 · 2026-01-28 11:26:20 +01:00 · 8003aa2a55
parent 51e6c4cad0
commit 8003aa2a55
1 changed files with 267 additions and 109 deletions
--- 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<Props>`, `VariantProps<T>`
- **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<Props>`, `VariantProps<T>`
+- **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<HTMLDivElement, ComponentProps>(
+// Forward ref para componentes composables
+const Component = React.forwardRef<HTMLDivElement, ComponentProps>(
  ({ className, ...props }, ref) => {
    return (
      <div
@ -120,19 +123,22 @@ const Component = forwardRef<HTMLDivElement, ComponentProps>(
 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 (`<button>`, `<nav>`, etc.)
- **ARIA attributes**: Add when needed for screen readers
- **Keyboard navigation**: Ensure all interactive elements are keyboard accessible
- **Focus management**: Handle focus in modals and dropdowns
+#### 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)

-## Development Workflow
+#### Estados de Proyecto
+```typescript
+type ProjectStatus = '0' | '1' | '2'; // 0: borrador, 1: validado/abierto, 2: cerrado

-1. **Start development**: `npm run dev`
-2. **Run linter**: `npm run lint` (fix any errors before committing)
-3. **Build test**: `npm run build` (ensure production build works)
-4. **Type checking**: TypeScript is strict - fix all type errors
+// Configuración de estados con helpers
+export const STATUS_CONFIG: Record<ProjectStatus, { label: string; getColorClasses: () => string }>

-## Key Dependencies
+// 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 (`<button>`, `<nav>`, etc.)
+- **Atributos ARIA**: Añadir cuando sea necesario para screen readers
+- **Navegación por teclado**: Asegurar que todos los elementos interactivos sean accesibles
+- **Gestión de foco**: Manejar foco en modales y dropdowns
+- **shadcn/ui**: Ya incluye muchas prácticas de accesibilidad por defecto
+
+### Componentes Específicos del Proyecto
+
+#### ProjectCard
+- Muestra información de un proyecto con avatar, estado, progreso, presupuesto
+- Usa gradientes `from-blue-500 to-purple-600`
+- Estados con colores específicos (ver `StatusBadge`)
+- Formato de fechas: `toLocaleDateString('es-ES')`
+- Formato de moneda: `toLocaleString('es-ES')` con símbolo €
+
+#### Layout Principal
+- Usa `SidebarProvider`, `SidebarInset`, `SidebarTrigger`
+- AppSidebar personalizado
+- Fuentes Geist Sans y Geist Mono con variables CSS
+- Idioma: español (lang="es" recomendado, actualmente "en")
+
+#### Patrones de Estado
+- Componentes internos para badges con clases directas (evitar dynamic classes)
+- Usar condicionales explícitos para estilos dinámicos de Tailwind
+
+## Flujo de Trabajo de Desarrollo
+
+1. **Iniciar desarrollo**: `npm run dev`
+2. **Ejecutar linter**: `npm run lint` (corregir errores antes de commit)
+3. **Test de build**: `npm run build` (asegurar que el build de producción funciona)
+4. **Type checking**: TypeScript está en modo estricto - corregir todos los errores de tipo
+
+## Dependencias Clave
+
+### Dependencias Principales
 - **Next.js**: 16.0.7 (App Router)
 - **React**: 19.2.0
+- **React DOM**: 19.2.0
 - **TypeScript**: 5.x
- **Tailwind CSS**: 3.4.18 + tailwindcss-animate
- **Radix UI**: Headless components for accessibility
- **Lucide React**: Icon library
- **shadcn/ui**: Component library built on Radix UI

-## Environment Variables
+### UI y Estilos
+- **Tailwind CSS**: 3.4.18
+- **tailwindcss-animate**: 1.0.7
+- **class-variance-authority**: 0.7.1 (cva)
+- **clsx**: 2.1.1
+- **tailwind-merge**: 3.4.0

-Required environment variables (create `.env.local`):
- `NEXT_PUBLIC_API_URL` - Dolibarr API base URL
- `NEXT_PUBLIC_DOLIBARR_API_KEY` - Dolibarr API key
+### Componentes UI (Radix UI)
+- **@radix-ui/react-avatar**: 1.1.11
+- **@radix-ui/react-dialog**: 1.1.15
+- **@radix-ui/react-dropdown-menu**: 2.1.16
+- **@radix-ui/react-separator**: 1.1.8
+- **@radix-ui/react-slot**: 1.2.4
+- **@radix-ui/react-tooltip**: 1.2.8
+
+### Iconos
+- **lucide-react**: 0.556.0
+
+### DevDependencies
+- **@tailwindcss/postcss**: 4
+- **@types/node**: 20
+- **@types/react**: 19
+- **@types/react-dom**: 19
+- **autoprefixer**: 10.4.22
+- **eslint**: 9
+- **eslint-config-next**: 16.0.7
+- **postcss**: 8.5.6
+
+## Variables de Entorno
+
+Crear archivo `.env.local` en la raíz con:
+```bash
+NEXT_PUBLIC_API_URL=https://tu-dolibarr-url.com/api/index.php
+NEXT_PUBLIC_DOLIBARR_API_KEY=tu-api-key-aqui
+```

 ## Testing

-No test framework is currently configured. Recommended setup:
- Add Jest/Vitest for unit tests
- Add React Testing Library for component tests
- Add Playwright/Cypress for E2E tests
- Update package.json with test scripts
+**Estado actual**: NO hay framework de testing configurado.
+
+**Recomendaciones** si se añaden tests:
+- Jest o Vitest para tests unitarios
+- React Testing Library para tests de componentes
+- Playwright o Cypress para tests E2E
+- Actualizar package.json con scripts de test
+
+## Notas Importantes para Agentes
+
+### Al Crear Nuevos Componentes
+1. Verificar si existe componente shadcn/ui similar
+2. Usar `"use client"` solo si necesita interactividad
+3. Seguir estructura de imports y naming conventions
+4. Usar TypeScript estricto con todas las props tipadas
+5. Aplicar `cn()` para clases condicionales
+
+### Al Modificar Componentes Existentes
+1. Respetar el patrón de estilos existente (Tailwind utility-first)
+2. Mantener consistencia con gradientes y colores del proyecto
+3. No romper la estructura del layout (SidebarProvider)
+4. Probar con `npm run build` antes de finalizar
+
+### Al Trabajar con la API Dolibarr
+1. Usar siempre `dolibarrFetch()` del cliente base
+2. Mapear datos con funciones helper en `types/project.ts`
+3. Manejar errores apropiadamente con try/catch
+4. Recordar que timestamps vienen en segundos
+
+### Al Añadir Nuevas Dependencias
+1. Verificar compatibilidad con Next.js 16 y React 19
+2. Preferir paquetes de Radix UI para componentes UI
+3. Actualizar este documento con nuevas dependencias clave
+4. Ejecutar `npm install` y verificar que no haya conflictos
+
+### Idioma y Localización
+- El proyecto está en **español**
+- Usar formato `es-ES` para fechas y números
+- Símbolo de moneda: `€`
+- Considerar cambiar `lang="en"` a `lang="es"` en layout.tsx
+
+---
+
+**Última actualización**: Enero 2026
+**Versión de Next.js**: 16.0.7
+**Versión de React**: 19.2.0