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

387 lines
12 KiB
Markdown
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
```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
Reference in New Issue View Git Blame Copy Permalink