[POST] Generate Timetables From Classes

[arafaysaleem]

Summary

As a student, I should be able to get all possible generated timetables, so that I can choose one for my semester.

Acceptance Criteria

GIVEN an student is requesting all possible timetables in the app
WHEN the app hits the /timetables/generate endpoint with a valid POST request containing body parameters:

• classes array, where each item is a:
  • class object
• num_of_subjects, number of unique subjects in a timetable.

THEN the app should receive a status 200
AND in the response, the following information should be returned:

• headers
• list of timetables

Sample Request/Sample Response

headers: {
    error: 0,
    message: "..."
}
body: [
    {
        term_id: 1,
        is_active: 0,
	classes : [
        {
        	class_erp: 5460,
  		semester: CS-4,
        	term_id: 1,
  		classroom: {
			classroom_id: 1,
			classroom: "MTC-21",
			campus: {
				campus_id: 1,
				campus: "MAIN"
			},
		},
  		subject: {
			subject_code: CSE104,
			subject: "Data Structures"
		}
  		teacher: {
			teacher_id: 1,
			full_name: "Shakeel Khoja",
			average_rating: 4.5,
			total_reviews: 10
		}
  		parent_class_erp: null, // this is not a lab class
  		timeslot_1: {
			timeslot_id: 1,
			start_time: 8:30,
			end_time: 9:45,
			slot_number: 1
		},
  		timeslot_2: {
			timeslot_id: 1,
			start_time: 8:30,
			end_time: 9:45,
			slot_number: 1
		},
  		day_1: monday,
  		day_2: wednesday
    	   },
        {
        	class_erp: 5590,
  		semester: CS-4,
        	term_id: 1,
  		classroom: {
			classroom_id: 1,
			classroom: "MTC-21",
			campus: {
				campus_id: 1,
				campus: "MAIN"
			},
		},
  		subject: {
			subject_code: CSE105,
			subject: "Data Mining"
		}
  		teacher: {
			teacher_id: 3,
			full_name: "Sajjad Haider",
			average_rating: 4.5,
			total_reviews: 10
		}
  		parent_class_erp: null, // this is not a lab class
  		timeslot_1: {
			timeslot_id: 2,
			start_time: 10:00,
			end_time: 11:15,
			slot_number: 2
		},
  		timeslot_2: {
			timeslot_id: 2,
			start_time: 10:00,
			end_time: 11:15,
			slot_number: 2
		},
  		day_1: monday,
  		day_2: wednesday
    	   },
        {...},
         ....
    ]
    },
    ...
]

Resources

• Development URL: {Here goes a URL to the feature on development API}
• Production URL: {Here goes a URL to the feature on production API}

Dev Notes

This is going to return all possible timetables for the specified classes. This endpoint is going to be accessible and work the same way for the admin as well.

Testing Notes

Scenario 1: POST request is successful

GIVEN a student is requesting all possible timetables in the app
WHEN the app hits the /timetables/generate endpoint with a valid POST request
THEN the app should receive a status 200
AND the body should be an array
AND the first item of the array should be an object containing the following fields:

• term_id
• is_active
• classes

AND the key classes should be an array
AND the first item of the array should be an object containing the following fields:

• class_erp
• semester
• classroom
• subject
• teacher
• parent_id
• timeslot_1
• timeslot_2
• day_1
• day_2
• term_id
  AND the key classroom should be an object containing the following fields:
• classroom_id
• classroom
• campus
  AND the key campus should be an object containing the following fields:
• campus_id
• campus
  AND the key subject should be an object containing the following fields:
• subject_code
• subject
  AND the key teacher should be an object containing the following fields:
• teacher_id
• full_name
• average_rating
• total_reviews
  AND the keys timeslot_1 and timeslot_2 should be objects containing the following fields:
• timeslot_id
• start_time
• end_time
• slot_number

Scenario 2: POST request is unsuccessful due to no possible timetables

GIVEN a student is requesting all possible timetables in the app
WHEN the app hits the /timetables/generate endpoint with a valid POST request
AND the classes in the body result in 0 timetables due to conflicts
THEN the app should receive a status 404
AND the response headers' code parameter should contain "NotFoundException"

Scenario 3: POST request is incorrect

GIVEN a student is requesting all possible timetables in the app
WHEN the app hits the /timetables/generate endpoint with a POST request
AND the body contains an incorrect key
THEN the app should receive a status 422
AND the response headers' code parameter should contain "InvalidPropertiesException"
AND the response headers' data parameter should contain the name of the invalid parameters

Scenario 4: POST request is unauthorized

GIVEN a student is requesting all possible timetables in the app
WHEN the app hits the /timetables/generate endpoint with a valid POST request
AND the request contains no authorization token
THEN the app should receive a status 401 Unauthorized
AND the response headers' code parameter should contain "TokenMissingException"

[arafaysaleem]

Referencing this StackOverflow comment:

https://stackoverflow.com/a/24936942/13973939

Main function

1. Sort the classes in step 2 according to timeslot.slot_number
2. Call sub function

Make a sub function that takes the following

1. A map of schedule (default: {})
2. A list of possible classes_list (default: [...fromRequestBody])
3. num_subject_left to be added (default: req.body.num_of_subjects)
4. A int for slot_number (default: 1)

The sub function will

1. Check if num_subject_left = 0, then:
   1.1. Add the schedule to global list of schedules
   1.2. Return
   Else if num_subject_left > 0 & len(classes_list) == 0, then:
   1.1. Return
2. Iterate over classes_list where:
   timeslot.slot_number == argument slot_number,
3. For each picked class
   3.1. Remove current & all classes with the same subject_name,
   3.2. Remove all classes with the slot_number. The rest is sublist.
   3.3. Add it to the map of schedule like

   map[time_slot] = class

   3.4. Search for next class from sublist recursively by calling the sub function again with these values:
   1. COPY of the same map of schedule.
   2. sublist of classes
   3. num_subject_left - 1
   4. slot_number + 1

After the main function ends, the global schedules list is going to have combinations and needs to be returned.