Backend: Add in attendance rate calculations to be returned

[izzyconner]

Context

Attendance rate can be calculated for:

• Shifts where reports were filed
• Shifts where the associate didn't show up
• Shifts where the associate was late/early

Attendance rates should be able to be calculated for a given associate:

• Per week
• Past month (last 30 days aka 4 timesheets)
• Total (all timesheets)

Description

This is the first ticket related to adding in the ability to get attendance rate calculations from the backend, and it will focus on calculating and passing back the attendance rates for a single weekly timesheet.

Keep in mind that these values may need to be requested separate from displaying a timesheet for a given week (i.e. exporting attendance rate data for all employees, showing attendance rate on profile cards, etc.), so even if it isn't necessary now, it might be good to do this work at least within it's own AttendanceCalculatorService-esque class to separate it from the normal Timesheet service. Or, if it makes more sense, we could add in a separate endpoint or controller for requesting attendance rates.

If necessary for calculations, a new attribute Attendance should be added to the TimeEntrySchema, which represents the reports, if any, which were filed for that shift:

{
...
  Attendance: z.array(z.enum([
    AttendanceType.ABSENT, 
    AttendanceType.ON_TIME, 
    AttendanceType.LATE, 
    AttendanceType.EARLY])).optional()
}

Alternatively, you may find it easier to complete the calculations just by reading in the reports list for each timesheet entry and dynamically tallying up which reports (if any) were filed - to do this, you'd need to have a good way to count and distinguish each report, so you may want to separate out Comments and Reports as two different arrays in the TimeEntrySchema, and use the existing frontend ReportSchema.

The drawback with the first method is that we will also need to make sure whenever the reports or comments for a TimeEntry get deleted or added, the Attendance array needs to be checked and pruned to keep in sync.

API Specifications

You will need to add an endpoint /attendance that takes in a GET request with the following optional query parameters:

timesheetId: string

The response body after a successful calculation should be:

timesheetId: string,
weekAttendance: AttendanceReport object,
monthAttendance: AttendanceReport object,
totalAttendance: AttendanceReport object

# In the attendance report object, each `Shifts` value represents the total number of shifts that meet those criteria within the given time period. 
# i.e. There were 15 total shifts in the week, and for 2 of those shifts, there was an `ABSENT` report filed.
AttendanceReport: {
    totalShifts: integer,
    absentShifts: integer,
    lateShifts: integer
    earlyOutShifts: integer
}

For this ticket, you do not need to worry about any of the other attendance report objects other than the weekAttendance for the provided timesheetId query. For all other AttendanceReport objects, default integer values to -1.

Something to consider

A decision that will have to be made is whether to:

• store the calculated attendance values in the database per weekly timesheet, and recalculate/update in the database when appropriate - likely when the backend receives an UPDATE request on the /timesheet endpoint that handles the Comments attribute.
• make the calculation of hours dynamically in the API every time that the data is requested.
• another option you come up with.

The first method has drawbacks, since dynamic calculation will still need to done for monthly and all-time rates, but it potentially saves a lot of repeated calculations done on the backend server's side. That being said, for the scope we are working in for this web app, performance likely won't be a major issue, so I'm leaning towards the second option.

Conditions of Satisfaction

• There is a valid endpoint attendance that can be requested with the supported params as specified above
• The Response body has the format specified above
• The Response body correctly has all shifts correctly calculated

Make sure you test for all the following cases:

• Shift calculations when there are 0 shifts that week
• Shift calculations where a shift has two different kinds of reports
• Shift calculations for each of the three different attendance report types
• Shift calculations when there are shifts entered for a week, but no reports

Keep in mind you may not have data in the database for this if you choose to add in the Attendance array for calculations. If that's the case, you can add dummy data manually to Dynamo via the AWS Console, or implement the updating of the Attendance array when updating a timesheet.