pagasis/docs/DESARROLLO.md

Guía de Desarrollo - Sistema de Asistencia MAC

Esta guía describe cómo configurar y usar el entorno de desarrollo con todas las herramientas de calidad de código, testing y análisis.

Índice

1. Configuración del Entorno
2. Herramientas de Desarrollo
3. Testing con Tox
4. Acceso a PostgreSQL
5. Comandos Útiles
6. Flujo de Trabajo

---

Configuración del Entorno

Requisitos Previos

• Docker y Docker Compose instalados
• Git
• Puerto 80 (nginx), 5432 (PostgreSQL) disponibles

Iniciar Entorno de Desarrollo

Opción 1: Usando docker-compose.dev.yml (Recomendado para desarrollo)

# Construir e iniciar todos los servicios
docker-compose -f docker-compose.dev.yml up --build

# En modo detached (segundo plano)
docker-compose -f docker-compose.dev.yml up -d --build

Opción 2: Usando docker-compose.yml (Producción)

docker-compose up --build

Diferencias entre Entornos

Característica	docker-compose.yml (Producción)	docker-compose.dev.yml (Desarrollo)
Servidor	Gunicorn (3 workers)	Django runserver
Herramientas dev	❌ No incluidas	✅ Tox, pytest, linters, etc.
Puerto PostgreSQL	✅ Expuesto (5432)	✅ Expuesto (5432)
Debugging	❌ Limitado	✅ ipdb, logging detallado
Volúmenes	Solo static/media	Código completo montado
Hot reload	❌ No	✅ Sí (Django runserver)

---

Herramientas de Desarrollo

Instaladas en el Contenedor

El archivo backend/requirements-dev.txt incluye:

Linting y Formateo

• flake8 - Verificador de estilo PEP8
• pycodestyle - Verificador de estilo PEP8
• autopep8 - Corrector automático de PEP8
• black - Formateador de código opinionado
• isort - Ordenador de imports

Análisis Estático

• pylint - Analizador de código estático
• mccabe - Complejidad ciclomática
• radon - Métricas de código

Type Checking

• mypy - Verificador de tipos estáticos
• django-stubs - Type stubs para Django
• djangorestframework-stubs - Type stubs para DRF

Seguridad

• bandit - Verificador de seguridad
• safety - Verificador de vulnerabilidades

Testing

• pytest - Framework de testing
• pytest-django - Plugin pytest para Django
• pytest-cov - Cobertura de tests
• coverage - Herramienta de cobertura
• factory-boy - Factories para testing

Testing Automation

• tox - Automatización de testing multi-entorno

Utilidades

• django-extensions - Extensiones útiles para Django
• ipython - Shell interactivo mejorado
• ipdb - Debugger interactivo
• pre-commit - Framework de pre-commit hooks

---

Testing con Tox

Tox automatiza testing en múltiples entornos. Configurado en backend/tox.ini.

Entornos Disponibles

# Entrar al contenedor backend
docker-compose -f docker-compose.dev.yml exec backend bash

# Ver todos los entornos disponibles
tox -l

Salida esperada:

py311-django52
test
test-fast
lint
format
format-check
type-check
security
security-full
coverage
coverage-report
metrics
complexity
docs
clean

Ejecutar Tests

Tests completos con cobertura:

docker-compose -f docker-compose.dev.yml exec backend tox -e py311-django52

Tests rápidos (sin cobertura):

docker-compose -f docker-compose.dev.yml exec backend tox -e test-fast

Solo tests unitarios:

docker-compose -f docker-compose.dev.yml exec backend tox -e test -- -m unit

Solo tests de integración:

docker-compose -f docker-compose.dev.yml exec backend tox -e test -- -m integration

Linting y Formateo

Ejecutar linters (flake8 + pylint):

docker-compose -f docker-compose.dev.yml exec backend tox -e lint

Verificar formato (sin modificar):

