Coverage for server / routes / teacher / teacher_dashboard.py: 72%
25 statements
« prev ^ index » next coverage.py v7.13.4, created at 2026-10-04 09:33 +0000
1from fastapi import APIRouter, Depends, HTTPException, Request, status
2from server.authentication.auth0_bearer import Auth0Bearer
3from server.services.growthbook import require_feature
5_DASHBOARD_DEPS = [
6 Depends(Auth0Bearer(access_levels=["teacher"])),
7 Depends(require_feature("teacher.dashboard")),
8]
9from server.services.teacher.teacher_dashboard import TeacherDashboardService
12router = APIRouter()
14teacher_dashboard_service = TeacherDashboardService()
17@router.get(
18 "/class/statistics/fetch",
19 dependencies=_DASHBOARD_DEPS,
20 status_code=status.HTTP_200_OK,
21 response_description="Get statistics for classes",
22 description="As a teacher, I can fetch statistics for classes",
23 summary="As a teacher, I can fetch statistics for classes",
24)
25async def class_statistics_fetch(
26 request: Request,
27 ) -> dict:
28 """
29 Retrieve statistical data for classes associated with the authenticated teacher.
31 This endpoint returns aggregated statistics about the classes the teacher manages,
32 including metrics about student enrollment, performance, and assignment completion.
34 Args:
35 request (Request): The incoming request object containing:
36 - JWT token in Authorization header
37 - Teacher authentication context
38 - Teacher role and permissions
40 Returns:
41 dict: Class statistics including:
42 - class_counts (dict):
43 - total (int): Total number of classes taught
44 - active (int): Number of currently active classes
45 - archived (int): Number of past/completed classes
46 - student_metrics (dict):
47 - total_students (int): Total enrolled students
48 - avg_class_size (float): Average students per class
49 - distribution (dict): Students per class breakdown
50 - performance_stats (dict):
51 - class_averages (dict): Mean scores by class
52 - passing_rates (float): Percentage of passing grades
53 - improvement_trends (dict): Score trends over time
54 - assignment_analytics (dict):
55 - completion_rates (float): Assignment completion percentage
56 - on_time_rates (float): On-time submission percentage
57 - difficulty_levels (dict): Assignment complexity metrics
58 - engagement_metrics (dict):
59 - attendance_rates (float): Class attendance percentages
60 - participation_scores (dict): Student engagement levels
61 - class_feedback (dict): Aggregated student feedback
63 Raises:
64 HTTPException:
65 - 401: Invalid or missing authentication token
66 - 403: Insufficient permissions to access statistics
67 - 404: No class data found for teacher
68 - 500: Error retrieving statistics
69 """
70 result = await teacher_dashboard_service.class_statistics_fetch(request)
71 if result is None:
72 raise HTTPException(
73 status_code=status.HTTP_404_NOT_FOUND,
74 detail="No class statistics found"
75 )
76 return result
79@router.get(
80 "/students/statistics/fetch",
81 dependencies=_DASHBOARD_DEPS,
82 status_code=status.HTTP_200_OK,
83 response_description="Get statistics for classes",
84 description="As a teacher, I can fetch statistics for students",
85 summary="As a teacher, I can fetch statistics for students",
86)
87async def student_statistics_fetch(request: Request):
88 """
89 Retrieve statistical data about students for the authenticated teacher.
91 This endpoint returns aggregated statistics about student performance, engagement,
92 and progress across all classes taught by the teacher. The data helps teachers
93 track student outcomes and identify areas needing intervention.
95 Args:
96 request (Request): The incoming request object containing:
97 - JWT token in Authorization header
98 - Teacher authentication context
99 - Teacher role and permissions
101 Returns:
102 dict: Student statistics including:
103 - enrollment_stats (dict):
104 - total_students (int): Total number of enrolled students
105 - active_students (int): Currently active students
106 - class_distribution (dict): Students per class breakdown
107 - performance_metrics (dict):
108 - grade_averages (dict): Mean scores by class/subject
109 - passing_rates (float): Percentage meeting requirements
110 - improvement_trends (dict): Progress over time
111 - engagement_analytics (dict):
112 - attendance_rates (float): Class attendance percentages
113 - participation_levels (dict): Activity engagement scores
114 - response_patterns (dict): Student interaction metrics
115 - assignment_stats (dict):
116 - completion_rates (float): Work completion percentage
117 - timeliness_metrics (dict): Submission timing analysis
118 - quality_scores (dict): Assignment quality metrics
119 - support_indicators (dict):
120 - at_risk_count (int): Students needing intervention
121 - extra_help_requests (int): Support session requests
122 - improvement_areas (list): Key focus areas
124 Raises:
125 HTTPException:
126 - 401: Invalid or missing authentication token
127 - 403: Insufficient permissions to access statistics
128 - 404: No student data found for teacher
129 - 500: Error retrieving statistics
130 """
131 result = await teacher_dashboard_service.student_statistics_fetch(request)
132 if result is None:
133 raise HTTPException(
134 status_code=status.HTTP_404_NOT_FOUND,
135 detail="No student statistics found"
136 )
137 return result
140@router.get(
141 "/assignments/statistics/fetch",
142 dependencies=_DASHBOARD_DEPS,
143 status_code=status.HTTP_200_OK,
144 response_description="Get statistics for assignments",
145 description="As a teacher, I can fetch statistics for assignments",
146 summary="As a teacher, I can fetch statistics for assignments",
147)
148async def get_stats_for_assignments(request: Request):
149 """
150 Retrieve statistical data about assignments for the authenticated teacher.
152 This endpoint returns aggregated statistics about assignments across all classes taught
153 by the teacher, including submission rates, grade distributions, and completion trends.
155 Args:
156 request (Request): The incoming request object containing:
157 - JWT token in Authorization header
158 - Teacher authentication context
159 - Teacher role and permissions
161 Returns:
162 dict: Assignment statistics including:
163 - overall_metrics (dict):
164 - total_assignments (int): Total number created
165 - active_assignments (int): Currently open assignments
166 - completed_assignments (int): Past due assignments
167 - submission_stats (dict):
168 - completion_rate (float): Overall submission percentage
169 - on_time_rate (float): Submissions before deadline
170 - late_submission_rate (float): Late submission percentage
171 - performance_metrics (dict):
172 - grade_distribution (dict): Score breakdown by ranges
173 - average_scores (dict): Mean scores by assignment type
174 - passing_rate (float): Percentage meeting requirements
175 - time_analytics (dict):
176 - average_completion_time (float): Mean time to submit
177 - submission_patterns (dict): Common submission times
178 - deadline_proximity (dict): Submission timing analysis
179 - feedback_metrics (dict):
180 - comment_frequency (float): Teacher feedback rate
181 - revision_requests (int): Resubmission counts
182 - student_responses (dict): Response to feedback stats
184 Raises:
185 HTTPException:
186 - 401: Invalid or missing authentication token
187 - 403: Insufficient permissions to access statistics
188 - 404: No assignment data found
189 - 500: Error calculating statistics
190 """
192 return await teacher_dashboard_service.assignment_statistics_fetch(request)
194@router.get(
195 "/submissions/statistics/fetch",
196 dependencies=_DASHBOARD_DEPS,
197 status_code=status.HTTP_200_OK,
198 response_description="Get statistics for submissions",
199 description="As a teacher, I can fetch statistics for submissions",
200 summary="As a teacher, I can fetch statistics for submissions",
201)
202async def get_submissions_stats(request: Request):
203 """
204 Retrieve submission statistics for each class handled by the authenticated teacher.
206 For every class assigned to the teacher:
207 - Counts the total number of assignments.
208 - Counts the total number of submissions across those assignments.
209 - Separately counts the number of submissions with remarks "passed" and "failed".
210 - Includes per-assignment breakdown of passed and failed submissions.
211 - Ensures that the "assignments" field is always present, even if empty.
213 Args:
214 request (Request): FastAPI request object containing the authenticated teacher's UUID
215 in `request.state.user_details["uuid"]`.
217 Returns:
218 dict: A dictionary with the following structure:
219 {
220 "details": "Successfully fetched submission statistics.",
221 "data": [
222 {
223 "class_id": "<class ObjectId as string>",
224 "class_title": "<title of the class>",
225 "total_assignments": <int>,
226 "total_submissions": <int>,
227 "total_passed_submissions": <int>,
228 "total_failed_submissions": <int>,
229 "assignments": [
230 {
231 "_id": "<assignment ObjectId as string>",
232 "passed_submissions": <int>,
233 "failed_submissions": <int>
234 },
235 ...
236 ]
237 },
238 ...
239 ]
240 }
242 Raises:
243 HTTPException: If the teacher ID is not found in the request or an error occurs while querying the database.
244 """
245 return await teacher_dashboard_service.submission_statistics_fetch(request)