💻Guía de Desarrollo - ToLearn

Esta guía proporciona información para desarrolladores que desean contribuir o personalizar ToLearn.

📋 Tabla de Contenidos

🛠️ Configuración del Entorno de Desarrollo

Requisitos

Python 3.10+
PostgreSQL 14+
Redis 6+
Node.js 14+ (opcional)
Git

Instalación Rápida

# 1. Clonar repositorio
git clone https://github.com/dpalik500/Tolearn.git
cd Tolearn

# 2. Crear y activar entorno virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 3. Instalar dependencias
pip install -r requirements.txt

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

# 5. Crear base de datos
createdb tolearn_dev

# 6. Ejecutar migraciones
python manage.py migrate

# 7. Crear superusuario
python manage.py createsuperuser

# 8. Recopilar estáticos
python manage.py collectstatic --noinput

# 9. Ejecutar servidor
python manage.py runserver

Variables de Entorno para Desarrollo

# .env para desarrollo
DEBUG=True
SECRET_KEY=dev-secret-key-not-for-production
ALLOWED_HOSTS=localhost,127.0.0.1

DB_NAME=tolearn_dev
DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=localhost
DB_PORT=5432

REDIS_HOST=localhost
REDIS_PORT=6379

# S3 (opcional en dev, usa almacenamiento local)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

Herramientas Recomendadas

IDE:

PyCharm Professional
VS Code con extensiones Python
Sublime Text

Extensiones VS Code:

ms-python.python
ms-python.vscode-pylance
batisteo.vscode-django
ms-toolsai.jupyter

Herramientas CLI:

# Pre-commit hooks
pip install pre-commit
pre-commit install

# Linters
pip install flake8 pylint black isort

# Testing
pip install pytest pytest-django pytest-cov

📁 Estructura del Código

Organización del Proyecto

Tolearn/
├── testfox/              # Proyecto principal
│   ├── settings.py       # Configuración global
│   ├── urls.py           # Rutas principales
│   ├── wsgi.py           # WSGI entry point
│   ├── asgi.py           # ASGI entry point
│   ├── routing.py        # WebSocket routing
│   └── middleware.py     # Middleware personalizado
│
├── accounts/             # Autenticación OAuth
│   ├── adapter.py
│   └── apps.py
│
├── homepage/             # Páginas públicas
│   ├── views.py
│   ├── urls.py
│   └── templates/
│
├── dashboard/            # Panel de estudiantes
│   ├── models.py         # Assignment, Question, etc.
│   ├── views.py
│   ├── admin.py
│   ├── urls.py
│   └── templates/
│
├── courses/              # Sistema de cursos
│   ├── models.py         # Course, Lesson, Task
│   ├── views.py
│   ├── admin.py
│   ├── translation.py    # Configuración i18n
│   └── templates/
│
├── webinar/              # Webinars en vivo
│   ├── models.py         # WebinarRoom, ChatMessage
│   ├── views.py
│   ├── consumers.py      # WebSocket consumers
│   ├── routing.py
│   └── templates/
│
├── adminpanel/           # Panel administrativo
│   ├── views.py
│   └── urls.py
│
├── templates/            # Plantillas globales
│   ├── base.html
│   ├── emails/
│   └── components/
│
├── static/               # Archivos estáticos
│   ├── css/
│   ├── js/
│   └── images/
│
├── locale/               # Traducciones
│   ├── es/
│   ├── en/
│   └── ru/
│
├── manage.py
├── requirements.txt
└── .env

Convenciones de Nombres

Python/Django:

# Clases: PascalCase
class UserProfile(models.Model):
    pass

# Funciones/métodos: snake_case
def get_user_courses(user):
    pass

# Constantes: UPPER_SNAKE_CASE
MAX_FILE_SIZE = 10485760

# Variables: snake_case
user_name = "Juan"

Archivos:

models.py        # Modelos de datos
views.py         # Vistas/controladores
urls.py          # Configuración de rutas
admin.py         # Configuración admin
forms.py         # Formularios
serializers.py   # Serializadores (futuro)
tests.py         # Tests unitarios
consumers.py     # WebSocket consumers

📝 Estándares de Codificación

PEP 8

Seguimos PEP 8 con algunas excepciones:

# Longitud de línea: 120 caracteres (en lugar de 79)
# flake8: max-line-length = 120

Imports

# Orden de imports:
# 1. Librería estándar
import os
import sys
from datetime import datetime

# 2. Terceros
import django
from django.db import models
from django.shortcuts import render

# 3. Locales
from .models import Course
from dashboard.models import Assignment

Docstrings

def calculate_grade(submission, total_points):
    """
    Calcula la calificación de un envío.
    
    Args:
        submission (Submission): El envío del estudiante
        total_points (int): Puntos totales posibles
        
    Returns:
        float: Calificación entre 0 y 10
        
    Raises:
        ValueError: Si total_points es 0
    """
    if total_points == 0:
        raise ValueError("Total points cannot be zero")
    
    return (submission.score / total_points) * 10

