Portal Escolar — Instituto Kambes

Sistema web de administración escolar con roles de administrador, maestro y alumno.

Stack

• Python 3.14 + Flask 3
• MySQL 8
• SQLAlchemy + Flask-Migrate
• Flask-Login + Flask-WTF (CSRF)
• APScheduler (tareas programadas)
• ReportLab + openpyxl (reportes)

Instalación

1. Crear la base de datos

CREATE DATABASE portal_escolar CHARACTER SET utf8mb4;

Importa el esquema inicial:

mysql -u root -p portal_escolar < schema.sql

Luego corre las migraciones de cada fase en orden:

mysql -u root -p portal_escolar < fase1_migracion.sql
mysql -u root -p portal_escolar < fase2_migracion.sql
mysql -u root -p portal_escolar < fase5_migracion.sql
mysql -u root -p portal_escolar < materias_licenciaturas.sql

2. Configuración

Copia el archivo de configuración de ejemplo:

cp .env.example .env

Edita .env con tus credenciales de base de datos y una SECRET_KEY aleatoria. Para generar una:

python -c "import secrets; print(secrets.token_hex(32))"

3. Dependencias de Python

python -m venv venv
# En Windows:
venv\Scripts\activate
# En Linux/Mac:
source venv/bin/activate

pip install -r requirements.txt

4. Crear admin por defecto

python seed.py

Usuario creado:

• Email: [email protected]
• Contraseña: Admin1234!

Cámbiala en el primer ingreso desde "Mi perfil".

5. Ejecutar

python run.py

La aplicación corre en http://localhost:5000.

Estructura del proyecto

portal_escolar/
├── app/
│   ├── __init__.py         # Factory de Flask
│   ├── models/             # Modelos SQLAlchemy
│   ├── routes/             # Blueprints (admin, maestro, alumno, etc.)
│   ├── services/           # Lógica de negocio reutilizable
│   └── utils/              # Helpers (seguridad, reportes, scheduler)
├── templates/              # Plantillas Jinja2
├── static/                 # CSS, JS, uploads
├── migrations/             # Migraciones generadas por Flask-Migrate
├── config.py               # Configuración centralizada
├── run.py                  # Entry point
├── seed.py                 # Script de inicialización
└── .env                    # Variables sensibles (no se versiona)

Migraciones con Flask-Migrate

Para cambios futuros al esquema:

# Inicializar (solo una vez)
flask db init

# Crear migración desde cambios en modelos
flask db migrate -m "descripción del cambio"

# Aplicar
flask db upgrade

Usuarios de prueba

Después del seed, puedes iniciar sesión como:

• Admin: [email protected] / Admin1234!

El admin puede crear maestros y alumnos desde la interfaz.

Scheduler

El scheduler corre automáticamente dos jobs:

• Pagos semanales — todos los lunes a las 6am genera el pago semanal de cada alumno activo y marca vencidos
• Caducidad de grupos — todos los días a las 7am notifica al admin de grupos que caducan en 7 días

Se puede forzar manualmente desde la pantalla de pagos con "Generar pagos semanales".

Cambios de configuración frecuentes

Todas las reglas de negocio están en .env y se leen desde config.py:

• CUOTA_INSCRIPCION — Costo único de inscripción (default 500)
• MONTO_MULTA_VENCIDO — Multa por pago vencido (default 20)
• MAX_PAGOS_VENCIDOS_BLOQUEO — Pagos vencidos para bloquear alumno (default 4)
• MESES_CADUCIDAD_GRUPO — Duración de grupos en meses (default 4)
• MAX_INTENTOS_LOGIN / MINUTOS_BLOQUEO_LOGIN — Protección contra fuerza bruta

No hace falta reiniciar el servidor para cambios triviales, pero sí para cambios de config.

Licencia

Proyecto interno de Instituto Kambes. Todos los derechos reservados.