pagasis/README.md

Sistema de Asistencia MAC - FES Acatlán

Sistema de gestión de asistencia para ponencias y eventos académicos de Matemáticas Aplicadas y Computación (MAC).

🚀 Características

• Gestión de Eventos: Crear y administrar ponencias, talleres, seminarios
• Registro de Asistencia: Manual, por código de barras o usuarios externos
• Panel de Estudiantes: Consulta de estadísticas y eventos disponibles
• Panel de Asistentes: Administración completa y registro de asistencias
• Usuarios Externos: Sistema de aprobación para asistentes externos
• Estadísticas: Seguimiento de porcentaje de asistencia por estudiante
• Seguridad Avanzada: JWT, rate limiting, auditoría completa
• Sistema de Auditoría: Registro automático de eventos de seguridad

📋 Requisitos Previos

Opción 1: Con Docker (Recomendado)

• Docker y Docker Compose instalados
• Puertos 80 y 5432 disponibles

Opción 2: Instalación Manual

• Python 3.11+
• Node.js 18+
• npm o yarn
• PostgreSQL 15+

🛠️ Instalación

Opción 1: Con Docker (Recomendado)

Producción

# Clonar el repositorio
git clone <url-del-repositorio>
cd pagina-mac-og

# Copiar variables de entorno
cp .env.example .env

# IMPORTANTE: Editar .env y cambiar las credenciales para producción
# Cambiar: SECRET_KEY, DB_PASSWORD, etc.

# Construir e iniciar contenedores
docker-compose up --build -d

# Ver logs
docker-compose logs -f

# Acceder a la aplicación
# http://localhost

El sistema estará disponible en http://localhost con:

• Frontend: Servido por Nginx en puerto 80
• Backend: API REST en /api/
• PostgreSQL: Base de datos (puerto 5432 expuesto)

Desarrollo

# Usar configuración de desarrollo
docker-compose -f docker-compose.dev.yml up --build -d

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

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

# Ejecutar tests
docker-compose -f docker-compose.dev.yml exec backend tox -e test

# Ver documentación completa de desarrollo
# docs/DESARROLLO.md

Características del entorno de desarrollo:

• ✅ Hot reload automático (Django runserver)
• ✅ Todas las herramientas de testing y calidad de código
• ✅ PostgreSQL con puerto expuesto para acceso desde host
• ✅ Debugging con ipdb
• ✅ Ver docs/DESARROLLO.md para más detalles

Opción 2: Instalación Manual

Backend (Django)

1. Crear entorno virtual:

cd backend
python -m venv venv

2. Activar entorno virtual:

• Windows: venv\Scripts\activate
• Linux/Mac: source venv/bin/activate

3. Instalar dependencias:

pip install -r requirements.txt

⚠️ IMPORTANTE: Si acabas de clonar el repositorio o actualizaste con nuevas funcionalidades de importación/exportación, ejecuta:

pip install django-import-export openpyxl tablib

4. Configurar variables de entorno:

cp .env.example .env
# Editar .env con tus configuraciones

5. Ejecutar migraciones:

python manage.py migrate

6. Crear superusuario (opcional):

python manage.py createsuperuser

7. Ejecutar servidor:

python manage.py runserver

El backend estará disponible en http://127.0.0.1:8000

Frontend (React + Vite)

1. Instalar dependencias:

cd frontend
npm install

2. Ejecutar servidor de desarrollo:

npm run dev

El frontend estará disponible en http://localhost:5173

📥 Importación y Exportación de Datos

El sistema incluye funcionalidades de importación/exportación de estudiantes y asistentes mediante archivos Excel (.xlsx) o CSV.

Formato de Archivos para Importación

Los archivos deben tener exactamente 2 columnas:

account_number	full_name
1234567	Juan Pérez García
7654321	María López Sánchez

Desde el Panel de Admin de Django

1. Ve a http://127.0.0.1:8000/admin/
2. Selecciona Estudiantes o Asistentes (Perfiles)
3. Haz clic en "Importar" en la esquina superior derecha
4. Selecciona tu archivo Excel (.xlsx) o CSV
5. Revisa los cambios propuestos
6. Confirma la importación

