Guía de Desarrollo

Guía de Desarrollo

Esta guía te ayudará a entender la estructura del proyecto y las mejores prácticas para desarrollar nuevas funcionalidades.

📁 Estructura del Proyecto

src/
├── components/          # Componentes reutilizables (Astro y React)
│   ├── Header.astro    # Navegación principal
│   ├── Footer.astro    # Pie de página
│   ├── Hero.astro      # Sección hero
│   └── ContactForm.tsx # Formulario de contacto React
├── layouts/            # Layouts principales
│   ├── Layout.astro    # Layout base con SEO
│   └── PanelLayout.astro # Layout para paneles de usuario
├── pages/              # Páginas del sitio (routing automático)
│   ├── index.astro     # Página principal
│   ├── api/            # Endpoints de API
│   └── panel/          # Paneles de usuario
├── styles/             # Estilos globales
│   └── global.css      # CSS global con Tailwind
├── utils/              # Utilidades
│   ├── auth.ts         # Autenticación y sesiones
│   ├── turso.ts        # Cliente de base de datos
│   ├── email.ts        # Envío de emails
│   └── sanitize.ts     # Sanitización de inputs
├── hooks/              # Hooks personalizados
│   └── useGSAP.ts      # Hook para animaciones GSAP
├── types/              # Tipos TypeScript
│   └── validation.ts   # Schemas de validación con Zod
└── config/             # Configuración
    └── site.ts         # Configuración del sitio

🛠️ Tecnologías Utilizadas

• Astro: Framework principal para el sitio
• React: Para componentes interactivos
• TypeScript: Para tipado estático
• Tailwind CSS v4: Para estilos
• Turso (LibSQL): Base de datos
• Zod: Validación de esquemas
• bcryptjs: Hash de contraseñas
• Resend: Envío de emails

📝 Convenciones de Código

Naming

• Componentes: PascalCase (Hero.astro, ContactForm.tsx)
• Páginas: kebab-case (about.astro, forgot-password.astro)
• Utilidades: camelCase (getTursoClient, sanitizeEmail)
• Tipos: PascalCase (User, ApiResponse)

Estructura de Archivos

• Usar 2 espacios para indentación
• Trailing commas en objetos y arrays
• TypeScript en modo estricto

🔐 Autenticación

El sistema de autenticación usa:

• Sesiones: Basadas en cookies HTTP-only
• TOTP: Para verificación de email
• bcrypt: Para hash de contraseñas
• Validación: Con Zod schemas

Ver la Guía de Autenticación para más detalles.

📄 Gestión de Documentos

Los documentos se almacenan en Backblaze B2 y se gestionan a través de:

• src/utils/backblaze.ts - Cliente de Backblaze
• src/utils/documentExpiry.ts - Gestión de vencimientos
• src/utils/documentValidation.ts - Validación de documentos

Ver la Guía de Documentos para más detalles.

🧪 Testing

El proyecto incluye:

• Unit tests: Con Vitest
• Integration tests: Para APIs
• E2E tests: Con Playwright

Ejecutar tests:

bun run test          # Unit tests
bun run test:e2e      # E2E tests
bun run test:all      # Todos los tests

🚀 Comandos de Desarrollo

bun run dev          # Servidor de desarrollo (localhost:4321)
bun run build        # Build para producción
bun run preview      # Preview de la build
bun run astro check  # Type checking

📚 Recursos Adicionales

• Guía de Instalación
• Guía de Autenticación
• Guía de Formularios
• Guía de Documentos