Type Hints

from typing import List, Optional, Dict

def get_courses(user: User, active_only: bool = True) -> List[Course]:
    """Obtiene cursos del usuario."""
    courses = user.courses.all()
    
    if active_only:
        courses = courses.filter(status=Course.STATUS_ACTIVE)
    
    return list(courses)

Comentarios

# Evitar comentarios obvios
user_name = "Juan"  # ❌ MAL: asignar nombre

# Comentar lógica compleja
# ✅ BIEN: Calculamos la nota considerando peso de cada pregunta
weighted_score = sum(
    answer.points * question.weight 
    for answer in answers
) / total_weight

🧪 Testing

Configuración de Tests

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = testfox.settings
python_files = tests.py test_*.py *_tests.py

Escribir Tests

# courses/tests.py
import pytest
from django.contrib.auth.models import User
from .models import Course, Lesson

@pytest.mark.django_db
class TestCourse:
    
    def test_create_course(self):
        """Test crear curso básico"""
        course = Course.objects.create(
            title="Test Course",
            description="Test Description",
            status=Course.STATUS_ACTIVE
        )
        
        assert course.title == "Test Course"
        assert course.status == Course.STATUS_ACTIVE
    
    def test_course_lessons_order(self):
        """Test que las lecciones se ordenan correctamente"""
        course = Course.objects.create(title="Test")
        
        Lesson.objects.create(course=course, order=2, title="Lesson 2")
        Lesson.objects.create(course=course, order=1, title="Lesson 1")
        
        lessons = course.lessons.all()
        assert lessons[0].order == 1
        assert lessons[1].order == 2

@pytest.mark.django_db
def test_user_course_access():
    """Test acceso de usuario a curso"""
    user = User.objects.create_user('test', '[email protected]', 'pass')
    course = Course.objects.create(title="Test")
    
    # Verificar que inicialmente no tiene acceso
    assert user not in course.student_access.all()
    
    # Dar acceso
    course.student_access.add(user)
    
    # Verificar acceso
    assert user in course.student_access.all()

Ejecutar Tests

# Todos los tests
pytest

# App específica
pytest courses/tests.py

# Test específico
pytest courses/tests.py::TestCourse::test_create_course

# Con cobertura
pytest --cov=. --cov-report=html

# Ver reporte de cobertura
open htmlcov/index.html

Fixtures

# conftest.py
import pytest
from django.contrib.auth.models import User, Group

@pytest.fixture
def user():
    """Usuario de prueba"""
    return User.objects.create_user(
        username='testuser',
        email='[email protected]',
        password='testpass123'
    )

@pytest.fixture
def student_user(user):
    """Usuario estudiante"""
    student_group = Group.objects.get_or_create(name='student')[0]
    user.groups.add(student_group)
    return user

@pytest.fixture
def course():
    """Curso de prueba"""
    return Course.objects.create(
        title="Test Course",
        status=Course.STATUS_ACTIVE
    )

🐛 Debugging

# settings.py (solo DEBUG=True)
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']
INTERNAL_IPS = ['127.0.0.1']

# urls.py
if settings.DEBUG:
    import debug_toolbar
    urlpatterns = [
        path('__debug__/', include(debug_toolbar.urls)),
    ] + urlpatterns

Logging

# Usar logger en lugar de print()
import logging

logger = logging.getLogger(__name__)

def my_view(request):
    logger.debug("Debug message")
    logger.info("Info message")
    logger.warning("Warning message")
    logger.error("Error message")
    logger.critical("Critical message")

Django Shell

# Shell interactivo
python manage.py shell

# Shell Plus (con django-extensions)
pip install django-extensions
python manage.py shell_plus

# IPython (mejor interfaz)
pip install ipython
python manage.py shell

Ejemplos en shell:

# Importar modelos
from courses.models import Course, Lesson
from django.contrib.auth.models import User

# Crear objetos
course = Course.objects.create(title="Test")

# Queries
courses = Course.objects.filter(status=Course.STATUS_ACTIVE)
users = User.objects.filter(groups__name='student')

# Inspeccionar
print(course.__dict__)
print(Course._meta.get_fields())

Breakpoints

# Python 3.7+
def my_function():
    x = 10
    breakpoint()  # Pausa aquí
    return x * 2

# O usar pdb
import pdb
pdb.set_trace()

# VS Code: Agregar breakpoint en UI
# F5 para debugar

🗄️ Base de Datos

Migraciones

# Crear migraciones
python manage.py makemigrations

# Aplicar migraciones
python manage.py migrate

# Ver migraciones
python manage.py showmigrations

# SQL de migración
python manage.py sqlmigrate courses 0001

# Squash migraciones (combinar múltiples)
python manage.py squashmigrations courses 0001 0005

Migraciones de Datos

# courses/migrations/0002_populate_defaults.py
from django.db import migrations

