Files

1444 lines
52 KiB
Python

"""
FastAPI Academic Router (/api/v1)
Provides modular endpoints for Careers, Subjects, Commissions, Academic Terms and Milestone Types.
"""
from typing import Optional, List, Dict, Any
from fastapi import APIRouter, Depends, HTTPException, Query, status, Request
from sqlalchemy import func, or_
from datetime import datetime, timezone
import math
from app import db
from app.models.career import Career
from app.models.subject import Subject, Commission, CommissionTeacher
from app.models.academic_term import AcademicTerm
from app.models.milestone import MilestoneType, AcademicMilestone
from app.models.user import User
from app.models.enrollment import StudentEnrollment
from app.services.enrollment_service import EnrollmentService
from app.services.gradebook_service import GradebookService
from dependencies import get_request_payload, get_current_user, require_roles
academic_router = APIRouter(prefix="/api/v1", tags=["Academic Management"])
# =========================================================
# CAREERS ENDPOINTS
# =========================================================
@academic_router.get("/careers")
def list_careers(
search: Optional[str] = Query(None),
current_user: User = Depends(get_current_user)
):
"""Lista todas las carreras académicas registradas."""
query = Career.query
if search:
s_clean = search.strip().lower()
query = query.filter(
or_(
Career.name.ilike(f'%{s_clean}%'),
Career.code.ilike(f'%{s_clean}%')
)
)
careers = query.order_by(Career.name.asc()).all()
return {
'status': 'success',
'total': len(careers),
'careers': [c.to_dict() for c in careers]
}
@academic_router.post("/careers", status_code=status.HTTP_201_CREATED)
async def create_career(
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Crea una nueva carrera en la institución."""
data = await get_request_payload(request)
name = (data.get('name') or '').strip()
code = (data.get('code') or '').strip()
description = (data.get('description') or '').strip()
if not name:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="El nombre de la carrera es obligatorio.")
if Career.query.filter(Career.name.ilike(name)).first():
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Ya existe una carrera con el nombre {name}.")
career = Career(name=name, code=code or None, description=description or None)
db.session.add(career)
db.session.commit()
return {
'status': 'success',
'message': 'Carrera creada exitosamente.',
'career': career.to_dict()
}
@academic_router.put("/careers/{id}")
async def update_career(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Actualiza una carrera existente."""
data = await get_request_payload(request)
career = Career.query.get(id)
if not career:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Carrera con ID {id} no encontrada.")
if 'name' in data and data['name']:
name = (data['name'] or '').strip()
existing = Career.query.filter(Career.name.ilike(name), Career.id != id).first()
if existing:
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Ya existe otra carrera con el nombre {name}.")
career.name = name
if 'code' in data:
career.code = (data['code'] or '').strip() or None
if 'description' in data:
career.description = (data['description'] or '').strip() or None
db.session.commit()
return {
'status': 'success',
'message': 'Carrera actualizada correctamente.',
'career': career.to_dict()
}
@academic_router.delete("/careers/{id}")
def delete_career(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Elimina una carrera si no posee asignaturas vinculadas."""
career = Career.query.get(id)
if not career:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Carrera con ID {id} no encontrada.")
if career.subjects and len(career.subjects) > 0:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=f"No se puede eliminar la carrera porque tiene {len(career.subjects)} asignaturas vinculadas."
)
db.session.delete(career)
db.session.commit()
return {
'status': 'success',
'message': 'Carrera eliminada permanentemente.'
}
# =========================================================
# SUBJECTS ENDPOINTS
# =========================================================
@academic_router.get("/subjects")
def list_subjects(
search: Optional[str] = Query(None),
career_id: Optional[str] = Query(None),
active: Optional[str] = Query(None),
page: Optional[int] = Query(None, ge=1),
per_page: Optional[int] = Query(None, ge=1, le=200),
current_user: User = Depends(get_current_user)
):
"""Lista las asignaturas con filtros opcionales de búsqueda, carrera, estado y paginación."""
query = Subject.query
if search and search.strip():
s_clean = search.strip().lower()
query = query.filter(
or_(
Subject.name.ilike(f'%{s_clean}%'),
Subject.code.ilike(f'%{s_clean}%'),
Subject.department.ilike(f'%{s_clean}%'),
Subject.careers.any(Career.name.ilike(f'%{s_clean}%'))
)
)
parsed_career_id = int(career_id.strip()) if career_id and career_id.strip().isdigit() else None
if parsed_career_id:
query = query.filter(or_(Subject.career_id == parsed_career_id, Subject.careers.any(Career.id == parsed_career_id)))
if active == 'true':
query = query.filter(Subject.is_active == True)
elif active == 'false':
query = query.filter(Subject.is_active == False)
total = query.count()
careers = Career.query.order_by(Career.name.asc()).all()
if page and per_page:
pages = math.ceil(total / per_page) if total > 0 else 1
subjects = query.order_by(Subject.id.asc()).offset((page - 1) * per_page).limit(per_page).all()
has_prev = page > 1
has_next = page < pages
else:
pages = 1
page = 1
per_page = total or 1
has_prev = False
has_next = False
subjects = query.order_by(Subject.id.asc()).all()
subjects_data = []
for s in subjects:
d = s.to_dict()
if isinstance(s.commissions, list):
d['commissions_count'] = len(s.commissions)
d['commissions'] = [{'id': c.id, 'code': c.code, 'schedule': c.schedule} for c in s.commissions]
elif s.commissions is not None:
d['commissions_count'] = 1
d['commissions'] = [{'id': s.commissions.id, 'code': s.commissions.code, 'schedule': s.commissions.schedule}]
else:
d['commissions_count'] = 0
d['commissions'] = []
subjects_data.append(d)
return {
'status': 'success',
'total': total,
'page': page,
'per_page': per_page,
'pages': pages,
'has_prev': has_prev,
'has_next': has_next,
'subjects': subjects_data,
'careers': [c.to_dict() for c in careers]
}
@academic_router.post("/subjects", status_code=status.HTTP_201_CREATED)
async def create_subject(
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Crea una nueva asignatura y la vincula a una o varias carreras."""
data = await get_request_payload(request)
code = (data.get('code') or '').strip().upper()
name = (data.get('name') or '').strip()
department = (data.get('department') or '').strip()
try:
credits = int(data.get('credits', 4) or 4)
except (ValueError, TypeError):
credits = 4
career_id = data.get('career_id')
description = (data.get('description') or '').strip()
career_ids = data.get('career_ids')
is_short_course = data.get('is_short_course', False)
if isinstance(is_short_course, str):
is_short_course = is_short_course.lower() in ['true', '1', 'on']
if not code or not name:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="El código y nombre de la asignatura son obligatorios.")
if Subject.query.filter(Subject.code == code).first():
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Ya existe una asignatura con el código {code}.")
c_id = int(career_id) if (career_id and str(career_id).strip()) else None
c_id_list = []
if isinstance(career_ids, str):
c_id_list = [int(x.strip()) for x in career_ids.split(',') if x.strip().isdigit()]
elif isinstance(career_ids, list):
c_id_list = [int(x) for x in career_ids if str(x).isdigit()]
if not c_id and c_id_list:
c_id = c_id_list[0]
subject = Subject(
code=code,
name=name,
department=department,
credits=credits,
career_id=c_id,
description=description or None,
is_short_course=bool(is_short_course),
is_active=True
)
if c_id_list:
subject.careers = Career.query.filter(Career.id.in_(c_id_list)).all()
elif c_id:
c_obj = Career.query.get(c_id)
if c_obj:
subject.careers = [c_obj]
db.session.add(subject)
db.session.commit()
return {
'status': 'success',
'message': 'Asignatura creada exitosamente.',
'subject': subject.to_dict()
}
@academic_router.put("/subjects/{id}")
async def update_subject(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Actualiza una asignatura existente."""
data = await get_request_payload(request)
subject = Subject.query.get(id)
if not subject:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Asignatura con ID {id} no encontrada.")
if 'code' in data and data['code']:
code = (data['code'] or '').strip().upper()
existing = Subject.query.filter(Subject.code == code, Subject.id != id).first()
if existing:
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Ya existe otra asignatura con el código {code}.")
subject.code = code
if 'name' in data and data['name']:
subject.name = (data['name'] or '').strip()
if 'department' in data:
subject.department = (data['department'] or '').strip()
if 'credits' in data and data['credits'] is not None:
try:
subject.credits = int(data['credits'])
except (ValueError, TypeError):
pass
if 'career_ids' in data:
career_ids = data.get('career_ids')
if isinstance(career_ids, str):
c_id_list = [int(x.strip()) for x in career_ids.split(',') if x.strip().isdigit()]
elif isinstance(career_ids, list):
c_id_list = [int(x) for x in career_ids if str(x).isdigit()]
else:
c_id_list = []
if c_id_list:
c_objs = Career.query.filter(Career.id.in_(c_id_list)).all()
subject.careers = c_objs
if not subject.career_id or subject.career_id not in c_id_list:
subject.career_id = c_objs[0].id if c_objs else None
else:
subject.careers = []
subject.career_id = None
elif 'career_id' in data:
c_id = data['career_id']
subject.career_id = int(c_id) if c_id else None
if subject.career_id:
c_obj = Career.query.get(subject.career_id)
if c_obj:
subject.careers = [c_obj]
else:
subject.careers = []
if 'description' in data:
subject.description = (data['description'] or '').strip()
if 'is_active' in data:
val = data['is_active']
subject.is_active = val in [True, 'true', '1', 'on']
db.session.commit()
return {
'status': 'success',
'message': 'Asignatura actualizada correctamente.',
'subject': subject.to_dict()
}
@academic_router.post("/subjects/{id}/toggle")
def toggle_subject(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Conmuta el estado activo de una asignatura."""
subject = Subject.query.get(id)
if not subject:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Asignatura con ID {id} no encontrada.")
subject.is_active = not subject.is_active
db.session.commit()
return {
'status': 'success',
'id': subject.id,
'is_active': subject.is_active,
'message': f'Asignatura {"activada" if subject.is_active else "desactivada"} correctamente.'
}
@academic_router.delete("/subjects/{id}")
def delete_subject(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Elimina una asignatura o la desactiva si tiene comisiones vinculadas."""
subject = Subject.query.get(id)
if not subject:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Asignatura con ID {id} no encontrada.")
if subject.commissions and len(subject.commissions) > 0:
subject.is_active = False
db.session.commit()
return {
'status': 'deactivated',
'action': 'deactivated',
'message': f'La asignatura "{subject.name}" tiene {len(subject.commissions)} comisión(es) vinculada(s). Se ha desactivado en su lugar para proteger el historial académico.'
}
name = subject.name
db.session.delete(subject)
db.session.commit()
return {
'status': 'deleted',
'action': 'deleted',
'message': f'Asignatura "{name}" eliminada permanentemente del sistema.'
}
# =========================================================
# COMMISSIONS ENDPOINTS
# =========================================================
@academic_router.get("/commissions")
def list_commissions(
search: Optional[str] = Query(None),
subject_id: Optional[str] = Query(None),
career_id: Optional[str] = Query(None),
shift: Optional[str] = Query(None),
active: Optional[str] = Query(None),
teacher_id: Optional[int] = Query(None),
student_id: Optional[int] = Query(None),
mine: Optional[bool] = Query(None),
page: Optional[int] = Query(None, ge=1),
per_page: Optional[int] = Query(None, ge=1, le=200),
current_user: User = Depends(get_current_user)
):
"""Lista las comisiones académicas con soporte para filtros de búsqueda, carrera, materia, turno, docente/alumno y paginación."""
query = Commission.query
joined_subject = False
user_role = (getattr(current_user, 'role', '') or '').lower()
# Si se solicita mine=True o si se proveen filtros específicos de usuario
effective_teacher_id = teacher_id
effective_student_id = student_id
if mine:
if user_role == 'docente':
effective_teacher_id = int(getattr(current_user, 'id'))
elif user_role == 'alumno':
effective_student_id = int(getattr(current_user, 'id'))
if effective_teacher_id:
query = query.filter(
or_(
Commission.teacher_id == effective_teacher_id,
Commission.teachers_association.any(CommissionTeacher.user_id == effective_teacher_id)
)
)
if effective_student_id:
query = query.filter(
Commission.enrollments.any(StudentEnrollment.student_id == effective_student_id)
)
if search and search.strip():
s_clean = search.strip().lower()
query = query.outerjoin(Subject, Commission.subject_id == Subject.id)
joined_subject = True
query = query.filter(
or_(
Commission.code.ilike(f'%{s_clean}%'),
Commission.schedule.ilike(f'%{s_clean}%'),
Subject.name.ilike(f'%{s_clean}%'),
Subject.code.ilike(f'%{s_clean}%')
)
)
parsed_subject_id = int(subject_id.strip()) if subject_id and subject_id.strip().isdigit() else None
parsed_career_id = int(career_id.strip()) if career_id and career_id.strip().isdigit() else None
if parsed_subject_id:
query = query.filter(Commission.subject_id == parsed_subject_id)
if parsed_career_id:
if not joined_subject:
query = query.join(Subject, Commission.subject_id == Subject.id)
joined_subject = True
query = query.filter(
or_(Subject.career_id == parsed_career_id, Subject.careers.any(Career.id == parsed_career_id))
)
if shift and shift.strip():
query = query.filter(Commission.shift == shift.strip())
if active == 'true':
query = query.filter(Commission.active == True)
elif active == 'false':
query = query.filter(Commission.active == False)
total = query.count()
if page and per_page:
pages = math.ceil(total / per_page) if total > 0 else 1
commissions = query.order_by(Commission.year.desc(), Commission.semester.desc(), Commission.code.asc()).offset((page - 1) * per_page).limit(per_page).all()
has_prev = page > 1
has_next = page < pages
else:
pages = 1
page = 1
per_page = total or 1
has_prev = False
has_next = False
commissions = query.order_by(Commission.year.desc(), Commission.semester.desc(), Commission.code.asc()).all()
all_subjects = Subject.query.filter_by(is_active=True).order_by(Subject.name.asc()).all()
all_careers = Career.query.order_by(Career.name.asc()).all()
all_terms = AcademicTerm.query.filter_by(is_active=True).order_by(AcademicTerm.year.desc()).all()
return {
'status': 'success',
'total': total,
'page': page,
'per_page': per_page,
'pages': pages,
'has_prev': has_prev,
'has_next': has_next,
'commissions': [c.to_dict() for c in commissions],
'subjects': [s.to_dict() for s in all_subjects],
'careers': [car.to_dict() for car in all_careers],
'academic_terms': [t.to_dict() for t in all_terms]
}
@academic_router.post("/commissions", status_code=status.HTTP_201_CREATED)
async def create_commission(
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Crea una comisión vinculada a una asignatura, ciclo lectivo y docente(s)."""
data = await get_request_payload(request)
subject_id = data.get('subject_id')
code = (data.get('code') or '').strip()
semester = (data.get('semester') or '1C').strip()
try:
year = int(data.get('year', datetime.now().year) or datetime.now().year)
except (ValueError, TypeError):
year = datetime.now().year
academic_term_id = data.get('academic_term_id')
academic_term_id = int(academic_term_id) if (academic_term_id and str(academic_term_id).strip().isdigit()) else None
if academic_term_id:
term_obj = AcademicTerm.query.get(academic_term_id)
if term_obj:
if not data.get('year') or int(data.get('year')) == datetime.now().year:
year = term_obj.year
if not data.get('semester') or data.get('semester') == '1C':
p_text = f"{term_obj.name} {term_obj.period_type or ''} {term_obj.code}".lower()
if '2c' in p_text or 'segundo' in p_text or '2º' in p_text or '2do' in p_text:
semester = '2C'
elif 'anual' in p_text:
semester = 'Anual'
else:
semester = '1C'
teacher_id = data.get('teacher_id')
teacher_id = int(teacher_id) if (teacher_id and str(teacher_id).strip().isdigit()) else None
try:
max_students = int(data.get('max_students', 35) or 35)
except (ValueError, TypeError):
max_students = 35
schedule = (data.get('schedule') or '').strip()
shift = (data.get('shift') or 'Mañana').strip()
virtual_link = (data.get('virtual_link') or '').strip()
active = data.get('active', True)
if isinstance(active, str):
active = active.lower() in ['true', '1', 'on']
if not subject_id or not code:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="La asignatura y código de comisión son obligatorios.")
subject = Subject.query.get(int(subject_id))
if not subject:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"La asignatura con ID {subject_id} no existe.")
virtual_link = virtual_link or None
existing = Commission.query.filter_by(
subject_id=int(subject_id),
code=code,
semester=semester,
year=year
).first()
if existing:
existing.teacher_id = teacher_id
existing.max_students = max_students
existing.schedule = schedule
existing.shift = shift
if academic_term_id:
existing.academic_term_id = academic_term_id
if virtual_link:
existing.virtual_link = virtual_link
existing.active = bool(active)
if teacher_id:
ct = CommissionTeacher.query.filter_by(commission_id=existing.id, user_id=teacher_id).first()
if not ct:
db.session.add(CommissionTeacher(commission_id=existing.id, user_id=teacher_id, role='Titular', is_primary=True))
db.session.commit()
return {
'status': 'success',
'message': f'Comisión {code} asociada a {subject.name} actualizada exitosamente.',
'commission': existing.to_dict()
}
commission = Commission(
subject_id=int(subject_id),
code=code,
semester=semester,
year=year,
teacher_id=teacher_id,
max_students=max_students,
schedule=schedule,
shift=shift,
virtual_link=virtual_link,
academic_term_id=academic_term_id,
active=bool(active)
)
db.session.add(commission)
db.session.flush()
if teacher_id:
db.session.add(CommissionTeacher(commission_id=commission.id, user_id=teacher_id, role='Titular', is_primary=True))
extra_teachers = data.get('teacher_ids') or data.get('teachers') or []
for et in extra_teachers:
u_id = et.get('user_id') if isinstance(et, dict) else et
u_role = et.get('role', 'Adjunto') if isinstance(et, dict) else 'Adjunto'
if u_id and int(u_id) != teacher_id:
db.session.add(CommissionTeacher(commission_id=commission.id, user_id=int(u_id), role=u_role, is_primary=False))
db.session.commit()
return {
'status': 'success',
'message': f'Comisión {code} asociada exitosamente a {subject.name}.',
'commission': commission.to_dict()
}
@academic_router.get("/commissions/{id}")
def get_commission(
id: int,
current_user: User = Depends(get_current_user)
):
"""Obtiene los detalles de una comisión."""
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión con ID {id} no encontrada.")
return {
'status': 'success',
'commission': comm.to_dict()
}
@academic_router.put("/commissions/{id}")
async def update_commission(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Actualiza los datos de una comisión."""
data = await get_request_payload(request)
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión con ID {id} no encontrada.")
if 'subject_id' in data and data['subject_id']:
comm.subject_id = int(data['subject_id'])
if 'academic_term_id' in data:
t_id = data['academic_term_id']
comm.academic_term_id = int(t_id) if (t_id and str(t_id).strip().isdigit()) else None
if 'code' in data and data['code']:
comm.code = (data['code'] or '').strip()
if 'semester' in data and data['semester']:
comm.semester = (data['semester'] or '').strip()
if 'year' in data and data['year']:
comm.year = int(data['year'])
if 'teacher_id' in data:
t_id = data['teacher_id']
comm.teacher_id = int(t_id) if (t_id and str(t_id).strip().isdigit()) else None
if comm.teacher_id:
ct = CommissionTeacher.query.filter_by(commission_id=comm.id, user_id=comm.teacher_id).first()
if not ct:
db.session.add(CommissionTeacher(commission_id=comm.id, user_id=comm.teacher_id, role='Titular', is_primary=True))
else:
ct.is_primary = True
if 'max_students' in data and data['max_students']:
comm.max_students = int(data['max_students'])
if 'schedule' in data:
comm.schedule = (data['schedule'] or '').strip()
if 'shift' in data and data['shift']:
comm.shift = (data['shift'] or '').strip()
if 'virtual_link' in data:
vl = (data['virtual_link'] or '').strip()
comm.virtual_link = vl or None
if 'active' in data:
val = data['active']
comm.active = val in [True, 'true', '1', 'on']
db.session.commit()
return {
'status': 'success',
'message': 'Comisión actualizada correctamente.',
'commission': comm.to_dict()
}
@academic_router.post("/commissions/{id}/toggle")
def toggle_commission(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Conmuta el estado activo de una comisión."""
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión con ID {id} no encontrada.")
comm.active = not comm.active
db.session.commit()
return {
'status': 'success',
'id': comm.id,
'active': comm.active,
'message': f'Comisión {"activada" if comm.active else "desactivada"} correctamente.'
}
@academic_router.delete("/commissions/{id}")
def delete_commission(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Elimina una comisión o la desactiva si contiene reservas históricas."""
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión con ID {id} no encontrada.")
from app.models.reservation import Reservation
res_count = Reservation.query.filter_by(commission_id=id).count()
if res_count > 0:
comm.active = False
db.session.commit()
return {
'status': 'deactivated',
'action': 'deactivated',
'message': f'La comisión tiene {res_count} reservas vinculadas. Se ha desactivado en su lugar.'
}
db.session.delete(comm)
db.session.commit()
return {
'status': 'deleted',
'action': 'deleted',
'message': 'Comisión eliminada permanentemente.'
}
# =========================================================
# ACADEMIC TERMS ENDPOINTS
# =========================================================
@academic_router.get("/academic-terms")
@academic_router.get("/admin/academic-terms")
def list_academic_terms(
search: Optional[str] = Query(None),
year: Optional[int] = Query(None),
current_user: User = Depends(get_current_user)
):
"""Lista todos los ciclos lectivos registrados."""
query = AcademicTerm.query
if search:
s_clean = search.strip().lower()
query = query.filter(
or_(
AcademicTerm.name.ilike(f'%{s_clean}%'),
AcademicTerm.code.ilike(f'%{s_clean}%'),
AcademicTerm.period_type.ilike(f'%{s_clean}%')
)
)
if year:
query = query.filter(AcademicTerm.year == year)
terms = query.order_by(AcademicTerm.year.desc(), AcademicTerm.id.desc()).all()
return {
'status': 'success',
'total': len(terms),
'terms': [t.to_dict() for t in terms]
}
@academic_router.post("/academic-terms", status_code=status.HTTP_201_CREATED)
@academic_router.post("/admin/academic-terms", status_code=status.HTTP_201_CREATED)
async def create_academic_term(
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Crea un nuevo ciclo lectivo en el sistema."""
data = await get_request_payload(request)
code = (data.get('code') or '').strip().upper()
name = (data.get('name') or '').strip()
try:
year = int(data.get('year', datetime.now().year) or datetime.now().year)
except (ValueError, TypeError):
year = datetime.now().year
period_type = (data.get('period_type') or 'Segundo Cuatrimestre').strip()
start_date = data.get('start_date')
end_date = data.get('end_date')
is_current = data.get('is_current', False)
if isinstance(is_current, str):
is_current = is_current.lower() in ['true', '1', 'on']
if not code or not name:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="El código y nombre del período lectivo son obligatorios.")
if AcademicTerm.query.filter(AcademicTerm.code == code).first():
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Ya existe un período lectivo con el código {code}.")
if is_current:
AcademicTerm.query.update({'is_current': False})
term = AcademicTerm(
code=code,
name=name,
year=year,
period_type=period_type,
start_date=datetime.strptime(start_date, '%Y-%m-%d').date() if start_date else None,
end_date=datetime.strptime(end_date, '%Y-%m-%d').date() if end_date else None,
is_current=bool(is_current),
is_active=True
)
db.session.add(term)
db.session.commit()
return {
'status': 'success',
'message': f'Período lectivo "{name}" creado con éxito.',
'term': term.to_dict()
}
@academic_router.post("/academic-terms/{id}/set-current")
@academic_router.post("/admin/academic-terms/{id}/set-current")
def set_current_academic_term(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Marca un ciclo lectivo como el período vigente institucional."""
term = AcademicTerm.query.get(id)
if not term:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Período lectivo con ID {id} no encontrado.")
AcademicTerm.query.update({'is_current': False})
term.is_current = True
term.is_active = True
db.session.commit()
return {
'status': 'success',
'message': f'El período "{term.name}" ha sido establecido como el ciclo lectivo activo actual.',
'term': term.to_dict()
}
@academic_router.post("/academic-terms/{id}/toggle")
@academic_router.post("/admin/academic-terms/{id}/toggle")
def toggle_academic_term(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Conmuta el estado activo de un ciclo lectivo."""
term = AcademicTerm.query.get(id)
if not term:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Período lectivo con ID {id} no encontrado.")
term.is_active = not term.is_active
db.session.commit()
return {
'status': 'success',
'is_active': term.is_active,
'message': f'Período {"activado" if term.is_active else "desactivado"} exitosamente.',
'term': term.to_dict()
}
@academic_router.delete("/academic-terms/{id}")
@academic_router.delete("/admin/academic-terms/{id}")
def delete_academic_term(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Elimina un ciclo lectivo."""
term = AcademicTerm.query.get(id)
if not term:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Período lectivo con ID {id} no encontrado.")
name = term.name
db.session.delete(term)
db.session.commit()
return {
'status': 'success',
'message': f'Período lectivo "{name}" eliminado correctamente.'
}
# =========================================================
# COMMISSION TEACHERS MANAGEMENT
# =========================================================
@academic_router.post("/commissions/{id}/assign-teacher")
async def assign_commission_teacher(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Asigna el docente titular a una comisión."""
data = await get_request_payload(request)
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión {id} no encontrada.")
t_id = data.get('teacher_id') or data.get('user_id')
role = (data.get('role') or 'Titular').strip()
if t_id:
t_id = int(t_id)
comm.teacher_id = t_id
ct = CommissionTeacher.query.filter_by(commission_id=comm.id, user_id=t_id).first()
if not ct:
ct = CommissionTeacher(commission_id=comm.id, user_id=t_id, role=role, is_primary=True)
db.session.add(ct)
else:
ct.role = role
ct.is_primary = True
else:
comm.teacher_id = None
db.session.commit()
return {
'status': 'success',
'id': comm.id,
'teacher_id': comm.teacher_id,
'teacher_name': comm.teacher_name,
'teachers': comm.teachers,
'message': 'Docente asignado correctamente.'
}
@academic_router.post("/commissions/{id}/teachers")
async def add_commission_teacher(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Agrega un docente (titular o adjunto/co-docente) a una comisión."""
data = await get_request_payload(request)
user_id = data.get('user_id') or data.get('teacher_id')
if not user_id:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="El docente es requerido.")
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión {id} no encontrada.")
user = User.query.get(int(user_id))
if not user:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"El usuario docente con ID {user_id} no existe.")
role = (data.get('role') or 'Adjunto').strip()
is_primary = data.get('is_primary', False)
if isinstance(is_primary, str):
is_primary = is_primary.lower() in ['true', '1', 'on']
existing = CommissionTeacher.query.filter_by(commission_id=comm.id, user_id=user.id).first()
if existing:
existing.role = role
existing.is_primary = bool(is_primary)
else:
if is_primary or comm.teacher_id is None:
comm.teacher_id = user.id
is_primary = True
ct = CommissionTeacher(
commission_id=comm.id,
user_id=user.id,
role=role,
is_primary=bool(is_primary)
)
db.session.add(ct)
db.session.commit()
return {
'status': 'success',
'message': f'{user.name} asignado/a como {role} en la comisión.',
'teachers': comm.teachers,
'commission': comm.to_dict()
}
@academic_router.delete("/commissions/{id}/teachers/{user_id}")
def remove_commission_teacher(
id: int,
user_id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Desvincula a un docente de una comisión."""
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión {id} no encontrada.")
ct = CommissionTeacher.query.filter_by(commission_id=comm.id, user_id=user_id).first()
if ct:
db.session.delete(ct)
if comm.teacher_id == user_id:
other = CommissionTeacher.query.filter(CommissionTeacher.commission_id == comm.id, CommissionTeacher.user_id != user_id).first()
comm.teacher_id = other.user_id if other else None
if other:
other.is_primary = True
db.session.commit()
return {
'status': 'success',
'message': 'Docente desvinculado de la comisión correctamente.',
'teachers': comm.teachers,
'commission': comm.to_dict()
}
# =========================================================
# COMMISSION ENROLLMENTS
# =========================================================
@academic_router.get("/commissions/{id}/enrollments")
def get_commission_enrollments(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA", "DOCENTE"]))
):
"""Lista los estudiantes matriculados en una comisión."""
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Comisión {id} no encontrada.")
enrollments = EnrollmentService.list_enrollments(comm.id)
return {
'commission_id': comm.id,
'commission_code': comm.code,
'count': len(enrollments),
'max_students': comm.max_students,
'current_students': comm.current_students,
'enrollments': enrollments
}
@academic_router.post("/commissions/{id}/enrollments", status_code=status.HTTP_201_CREATED)
async def enroll_commission_student(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Matricula a un estudiante en una comisión."""
data = await get_request_payload(request)
student_id = data.get('student_id')
notes = data.get('notes')
allow_same_day_exception = bool(data.get('allow_same_day_exception', False))
exception_reason = data.get('exception_reason')
if not student_id:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="student_id es obligatorio.")
try:
enrollment = EnrollmentService.enroll_student(
commission_id=id,
student_id=int(student_id),
notes=notes,
allow_same_day_exception=allow_same_day_exception,
exception_reason=exception_reason
)
return {
'status': 'success',
'message': 'Estudiante matriculado exitosamente en la comisión.',
'enrollment': enrollment.to_dict()
}
except ValueError as e:
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e))
@academic_router.delete("/commissions/{id}/enrollments/{student_id}")
def unenroll_commission_student(
id: int,
student_id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Desmatricula a un estudiante de una comisión."""
success = EnrollmentService.unenroll_student(commission_id=id, student_id=student_id)
if not success:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Matrícula no encontrada para este estudiante.")
return {
'status': 'success',
'message': 'Estudiante desvinculado de la comisión exitosamente.'
}
@academic_router.put("/commissions/{id}/enrollments/{student_id}")
async def update_commission_enrollment(
id: int,
student_id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Actualiza el estado de matrícula de un estudiante."""
data = await get_request_payload(request)
status_val = data.get('status', 'activo')
notes = data.get('notes')
enrollment = EnrollmentService.update_enrollment_status(
commission_id=id,
student_id=student_id,
status=status_val,
notes=notes
)
if not enrollment:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Matrícula no encontrada.")
return {
'status': 'success',
'message': 'Estado de matrícula actualizado.',
'enrollment': enrollment.to_dict()
}
# =========================================================
# GRADEBOOK & ACTAS DE REGULARIDAD
# =========================================================
@academic_router.get("/commissions/{id}/gradebook")
def get_commission_gradebook(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA", "DOCENTE"]))
):
"""Obtiene la sábana completa de notas y regularidad de la comisión."""
try:
data = GradebookService.get_commission_gradebook(id)
return {'status': 'success', 'data': data}
except ValueError as e:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
except Exception as e:
raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
@academic_router.post("/commissions/{id}/gradebook/grades")
@academic_router.put("/commissions/{id}/gradebook/grades")
async def save_commission_grades(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA", "DOCENTE"]))
):
"""Carga de notas individual o masiva para hitos evaluativos."""
data = await get_request_payload(request)
try:
if 'grades' in data and isinstance(data['grades'], list):
res = GradebookService.bulk_save_grades(
commission_id=id,
grades_data=data['grades'],
grader_id=int(getattr(current_user, 'id'))
)
return {'status': 'success', 'message': f"{res['saved_count']} calificaciones guardadas.", 'data': res}
else:
milestone_id = data.get('milestone_id')
student_id = data.get('student_id')
score = data.get('score')
is_absent = bool(data.get('is_absent', False))
feedback = data.get('feedback', '')
if not milestone_id or not student_id:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="milestone_id y student_id son obligatorios.")
grade = GradebookService.save_single_grade(
commission_id=id,
milestone_id=int(milestone_id),
student_id=int(student_id),
score=float(score) if score is not None and str(score).strip() != '' else None,
is_absent=is_absent,
feedback=feedback,
grader_id=int(getattr(current_user, 'id'))
)
return {'status': 'success', 'message': 'Calificación guardada.', 'grade': grade.to_dict()}
except ValueError as e:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
except Exception as e:
raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
@academic_router.post("/commissions/{id}/gradebook/close")
async def close_commission_gradebook(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA", "DOCENTE"]))
):
"""Cierre formal del acta de calificaciones de la comisión."""
data = {}
try:
data = await request.json()
except Exception:
pass
notes = data.get('notes', '')
try:
res = GradebookService.close_gradebook(commission_id=id, user_id=int(getattr(current_user, 'id')), notes=notes)
return {'status': 'success', **res}
except ValueError as e:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
except Exception as e:
raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
@academic_router.post("/commissions/{id}/gradebook/reopen")
async def reopen_commission_gradebook(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Reapertura administrativa del acta de calificaciones."""
data = {}
try:
data = await request.json()
except Exception:
pass
reason = data.get('reason', '')
try:
res = GradebookService.reopen_gradebook(commission_id=id, user_id=int(getattr(current_user, 'id')), reason=reason)
return {'status': 'success', **res}
except ValueError as e:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
except Exception as e:
raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
@academic_router.get("/commissions/{id}/milestones")
def list_commission_milestones(
id: int,
current_user: User = Depends(get_current_user)
):
"""Lista todos los hitos evaluativos de una comisión."""
comm = Commission.query.get(id)
if not comm:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Comisión no encontrada.")
milestones = AcademicMilestone.query.filter_by(commission_id=id, is_active=True).order_by(AcademicMilestone.date.asc()).all()
return {'status': 'success', 'milestones': [m.to_dict() for m in milestones]}
@academic_router.post("/commissions/{id}/milestones", status_code=status.HTTP_201_CREATED)
async def create_commission_milestone(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA", "DOCENTE"]))
):
"""Crea un nuevo hito evaluativo (examen, parcial, TP) para la comisión."""
data = await get_request_payload(request)
milestone_type_id = data.get('milestone_type_id')
title = data.get('title', '')
date_str = data.get('date', '')
notes = data.get('notes', '')
if not milestone_type_id or not date_str:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="milestone_type_id y date son obligatorios.")
try:
if 'T' in date_str:
date_val = datetime.fromisoformat(date_str)
else:
date_val = datetime.strptime(date_str, '%Y-%m-%d')
except Exception:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Formato de fecha inválido (use YYYY-MM-DD o ISO).")
try:
m = GradebookService.create_milestone(
commission_id=id,
milestone_type_id=int(milestone_type_id),
title=title,
date_val=date_val,
notes=notes
)
return {'status': 'success', 'message': 'Hito evaluativo programado exitosamente.', 'milestone': m.to_dict()}
except ValueError as e:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
except Exception as e:
raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
@academic_router.delete("/commissions/{id}/milestones/{milestone_id}")
def delete_commission_milestone(
id: int,
milestone_id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA", "DOCENTE"]))
):
"""Elimina un hito evaluativo programado si el acta aún está abierta."""
try:
GradebookService.delete_milestone(commission_id=id, milestone_id=milestone_id)
return {'status': 'success', 'message': 'Hito evaluativo eliminado exitosamente.'}
except ValueError as e:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
except Exception as e:
raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
# =========================================================
# MILESTONE TYPES CRUD
# =========================================================
@academic_router.get("/milestone-types")
def get_milestone_types(
current_user: User = Depends(get_current_user)
):
"""Lista las tipificaciones de hitos académicos disponibles."""
types = MilestoneType.query.order_by(MilestoneType.sort_order.asc(), MilestoneType.id.asc()).all()
return {
'status': 'success',
'total': len(types),
'milestone_types': [t.to_dict() for t in types]
}
@academic_router.post("/milestone-types", status_code=status.HTTP_201_CREATED)
async def create_milestone_type(
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Crea una nueva tipificación de hito evaluativo."""
data = await get_request_payload(request)
name = str(data.get('name', '')).strip()
code = str(data.get('code', '')).strip().lower().replace(' ', '_')
color = str(data.get('color', '#0d6efd')).strip()
description = str(data.get('description', '')).strip()
try:
sort_order = int(data.get('sort_order', 0) or 0)
except (ValueError, TypeError):
sort_order = 0
is_active = data.get('is_active', True)
if isinstance(is_active, str):
is_active = is_active.lower() in ['true', '1', 'on']
if not name or not code:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Nombre y código son obligatorios.")
existing = MilestoneType.query.filter_by(code=code).first()
if existing:
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Ya existe una tipificación con el código {code}.")
mt = MilestoneType(
name=name,
code=code,
color=color,
description=description,
sort_order=sort_order,
is_active=bool(is_active)
)
db.session.add(mt)
db.session.commit()
return {
'status': 'success',
'message': 'Tipificación de hito creada correctamente.',
'milestone_type': mt.to_dict()
}
@academic_router.put("/milestone-types/{id}")
async def update_milestone_type(
id: int,
request: Request,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Actualiza una tipificación de hito evaluativo existente."""
data = await get_request_payload(request)
mt = MilestoneType.query.get(id)
if not mt:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Tipificación con ID {id} no encontrada.")
if 'name' in data and data['name']:
mt.name = str(data['name']).strip()
if 'code' in data and data['code']:
code = str(data['code']).strip().lower().replace(' ', '_')
existing = MilestoneType.query.filter(MilestoneType.code == code, MilestoneType.id != id).first()
if existing:
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Ya existe otra tipificación con el código {code}.")
mt.code = code
if 'color' in data:
mt.color = str(data['color']).strip()
if 'description' in data:
mt.description = str(data['description']).strip()
if 'sort_order' in data:
try:
mt.sort_order = int(data['sort_order'])
except (ValueError, TypeError):
pass
if 'is_active' in data:
mt.is_active = data['is_active'] in [True, 'true', '1', 'on']
db.session.commit()
return {
'status': 'success',
'message': 'Tipificación actualizada correctamente.',
'milestone_type': mt.to_dict()
}
@academic_router.post("/milestone-types/{id}/toggle")
def toggle_milestone_type(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Conmuta el estado activo de una tipificación de hito."""
mt = MilestoneType.query.get(id)
if not mt:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Tipificación con ID {id} no encontrada.")
mt.is_active = not mt.is_active
db.session.commit()
return {
'status': 'success',
'id': mt.id,
'is_active': mt.is_active,
'message': f'Tipificación {"activada" if mt.is_active else "desactivada"} correctamente.'
}
@academic_router.delete("/milestone-types/{id}")
def delete_milestone_type(
id: int,
current_user: User = Depends(require_roles(["ADMIN", "BEDELIA"]))
):
"""Elimina o desactiva una tipificación de hito."""
mt = MilestoneType.query.get(id)
if not mt:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Tipificación con ID {id} no encontrada.")
milestone_count = AcademicMilestone.query.filter_by(milestone_type_id=id).count()
if milestone_count > 0:
mt.is_active = False
db.session.commit()
return {
'status': 'success',
'message': f'La tipificación tiene {milestone_count} hitos registrados. Se ha desactivado en su lugar.'
}
db.session.delete(mt)
db.session.commit()
return {
'status': 'success',
'message': 'Tipificación eliminada permanentemente.'
}