Exportación

1. Selecciona los registros que deseas exportar
2. En el menú de acciones, selecciona "📊 Exportar estudiantes/asistentes seleccionados"
3. Haz clic en "Ir"
4. Se descargará un archivo Excel con los datos

Creación Manual

También puedes crear estudiantes y asistentes manualmente:

1. Ve al panel de admin de Django
2. Selecciona Estudiantes o Asistentes (Perfiles)
3. Haz clic en "Agregar estudiante" o "Agregar asistente"
4. Completa los campos:
   • Número de cuenta (7 dígitos)
   • Nombre completo
5. Guarda - el sistema creará automáticamente el usuario de Django asociado

📁 Estructura del Proyecto

mac_attendance/
├── backend/
│   ├── attendance/          # App de registro de asistencias
│   ├── authentication/      # App de autenticación y auditoría
│   ├── events/             # App de eventos y usuarios externos
│   ├── mac_attendance/     # Configuración principal y middleware
│   ├── scripts/            # Scripts de utilidad
│   │   ├── check_production.py   # Verificar config de producción
│   │   └── test_ratelimit.py     # Probar rate limiting
│   ├── static/             # Archivos estáticos
│   ├── media/              # Archivos subidos
│   ├── logs/               # Archivos de log (no trackeados)
│   ├── requirements.txt    # Dependencias Python
│   └── .env.example       # Ejemplo de variables de entorno
├── frontend/
│   ├── src/
│   │   ├── components/    # Componentes React
│   │   ├── contexts/      # Contextos (AuthContext)
│   │   └── services/      # Servicios API
│   └── package.json       # Dependencias Node
├── docker/                 # Archivos Docker
│   ├── Dockerfile.backend        # Dockerfile producción
│   ├── Dockerfile.backend.dev    # Dockerfile desarrollo
│   ├── Dockerfile.frontend       # Dockerfile frontend
│   └── nginx.conf                # Configuración Nginx
├── docs/                   # Documentación del proyecto
│   ├── SECURITY.md               # Guía de seguridad completa
│   ├── RATE_LIMITING.md          # Documentación rate limiting
│   ├── AUDIT.md                  # Sistema de auditoría
│   ├── POSTGRESQL_MIGRATION.md   # Migración a PostgreSQL
│   ├── DESARROLLO.md             # Guía de desarrollo completa
│   └── ESTRUCTURA_PROYECTO.md    # Estructura del proyecto
├── docker-compose.yml      # Docker Compose producción
├── docker-compose.dev.yml  # Docker Compose desarrollo
├── .env.example           # Ejemplo de variables de entorno
└── README.md

🔐 Configuración Inicial

Crear Superusuario (Administrador)

Después de iniciar los contenedores, crea un superusuario para acceder al panel de administración:

# Con Docker
docker-compose exec backend python manage.py createsuperuser

# O en desarrollo
docker-compose -f docker-compose.dev.yml exec backend python manage.py createsuperuser

Sigue las instrucciones para crear:

• Username
• Email
• Password

Acceso al Sistema

Panel de Administración Django:

• URL: http://localhost/admin/
• Usuario: El superusuario que acabas de crear

Aplicación Web:

• URL: http://localhost/
• Los usuarios (asistentes y estudiantes) deben ser creados desde el panel de administración
• Usuarios externos pueden registrarse desde el formulario público

📊 Modelos Principales

UserProfile

• Tipo de usuario (estudiante/asistente)
• Número de cuenta (7 dígitos)
• Información personal

Event

• Título, descripción, ponente
• Fecha, hora de inicio/fin
• Modalidad (presencial/online/híbrido)
• Capacidad máxima

Attendance

• Estudiante o usuario externo
• Evento asociado
• Método de registro (manual/barcode/external)
• Registrado por (asistente)

ExternalUser

• Usuarios externos pendientes de aprobación
• Información de institución y motivo
• ID temporal único

🔧 Configuración Adicional

Variables de Entorno (.env)

SECRET_KEY=tu-clave-secreta
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
CORS_ALLOWED_ORIGINS=http://localhost:5173

CORS