def populate_defaults(apps, schema_editor):
    Course = apps.get_model('courses', 'Course')
    
    # Crear cursos por defecto
    Course.objects.bulk_create([
        Course(title="Curso 1", status="Activo"),
        Course(title="Curso 2", status="Activo"),
    ])

class Migration(migrations.Migration):
    
    dependencies = [
        ('courses', '0001_initial'),
    ]
    
    operations = [
        migrations.RunPython(populate_defaults),
    ]

Backup y Restore

# Backup
python manage.py dumpdata > backup.json
python manage.py dumpdata courses > courses_backup.json

# Restore
python manage.py loaddata backup.json

# Solo datos (sin estructura)
python manage.py dumpdata --exclude auth.permission --exclude contenttypes > data.json

Consultas Optimizadas

# ❌ MAL: N+1 queries
courses = Course.objects.all()
for course in courses:
    print(course.lessons.count())  # Query por cada curso

# ✅ BIEN: 2 queries total
courses = Course.objects.all().prefetch_related('lessons')
for course in courses:
    print(course.lessons.count())

# Select related para ForeignKey
submissions = Submission.objects.select_related('student', 'assignment')

# Prefetch related para ManyToMany
courses = Course.objects.prefetch_related('student_access')

# Annotate para agregaciones
from django.db.models import Count
courses = Course.objects.annotate(lesson_count=Count('lessons'))

🎨 Frontend

Estructura de Templates

<!-- templates/base.html -->
<!DOCTYPE html>
<html lang="{{ LANGUAGE_CODE }}">
<head>
    {% load static %}
    <meta charset="UTF-8">
    <title>{% block title %}ToLearn{% endblock %}</title>
    <link rel="stylesheet" href="{% static 'css/main.css' %}">
    {% block extra_css %}{% endblock %}
</head>
<body>
    {% include 'components/navbar.html' %}
    
    <main>
        {% block content %}{% endblock %}
    </main>
    
    {% include 'components/footer.html' %}
    
    <script src="{% static 'js/main.js' %}"></script>
    {% block extra_js %}{% endblock %}
</body>
</html>

<!-- templates/courses/course_detail.html -->
{% extends 'base.html' %}

{% block title %}{{ course.title }}{% endblock %}

{% block content %}
    <h1>{{ course.title }}</h1>
    <p>{{ course.description }}</p>
{% endblock %}

JavaScript Modular

// static/js/modules/exam.js
export class ExamController {
    constructor(examId) {
        this.examId = examId;
        this.timeLeft = null;
    }
    
    startTimer(duration) {
        this.timeLeft = duration;
        setInterval(() => this.tick(), 1000);
    }
    
    tick() {
        this.timeLeft--;
        this.updateDisplay();
        if (this.timeLeft <= 0) {
            this.submitExam();
        }
    }
    
    updateDisplay() {
        const minutes = Math.floor(this.timeLeft / 60);
        const seconds = this.timeLeft % 60;
        document.getElementById('timer').textContent = 
            `${minutes}:${seconds.toString().padStart(2, '0')}`;
    }
    
    submitExam() {
        // Lógica de envío
    }
}

// static/js/main.js
import { ExamController } from './modules/exam.js';

document.addEventListener('DOMContentLoaded', () => {
    const examId = document.body.dataset.examId;
    if (examId) {
        const controller = new ExamController(examId);
        controller.startTimer(3600);
    }
});

CSS/SCSS

// static/scss/main.scss
$primary-color: #007bff;
$secondary-color: #6c757d;

.btn-primary {
    background-color: $primary-color;
    color: white;
    
    &:hover {
        background-color: darken($primary-color, 10%);
    }
}

// Compilar con:
// sass static/scss/main.scss static/css/main.css --watch

🚀 Deployment

Preparar para Producción

# settings.py
DEBUG = False
ALLOWED_HOSTS = ['tudominio.com', 'www.tudominio.com']

# Security
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000

Recopilar Estáticos

# Producción
python manage.py collectstatic --noinput

Gunicorn

# Instalar
pip install gunicorn

# Ejecutar
gunicorn testfox.wsgi:application \
    --bind 0.0.0.0:8000 \
    --workers 4 \
    --worker-class sync \
    --timeout 60

Docker

# Dockerfile
FROM python:3.10-slim

ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

RUN python manage.py collectstatic --noinput

EXPOSE 8000

CMD ["gunicorn", "testfox.wsgi:application", "--bind", "0.0.0.0:8000"]

CI/CD

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
    
    steps:
      - uses: actions/checkout@v2
      
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-django
      
      - name: Run tests
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost/postgres
        run: pytest

📚 Recursos Adicionales

✅ Checklist para Nuevos Desarrolladores

¡Bienvenido al equipo de desarrollo de ToLearn! 🚀

PreviousGuía de Contribución - ToLearn NextGuía del Administrador - ToLearn

Last updated 6 minutes ago

Good night