docker-compose -f docker-compose.dev.yml exec backend tox -e format-check

Formatear código automáticamente:

docker-compose -f docker-compose.dev.yml exec backend tox -e format

Type Checking

Verificar tipos con mypy:

docker-compose -f docker-compose.dev.yml exec backend tox -e type-check

Análisis de Seguridad

Escaneo de seguridad básico:

docker-compose -f docker-compose.dev.yml exec backend tox -e security

Escaneo completo (genera reportes JSON):

docker-compose -f docker-compose.dev.yml exec backend tox -e security-full

Cobertura de Código

Generar reporte de cobertura:

docker-compose -f docker-compose.dev.yml exec backend tox -e coverage

Ver reporte en consola:

docker-compose -f docker-compose.dev.yml exec backend tox -e coverage-report

Reporte HTML se genera en backend/htmlcov/index.html

Métricas de Código

Complejidad ciclomática y mantenibilidad:

docker-compose -f docker-compose.dev.yml exec backend tox -e metrics

Solo complejidad (con promedio):

docker-compose -f docker-compose.dev.yml exec backend tox -e complexity

Limpieza

Eliminar archivos generados:

docker-compose -f docker-compose.dev.yml exec backend tox -e clean

Ejecutar Todos los Entornos

Ejecutar todos los chequeos:

docker-compose -f docker-compose.dev.yml exec backend tox

⚠️ Nota: Esto puede tardar varios minutos.

---

Acceso a PostgreSQL

Desde tu Laptop (Host)

El puerto 5432 está expuesto en ambos entornos (producción y desarrollo).

Credenciales por defecto:

• Host: localhost
• Puerto: 5432
• Database: mac_attendance
• Usuario: mac_user
• Password: mac_password_2024_secure

Con psql (línea de comandos)

psql -h localhost -p 5432 -U mac_user -d mac_attendance

Con pgAdmin

1. Abrir pgAdmin
2. Crear nueva conexión:
   • Name: MAC Attendance
   • Host: localhost
   • Port: 5432
   • Database: mac_attendance
   • Username: mac_user
   • Password: mac_password_2024_secure

Con DBeaver / DataGrip

Similar a pgAdmin, usar las credenciales arriba.

Desde el Contenedor Backend

# Entrar al contenedor backend
docker-compose -f docker-compose.dev.yml exec backend bash

# Conectarse a PostgreSQL
psql -h db -U mac_user -d mac_attendance

Comandos Útiles de PostgreSQL

Listar tablas:

\dt

Describir tabla:

\d authentication_student

Ver tamaño de base de datos:

SELECT pg_size_pretty(pg_database_size('mac_attendance'));

Ver conexiones activas:

SELECT * FROM pg_stat_activity;

Contar registros:

SELECT COUNT(*) FROM authentication_student;
SELECT COUNT(*) FROM events_event;
SELECT COUNT(*) FROM attendance_attendance;

---

Comandos Útiles

Gestión de Contenedores

Ver logs en tiempo real:

docker-compose -f docker-compose.dev.yml logs -f backend
docker-compose -f docker-compose.dev.yml logs -f db

Entrar al contenedor backend:

docker-compose -f docker-compose.dev.yml exec backend bash

Ejecutar comando Django:

docker-compose -f docker-compose.dev.yml exec backend python manage.py <comando>

Crear superusuario:

docker-compose -f docker-compose.dev.yml exec backend python manage.py createsuperuser

Hacer migraciones:

docker-compose -f docker-compose.dev.yml exec backend python manage.py makemigrations
docker-compose -f docker-compose.dev.yml exec backend python manage.py migrate

Django shell:

docker-compose -f docker-compose.dev.yml exec backend python manage.py shell

Django shell_plus (con django-extensions):

docker-compose -f docker-compose.dev.yml exec backend python manage.py shell_plus

Backup y Restore

Backup de base de datos:

