trello_fake/AGENTS.md

# 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<Props>`, `VariantProps<T>`
- **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<HTMLDivElement, ComponentProps>(
  ({ className, ...props }, ref) => {
    return (
      <div
        className={cn(variantClasses, className)}
        ref={ref}
        {...props}
      />
    );
  }
);
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<ProjectStatus, { label: string; getColorClasses: () => 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 (`<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

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

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

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