12 KiB

Raw Permalink Blame History

AGENTS.md

Este archivo contiene directrices y comandos para agentes de codificación que trabajan en este repositorio.

Comandos de Build/Lint/Test

# 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

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

"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

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

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

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:

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

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

Iniciar desarrollo: npm run dev
Ejecutar linter: npm run lint (corregir errores antes de commit)
Test de build: npm run build (asegurar que el build de producción funciona)
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:

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

Verificar si existe componente shadcn/ui similar
Usar "use client" solo si necesita interactividad
Seguir estructura de imports y naming conventions
Usar TypeScript estricto con todas las props tipadas
Aplicar cn() para clases condicionales

Al Modificar Componentes Existentes

Respetar el patrón de estilos existente (Tailwind utility-first)
Mantener consistencia con gradientes y colores del proyecto
No romper la estructura del layout (SidebarProvider)
Probar con npm run build antes de finalizar

Al Trabajar con la API Dolibarr

Usar siempre dolibarrFetch() del cliente base
Mapear datos con funciones helper en types/project.ts
Manejar errores apropiadamente con try/catch
Recordar que timestamps vienen en segundos

Al Añadir Nuevas Dependencias

Verificar compatibilidad con Next.js 16 y React 19
Preferir paquetes de Radix UI para componentes UI
Actualizar este documento con nuevas dependencias clave
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

12 KiB Raw Permalink Blame History

AGENTS.md

Comandos de Build/Lint/Test

Arquitectura del Proyecto

Guías de Estilo de Código

Imports y Dependencias

Estructura de Componentes

Directrices TypeScript

Convenciones de Nomenclatura

Patrones de Componentes shadcn/ui

Directrices de Estilos

Manejo de Errores

Organización de Archivos

Path Aliases

Integración API (Dolibarr)

Cliente Base

Variables de Entorno

Servicios

Transformación de Datos

Estados de Proyecto

Directrices de Rendimiento

Accesibilidad

Componentes Específicos del Proyecto

ProjectCard

Layout Principal

Patrones de Estado

Flujo de Trabajo de Desarrollo

Dependencias Clave

Dependencias Principales

UI y Estilos

Componentes UI (Radix UI)

Iconos

DevDependencies

Variables de Entorno

Testing

Notas Importantes para Agentes

Al Crear Nuevos Componentes

Al Modificar Componentes Existentes

Al Trabajar con la API Dolibarr

Al Añadir Nuevas Dependencias

Idioma y Localización

12 KiB

Raw Permalink Blame History