# Contexto — Módulo Reacciones Químicas (4.1)

## 1. Descripción general
Módulo de aprendizaje sobre reacciones químicas para el curso de Química del INTECAP. Incluye teoría, evaluación interactiva con anti-trampa y calificación automática.

## 2. Temas cubiertos
- **4.1.1** Concepto de reacción química (1 h)
- **4.1.2** Evidencias de las reacciones químicas (1 h)
- **4.1.3** Representación simbólica de las reacciones (1 h)
- **4.1.4** Clasificación de las reacciones químicas: síntesis, descomposición, sustitución simple, doble sustitución y combustión (3 h)

## 3. Estructura técnica
### Archivos principales
- `reacciones_config.py`: Configuración central (temas, puntos, descuentos)
- `reacciones_cdt.py`: Blueprint Flask con rutas para iniciar, reportar incidentes y guardar
- `reacciones_grader.py`: Dominio puro de calificación (clave de respuestas, normalización)
- `templates/reacciones-quimicas.html`: Página autocontenida con teoría y evaluación

### Endpoints
- `GET /reacciones-quimicas`: Página del módulo
- `POST /iniciar-reacciones`: Crea sesión con token
- `POST /incidente-reacciones`: Registra incidentes anti-trampa
- `POST /guardar-reacciones`: Califica y guarda resultados en CSV

## 4. Sistema anti-trampa
### Incidentes detectados (−5 pts cada uno)
- Cambio de pestaña/ventana (visibilitychange, blur)
- Copiar/pegar/cortar
- Atajos de teclado (F12, Ctrl+Shift+I/J/C, Ctrl+U/S/P/C/V)
- Clic derecho
- DevTools

### Implementación
- Detección en cliente con JavaScript
- Reporte asíncrono al servidor con enfriamiento de 3 segundos
- Notificación visible al estudiante
- Registro en CSV de incidencias

## 5. Sistema de evaluación
### Formato por tema
- **4.1.1**: 5 preguntas de selección múltiple (A/B/C/D) → 5 puntos
- **4.1.2**: 5 preguntas de selección múltiple (A/B/C/D) → 5 puntos
- **4.1.3**: 5 preguntas de respuesta corta (palabras específicas) → 5 puntos
- **4.1.4**: 10 ecuaciones para clasificar (desplegables) → 10 puntos

### Calificación
- **Nota unificada**: Se suman los puntos obtenidos en todos los temas y se divide entre los puntos totales posibles (25), multiplicando por 100
- Nota final = max(0, nota académica − 5 × incidentes)
- Resultados guardados en CSV: No, Apellidos, Nombres, Carrera, Puntos, Posibles, Nota
- Una sola fila por estudiante

## 6. Seguridad
- Allow-list para respuestas de selección múltiple
- Límites de longitud para nombres y textos
- Sanitización de entradas (escape de fórmulas CSV, XSS)
- Sesiones con token `secrets.token_hex(16)`
- Envío único por sesión (bloqueo de reenvío)
- Clave de respuestas solo en servidor

## 7. Despliegue
### Requisitos
- Python 3.x con Flask
- Servidor en `adoniz@192.168.0.150`
- Directorio: `/home/adoniz/apps/quimica/`

### Pasos de despliegue
1. Copiar archivos del módulo al servidor
2. Ejecutar `patch_app_reacciones.py` para registrar blueprint y tarjeta
3. Reiniciar servicio Flask

### URLs de producción
- Funnel: `https://adoniz-acer.tail60dd6a.ts.net/quimica/reacciones-quimicas`
- LAN: `http://192.168.0.150:8081/reacciones-quimicas`

## 8. QA y verificación
### Pruebas implementadas
- Unitarias: `test_reacciones_grader.py`, `test_reacciones_api.py`
- E2E: `qa_funnel_reacciones.py` (19 casos L3/L4 + ATK-SEC)

### Estado actual
- 32/32 pruebas unitarias+integración pasan localmente
- 19/19 pruebas funnel pasan en producción
- CSVs reseteados a solo encabezado tras pruebas

## 9. Mantenimiento
### Para actualizar respuestas
Editar `CLAVE` en `reacciones_grader.py`

### Para modificar puntos o temas
Editar `TEMAS` en `reacciones_config.py`

### Para agregar carreras
Editar `CARRERAS_PERMITIDAS` en `reacciones_config.py`

## 10. Contacto
- Desarrollador: Agente Cline/Kimi
- Fecha de creacion: 2026-08-28
- Ultima actualizacion: 2026-09-10

## 11. Modulo adicional: Estequiometria (4.1.5-4.1.7)

### Descripcion
Modulo de aprendizaje sobre estequiometria con teoria detallada paso a paso, ejemplos resueltos y evaluacion interactiva.

### Temas
- **4.1.5** Ley de conservacion de la materia (1 h, 5 pts)
- **4.1.6** Balanceo de ecuaciones quimicas por tanteo (2 h, 10 pts)
- **4.1.7** Relaciones estequiometricas mol-mol y masa-masa (2 h, 10 pts)
- **ACT** Actividad: ejercicios de balanceo y calculos estequiometricos (1 h, 5 pts)

### Sistema de calificacion
- Nota unificada: (puntos_obtenidos / 30) x 100 - 5 x incidentes
- Anti-trampa: -5 pts por incidente

### URLs de produccion
- Funnel: `https://thinkpad.tail60dd6a.ts.net/quimica/estequiometria`
- LAN: `http://192.168.0.150:8081/estequiometria`

### QA
- 37/32 pruebas unitarias+integracion pasan
- 19/19 pruebas funnel pasan en produccion
- Informe detallado en `estequiometria/qa_informe.md`