levi.2526
/
trello_fake
mirror of https://github.com/LeviPlanelles/trello_fake.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add/update AGENTS.md

This commit is contained in:
Levi Planelles 2026-01-28 11:26:20 +01:00
parent 51e6c4cad0
commit 8003aa2a55
1 changed files with 267 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

372
AGENTS.md
View File

@ -1,102 +1,105 @@
# AGENTS.md # 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 ```bash
# Development # Desarrollo
npm run dev # Start development server (Next.js) npm run dev # Iniciar servidor de desarrollo (Next.js)
# Build & Production # Build y Producción
npm run build # Build for production npm run build # Construir para producción
npm run start # Start production server npm run start # Iniciar servidor de producción
# Code Quality # Calidad de Código
npm run lint # Run ESLint 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 - **Framework UI**: Componentes shadcn/ui con primitivos Radix UI
- **Styling**: Tailwind CSS with custom design system - **Estilos**: Tailwind CSS con sistema de diseño personalizado
- **State Management**: React hooks and context - **Gestión de Estado**: React hooks y context
- **API Integration**: Custom Dolibarr client - **Integración API**: Cliente personalizado de Dolibarr
- **Icons**: Lucide React - **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 ```typescript
// 1. React imports first // 1. Imports de React primero
import React from "react"; import React from "react";
import { forwardRef } 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 { cva, type VariantProps } from "class-variance-authority";
import { Slot } from "@radix-ui/react-slot"; import { Slot } from "@radix-ui/react-slot";
// 3. Internal imports (use @/ aliases) // 3. Imports internos (usar aliases @/)
import { cn } from "@/lib/utils"; import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button"; import { Button } from "@/components/ui/button";
import { Project } from "@/types/project"; import { Project } from "@/types/project";
``` ```
### Component Structure ### Estructura de Componentes
```typescript ```typescript
"use client"; // Add for client components "use client"; // Añadir para componentes cliente
// Imports // Imports
import { ComponentProps } from "react"; import { ComponentProps } from "react";
// Types/Interfaces // Types/Interfaces
interface ComponentProps { interface ComponentProps {
// props here // props aquí
} }
// Helper functions (if any) // Funciones helper (si las hay)
function helper() { function helper() {
// implementation // implementación
} }
// Main component // Componente principal
export default function Component({ prop }: ComponentProps) { export default function Component({ prop }: ComponentProps) {
// implementation // implementación
} }
``` ```
### TypeScript Guidelines ### Directrices TypeScript
- **Always use types** for props, function parameters, and return values - **Siempre usar tipos** para props, parámetros de función y valores de retorno
- **Prefer interfaces** for object shapes, types for unions/primitives - **Preferir interfaces** para formas de objetos, types para unions/primitivos
- **Use generic types** when appropriate: `React.FC<Props>`, `VariantProps<T>` - **Usar tipos genéricos** cuando sea apropiado: `React.FC<Props>`, `VariantProps<T>`
- **Strict mode enabled** - no implicit `any` - **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`) - **Componentes**: PascalCase (`ProjectCard`, `DashboardHeader`)
- **Functions**: camelCase (`getInitials`, `mapDolibarrProject`) - **Funciones**: camelCase (`getInitials`, `mapDolibarrProject`)
- **Constants**: UPPER_SNAKE_CASE (`STATUS_CONFIG`, `API_BASE_URL`) - **Constantes**: UPPER_SNAKE_CASE (`STATUS_CONFIG`, `API_BASE_URL`)
- **Files**: kebab-case (`project-card.tsx`, `dolibarr-client.ts`) - **Archivos**: kebab-case (`project-card.tsx`, `dolibarr-client.ts`)
- **Types**: PascalCase with descriptive suffixes (`ProjectStatus`, `DolibarrProject`) - **Types**: PascalCase con sufijos descriptivos (`ProjectStatus`, `DolibarrProject`)
### shadcn/ui Component Patterns ### Patrones de Componentes shadcn/ui
```typescript ```typescript
// Use cva for variant styling // Usar cva para estilos con variantes
const buttonVariants = cva( const buttonVariants = cva(
"base-classes", "clases-base",
{ {
variants: { variants: {
variant: { variant: {
default: "variant-classes", default: "clases-variante",
// other variants // otras variantes
}, },
}, },
defaultVariants: { defaultVariants: {
@ -105,8 +108,8 @@ const buttonVariants = cva(
} }
); );
// Forward ref for composable components // Forward ref para componentes composables
const Component = forwardRef<HTMLDivElement, ComponentProps>( const Component = React.forwardRef<HTMLDivElement, ComponentProps>(
({ className, ...props }, ref) => { ({ className, ...props }, ref) => {
return ( return (
<div <div
@ -120,19 +123,22 @@ const Component = forwardRef<HTMLDivElement, ComponentProps>(
Component.displayName = "Component"; Component.displayName = "Component";
``` ```
### Styling Guidelines ### Directrices de Estilos
- **Use Tailwind classes** for all styling - **Usar clases Tailwind** para todos los estilos
- **Utility-first approach** - avoid custom CSS when possible - **Enfoque utility-first** - evitar CSS personalizado cuando sea posible
- **Responsive design**: `sm:`, `md:`, `lg:`, `xl:` prefixes - **Diseño responsivo**: prefijos `sm:`, `md:`, `lg:`, `xl:`
- **State styling**: `hover:`, `focus:`, `disabled:` prefixes - **Estilos de estado**: prefijos `hover:`, `focus:`, `disabled:`
- **Use cn() utility** for conditional class merging - **Usar utilidad cn()** para fusionar clases condicionalmente
- **Design tokens**: Use CSS custom properties from `globals.css` - **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 ```typescript
// API calls - throw errors, handle at call site // Llamadas API - lanzar errores, manejar en el sitio de llamada
export async function apiCall() { export async function apiCall() {
const res = await fetch(url); const res = await fetch(url);
if (!res.ok) { if (!res.ok) {
@ -142,87 +148,239 @@ export async function apiCall() {
return res.json(); return res.json();
} }
// Components - handle errors gracefully // Componentes - manejar errores graciosamente
try { try {
const data = await apiCall(); const data = await apiCall();
// render data // renderizar datos
} catch (error) { } catch (error) {
console.error("Failed to load data:", 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 ├── app/ # Next.js app router
├── components/ # React components │ ├── layout.tsx # Layout principal con SidebarProvider
│ ├── ui/ # shadcn/ui components │ ├── page.tsx # Página principal
│ └── dashboard/ # Feature components │ ├── 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 ├── hooks/ # Custom React hooks
├── lib/ # Utilities, API clients │ └── use-mobile.tsx # Hook para detectar mobile
├── types/ # TypeScript type definitions ├── lib/ # Utilidades, clientes API
└── public/ # Static assets │ ├── 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 ### Path Aliases
Use these configured path aliases: Configurados en `tsconfig.json`:
- `@/components` → `./components` - `@/*` → `./*` (todos los paths desde raíz)
- `@/lib` → `./lib`
- `@/hooks` → `./hooks`
- `@/utils` → `./lib/utils`
- `@/ui` → `./components/ui`
### 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 ### Integración API (Dolibarr)
- **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
### 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 #### Variables de Entorno
- **Image optimization**: Use Next.js Image component - **OBLIGATORIAS**: Usar `NEXT_PUBLIC_*` para acceso client-side
- **Bundle analysis**: Check bundle size with `npm run build` - `NEXT_PUBLIC_API_URL` - URL base de la API de Dolibarr
- **Memoization**: Use `React.memo()` for expensive components - `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
- **Semantic HTML**: Use appropriate elements (`<button>`, `<nav>`, etc.) - **usersService.ts**: Funciones para gestión de usuarios
- **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
## Development Workflow #### 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)
1. **Start development**: `npm run dev` #### Estados de Proyecto
2. **Run linter**: `npm run lint` (fix any errors before committing) ```typescript
3. **Build test**: `npm run build` (ensure production build works) type ProjectStatus = '0' | '1' | '2'; // 0: borrador, 1: validado/abierto, 2: cerrado
4. **Type checking**: TypeScript is strict - fix all type errors
## Key Dependencies // 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) - **Next.js**: 16.0.7 (App Router)
- **React**: 19.2.0 - **React**: 19.2.0
- **React DOM**: 19.2.0
- **TypeScript**: 5.x - **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`): ### Componentes UI (Radix UI)
- `NEXT_PUBLIC_API_URL` - Dolibarr API base URL - **@radix-ui/react-avatar**: 1.1.11
- `NEXT_PUBLIC_DOLIBARR_API_KEY` - Dolibarr API key - **@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 ## Testing
No test framework is currently configured. Recommended setup: **Estado actual**: NO hay framework de testing configurado.
- Add Jest/Vitest for unit tests
- Add React Testing Library for component tests **Recomendaciones** si se añaden tests:
- Add Playwright/Cypress for E2E tests - Jest o Vitest para tests unitarios
- Update package.json with test scripts - 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