docker-compose -f docker-compose.dev.yml exec db pg_dump -U mac_user mac_attendance > backup_$(date +%Y%m%d).sql

Restaurar backup:

cat backup.sql | docker-compose -f docker-compose.dev.yml exec -T db psql -U mac_user mac_attendance

---

Flujo de Trabajo

1. Desarrollo de Nueva Funcionalidad

# 1. Iniciar entorno de desarrollo
docker-compose -f docker-compose.dev.yml up -d

# 2. Crear rama de feature
git checkout -b feature/nueva-funcionalidad

# 3. Desarrollar (los cambios se reflejan automáticamente)
# Editar archivos en backend/ o frontend/

# 4. Ejecutar tests mientras desarrollas
docker-compose -f docker-compose.dev.yml exec backend tox -e test-fast

# 5. Verificar formato antes de commit
docker-compose -f docker-compose.dev.yml exec backend tox -e format-check

# 6. Formatear código si es necesario
docker-compose -f docker-compose.dev.yml exec backend tox -e format

# 7. Ejecutar linters
docker-compose -f docker-compose.dev.yml exec backend tox -e lint

# 8. Verificar tipos
docker-compose -f docker-compose.dev.yml exec backend tox -e type-check

# 9. Verificar seguridad
docker-compose -f docker-compose.dev.yml exec backend tox -e security

# 10. Ejecutar suite completa antes de commit
docker-compose -f docker-compose.dev.yml exec backend tox

2. Debugging

Con ipdb:

# En tu código Python
import ipdb; ipdb.set_trace()

Luego:

docker-compose -f docker-compose.dev.yml up
# El contenedor se pausará en el breakpoint

Ver logs detallados:

docker-compose -f docker-compose.dev.yml logs -f backend

3. Testing

# Tests rápidos durante desarrollo
docker-compose -f docker-compose.dev.yml exec backend pytest

# Con cobertura
docker-compose -f docker-compose.dev.yml exec backend pytest --cov=.

# Solo una app
docker-compose -f docker-compose.dev.yml exec backend pytest authentication/

# Solo un archivo
docker-compose -f docker-compose.dev.yml exec backend pytest authentication/tests/test_models.py

# Solo una función de test
docker-compose -f docker-compose.dev.yml exec backend pytest authentication/tests/test_models.py::test_student_creation

4. Antes de Hacer Commit

Checklist:

• Tests pasan: tox -e test
• Código formateado: tox -e format
• Linters limpios: tox -e lint
• Type checking OK: tox -e type-check
• Sin vulnerabilidades: tox -e security
• Cobertura > 80%: tox -e coverage

Ejecutar todo de una vez:

docker-compose -f docker-compose.dev.yml exec backend tox

5. Pre-commit Hooks (Opcional)

Para automatizar chequeos antes de cada commit:

# Dentro del contenedor backend
docker-compose -f docker-compose.dev.yml exec backend bash

# Instalar hooks
pre-commit install

# Ejecutar manualmente
pre-commit run --all-files

---

Solución de Problemas

"Database does not exist"

docker-compose -f docker-compose.dev.yml down -v
docker-compose -f docker-compose.dev.yml up -d

"Port 5432 already in use"

Cambiar el puerto en docker-compose.dev.yml:

ports:
  - "5433:5432"  # Usar puerto 5433 en host

"Permission denied" en archivos

# Dentro del contenedor
chown -R $(whoami) /app

Limpiar todo y empezar de nuevo

docker-compose -f docker-compose.dev.yml down -v
docker system prune -a
docker volume prune
docker-compose -f docker-compose.dev.yml up --build

---

Recursos Adicionales

• Documentación de Django
• Documentación de Django REST Framework
• Documentación de Tox
• Documentación de pytest
• PostgreSQL Docs

---

Fecha de Creación

Octubre 15, 2025

---

Nota: Este documento describe el entorno de desarrollo completo con todas las herramientas de calidad de código, testing y análisis integradas.