Saltar al contenido principal

Guía de Desarrollo

Guía completa para desarrollar en Floutic, incluyendo flujo de trabajo, mejores prácticas y herramientas útiles.

Flujo de Trabajo Recomendado​

1. Configuración Inicial​

# Clonar el repositorio
git clone https://github.com/floutic/floutic.git
cd floutic

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus configuraciones

# Iniciar el entorno de desarrollo
./start-dev.sh

2. Verificar que Todo Funciona​

# Ver estado de servicios
./status-dev.sh

# Verificar backend
docker compose exec backend curl http://localhost:8000/health

# Verificar frontend
curl http://localhost:3000

3. Desarrollo​

Backend​

  • Hot Reload: Los cambios en backend/ se reflejan automáticamente
  • Logs: docker compose logs -f backend
  • Shell: docker compose exec backend bash

Frontend​

  • Hot Reload: Los cambios en frontend/ se reflejan automáticamente
  • Logs: docker compose logs -f frontend
  • Shell: docker compose exec frontend bash

Documentación​

  • Editar: Archivos en docs-site/docs/
  • Reconstruir: docker compose exec docs npm run build
  • Ver localmente: docker compose exec docs npm run start

4. Testing​

# Tests del backend
./test-dev.sh

# Tests del frontend (unitarios)
./scripts/test_frontend_unit.sh

# Tests E2E
./scripts/test_e2e.sh

# Tests de seguridad
./scripts/test_frontend_security.sh

5. Detener el Entorno​

./stop-dev.sh

Estructura del Proyecto​

floutic/
├── backend/          # API FastAPI
│   ├── app/
│   │   ├── api/v1/endpoints/  # Endpoints de la API
│   │   ├── models/            # Modelos de base de datos
│   │   ├── schemas/            # Esquemas Pydantic
│   │   ├── services/           # Servicios de negocio
│   │   └── core/               # Configuración
│   ├── alembic/                # Migraciones
│   └── tests/                  # Tests
├── frontend/        # Frontend Astro + React
│   ├── src/
│   │   ├── components/    # Componentes React
│   │   ├── pages/        # Páginas Astro
│   │   ├── layouts/      # Layouts
│   │   ├── stores/       # Stores Zustand
│   │   └── lib/          # Utilidades
│   └── tests/            # Tests E2E
├── docs-site/       # Documentación Docusaurus
├── docs/            # Documentación en Markdown
└── scripts/         # Scripts de utilidades

Desarrollo del Backend​

Comandos Útiles​

# Ejecutar migraciones
docker compose exec backend alembic upgrade head

# Crear nueva migración
docker compose exec backend alembic revision --autogenerate -m "descripción"

# Ver logs
docker compose logs -f backend

# Acceder al shell
docker compose exec backend bash

# Ejecutar tests
docker compose exec backend pytest

# Ejecutar tests específicos
docker compose exec backend pytest tests/endpoints/test_projects.py

Crear un Nuevo Endpoint​

  1. Crear el endpoint en backend/app/api/v1/endpoints/
  2. Crear el schema en backend/app/schemas/
  3. Crear el servicio si es necesario en backend/app/services/
  4. Añadir tests en backend/tests/endpoints/
  5. Documentar en Swagger (se genera automáticamente)

Ejemplo de Endpoint​

from fastapi import APIRouter, Depends
from app.schemas.example import ExampleCreate, ExampleResponse
from app.api.deps import get_current_user

router = APIRouter()

@router.post("/examples", response_model=ExampleResponse)
async def create_example(
    example: ExampleCreate,
    current_user: User = Depends(get_current_user)
):
    # Lógica del endpoint
    return {"id": 1, "name": example.name}

Desarrollo del Frontend​

Comandos Útiles​

# Ver logs
docker compose logs -f frontend

# Acceder al shell
docker compose exec frontend bash

# Ejecutar tests unitarios
docker compose exec frontend npm test

# Ejecutar tests E2E
docker compose exec frontend npm run test:e2e

# Build de producción
docker compose exec frontend npm run build

Crear un Nuevo Componente​

  1. Crear el componente en frontend/src/components/features/
  2. Crear tests en frontend/src/components/features/__tests__/
  3. Usar TypeScript y validación Zod
  4. Seguir las convenciones de shadcn/ui

Ejemplo de Componente​

import { useState } from 'react';
import { Button } from '@/components/ui/button';

export const ExampleComponent = () => {
  const [count, setCount] = useState(0);
  
  return (
    <div>
      <p>Count: {count}</p>
      <Button onClick={() => setCount(count + 1)}>
        Increment
      </Button>
    </div>
  );
};

Datos de Prueba​

Actualizar Datos Demo​

# Cargar todos los usuarios de prueba
docker compose exec backend python clean_and_seed.py --scenario full

# Eliminar solo artefactos generados por Playwright (tests E2E)
docker compose exec backend python clean_and_seed.py --scenario e2e

Usuarios Demo Disponibles​

  • 1 Admin: admin / AdminFloutic2024!
  • 10 Expertos: Todos con contraseña Expert123!
  • 5 Empresas: Todas con contraseña Company123!

Ver Actualización de Datos Demo para más detalles.

Debugging​

Backend​

# Ver logs en tiempo real
docker compose logs -f backend

# Acceder a la base de datos
docker compose exec postgres psql -U ${POSTGRES_USER} -d ${POSTGRES_DB}

# Verificar Redis
docker compose exec redis redis-cli

# Ejecutar Python interactivo
docker compose exec backend python

Frontend​

# Ver logs en tiempo real
docker compose logs -f frontend

# Inspeccionar en el navegador
# Abre DevTools en http://localhost:3000

# Verificar build
docker compose exec frontend npm run build

Mejores Prácticas​

Código​

  • TypeScript: Usar tipos estrictos en frontend
  • Validación: Validar inputs con Zod/Pydantic
  • Tests: Escribir tests para nueva funcionalidad
  • Documentación: Documentar funciones y endpoints

Git​

  • Commits: Mensajes descriptivos y en español
  • Branches: Usar nombres descriptivos (feature/nombre, fix/nombre)
  • PRs: Incluir descripción y tests

Testing​

  • Unitarios: Para lógica de negocio
  • E2E: Para flujos críticos
  • Cobertura: Mantener > 80% de cobertura

Recursos Adicionales​

Documentación​

Guías​

Obtener Ayuda​

Si tienes problemas:

  1. Revisa los logs: docker compose logs -f [servicio]
  2. Consulta la documentación específica del componente
  3. Revisa los tests existentes para ejemplos
  4. Abre un issue en GitHub con logs y detalles