El backend está configurado para aceptar peticiones desde:

• http://localhost:5173 (desarrollo)
• http://127.0.0.1:5173 (desarrollo)

🔒 Seguridad

Este proyecto implementa múltiples capas de seguridad:

Autenticación y Autorización

• ✅ JWT (JSON Web Tokens) para autenticación stateless
• ✅ Control de acceso basado en roles (estudiante/asistente)
• ✅ Tokens de corta duración (1 hora) con refresh tokens (7 días)

Protección contra Ataques

• ✅ Rate Limiting: Límites en todos los endpoints críticos
  • Login: 5 intentos/minuto por IP
  • Registro externo: 3/hora por IP
  • Ver docs/RATE_LIMITING.md para detalles
• ✅ Headers de seguridad HTTP (HSTS, X-Frame-Options, etc.)
• ✅ Sanitización automática de datos sensibles en logs

Sistema de Auditoría

• ✅ Registro automático de eventos de seguridad
• ✅ Trazabilidad completa: IP, user agent, timestamp
• ✅ Logs inmutables consultables desde Django Admin
• ✅ Ver docs/AUDIT.md para documentación completa

Documentación de Seguridad

• 📄 docs/SECURITY.md - Guía de seguridad y checklist de producción
• 📄 docs/RATE_LIMITING.md - Configuración de rate limiting
• 📄 docs/AUDIT.md - Sistema de auditoría

🧪 Testing y Calidad de Código

El proyecto incluye un entorno completo de testing y calidad de código usando Tox.

Ejecutar Tests

# Con Docker (desarrollo)
docker-compose -f docker-compose.dev.yml exec backend tox -e test

# Tests rápidos
docker-compose -f docker-compose.dev.yml exec backend tox -e test-fast

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

Herramientas Disponibles

• Testing: pytest, pytest-django, pytest-cov, factory-boy
• Linting: flake8, pylint, black, isort
• Type Checking: mypy con stubs para Django/DRF
• Seguridad: bandit, safety
• Métricas: radon (complejidad ciclomática)

Ver docs/DESARROLLO.md para documentación completa.

🐘 PostgreSQL

El sistema usa PostgreSQL como base de datos para producción.

Acceso desde Host

⚠️ Configurar credenciales en archivo .env antes de usar:

Host: localhost
Port: 5432
Database: [DB_NAME del .env]
User: [DB_USER del .env]
Password: [DB_PASSWORD del .env]

Comandos Útiles

# Conectarse con psql
psql -h localhost -p 5432 -U mac_user -d mac_attendance

# Backup
docker-compose exec db pg_dump -U mac_user mac_attendance > backup.sql

# Restore
cat backup.sql | docker-compose exec -T db psql -U mac_user mac_attendance

Ver docs/POSTGRESQL_MIGRATION.md para más detalles.

📚 Documentación

• docs/DESARROLLO.md - Guía completa de desarrollo
• docs/SECURITY.md - Guía de seguridad y checklist de producción
• docs/RATE_LIMITING.md - Configuración de rate limiting
• docs/AUDIT.md - Sistema de auditoría
• docs/POSTGRESQL_MIGRATION.md - Migración a PostgreSQL
• docs/ESTRUCTURA_PROYECTO.md - Estructura del proyecto

🚧 Mejoras Futuras

• Implementar JWT para autenticación
• Sistema de auditoría y logging
• Rate limiting en endpoints
• Dockerización del proyecto
• Migración a PostgreSQL
• Entorno de desarrollo con Tox
• Agregar exportación de reportes (CSV/PDF)
• Implementar lector de códigos de barras
• Notificaciones por email
• Panel de estadísticas avanzadas
• Cobertura de tests > 80%

📝 Licencia

Este proyecto está bajo la Licencia MIT.

👥 Contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -m 'Agregar nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

📧 Soporte

Para preguntas o soporte técnico sobre el sistema, contactar a:

• Matemáticas Aplicadas y Computación (MAC)
• FES Acatlán - UNAM

---

Desarrollado para: Matemáticas Aplicadas y Computación (MAC) Institución: FES Acatlán - UNAM Año: 2025